# ArcBlock — full content

---

## AFS

URL: https://www.arcblock.io/en/docs/afs/

---

## Author a provider

URL: https://www.arcblock.io/en/docs/afs/author-a-provider/

Start from a provider covered by current tests, not from an old planning document. In the ARC source tree:

| Artifact | Role |
|---|---|
| `providers/core/json/src/index.ts` | Compact implementation baseline (`AFSJSON` extends `AFSBaseProvider`) |
| `providers/core/json/test/conformance.test.ts` | Conformance fixture via `runProviderTests` |
| `packages/testing` (`@aigne/afs-testing`) | Shared suite runner and contract-gated fixtures |
| `docs/guides/provider-authoring.md` | Authoring discipline (ops vs semantic actions, ifMatch, query) |

## Minimal public contract

| Piece | What to implement |
|---|---|
| Module identity | `name`, optional `description`, `uri` / load params |
| Path ownership | Stable path layout; no reserved virtual prefix abuse (`.actions`, `.meta`, `.as`, …) |
| Operations | Only methods you can enforce: `list` / `read` / `write` / `delete` / `stat` / `search` / `exec` / `explain` / `rename` / optional `query` / optional batch |
| Capability declaration | `OperationsDeclaration` (+ features). **Declare ⇒ execute**; never advertise ifMatch/query without enforcement |
| Errors | Use shared `AFS*Error` codes (`AFS_NOT_FOUND`, `AFS_VALIDATION_ERROR`, `AFS_CONFLICT`, …) |
| Conformance | `test/conformance.test.ts` calling `runProviderTests` |

Typical baseline pattern (JSON provider):

1. Extend `AFSBaseProvider`.
2. Provide `static manifest()` / `load()` for registry/URI loading.
3. Decorate handlers with `@List`, `@Read`, `@Write`, `@Delete`, `@Search`, `@Stat`, `@Explain`, …
4. Override `getOperationsDeclaration()` when you need features such as `ifMatch`.
5. Expose `/.meta/.capabilities` for runtime discovery.

## Run the JSON baseline conformance

From a current ARC monorepo checkout (package `@aigne/afs-json`):

```bash
pnpm --filter @aigne/afs-json test -- test/conformance.test.ts
```

Verified on ARC source `44fbd616f` (2026-08-10):

```text
372 pass
6 skip
0 fail
Ran 378 tests across 1 file.
```

Treat that result as evidence for **this baseline and this commit**, not for every provider or every release. Skipped suites (for example subscribe when not declared) are expected when fixtures omit optional capabilities.

## Suggested implementation order

1. Sketch the FS layout (directories vs leaves vs action paths).
2. Implement inspection first: `list` + `read` (+ `stat`/`explain`). Anything stored should be enumerable—do not hide data only behind custom actions.
3. Add path mutation (`write`/`delete`/`rename`) only where the store can enforce it.
4. Add semantic `@Actions` only for operations that need provider-specific meaning beyond path CRUD.
5. Wire `runProviderTests` with a `structure` fixture matching real data.
6. If you declare `query`, ship a `collectionQuery` fixture (declare ⇒ test).
7. If you declare `write.features.ifMatch`, ship `ifMatch` **and** `peerProvider` against the same backing store.
8. Document data, auth, search, and failure boundaries separately from the generic AFS contract.

Do not claim `query` because you can `list`, or a particular search quality because you expose `search`.

## Keep an acceptance record

Use this record before presenting a provider as a public catalog candidate. It is a checklist, not a claim that every provider has already passed it.

| Record | What to capture |
|---|---|
| Contract | Owned paths, operations, declared capabilities; do not infer one from another |
| Data and access boundary | Backing system, credentials or caller boundary, data read/changed, observable failures |
| Conformance evidence | Exact test command, ARC/source version, pass/skip/fail counts |
| Local acceptance | Isolated local exercise: ARC version, commands, non-secret env choices, observed result. Do **not** substitute DID Space deploy for local evidence |
| Compatibility | ARC/runtime version and provider backend versions the observation depends on |
| Support ownership | Maintainer, lifecycle state, documentation location users should rely on |

If any row is unknown, keep the provider out of the public catalog. A package in the source tree is implementation evidence, not a support promise. See [Provider catalog](../provider-catalog/).

---

## Core contract

URL: https://www.arcblock.io/en/docs/afs/core-contract/

AFS exposes path operations. The provider responsible for a path supplies the operation and its behavior. Do not model the API as one universal filesystem with mandatory support for every verb.

Evidence for this page: `packages/core/src/type.ts` (`AFSModule`, `AFSRoot`), `packages/core/src/afs.ts`, `packages/core/src/capabilities/types.ts` (`OperationsDeclaration`), `packages/core/src/error.ts`, checked against ARC source `44fbd616f` and CLI `arc` `2.0.0-beta.28`.

## Operation families

| Operation | Module method (core) | Purpose | Capability boundary |
|---|---|---|---|
| `list` | `list?` | Enumerate entries under a path | Options and listing semantics are provider-defined; unsupported list flags may be best-effort |
| `read` / batch read | `read?`, optional `batchRead?` | Read one or more resources | Depends on provider and path; `visibility: "meta"` returns meta only |
| `write` / batch write | `write?`, optional `batchWrite?` | Create or change content | Writable is not implied by path existence; write modes include replace/append/prepend/patch/create/update |
| `delete` / batch delete | `delete?`, optional `batchDelete?` | Remove resources | Recursive and predicate options are provider/feature-specific |
| `rename` | `rename?` | Move/rename within provider rules | Not every CLI surface exposes rename; check core/API and provider |
| `stat` | `stat?` | Inspect metadata | Shared result envelope; fields inside are provider-defined |
| `search` | `search?` | Free-text retrieval | Coverage and ranking are provider-defined; see [Search and query](../search-and-query/) |
| `exec` | `exec?` | Invoke an action at a path | Requires explicit action path, args, and permission/severity policy |
| `explain` | `explain?` | Report how a path resolves | Use for routing and ownership inspection |
| `query` | `query?` (optional) | Typed collection query via `/.actions/query` | Optional and **strict**; declare fully or not at all |

Optional methods on `AFSModule` are real: a provider that omits a method does not implement that operation. Root `AFSRoot` requires the common ops at the dispatcher level and still routes through mount capabilities.

## Capability declaration

Providers declare operations through `OperationsDeclaration` (boolean or `{ supported, features }`):

| Field | Notes |
|---|---|
| `read`, `list`, `write`, `delete`, `search`, `exec`, `stat`, `explain` | Core op flags |
| `query?` | Mirrors the standard collection-query action for tooling |
| `batchWrite?`, `batchDelete?` | Often derived; pushdown needs method presence + `features.batchPushdown` |
| `subscribe?`, `interact?` | Optional event / human-elicitation capabilities |

Sub-capability features (examples):

| Feature | Meaning when declared |
|---|---|
| `write.features.ifMatch` | Optimistic concurrency via opaque `meta.version`; must enforce or reject, not silent degrade |
| `list.features.orderBy` | Server-side list ordering |
| `delete.features.where` | Predicate delete |

Read live declarations when available:

```bash
arc afs read <mount>/.meta/.capabilities
```

## Access mode and visibility

| Concept | Values | Effect |
|---|---|---|
| `accessMode` | `readonly` · `create` · `append` · `readwrite` | Constrains which mutations are allowed at the module/mount |
| `visibility` | `full` · `meta` | `meta`: read returns metadata only; search denied |

Do not assume `readwrite` from the fact that a path lists children.

## Error codes (selected)

From `packages/core/src/error.ts`. Applications should branch on `code`, not English message text alone.

| Code | Class | Typical cause |
|---|---|---|
| `AFS_NOT_FOUND` | `AFSNotFoundError` | Path does not exist |
| `AFS_UNSUPPORTED` | `AFSUnsupportedError` | Operation not supported |
| `AFS_VALIDATION_ERROR` | `AFSValidationError` | Bad args or strict query/spec failure |
| `AFS_READONLY` | `AFSReadonlyError` | Mutation against readonly surface |
| `AFS_ACCESS_MODE` | `AFSAccessModeError` | Violates mount access mode |
| `AFS_ACCESS_DENIED` | `AFSAccessDeniedError` | Substrate access denied |
| `AFS_FORBIDDEN` | `AFSForbiddenError` | Policy forbid |
| `AFS_AUTH_REQUIRED` | `AFSAuthRequiredError` | Mutating action needs auth |
| `AFS_CONFLICT` | `AFSConflictError` | `ifMatch` version mismatch |
| `AFS_ALREADY_EXISTS` | `AFSAlreadyExistsError` | Create/collision |
| `AFS_MOUNT_FAILED` | `AFSMountError` | Mount check failed |
| `AFS_ACTION_NOT_FOUND` | `AFSActionNotFoundError` | Unknown action |

CLI observation on beta.28: missing path via `arc afs read` prints `ERROR: Path not found: …` and exits `5`.

## CLI vs core surface

| Surface | Ops commonly exposed |
|---|---|
| `arc afs` (beta.28) | `ls`, `read`, `write`, `delete`, `stat`, `exec`, `explain`, `search`, `mount` |
| Core `AFSModule` | Above plus `rename`, optional `query`, optional batch pushdown, `subscribe`, etc. |

If you need an operation that is in core types but missing from the CLI group, use the programmatic/RPC surface or check whether a root `/.actions/*` action covers it. See [arc afs](../../arc-cli/command-reference-afs/).

## Provider authors

Implement an `AFSModule` (typically via `AFSBaseProvider` and operation decorators), expose only operations you can enforce, and run shared conformance tests. Continue with [Author a provider](../author-a-provider/).

---

## Browse AFS with the Explorer

URL: https://www.arcblock.io/en/docs/afs/explorer/

Use this page to browse a **running local AFS surface** in a browser instead of the CLI. Everything below was verified against a local daemon running `arc` `2.0.0-beta.34`, with the AFS Explorer blocklet served at `http://explorer.localhost:4900`. Your mounts, paths, and children will differ. For the CLI equivalent of every read operation here, see [Inspect a local AFS surface](../local-inspection/).

The Explorer is declared with `scope: root`: it sees your **entire** AFS namespace, including every mount. Treat it as a private inspection surface for your own machine or your own deployment, and apply the same secret-hygiene rules as [`arc afs mount list`](../local-inspection/) output — provider URIs visible in the tree can embed tokens.

## 1. Open the Explorer

On a local daemon (started via `arc`), the Explorer answers on the `explorer.localhost` domain of the daemon port:

```text
http://explorer.localhost:4900/
```

The URL path **is** the AFS path. Navigating to `/registry/providers` in the app puts `/registry/providers` in the address bar, and pasting that URL back opens the same directory. Selecting a file adds a `?sel=` query parameter:

```text
http://explorer.localhost:4900/registry/providers          ← directory = URL path
http://explorer.localhost:4900/modules/project?sel=%2Fmodules%2Fproject%2FREADME.md
```

Both forms are shareable deep links. One verified caveat: on first load the app may restore the location you visited last instead of the URL you pasted — load the URL a second time and it lands correctly (see [Failures to expect](#failures-to-expect)).

## 2. Read the four panes

| Pane | What it shows (verified) |
|---|---|
| **Sidebar** | A directories-only tree of the whole namespace with its own filter box. It auto-expands to the path you are on. Below it, a **Tags** section shows `No tags yet` until entries carry tags. |
| **Primary list** | The current directory: view-mode toggle (`☰` list, `▦` grid, `▶` slideshow), a filter box, a clickable breadcrumb, a `..` row, and one row per entry with type and size badges. Long directories load incrementally; a footer such as `69 of 185` shows how much of the directory is loaded. |
| **Inspector** | The selected entry: name and size header, **Download / Open / Copy link** actions, collapsible **Details** and **About** sections, and a **Preview**. |
| **Status bar** | The static text `Ready`. It is not an activity indicator. |

![AFS Explorer root directory: sidebar tree with mount descriptions, primary list with checkboxes, inspector preview, status bar](media/01-root-overview.png)

## 3. Navigate

| Action | Result (verified on beta.34) |
|---|---|
| Click an entry | Selects it; the inspector updates and `?sel=` is added to the URL |
| Double-click a directory | Opens it |
| Click `..` or a breadcrumb segment | Goes up / jumps to that ancestor |
| `↑` / `↓` | Moves the selection (URL `?sel=` follows) |
| `Enter` | Opens the selected directory |
| `Backspace` | Goes to the parent directory |
| Sidebar directory click | Jumps there; the tree expands along the way |

Type in either filter box to narrow the tree or the current listing.

![Breadcrumb and provider catalog at /registry/providers with the sidebar tree expanded to the same path](media/02-registry-providers.png)

## 4. Inspect a file

Select a file and open **Details**. Verified fields for a file on a local `fs` mount:

```text
path          /modules/project/README.md
version       177993786…721-5320        ← opaque optimistic-concurrency token
kind          fs:file
access        readwrite
modified      2 months ago | May 27, 2026, 8:11 PM
capabilities  list read stat search write delete exec explain
```

The **Preview** renders what it can inline — verified: Markdown files render as formatted text, images load through a signed `/api/afs/raw` URL, and directories show an item list. Entries the preview cannot render inline (verified with a `registry:guide` node) show `No preview available` plus a working **Download** link. **Download / Open / Copy link** are the only actions in the inspector header — the list row additionally offers **Collect** (see section 6).

![Inspector showing Details metadata and a rendered Markdown preview for README.md](media/03-file-inspector-preview.png)

## 5. Switch views

- **List `☰`** — rows with mime-type and size badges, selection checkboxes, and per-row actions.
- **Grid `▦`** — cards with content thumbnails (text files show their opening lines, images show the picture), plus the same checkboxes and per-card actions.
- **Slideshow `▶`** — one large card at a time with a `◀ 1 / N ▶` pager; browsing only, no selection.

![Grid view of a writable directory: content thumbnails on cards, and the Upload File / New Folder / Upload Folder toolbar](media/04-grid-view.png)

## 6. Select entries and use the item menu

Tick checkboxes in list or grid view. The toolbar shows `N selected` with two batch actions: **Collect** and **Clear**. Right-clicking a row and clicking its `⋯` button open the **same** menu; on beta.34 it contains exactly one action, **Collect**, which bookmarks the entry into your per-user collection. Collect appears on every entry, including entries in read-only directories.

There is **no rename, delete, move, or copy** anywhere in this surface on beta.34 — not in the menu, not in the batch bar. See [Failures to expect](#failures-to-expect).

![List view with two rows selected, the “2 selected · Collect · Clear” batch bar, and the open item menu showing Collect](media/05-list-menu-multiselect.png)

## 7. Write into a writable directory

The Explorer probes each directory's writability as you navigate. On directories that probe writable, the toolbar gains **Upload File**, **New Folder**, and **Upload Folder**; on read-only directories these buttons stay hidden. **New Folder** opens an inline name input — type a name and press `Enter`.

Whether the write then *succeeds* depends on the mount actually implementing plain writes. Verified failure case: on `/blocklet-manager` (a workspace mount whose declared capabilities do not include `write`), the toolbar appears, the name input accepts and clears — and nothing is created, with no error shown. The same write through the CLI fails explicitly (`ERROR: Internal server error`). Trust the mount's declared capabilities, not the toolbar, before relying on a write.

## 8. Use it on a narrow screen

Below roughly phone width the four panes collapse into a tab bar — **sidebar / primary / inspector** — showing one pane at a time. Verified at 390 px width.

## Failures to expect

| What you do | What happens on beta.34 | Meaning |
|---|---|---|
| Paste a deep link into a running session's browser | May land on the last-visited path instead | Load the same URL again; it then resolves correctly |
| `New Folder` on a mount without plain `write` support | Input accepted, nothing created, no error | Silent no-op; check the entry's `capabilities` in Details first |
| Look for rename / delete / move / copy | Not present in any menu or toolbar | This surface is browse + collect + upload only |
| Look for an "execute action" button | Not present; `exec` may still appear under `capabilities` | Action execution is not exposed here — use `arc afs exec`, or the daemon's `/explorer-classic/` route (see [Appendix](#appendix-the-classic-explorer-no-longer-a-separate-command)) |
| Select a `registry:` documentation node | `No preview available` + Download | Inline preview depends on the node kind, not the file extension |
| Watch the status bar for progress | Always `Ready` | Static text, not a live indicator |

## Appendix: the classic explorer (no longer a separate command)

There used to be a second, standalone way to reach this UI: `arc explore [path] --port <port>` started its own local server independent of any running daemon. That command was removed in ArcBlock/arc#5234 (it registered no automated callers) — but the UI itself did not go away. Every daemon started with `arc service start` now serves it directly at **`/explorer-classic/`** (verified: `curl http://localhost:<port>/explorer-classic` 301-redirects to `/explorer-classic/`, which returns the same `AFS Explorer` page with **Browse / Mounts / Registry** tabs, mount management, and action execution — this is a *different, fuller* surface than the blocklet-served `/explorer` documented above, whose [Failures to expect](#failures-to-expect) table explicitly lacks mount management and action execution). If you have old notes or scripts calling `arc explore`, replace them with `arc service start` and open `http://localhost:<port>/explorer-classic/`.

## What this page does not do

- It does not claim your instance shows the same mounts, paths, or children as the screenshots.
- It does not document tag authoring — the Tags section was verified only in its empty state.
- It does not promise write support on any given mount; capabilities are declared per mount.
- It does not cover formal publish or DID Space deployment checks; see [Runtime boundaries](../runtime-boundaries/).

---

## Get started with AFS

URL: https://www.arcblock.io/en/docs/afs/getting-started/

Start by checking the runtime you are actually using. Commands and provider availability can vary between ARC releases.

```bash
arc --version
arc afs --help
```

Verified on `arc` `2.0.0-beta.28`:

```text
2.0.0-beta.28
```

```text
arc afs

AFS file system operations (ls, read, write, stat, exec, search, mount…)

Commands:
  arc afs ls [path]               List directory contents        [aliases: list]
  arc afs read <path>             Read file content               [aliases: cat]
  arc afs write <path> [content]  Write content to file
  arc afs delete <path>           Delete file or directory         [aliases: rm]
  arc afs stat <path>             Get file or directory info
  arc afs exec <executable_path>  Execute an action
  arc afs explain [topic]         Explain AFS concepts or paths
  arc afs search <path> <query>   Search for content within an AFS path
                                                           [aliases: grep, find]
  arc afs mount                   Mount management
```

These commands only report the installed version and available AFS command surface. They do not invent mounts or storage for you.

## What to do next

1. Prefer **read-only** inspection first: `ls`, `stat`, `read`, `explain`, and `search` on paths that already exist on your instance.
2. Do **not** begin with `write`, `delete`, or `exec` against an unknown path. A path is meaningful only after the target instance has a provider and mount configuration.
3. Continue with [local inspection](../local-inspection/) for a verified walk of a running instance.
4. Read [the core contract](../core-contract/) before relying on an operation in application code.

## Related CLI man page

The full `arc afs` flag reference lives in the [arc-cli board](../../arc-cli/command-reference-afs/). This AFS board explains the path, capability, and provider contract; it does not restate every CLI flag.

## Environment notes

- `arc afs` talks to the local AFS surface available to your CLI session (typically a running daemon). Paths and mounts on **your** machine are not universal defaults.
- `mount list` can print provider URIs that include credentials. Treat that output as secret material; redact before sharing or pasting into issues.
- Adding a mount with `arc afs mount add` may report success while subsequent `ls`/`read` still fail on that path. Confirm with `stat`/`ls` before documenting a new mount as usable. See [Runtime boundaries](../runtime-boundaries/).

---

## Inspect a local AFS surface

URL: https://www.arcblock.io/en/docs/afs/local-inspection/

Use this page to inspect a **running local AFS surface** that you already own. All pasted output below was produced with `arc` `2.0.0-beta.28` against a local daemon. Your mounts, paths, and children will differ. Do not treat the sample paths as product defaults.

**Safety rules for this walkthrough**

| Rule | Why |
|---|---|
| Prefer `explain`, `ls`, `stat`, `read`, `search` first | They inspect without inventing structure |
| Use only paths your instance already exposes | Unknown paths are not a universal demo tree |
| Redact secrets from `mount list` | Provider URIs can embed tokens |
| Do not run `write`/`delete`/`exec` until you know the mount's access mode | Mutation is mount- and permission-specific |
| Do not assume a fresh `mount add` is immediately usable | Verified gap: CLI may report success while ops fail |

## 1. Confirm version and help

```bash
arc --version
arc afs --help
```

```text
2.0.0-beta.28
```

The help text lists `ls`, `read`, `write`, `delete`, `stat`, `exec`, `explain`, `search`, and `mount`. Full flags: [arc afs](../../arc-cli/command-reference-afs/).

## 2. Explain concepts, then mounts

```bash
arc afs explain
```

```text
AFS Overview
============

AFS (Agentic File System) is a virtual filesystem that unifies different data sources into a single namespace.

Core Concepts:
- mount: Mount a data source to a virtual path
- path: Virtual path, e.g., /src, /data
- uri: Data source address, e.g., fs://, git://, sqlite://

Data Flow:
  User Path -> AFS -> /{mount} -> Provider -> Actual Data
```

```bash
arc afs explain mount
```

`explain mount` lists **this instance's** mounts. Output is environment-specific. Example shape (paths redacted where sensitive):

```text
Mounts
======

Current mount configuration:

  /dev/ai/hub
  /dev/web - Web Device — Site Host
  /ash - ASH pipeline DSL
  /modules/vault
  /modules/project
  /modules/memory
  …
```

```bash
arc afs mount list
```

Example (credentials redacted):

```text
/dev/ai/hub -> aignehub://hub.aigne.io
/dev/web -> web-device:// (Web Device — Site Host)
/ash -> ash:// (ASH pipeline DSL)
/modules/vault -> vault://…[redacted]
/modules/project -> fs:///…/project
/modules/memory -> fs:///…/test-mem
/telegram -> telegram://[REDACTED]
…
```

```bash
arc afs mount validate
```

```text
Configuration is valid
```

`validate` checks configuration shape. It does not prove every mount can serve data.

## 3. List the root namespace

```bash
arc afs ls / -l
```

Sample (truncated; your root entries differ):

```text
├── 📁 blocklet-manager — Local blocklet workspace manager: …
├── 📁 spaces — Local DID Space logical roots
├── 📁 web — Web Device — renders .web/ + pages/ into static HTML. …
├── 📁 registry
├── 📁 modules
├── 📁 .knowledge (afs:system) — Provider capability index
├── 📁 .meta (afs:system) — Root metadata and mount info
└── 📁 .actions (afs:system) — Root-level executable actions
```

```bash
arc afs stat /
```

```text
PATH=/
CHILDREN=108
ACTIONS=mount,unmount,read,list,write,query,aggregate,delete
```

Root `ACTIONS` advertise root-level actions. A listed action name is not a promise that every mount supports the same verb.

## 4. Inspect a known mount path

Pick a path that already appears under your root or in `mount list`. On the verification host, `/modules/project` was a local `fs://` mount.

```bash
arc afs ls /modules
arc afs stat /modules/project
arc afs explain /modules/project
```

```text
PATH=/modules/project
KIND=fs:directory
CHILDREN=185
MODIFIED=2026-07-30T21:14:23.150Z
```

```bash
arc afs read /modules/project/package.json --start-line 1 --end-line 12
```

```text
{
  "name": "afs",
  "description": "Explore and manage AFS file systems",
  "version": "2.0.0-beta.15",
  …
}
```

## 5. Read declared capabilities on a path

When a provider exposes them, capabilities live under `/.meta/.capabilities` relative to the mount (or aggregated views).

```bash
arc afs read /modules/project/.meta/.capabilities
```

Truncated, verified shape for the local `fs` mount:

```json
{
  "schemaVersion": 1,
  "provider": "fs",
  "description": "Local filesystem provider",
  "operations": {
    "read": true,
    "list": { "supported": true, "features": { "orderBy": true } },
    "write": {
      "supported": true,
      "features": { "ifMatch": true, "treeMerge": true, "treeToggle": true, "treeIncrement": true }
    },
    "delete": { "supported": true, "features": { "where": true } },
    "search": true,
    "exec": true,
    "stat": true,
    "explain": true,
    "batchWrite": true,
    "batchDelete": true
  }
}
```

Use this declaration—not a guess from path shape—to decide whether `search`, `write`, or batch ops are in contract.

## 6. Search (provider-defined free text)

```bash
arc afs search /modules/project RELEASING
```

Sample hits (truncated):

```text
/modules/project/CLAUDE.md
/modules/project/README.md
/modules/project/RELEASING.md
…
```

Search quality, coverage, and ranking are provider-defined. See [Search and query](../search-and-query/).

## 7. Failures to expect

| Command | Observed on beta.28 | Meaning |
|---|---|---|
| `arc afs read /this-path-does-not-exist-xyz` | `ERROR: Path not found: …` (exit `5`) | Missing path |
| `arc afs ls /modules/project/definitely-missing-xyz` | `ERROR: Path not found: …` (exit `5`) | Missing child under a mount |
| `arc afs exec /.actions/query --args '{"path":"/modules/project","limit":2}'` | `ERROR: Collection query is not available on this surface` (exit `5`) | Query not declared / not available here — not a silent list fallback |
| `arc afs mount add /modules/… fs:///tmp/…` then `ls`/`read` | Mount message prints success; `explain` may show `TYPE unknown`; `ls` empty or error; `read` not found | Do not treat add success as operational readiness without re-checking |

## 8. Optional: mutate only on a known writable mount

If—and only if—you have a writable mount you control (for example a disposable directory already mounted as `fs://`), you can exercise write/read/delete. Do not invent a universal writable path.

Verified on a pre-mounted writable `fs://` path (`/modules/memory` on the verification host — **your path will differ**):

```bash
arc afs write /modules/memory/afs-doc-recipe.txt --content 'Hello from AFS recipe' --mode create
arc afs read /modules/memory/afs-doc-recipe.txt
arc afs stat /modules/memory/afs-doc-recipe.txt
arc afs delete /modules/memory/afs-doc-recipe.txt
```

```text
OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe
PATH=/modules/memory/afs-doc-recipe.txt
KIND=fs:file
SIZE=21
…
delete
```

After delete, read fails with not-found. Full task form: [Recipes](../recipes/).

## What this page does not do

- It does not start or reconfigure your daemon for you.
- It does not claim a single demo tree ships with every install.
- It does not treat repository package names as mounted products.
- It does not substitute for formal publish or DID Space deployment checks. Local inspection is a different verification surface; see [Runtime boundaries](../runtime-boundaries/).

---

## AFS

URL: https://www.arcblock.io/en/docs/afs/overview/

AFS is ARC's path-addressable filesystem abstraction. A provider supplies resources and declares the operations it supports. ARC routes an operation to the provider that owns the path.

Treat a path as an interface boundary, not evidence that all data lives in one store. A provider decides how it reaches or stores its own data. AFS does not require a client to copy every resource into one shared repository before addressing it.

## Path routing

A caller issues an operation on an AFS path. The runtime matches the path to a mount, then hands the operation to that mount's provider. The provider executes only the operations it implements and enforces.

| Stage | Role |
|---|---|
| Caller | CLI (`arc afs`), RPC, agent tool, or application code |
| AFS path | Virtual address in the instance namespace (for example `/modules/project`) |
| Mount route | Match the path prefix to a mounted provider |
| Provider | Capability gate and operation implementation |
| Backing system | Provider-owned store or transport |

![Flow from caller through AFS path and mount routing to a provider and its backing system](https://raw.githubusercontent.com/ArcBlock/loop-agent-assets/main/arcblock-site/docs-afs-20260810/afs-path-routing-20260811071326.svg)

## Start with the contract, not a storage assumption

The core API includes operations for listing, reading, writing, deleting, renaming, inspecting, searching, executing, explaining, and optional batch forms. A provider can expose only the operations it implements. Check the provider's declared capability before making an operation part of an application contract.

| Need | Read next |
|---|---|
| Inspect the installed command surface without changing data | [Get started](../getting-started/) |
| Walk a real local instance with verified command output | [Local inspection](../local-inspection/) |
| Understand the operations and their capability boundary | [Core contract](../core-contract/) |
| Keep enumeration, structured query, and free-text search separate | [Search and query](../search-and-query/) |
| Use or implement a provider | [Providers](../providers/) |
| Look up a term or run a repeatable task | [Reference](../reference/) · [Recipes](../recipes/) |

## What this page does not promise

AFS does not make every provider searchable, writable, or executable. In particular, a provider defines its search coverage, index strategy, and relevance or ranking. ARC returns matches in a shared `AFSSearchResult` envelope and may merge results from searchable providers routed beneath the requested path. Do not assume that this produces a global full-text index, a semantic index, or one uniform ranking across providers.

`query` is a separate optional collection capability at `/.actions/query`. A provider that declares the standard query action must execute the complete typed specification; ARC does not turn an unsupported provider into a query provider with a client-side fallback.

A package present under `providers/` in the ARC source tree is implementation inventory, not a public support catalog. See [Provider catalog](../provider-catalog/).

## Version boundary

Facts and command samples on this board were checked against `arc` `2.0.0-beta.28` and ARC source `44fbd616f` unless a page names another boundary. When you use another release, re-run the commands on that release before treating the pasted output as authoritative.

---

## afs/overview/visuals

URL: https://www.arcblock.io/en/docs/afs/overview/visuals/

---

## Provider catalog

URL: https://www.arcblock.io/en/docs/afs/provider-catalog/

This page defines **tiers** for talking about providers. It is intentionally not a generated list of every package under `providers/`.

A recent ARC tree inventory observed on the order of **77** provider packages (implementation count, not a support promise). Most of them must stay out of the public catalog until they meet the evidence bar.

## Tiers

| Tier | What belongs there | Evidence required before public wording |
|---|---|---|
| **Core runtime contract** | Shared path, operation, capability, and error contracts every author must understand | Current source + contract tests. This board documents those contracts; it does **not** list individual providers as "core products" |
| **Reference / optional (documented)** | A named integration you may present to developers as a starting point or optional module | Complete [authoring acceptance record](../author-a-provider/): contract, access boundary, conformance result, isolated local acceptance, compatibility, support ownership |
| **Source inventory only** | Packages visible in ARC source, including experimental, test-oriented, or incomplete work | Package presence alone. Keep source notes separate from the public catalog |
| **Do not list** | Internal, abandoned, or unverified backends; anything whose search/auth story would mislead | — |

## Verified-with-evidence entries (this board revision)

Entries below are **not** a complete product matrix. Each row cites the evidence used for this revision (`arc` `2.0.0-beta.28` and/or ARC `44fbd616f`). Absence from the table means "not admitted here yet," not "does not exist in source."

### Core / reference evidence (not full product acceptance)

Rows below are **core-contract or reference baselines with the evidence cited**. They are **not** a claim that every field of the [authoring acceptance record](../author-a-provider/) is already on file as a product support commitment (owner, lifecycle, isolated demo pack, public support surface). Use them to start from, not as a finished “admitted product” matrix.

| Name | Role | Evidence | Limits |
|---|---|---|---|
| **JSON / YAML provider** (`@aigne/afs-json`, `providers/core/json`) | Compact tree-as-FS baseline for authors | Conformance: `pnpm --filter @aigne/afs-json test -- test/conformance.test.ts` → **372 pass, 6 skip, 0 fail** on ARC `44fbd616f`. Source implements list/read/write/delete/search/stat/explain (+ rename in capabilities when writable) | Local file-backed JSON/YAML; not a remote multi-tenant store; search is provider-local over that tree; **not** a complete product acceptance record |
| **Local filesystem provider** (`providers/basic/fs`, URI scheme `fs://`) | Common local directory mount | Live local acceptance on beta.28: `ls`/`stat`/`read`/`search` on a mounted project tree; `read …/.meta/.capabilities` shows `provider: "fs"` with write/search/exec/batch flags; disposable write/read/delete on a separate pre-mounted writable `fs://` path | Instance-specific mounts; `mount add` success ≠ immediate operational readiness (see [Runtime boundaries](../runtime-boundaries/)); search is filesystem search for that mount, not global FTS |

### Observed on a sample daemon (not catalog admission)

The following appeared on **one** verification host's `mount list` / root listing. They illustrate environment mounts only. They are **not** elevated to supported public products by this page:

- `web-device://` (Web Device site host — contract lives on the [Web Device board](../../web-device/))
- `vault://`, agent `code-agent://` mounts, messaging mounts, hub URIs, and others

Do not copy a host's mount list into marketing or onboarding as "supported providers."

## Admission rule (repeat)

Do not promote a provider because the backend name is familiar or because a package exists. A future catalog row must name version boundary, supported operations, access/data boundary, maintainer, docs location, and the exact local acceptance evidence used.

Until more rows meet that rule, this catalog stays intentionally thin.

---

## Providers

URL: https://www.arcblock.io/en/docs/afs/providers/

An AFS provider is an `AFSModule` that supplies resources and operations behind paths. It is the unit that decides which operations exist, how paths resolve, and how a backing system is reached.

## Role in routing

| Step | Who owns it |
|---|---|
| Path string in the instance namespace | Caller |
| Mount path → provider instance | Runtime / configuration |
| Operation implementation and enforcement | Provider |
| Backing store or network transport | Provider |

Without a mount that maps a path prefix to a provider, the path is not a product feature—it is an unresolved address. See the routing diagram on [Overview](../overview/).

## What a provider must make explicit

Provider documentation (or acceptance records) should state:

| Topic | Why it matters |
|---|---|
| Owned path shape | How callers form stable paths |
| Declared operations and features | What is in contract vs optional |
| Access mode / auth / network-read policy | Who may read or mutate |
| Search and query behavior | Separate contracts; see [Search and query](../search-and-query/) |
| Failure codes and side effects | What callers can branch on |
| Support ownership | Who maintains it |

## Source inventory is not a catalog

The current ARC repository groups provider packages under areas such as core, basic, AI, messaging, platform, runtime, cost, IoT, and test. That inventory is **implementation evidence**. A package directory does not by itself become a stable public integration.

This board therefore:

- Explains the module contract on [Author a provider](../author-a-provider/)
- Defines admission tiers on [Provider catalog](../provider-catalog/)
- Does **not** flatten every package as an equally supported product

## Runtime modules you may already see

On a local daemon, `arc afs ls /` and `mount list` show **this instance's** mounts—not the full source inventory. Examples observed on one beta.28 host (not a support matrix): `fs://` project and memory trees, `web-device://`, `vault://`, agent code mounts, and others. Treat them as environment-specific until a catalog entry with evidence exists.

---

## AFS recipes

URL: https://www.arcblock.io/en/docs/afs/recipes/

Each recipe names its version, mutation risk, and assumptions. Paths like `/modules/project` are **examples from the verification host**, not universal defaults. Substitute mounts from your own `arc afs mount list`.

**Version:** `arc` `2.0.0-beta.28`

## Recipe 1 — Read-only root and mount survey

**Goal:** Learn what this instance exposes without changing data.  
**Mutates:** No  
**Assumes:** Local CLI can reach your AFS surface (typically a running daemon)

```bash
arc --version
arc afs explain
arc afs mount list   # redact secrets before sharing
arc afs mount validate
arc afs ls / -l
arc afs stat /
arc afs ls /.actions
```

**Observed (truncated, host-specific):**

```text
2.0.0-beta.28
```

```text
Configuration is valid
```

```text
PATH=/
CHILDREN=108
ACTIONS=mount,unmount,read,list,write,query,aggregate,delete
```

```text
/.actions/unmount
/.actions/read
/.actions/list
/.actions/write
/.actions/query
/.actions/aggregate
/.actions/delete
/.actions/mount
```

**Done when:** You can name at least one mount path you are willing to inspect further.

---

## Recipe 2 — Inspect a known mount (list / stat / read / capabilities / search)

**Goal:** Verify routing and capabilities on one existing mount.  
**Mutates:** No  
**Assumes:** A mount already serves data (verification host used `/modules/project` → `fs://…`)

```bash
MOUNT=/modules/project   # replace with your path

arc afs ls "$MOUNT"
arc afs stat "$MOUNT"
arc afs explain "$MOUNT"
arc afs read "$MOUNT/.meta/.capabilities"
arc afs search "$MOUNT" RELEASING
```

**Observed (truncated):**

```text
PATH=/modules/project
KIND=fs:directory
CHILDREN=185
MODIFIED=2026-07-30T21:14:23.150Z
```

Capabilities JSON included `"provider": "fs"` with `search: true` and write features such as `ifMatch` (full blob on [local inspection](../local-inspection/)).

Search returned paths under the mount, for example `/modules/project/RELEASING.md`.

**Failure check:**

```bash
arc afs read /this-path-does-not-exist-xyz
# ERROR: Path not found: /this-path-does-not-exist-xyz  (exit 5)
```

**Done when:** You know whether `search`/`write` appear in that mount's capabilities and you have read one real file.

---

## Recipe 3 — Disposable write / read / delete on a pre-mounted writable path

**Goal:** Exercise mutation only where you already have a writable mount.  
**Mutates:** Yes (creates and deletes one file)  
**Assumes:** An **already mounted** writable path you control. On the verification host this was `/modules/memory` (`fs://…/test-mem`). **Do not** copy that path blindly.  
**Does not assume:** That `arc afs mount add` just succeeded—see [Runtime boundaries](../runtime-boundaries/).

```bash
W=/modules/memory/afs-doc-recipe.txt   # replace prefix with YOUR writable mount

arc afs write "$W" --content 'Hello from AFS recipe' --mode create
arc afs read "$W"
arc afs stat "$W"
arc afs write "$W" --content ' — append' --mode append
arc afs read "$W"
arc afs delete "$W"
arc afs read "$W"   # expect not found
```

**Observed:**

```text
OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe
PATH=/modules/memory/afs-doc-recipe.txt
KIND=fs:file
SIZE=21
MODIFIED=2026-08-11T06:47:04.762Z
OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe — append
delete
ERROR: Path not found: …
```

**Optional negative checks (do not invent success):**

```bash
MOUNT=/modules/project   # replace with your path (recipe stands alone; do not rely on Recipe 2)
arc afs exec /.actions/query --args "{\"path\":\"$MOUNT\",\"limit\":2}"
# On the verification fs mount: ERROR: Collection query is not available on this surface
```

**Done when:** Create, read, append, and delete all behaved as expected on **your** mount, and the disposable file is gone.

---

## Recipe hygiene

| Rule | Reason |
|---|---|
| Name `arc --version` in any shared runbook | Commands drift across betas |
| Prefer pre-existing mounts for demos | Avoid unproven `mount add` paths |
| Redact `mount list` | Credentials appear in URIs |
| Separate list / search / query | Different contracts |
| Clean up disposable files | Leave the instance as you found it |

---

## AFS reference

URL: https://www.arcblock.io/en/docs/afs/reference/

Version boundary for pointers on this page: ARC source layout as of `44fbd616f`, CLI `arc` `2.0.0-beta.28`. Paths under `packages/` and `providers/` refer to the ARC repository (read-only reference for site authors), not to files inside this site blocklet.

## Terminology

| Term | Meaning |
|---|---|
| **AFS** | Path-addressable filesystem abstraction in ARC |
| **Path** | Virtual address in an instance namespace (for example `/modules/project/README.md`) |
| **Mount** | Binding from a path prefix to a provider URI/instance |
| **Provider / `AFSModule`** | Module that implements operations for owned paths |
| **Capability / operations declaration** | What ops (and features) the provider claims to support |
| **`list`** | Enumerate children; best-effort options |
| **`search`** | Provider-defined free-text retrieval |
| **`query`** | Optional strict typed collection query at `/.actions/query` |
| **`exec`** | Invoke an action at an executable path |
| **`explain`** | Describe concept or path resolution |
| **Access mode** | `readonly` / `create` / `append` / `readwrite` |
| **Visibility** | `full` / `meta` |
| **Conformance** | Shared provider tests via `@aigne/afs-testing` |
| **Instance** | A concrete runtime with its own mounts and data |

## Core types and ops (source pointers)

| Topic | Where in ARC |
|---|---|
| `AFSModule`, `AFSRoot`, entry/result types | `packages/core/src/type.ts` |
| Dispatcher / routing | `packages/core/src/afs.ts` |
| `OperationsDeclaration`, capability helpers | `packages/core/src/capabilities/types.ts` |
| Collection query types + strict validator | `packages/core/src/capabilities/collection-query.ts` |
| Error classes and codes | `packages/core/src/error.ts` |
| Base provider + decorators | `packages/core/src/provider/` |
| JSON reference provider | `providers/core/json/` |
| FS provider | `providers/basic/fs/` |
| Conformance runner | `packages/testing/` (`runProviderTests`) |
| Authoring guide | `docs/guides/provider-authoring.md` |
| Collection query guide | `docs/guides/collection-query.md` |

## CLI command group

| Command | Role |
|---|---|
| `arc afs ls` | List |
| `arc afs read` | Read |
| `arc afs write` | Write |
| `arc afs delete` | Delete |
| `arc afs stat` | Stat |
| `arc afs search` | Search |
| `arc afs exec` | Exec action |
| `arc afs explain` | Explain |
| `arc afs mount …` | Mount management |

Full flag reference: [arc afs](../../arc-cli/command-reference-afs/).

## Board map

| Page | Question |
|---|---|
| [Overview](../overview/) | Abstraction and non-promises |
| [Get started](../getting-started/) | First command surface |
| [Local inspection](../local-inspection/) | Verified inspect walk |
| [Core contract](../core-contract/) | Ops, capabilities, errors |
| [Search and query](../search-and-query/) | list vs query vs search |
| [Providers](../providers/) | Provider role |
| [Author a provider](../author-a-provider/) | Implementation start |
| [Provider catalog](../provider-catalog/) | Tiered public listing |
| [Runtime boundaries](../runtime-boundaries/) | Mounts, state, local vs publish |
| [Recipes](../recipes/) | Repeatable tasks |

## Related boards

- [AUP](../../aup/) — declarative UI model
- [Web Device](../../web-device/) — static site provider over AFS paths
- [arc-cli](../../arc-cli/) — command man pages

## Error codes (quick index)

See the table on [Core contract](../core-contract/). Branch on codes such as `AFS_NOT_FOUND`, `AFS_UNSUPPORTED`, `AFS_VALIDATION_ERROR`, `AFS_CONFLICT`, `AFS_READONLY`, `AFS_AUTH_REQUIRED`.

---

## Runtime boundaries

URL: https://www.arcblock.io/en/docs/afs/runtime-boundaries/

AFS behavior is always **instance-shaped**. The same CLI binary against two daemons, two `ARC` data directories, or two mount tables will not produce the same paths.

Verified with `arc` `2.0.0-beta.28` against a local daemon unless noted.

## Mounts

| Fact | Detail |
|---|---|
| Mount binds a path prefix to a provider URI | Example shape: `/modules/project -> fs:///absolute/path` |
| List mounts | `arc afs mount list` / `arc afs explain mount` |
| Validate config shape | `arc afs mount validate` → `Configuration is valid` on the verification host |
| Secrets | URIs may embed credentials (tokens, vault paths). Redact before sharing |

### `mount add` is not automatically an acceptance path

On beta.28, the following sequence was observed:

1. `arc afs mount add /modules/… fs:///tmp/…` printed `Mounted …`.
2. `arc afs mount list` showed the new row.
3. `arc afs explain <path>` reported `TYPE unknown`.
4. `ls` returned empty or connection errors; `read` returned not found.
5. `arc afs mount remove <path>` cleared the list entry.

**Do not** document a recipe that assumes add-then-immediately-write succeeds on every host. Prefer:

- inspecting mounts that are already serving data, or
- an isolation procedure your team has verified end-to-end (separate data dir / service instance), then re-check with `stat`/`ls` before mutation.

## Permissions and access

| Layer | What it constrains |
|---|---|
| Provider `accessMode` | `readonly` / `create` / `append` / `readwrite` |
| `visibility` | `full` vs `meta` (meta denies search content) |
| Action severity / policy | Which `exec` actions may run |
| Caller / network gates | Auth and network-read rules on some mounts |

A root that lists `write` among root actions still does not make every child mount writable.

## Instance state

| Kind of state | Examples | Doc implication |
|---|---|---|
| Process | Running daemon PID/port under the host's AFS data dir | CLI often talks to this daemon |
| Mount table | Configured provider URIs | Environment-specific |
| Provider data | Files under an `fs://` path, vault contents, remote resources | Mutation changes real data |
| Blocklet / space data | Under local DID Space trees | Different board; do not treat as disposable |

Do not treat an arbitrary long-lived daemon as disposable test infrastructure. Commands that register mounts or write provider data need a deliberate isolation story.

## Local validation vs formal publish

| Surface | What it proves | What it does not prove |
|---|---|---|
| Local `arc afs …` against your daemon | This instance's path/ops/mount behavior | Global product defaults, multi-tenant deploy |
| Local blocklet service / browser (site docs) | Site rendering of documentation | Remote DID Space hosting of your app |
| `arc deploy` / DID Space publish | Publish integration when that is the task | Local AFS contract correctness by itself |
| Provider conformance tests in ARC monorepo | Provider interface discipline at a commit | That your host's mounts match that provider |

For this AFS board, **local inspection and recipes are the primary evidence**. Formal publish is a separate checklist—use it only when the task is deployment.

## Practical checklist

1. Record `arc --version`.
2. Prefer read-only commands until mounts and capabilities are known.
3. Read `<mount>/.meta/.capabilities` when present.
4. Mutate only on mounts you own; clean up disposable paths.
5. Redact secrets from any shared output.
6. When a command fails, preserve the exact error—do not invent success output.

---

## Search and query

URL: https://www.arcblock.io/en/docs/afs/search-and-query/

Do not use `list`, `query`, and `search` as names for the same feature. They solve different problems and make different promises.

Evidence: `packages/core/src/capabilities/collection-query.ts`, `docs/guides/collection-query.md`, `AFSModule.search` / `query` in `type.ts`, and CLI runs on `arc` `2.0.0-beta.28`.

## Three contracts

| Operation | Use it for | Do not assume |
|---|---|---|
| `list` | Enumerating paths or entries under a path | A relevance-ranked result set, or a provider-independent data query language |
| `query` | A typed collection specification at the standard `/.actions/query` action | Client-side fallback when a provider has not declared the capability |
| `search` | Provider-defined free-text retrieval returned in a shared result envelope | Universal full-text coverage, semantic retrieval, a shared index, or one ranking algorithm |

### list — best-effort enumeration

`list` is the filesystem-style directory walk. Unsupported options may be ignored or marked (for example order-by ignored metadata). It is the right tool for "what children exist here?"

```bash
arc afs ls /modules/project
```

### search — provider-defined free text

```bash
arc afs search <path> <query>
```

Verified sample on a local `fs://` mount (`arc` `2.0.0-beta.28`):

```bash
arc afs search /modules/project RELEASING
```

```text
/modules/project/CLAUDE.md
/modules/project/README.md
/modules/project/RELEASING.md
…
```

| Rule | Detail |
|---|---|
| Ownership | The provider owns what it searches, how it indexes, and how it ranks |
| Envelope | ARC returns matches in `AFSSearchResult` and can merge searchable providers under the requested path |
| No global promise | Merging results is not a global FTS index or semantic search product |
| Visibility | On `visibility: "meta"` mounts, search is denied |

Document search expectations in the **provider's** docs, not by copying behavior observed on a different provider.

### query — optional and strict

Collection query is the typed action at `/.actions/query` (entries mode and aggregate mode). Philosophy is **declare ⇒ execute the whole spec**. Malformed specs and unsupported blocks are `AFS_VALIDATION_ERROR` (or equivalent). There is no silent client-side degradation to "sort of query via list".

Probe before relying on it: read `<mount>/.meta/.capabilities` (or root capabilities) and look for the standard action with `name === "query"` and `pathTemplate === "/.actions/query"`. Provider-local dialects (for example table-scoped query paths) are not this contract.

Verified on beta.28 against an `fs://` project mount that does **not** offer collection query on this surface:

```bash
arc afs exec /.actions/query --args '{"path":"/modules/project","limit":2}'
```

```text
ERROR: Collection query is not available on this surface
```

Exit code observed: `5`. That failure is the correct signal—not a partial list of files.

When a provider **does** declare query, a consumer issues a typed spec (fields such as `path`, `doc`, `where`, `orderBy`, `limit`/`offset` or cursor, `count`, `groupBy`, optional aggregate ops). Full field vocabulary and provider implementation checklist live in ARC's internal guide `docs/guides/collection-query.md` and `packages/core/src/capabilities/collection-query.ts`.

## Choosing among the three

| Goal | Prefer |
|---|---|
| Browse a tree | `list` |
| Find free-text matches the provider knows how to find | `search` (after checking capability) |
| Server-side typed filter / order / count / aggregate over a record collection | `query` (only if declared) |
| "Search everything on the machine like a desktop FTS product" | **Out of contract** for AFS as a whole |

## Product narrative caution

A future document library or NAS-oriented product may still layer catalogs, selected full-text collections, and richer indexes as **separate product choices**. Those choices are not automatic consequences of using AFS paths.

---

## Agent Access

URL: https://www.arcblock.io/en/docs/agent-access/

---

## Access tiers

URL: https://www.arcblock.io/en/docs/agent-access/access-tiers/

Whether a call succeeds is decided by four gates, in this order. They are independent: clearing one says nothing about the next.

The most common mistake is assuming a credential is enough. It clears gate 2. Gates 3 and 4 still apply, and on a blocklet that has declared no network rules they will still refuse a write from an owner-role caller.

| # | Gate | Decided by | Failure looks like |
|---|---|---|---|
| 1 | Method allowlist | Whether the JSON-RPC method is anonymous-safe | `401` + `WWW-Authenticate` |
| 2 | Credential | The bearer token or session cookie you sent | `401` + `WWW-Authenticate` |
| 3 | Path policy | What the **blocklet** declared for that path | `200` with `isError` and `AFS_FORBIDDEN` |
| 4 | Provider capability | What the provider behind the path implements | `200` with `isError` and a not-supported error |

Gates 1 and 2 are transport-level: they answer with an HTTP status and no JSON-RPC result. Gates 3 and 4 are inside a successful MCP call: the call itself worked, the operation did not. See [Errors](../errors/).

## Why there are four

Because three different parties decide them, and none can answer for another.

| Gate | Decided by | What it is really asking |
|---|---|---|
| 1, 2 | The runtime | Is this method safe without a caller, and is this caller who they say they are? |
| 3 | The blocklet | Have I opened this path to the network? |
| 4 | The provider | Do I implement this operation at all? |

This is why a credential is not enough, and why no better credential would help. A credential is an answer to the runtime, and the runtime does not own gates 3 and 4. No token can speak for the blocklet, and none can add an operation the provider never implemented.

It also explains the failure shapes. Gates 1 and 2 are decided before a tool is reached, so they can only answer in HTTP. Gates 3 and 4 are decided by code that already ran, so they answer inside a `200`.

## Gate 1: the method allowlist

Without a credential, only these are allowed:

| Allowed anonymously | Not allowed anonymously |
|---|---|
| `initialize`, `notifications/initialized` | `tools/call` with `afs_write`, `afs_delete`, `afs_exec` |
| `tools/list`, `resources/list`, `prompts/list` | Any other method, including unknown ones |
| `tools/call` with `afs_read`, `afs_list`, `afs_search`, `afs_stat`, `afs_explain`, `search_content`, `list_content`, `get_content` | |

The rule is fail-closed: anything not on the list is refused, and in a batch every message must be allowed or the whole batch is refused.

## Gate 2: the credential

Three ways to clear it:

| Tier | Credential | Where it comes from |
|---|---|---|
| Anonymous | none | n/a |
| Authenticated | `Authorization: Bearer blocklet-…` or a DID-Connect session cookie | [Authorize a client](../authorize-a-client/) or [the device grant](../device-grant/) |
| Loopback operator | verified same-machine socket peer, Node runtime only | Nothing to obtain. Never available over the network; the Cloudflare runtime never grants it |

### Roles

When a person approves a client, the consent screen asks for an **access level**. Four are offered:

| Role | |
|---|---|
| `owner` | the default on the consent screen |
| `admin` | |
| `member` | |
| `guest` | |

The credential carries the role the person picked, scoped to that blocklet instance. It is not a global role: the same person can be `owner` on one blocklet and have no access on another.

**The role is an upper bound, not a grant.** It cannot open a path that gate 3 has closed.

## Gate 3: the path policy

This is the gate most callers hit and the one no credential can bypass.

A blocklet decides, per path, what a **network** client may do. Paths that were not declared are closed to the network, including to an owner. The refusal is explicit about the fix:

```json
{
  "result": {
    "content": [{
      "type": "text",
      "text": "AFS_FORBIDDEN: Forbidden at /instance/notes.txt: network clients cannot write base paths; use a resolver overlay or internal code"
    }],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 3
}
```

Read and list produce the same shape with `cannot read base paths` / `cannot list base paths` and `declare a networkRead rule or use an overlay`.

What the declaration changes, compared across two blocklets:

| Call | Blocklet that declares nothing | Blocklet that declares collections with `readRole: guest` |
|---|---|---|
| anonymous `afs_list /` | refused | **200** |
| anonymous `afs_list /packages` | refused | **200** |
| anonymous `afs_list /.knowledge` | refused | refused, because that path was not declared either |
| anonymous `list_content` on a declared collection | tool not registered | **200** |
| **owner-credential `afs_write` on any base path** | **refused** | **refused** |

The last row is the one to remember. Writing from the network is not something a credential turns on; it needs a resolver overlay or code running inside the blocklet. If you are building an agent that must write, that is a decision for whoever owns the blocklet. See [Declare what agents see](../declare-what-agents-see/).

## Gate 4: provider capabilities

Each path is served by a provider that implements only some operations. `afs_stat` reports both what the provider can do and what you are allowed to do:

```json
{
  "capabilities": ["list", "read", "stat", "search", "write", "delete", "exec", "explain"],
  "accessMode": "readonly"
}
```

`capabilities` is the provider's implementation. `accessMode` is your effective access after gate 3. A path can list `write` in `capabilities` and still be `readonly` for you.

Check `capabilities` before making an operation part of an integration. See [AFS](../../afs/core-contract/) for the contract these operations belong to.

## What this means in practice

- **Reading published content works without any credential** when the blocklet declared it. That is the intended path for most agents, and it is what the content tools are for.
- **Getting a credential is worth doing** when you need a specific person's view of the data, or when the blocklet has opened write paths to the network.
- **A credential is not a write switch.** If writes are refused after you authenticate, gate 3 is the reason and the blocklet owner is the only one who can change it.

---

## AFS over HTTP

URL: https://www.arcblock.io/en/docs/agent-access/afs-over-http/

A client that cannot speak MCP can reach the same AFS operations over plain JSON-RPC at `/api/afs/rpc`. It is the same data plane and the same access tiers; only the envelope differs.

Use it when the caller is a script, a language without an MCP library, or a model that can issue an HTTP request but has no tool-calling harness.

## Call it

```bash
curl -s -X POST https://<host>/api/afs/rpc \
  -H 'Content-Type: application/json' \
  -d '{"type":"list","path":"/"}'
```

```json
{
  "ok": true,
  "data": [
    {
      "id": "instance",
      "path": "/instance",
      "summary": "DID-scoped persistent storage with CID-based content deduplication…",
      "meta": { "childrenCount": -1 }
    }
  ]
}
```

The request names an operation in `type` and its arguments alongside. Responses are wrapped in `{ "ok": …, "data": … }`.

No credential was sent in the request above; anonymous read works here exactly as it does on `/mcp`.

## Inspect a path before you read it

`stat` returns what a provider will actually accept, which saves a round of failed calls:

```bash
curl -s -X POST https://<host>/api/afs/rpc \
  -H 'Content-Type: application/json' \
  -d '{"type":"stat","path":"/packages"}'
```

```json
{
  "ok": true,
  "data": {
    "id": "arcblock",
    "path": "/packages",
    "meta": {
      "kind": "did-space:directory",
      "capabilities": ["list", "read", "stat", "search", "write", "delete", "exec", "explain"],
      "accessMode": "readonly",
      "projection": { "base": "arcblock" }
    }
  }
}
```

`capabilities` is what the provider implements. `accessMode` is what this caller gets. The two are separate: a provider can implement `write` while the path is `readonly` for you.

Read `capabilities` before making an operation part of your integration; a provider is not required to implement all of them. See [AFS](../../afs/core-contract/).

## Relationship to the MCP tools

| | `/mcp` | `/api/afs/rpc` |
|---|---|---|
| Envelope | MCP over streamable HTTP | JSON-RPC |
| Operations | `afs_*` tools, plus content tools when declared | AFS operations |
| Anonymous read | Yes | Yes |
| Writes | Credential required | Credential required |
| Discovery | `tools/list` | `stat` and `explain` on a path |

Both endpoints are listed in the host's [API catalog](../discovery-surfaces/#api-catalog), pointing at the same service description.

Prefer `/mcp` when your client supports it: the tool schemas tell an agent what the arguments are, which `stat` does not.

## Writes

Writes over this endpoint follow the same rules as `/mcp`: a credential is required, and the blocklet must have published the path to network clients. See [Access tiers](../access-tiers/).

The full operation set and its argument shapes belong to the [AFS](../../afs/) contract.

---

## Authorize a client

URL: https://www.arcblock.io/en/docs/agent-access/authorize-a-client/

A client that receives `401` with a `WWW-Authenticate` challenge has everything it needs to reach the authorization server. Every step is a plain `GET` or `POST` against the same host. Replace `<host>` with the blocklet's host.

| Step | Request | Result |
|---|---|---|
| 1 | `tools/call` a write tool, no credential | `401` + `WWW-Authenticate` carrying the metadata URL |
| 2 | `GET /.well-known/oauth-protected-resource` | Which authorization server protects this resource |
| 3 | `GET /.well-known/oauth-authorization-server` | Endpoints, grant types, PKCE method |
| 4 | `POST /.well-known/service/oauth/register` | A `client_id` for this client |
| 5 | Authorize, then exchange for a credential | `Authorization: Bearer blocklet-…` |

## Step 2: protected resource

```bash
curl -s https://<host>/.well-known/oauth-protected-resource
```

```json
{
  "resource": "https://<host>/mcp",
  "authorization_servers": ["https://<host>"]
}
```

The authorization server is the same host. A blocklet protects only its own resource and issues only its own credentials, so a client that talks to several blocklets registers and authorizes with each one separately.

## Step 3: authorization server metadata

```bash
curl -s https://<host>/.well-known/oauth-authorization-server
```

```json
{
  "issuer": "https://<host>",
  "authorization_endpoint": "https://<host>/.well-known/service/oauth/authorize",
  "registration_endpoint": "https://<host>/.well-known/service/oauth/register",
  "device_authorization_endpoint": "https://<host>/.well-known/service/oauth/device_authorization",
  "token_endpoint": "https://<host>/.well-known/service/oauth/token",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:device_code",
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}
```

`token_endpoint_auth_methods_supported` is `none`, so a client authenticates the token request with its PKCE verifier rather than a client secret. `scopes_supported` has one entry, so there is no narrower or broader scope to choose between.

## Step 4: register the client

A client obtains its `client_id` by registering itself. No pre-shared identifier is handed out.

```bash
curl -s -X POST https://<host>/.well-known/service/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "my agent",
    "redirect_uris": ["http://127.0.0.1:3118/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'
```

```json
{
  "client_id": "b665f46e-8fb5-4bf9-bd32-53df5b35f7f5",
  "redirect_uris": ["http://127.0.0.1:3118/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

The response echoes the registration, not just the identifier. Clients validate this and reject a reply that omits fields they sent.

**Register once and keep the `client_id`.** Registration is rate limited per source address, and a registration never used in a completed authorization is swept after seven days.

### Redirect URIs

A client running on the user's machine listens on a port chosen at run time, so register the exact `redirect_uris` this session will use rather than expecting a fixed value to be pre-approved. Loopback addresses, `https` URLs, and private-use schemes are accepted; anything else is rejected. See [Errors](../errors/#authorization-flow-failures).

## Step 5: obtain the credential

Two grants lead to the same credential. Your tool usually picks one for you, see [Connect your tool](../clients/).

| Your client | Grant |
|---|---|
| Can open a browser and listen on a local port, as most MCP clients do | `authorization_code` with PKCE, using `authorization_endpoint` then `token_endpoint` |
| Cannot: a CLI, CI job, or headless agent | The device grant, see [Credentials without a browser](../device-grant/) |

Both end at the same `token_endpoint` and return the same credential shape.

### What the credential is

The token endpoint returns a bearer token that is also an **access key**:

```json
{
  "access_token": "blocklet-zEJYCdC9awCqxEPLhqreFbwXjqU6Y2BHvKVQAx6kMZfRh",
  "token_type": "Bearer",
  "scope": "mcp"
}
```

Three things follow from that response, and each matters:

- **The `blocklet-` prefix is how the runtime recognises it.** OAuth token and access key are not two mechanisms; they are one credential with one prefix.
- **It carries the role the person picked** on the consent screen (`owner`, `admin`, `member`, or `guest`), scoped to this blocklet instance. See [Access tiers](../access-tiers/#roles).
- **The device grant returns no `expires_in` and no `refresh_token`.** The authorization server advertises `refresh_token` as a supported grant, but the device flow does not hand one back.

## Use it

Send it as a bearer token on `/mcp`:

```bash
curl -s -X POST https://<host>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer blocklet-…' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

The `401` is gone: the same `tools/call` that was refused before now reaches the tool.

## What the credential leaves closed

Reaching the tool is not the same as the operation succeeding. An authenticated write can still come back like this, `200` at the transport layer but refused inside:

```json
{
  "result": {
    "content": [{
      "type": "text",
      "text": "AFS_FORBIDDEN: Forbidden at /instance/notes.txt: network clients cannot write base paths; use a resolver overlay or internal code"
    }],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 3
}
```

An owner-role credential gets the same refusal. Writing from the network is not something a credential turns on. The blocklet must have declared that path open to network clients, via a resolver overlay or code running inside it.

If your agent must write, that is a decision for whoever owns the blocklet. Read [Access tiers](../access-tiers/#gate-3-the-path-policy) before designing around it.

---

## Connect your tool

URL: https://www.arcblock.io/en/docs/agent-access/clients/

Point your tool at `https://<host>/mcp`, where `<host>` is the domain the blocklet is served at. Adding it needs no credential; signing in takes one browser click and is only needed to go past what the blocklet publishes openly.

## Claude Code

Add the server:

```bash
claude mcp add --transport http arc https://<host>/mcp
```

Check it:

```bash
claude mcp list
```

```text
arc: https://<host>/mcp (HTTP) - ✔ Connected
```

You can now use the read tools. To go further, sign in:

```bash
claude mcp login arc
```

Your browser opens a consent screen showing which tool is asking, the verified domain it came from, the account it will act as, and the local port your credential will be delivered to. Pick an **access level** and choose **Authorize**. The command completes on its own.

Run it from a real terminal. In a pipe or a CI job it stops with `stdin isn't a terminal`.

`claude mcp logout arc` clears the credential. `claude mcp remove arc` removes the server.

## Codex CLI

One command adds the server and signs you in:

```bash
codex mcp add arc --url https://<host>/mcp
```

It prints the authorization URL, opens your browser for the same consent screen, and finishes:

```text
Successfully logged in.
```

Check it:

```bash
codex mcp list
```

```text
Name  Url                       Bearer Token Env Var  Status   Auth
arc   https://<host>/mcp        -                     enabled  OAuth
```

`codex mcp login arc` signs in again later; `codex mcp logout arc` clears it.

## grok

Not supported yet. `grok mcp add arc -t http https://<host>/mcp` writes the entry, but the connection fails during the handshake:

```text
✗ handshake failed (… Auth error: OAuth authorization required, when send initialize request)
```

grok asks for authorization before the handshake that would tell it none is needed, and `grok mcp` has no `login` command to complete one. Use the header method below instead.

## Any other tool

If your tool can send a custom header, [obtain a credential without a browser](../device-grant/) and pass it directly:

```bash
claude mcp add --transport http arc https://<host>/mcp \
  --header "Authorization: Bearer blocklet-…"
```

This works with any client that supports headers, and is the way to connect from a server or a CI job where no browser is available.

## After you are connected

- Signing in raises what you are allowed to ask for. It does not open write access on its own: a blocklet has to publish a path to network clients before anyone can write to it. See [Access tiers](../access-tiers/).
- Which tools you see depends on the blocklet, not on your credential. See [Tools](../tools/).
- A credential belongs to one blocklet. Connect to a second one and you sign in again.

---

## Connect a client

URL: https://www.arcblock.io/en/docs/agent-access/connect-a-client/

Connect an MCP client to a blocklet by giving it the host URL plus `/mcp`.

**`<host>` is the domain the blocklet is served at**, the same one you would open in a browser. If you are unsure you have the right one, `GET https://<host>/.well-known/mcp.json` and check its `url` field: it echoes the endpoint the runtime believes it is serving.

```bash
claude mcp add --transport http arc https://<host>/mcp
```

No header and no client id are needed to connect. The endpoint accepts anonymous requests and answers the read tools; a credential is only required once you call a write tool.

For the exact commands for Claude Code and Codex CLI, see [Connect your tool](../clients/).

## Confirm it without a client

The endpoint is plain HTTP, so `curl` is enough to check a host before you wire up an agent.

```bash
curl -s -X POST https://<host>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A blocklet that declares no content collections answers with eight tools:

```text
afs_read  afs_list  afs_write  afs_delete  afs_search  afs_exec  afs_stat  afs_explain
```

A blocklet that declares content collections answers with those eight plus three more:

```text
search_content  list_content  get_content
```

Which set you get depends on the blocklet's own declaration, not on your credential. See [Tools](../tools/).

## `initialize` is not required

The request above sends `tools/list` directly, with no preceding `initialize`, and returns `200`.

The endpoint is stateless. It does not issue an `mcp-session-id`, so there is no session for a client to hold, lose, or resynchronise. A client can send a stale session id and the request still succeeds; a runtime restart does not invalidate anything on the client side.

This matters for long-lived agents: there is no reconnect handshake to implement.

## What anonymous access gives you

The handshake, the three list methods, and the read tools. Write, delete, and exec return `401` with a challenge, and so does any method not on the list. The rule is fail-closed.

Whether an allowed read actually returns data is a separate question, decided by what the blocklet declared. Both rules are set out in [Access tiers](../access-tiers/).

## When you need to write

Calling a write tool without a credential returns the challenge that starts authorization:

```bash
curl -s -i -X POST https://<host>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"afs_write","arguments":{"path":"/tmp/x","content":"x"}}}'
```

```text
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource"

{"error":"Unauthorized"}
```

Follow that URL to continue. See [Authorize a client](../authorize-a-client/).

## Connecting a stdio-only client

Clients that speak MCP over stdio and cannot open an HTTP transport need a bridge. Use [`arc mcp`](../../arc-cli/command-reference-mcp/), which bridges stdio to a running local daemon.

The bridge is a compatibility path for those clients. If your client supports streamable HTTP, connect to `/mcp` directly and skip it.

## Local runtime

Against a local Node runtime, a request from the same machine is a verified socket peer and is granted operator access, so write tools answer without a credential. That is the loopback tier; it does not exist over the network and it is not how a deployed blocklet behaves. Use a remote host to exercise the anonymous and authenticated paths.

---

## Declare what agents see

URL: https://www.arcblock.io/en/docs/agent-access/declare-what-agents-see/

The content tools, the per-collection `llms` shards, the sitemap, and the web pages are all projections of one declaration in the blocklet manifest. A collection appears on a surface when, and only when, the declaration names that surface.

This page covers the parts of that declaration an agent can observe. For the manifest as a whole, see [Blocklets](../../blocklets/).

## The shape

```yaml
collections:
  docs:
    scope: /packages
    indexable:
      - "content/docs/**/content.md"
      - "content/docs/**/content.zh.md"
    readRole: guest
    defaultLocale: en
    fields:
      nav-group: $.nav-group
    summary:
      - $.name
      - $.summary
    faces:
      web: true
      sitemap: true
      llms: true
      mcp: [search, list, get]
```

| Key | Decides |
|---|---|
| `indexable` | Which files belong to the collection |
| `readRole` | Whether a caller without a credential can read it |
| `fields` | Which front matter becomes a filter on the content tools |
| `summary` | Which front matter appears in a result, and in what order |
| `faces` | Which surfaces the collection reaches |

## Faces are opt-in and fail-closed

Omitting `faces` closes every surface. Omitting `readRole` means the collection is not anonymous. Neither defaults to open, so a collection cannot reach an agent by accident.

`faces.mcp` takes the verbs to expose. `[search, list, get]` maps to `search_content`, `list_content`, and `get_content` for that collection.

## Different collections can reach different surfaces

Faces are chosen per collection, so one blocklet can publish a collection to the web while keeping it off the agent surfaces entirely.

A worked example from a site with five collections:

| Collection | `web` | `sitemap` | `llms` | `mcp` |
|---|---|---|---|---|
| `docs`, `glossary`, `products` | Yes | Yes | Yes | Yes |
| `articles` | Yes | Yes | **No** | Yes |
| `events` | Yes | Yes | **No** | **No** |

The reasoning behind that split is a judgement about what is worth an agent's tokens, not a technical limit: reference material earns a place in the text surfaces, a large archive of posts does not, and a list of past events serves neither.

## The declaration is observable

You do not need the manifest to see the result. Two checks from outside:

The collection list appears in each content tool's description and in its `collection` parameter, so `tools/list` shows exactly which collections have an `mcp` face:

```text
Search published content by free text and optional facets. Collections: articles; docs; glossary; products
```

A collection with no `mcp` face is absent from that list; in the example above, `events`.

The `llms` face is visible the same way. A collection with the face has a shard; one without it returns `404`:

```bash
curl -s -o /dev/null -w '%{http_code}\n' https://<host>/llms-docs.txt      # 200
curl -s -o /dev/null -w '%{http_code}\n' https://<host>/llms-articles.txt  # 404
```

## Anonymous reads

`readRole: guest` is what lets a caller without a credential read the collection through the content tools. Without it the tools still register, but that collection is not available to an anonymous caller.

The tool names themselves are on the anonymous allowlist either way; see [Tools](../tools/#content-tools).

---

## Credentials without a browser

URL: https://www.arcblock.io/en/docs/agent-access/device-grant/

The authorization code grant needs a browser to redirect to and a local port to redirect back to. A client with neither, such as a CLI on a server, a CI job, or an agent on a headless machine, uses the device grant instead.

It produces the same credential as the browser grant: a `blocklet-` prefixed **access key**, sent as a bearer token. Replace `<host>` with the blocklet's host.

## 1. Start a device authorization

```bash
curl -s -X POST https://<host>/.well-known/service/oauth/device_authorization \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<client_id>&scope=mcp'
```

```json
{
  "device_code": "bc0cedc2-899f-49da-b413-213f31c4aae8",
  "user_code": "BZVR-ZQZQ",
  "verification_uri": "https://<host>/.well-known/service/gen-access-key",
  "verification_uri_complete": "https://<host>/.well-known/service/gen-access-key?__token__=bc0cedc2-…",
  "expires_in": 300,
  "interval": 5
}
```

Obtain the `client_id` by registering first. See [Authorize a client](../authorize-a-client/#step-4-register-the-client).

| Field | Use |
|---|---|
| `user_code` | Show it to the person. The alphabet excludes vowels and ambiguous characters, so it can be read aloud |
| `verification_uri` | Where the person goes to approve |
| `verification_uri_complete` | The same page with the request pre-filled; use it when you can render a link or a QR code |
| `expires_in` | Seconds until **this request** expires. `300` above. It does not describe the credential |
| `interval` | Minimum seconds between polls. `5` above |

## 2. The person approves

Opening `verification_uri_complete` shows a consent screen naming the requesting application and the account, with an **access level** selector. It offers `owner` (the default), `admin`, `member`, and `guest`; the credential carries whichever is chosen.

The role is scoped to this blocklet instance and is an upper bound, not a grant. See [Access tiers](../access-tiers/#roles).

## 3. Poll for the credential

Poll the token endpoint with the device code grant until the request is approved or expires. Respect `interval`; polling faster is what the field exists to prevent.

```bash
curl -s -X POST https://<host>/.well-known/service/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  --data-urlencode 'device_code=bc0cedc2-899f-49da-b413-213f31c4aae8' \
  --data-urlencode 'client_id=<client_id>'
```

Once approved:

```json
{
  "access_token": "blocklet-zEJYCdC9awCqxEPLhqreFbwXjqU6Y2BHvKVQAx6kMZfRh",
  "token_type": "Bearer",
  "scope": "mcp"
}
```

Before approval, and after the five-minute window closes, the same request answers `400`:

```json
{"error":"invalid_grant","error_description":"Invalid or expired device_code"}
```

`invalid_grant` most often means the window expired rather than that the code was wrong. Restart from step 1.

**No `expires_in`, no `refresh_token`.** The authorization server advertises `refresh_token` as a supported grant, but this flow does not return one. Treat the access key as the credential you keep.

## 4. Use it

```bash
curl -s -X POST https://<host>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer blocklet-…' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

The credential clears the credential gate. It does not clear the path policy: an authenticated write can still return `AFS_FORBIDDEN`. See [Authorize a client](../authorize-a-client/#what-the-credential-leaves-closed).

## Which grant to use

| Situation | Grant |
|---|---|
| Client can open a browser and listen on a local port | `authorization_code` with PKCE. See [Authorize a client](../authorize-a-client/) |
| Client has no browser, or the person approving is on a different device | Device grant, this page |

MCP clients generally implement the authorization code grant, not the device grant. Use the device grant for your own tooling rather than expecting a third-party MCP client to discover and drive it.

---

## Discovery surfaces

URL: https://www.arcblock.io/en/docs/agent-access/discovery-surfaces/

A blocklet publishes four discovery **documents**. All are anonymous `GET` requests and none requires a prior connection to `/mcp`. Replace `<host>` with the blocklet's host.

The server card is reachable at three paths that return the same document, so [Endpoints](../endpoints/) lists more rows than there are documents. The authorization endpoints listed there are a different surface: they are named *by* these documents, not among them.

| Path | Answers |
|---|---|
| `/.well-known/mcp.json` | What this MCP server is, where it is, and which tools need a credential |
| `/.well-known/oauth-protected-resource` | Which authorization server protects `/mcp` |
| `/.well-known/oauth-authorization-server` | Endpoints, grant types, PKCE method |
| `/.well-known/api-catalog` | Which service descriptions exist on this host |

## Server card

```bash
curl -s https://<host>/.well-known/mcp.json
```

```json
{
  "name": "arc",
  "description": "AFS MCP server — agents discover published content via content tools and generic afs_* tools. Anonymous public read; authenticated writes via DID-Connect.",
  "url": "https://<host>/mcp",
  "transport": "streamable-http",
  "authentication": {
    "required": false,
    "schemes": ["bearer"],
    "oauth_protected_resource": "https://<host>/.well-known/oauth-protected-resource",
    "note": "Anonymous callers may tools/list and generic public-read afs_* tools; content tools (when declared without readRole:guest) and write/delete/exec require DID-Connect session."
  },
  "tools": {
    "anonymous": ["afs_read", "afs_list", "afs_search", "afs_stat", "afs_explain"],
    "authenticated": ["afs_write", "afs_delete", "afs_exec"]
  }
}
```

`authentication.required` is `false` because connecting and reading do not require a credential. The `tools` object states which names change that.

The example above is from a blocklet that declares no content collections. One that declares them lists `search_content`, `list_content`, and `get_content` under `tools.anonymous` as well.

The server card is not part of the MCP protocol, so MCP clients do not read it during a connection. Use it when you want to inspect a host, build a directory, or decide whether to connect at all, not as the mechanism that triggers authorization. That mechanism is the `401` challenge described in [Authorize a client](../authorize-a-client/).

## Protected resource

```bash
curl -s https://<host>/.well-known/oauth-protected-resource
```

```json
{
  "resource": "https://<host>/mcp",
  "authorization_servers": ["https://<host>"]
}
```

This is the document the `WWW-Authenticate` challenge points at. It always names the same host as its own authorization server.

## Authorization server metadata

Endpoints and grant types are listed in [Authorize a client](../authorize-a-client/#step-3-authorization-server-metadata). The document is served from the blocklet host, but the endpoints it names are implemented by the connect service; see [Endpoints](../endpoints/).

## API catalog

```bash
curl -s https://<host>/.well-known/api-catalog
```

```json
{
  "linkset": [
    {
      "anchor": "https://<host>/mcp",
      "https://www.iana.org/assignments/link-relations/link-relations.xhtml#service-desc": [
        { "href": "https://<host>/.well-known/mcp.json" }
      ]
    },
    {
      "anchor": "https://<host>/api/afs/rpc",
      "https://www.iana.org/assignments/link-relations/link-relations.xhtml#service-desc": [
        { "href": "https://<host>/.well-known/mcp.json" }
      ]
    }
  ]
}
```

Two anchors are listed: the MCP endpoint, and the AFS RPC endpoint for clients that do not speak MCP. Both point at the same service description.

## Known drift

The server card's `authentication.note` names a DID-Connect session as the way to authenticate writes. A bearer token obtained through the authorization server is also accepted, and the `schemes` field already says `bearer`. Treat `schemes` and the [access tiers](../access-tiers/) as authoritative and the prose note as incomplete.

---

## Endpoints

URL: https://www.arcblock.io/en/docs/agent-access/endpoints/

All paths below are relative to a blocklet host. Replace `<host>` with that host.

## Data plane

| Path | Method | Credential | Notes |
|---|---|---|---|
| `/mcp` | `POST` | Optional | MCP over streamable HTTP. Stateless: no `mcp-session-id` is issued, and `initialize` is not required before other methods |
| `/api/afs/rpc` | `POST` | Optional | AFS operations for clients that do not speak MCP |

Anonymous requests to `/mcp` may use the handshake methods, the list methods, and the read tools. Anything else returns `401` with a `WWW-Authenticate` header naming the protected-resource document.

## Discovery

All four are `GET` and none requires a credential.

| Path | Serves |
|---|---|
| `/.well-known/mcp.json` | Server card: name, URL, transport, authentication summary, tool split |
| `/.well-known/mcp` | Same document |
| `/.well-known/mcp/server-card.json` | Same document |
| `/.well-known/oauth-protected-resource` | RFC 9728 protected-resource metadata |
| `/.well-known/oauth-authorization-server` | RFC 8414 authorization server metadata |
| `/.well-known/api-catalog` | RFC 9727 linkset naming the service descriptions on this host |

The three server-card paths are aliases for one document. Use whichever your client already looks for.

## Authorization

These paths are named by the authorization server metadata and served by the connect service running behind the same host. To an agent they are ordinary paths on the blocklet host.

| Path | Method | Credential | Purpose |
|---|---|---|---|
| `/.well-known/service/oauth/register` | `POST` | None | Dynamic client registration. Returns a `client_id` and echoes the registration |
| `/.well-known/service/oauth/authorize` | `GET`, `POST` | User session | Authorization request and consent |
| `/.well-known/service/oauth/token` | `POST` | PKCE verifier | Token exchange and refresh |
| `/.well-known/service/oauth/device_authorization` | `POST` | None | Device flow, for clients that cannot open a browser |
| `/.well-known/service/gen-access-key` | `GET` | User session | Browser page that completes an authorization in a user's session |

Grant types advertised: `authorization_code`, `refresh_token`, and the device code grant. PKCE method: `S256`. Token endpoint authentication: `none`.

## Response shapes

| Request | Result |
|---|---|
| `POST /mcp` `tools/list`, anonymous, no `initialize` | `200`; eight tools, or eleven when the blocklet declares content collections |
| `POST /mcp` `tools/call afs_write`, anonymous | `401`, body `{"error":"Unauthorized"}`, header `www-authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource"` |
| `GET /.well-known/oauth-protected-resource` | `200`; `resource` is `https://<host>/mcp`, `authorization_servers` is `["https://<host>"]` |
| `GET /.well-known/oauth-authorization-server` | `200`; `issuer` equals the host |
| `POST /.well-known/service/oauth/register` | `201`; `client_id` plus the echoed registration fields |
| `POST /.well-known/service/oauth/device_authorization` | `200`; `device_code`, `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in: 300`, `interval: 5` |
| `POST /.well-known/service/oauth/token` (device grant, approved) | `200`; `{"access_token":"blocklet-…","token_type":"Bearer","scope":"mcp"}`, with no `expires_in` and no `refresh_token` |
| `POST /mcp` `tools/call afs_write`, owner credential, undeclared path | `200` with `isError` and `AFS_FORBIDDEN` |

For every failure shape and how to tell them apart, see [Errors](../errors/).

## Text surfaces

| Path | Method | Credential | Serves |
|---|---|---|---|
| `/llms.txt` | `GET` | None | Pointer document naming the agent surfaces, plus a section per collection |
| `/llms-<collection>.txt` | `GET` | None | Index for one collection. `404` when the collection declared no `llms` face |
| `/llms-<collection>-full.txt` | `GET` | None | Full text for one collection |
| `/llms-full.txt` | `GET` | None | Full text for every collection |

See [llms.txt](../llms-txt/).

## Compatibility path

| Path | Notes |
|---|---|
| `arc mcp` | Bridges stdio to a running local daemon, for clients that cannot use HTTP. See [`arc mcp`](../../arc-cli/command-reference-mcp/) |

---

## Errors

URL: https://www.arcblock.io/en/docs/agent-access/errors/

Failures arrive in two shapes, and confusing them wastes time.

| Shape | Meaning | Where it is decided |
|---|---|---|
| HTTP `4xx` with no JSON-RPC result | The call never reached a tool | Method allowlist or credential, [gates 1 and 2](../access-tiers/) |
| HTTP `200` with `"isError": true` | The call reached the tool; the operation failed | Path policy or provider, [gates 3 and 4](../access-tiers/) |

A `200` is not success. Check `result.isError` on every `tools/call`.

## Transport failures

### `401` on `/mcp`

```http
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource"

{"error":"Unauthorized"}
```

The body is identical for every cause. Three produce it:

| Cause | How to tell | Fix |
|---|---|---|
| Anonymous call to a write tool | You sent no `Authorization` header | Follow the challenge: [Authorize a client](../authorize-a-client/) |
| Method not on the anonymous allowlist | The method is not `initialize` / `tools/list` / `resources/list` / `prompts/list` / an allowed `tools/call` | Authenticate, or use an allowed method |
| Credential rejected | You sent a header but it is malformed, unknown, or issued by a different blocklet | Obtain a credential from **this** host. Credentials are instance-bound |

An unknown tool name also returns `401` when you are anonymous, not a "no such tool" error. The allowlist is checked before the tool is looked up. If a tool name you saw in `tools/list` returns `401`, it is a privileged tool, not a typo.

## Authorization-flow failures

All are `400` with an RFC 6749 error code.

| Request | Response |
|---|---|
| `POST /oauth/register` without `redirect_uris` | `{"error":"invalid_redirect_uri","error_description":"Missing redirect_uris"}` |
| `POST /oauth/register` with an unsupported scheme | `{"error":"invalid_redirect_uri","error_description":"redirect_uris must be https, RFC 8252 loopback http, or a private-use scheme …"}` |
| `POST /oauth/token` with an unknown or expired `device_code` | `{"error":"invalid_grant","error_description":"Invalid or expired device_code"}` |
| `POST /oauth/token` with any other grant | `{"error":"unsupported_grant_type","error_description":"Only device_code, authorization_code, and refresh_token grants are supported"}` |

Two more you should expect but that are not shown above:

- **Registration is rate limited per source address.** A client that re-registers on every start will eventually be throttled. Register once and keep the `client_id`.
- **A registration that is never used in a completed authorization is swept after seven days.** A long-lived client that registered but never got consent must register again.

`invalid_grant` on a device code most often means the five-minute window expired, not that the code was wrong. Restart the flow.

## In-call failures

These arrive as `200` with `isError`. The text is a code followed by the path and an explanation.

### `AFS_FORBIDDEN`

```text
AFS_FORBIDDEN: Forbidden at /instance/notes.txt: network clients cannot write base paths;
use a resolver overlay or internal code
```

The blocklet has not opened that path to network clients. Variants:

| Operation | Text |
|---|---|
| write | `cannot write base paths; use a resolver overlay or internal code` |
| read | `cannot read base paths; declare a networkRead rule or use an overlay` |
| list | `cannot list base paths; declare a networkRead rule or use an overlay` |
| stat | `cannot stat base paths; declare a networkRead rule or use an overlay` |

**A credential does not fix this.** An owner-role caller gets the same refusal. Only the blocklet's own declaration changes it. See [Access tiers, gate 3](../access-tiers/#gate-3-the-path-policy).

### `AFS_NOT_FOUND`

```text
AFS_NOT_FOUND: Path not found: /new
```

The path does not exist **on this host**. Paths are host-scoped, so a path that resolves on one blocklet can be absent on another even when both mount the same provider name. Confirm with `afs_list` on the parent before assuming the provider is missing.

## Diagnosing in order

Work down the gates; each step rules out everything above it.

1. **Does anonymous `tools/list` return `200`?** No → the host is not reachable or is not an ARC blocklet. Check the URL and `/.well-known/mcp.json`.
2. **Does the tool appear in `tools/list`?** No → for content tools, the blocklet declared no collections; see [Declare what agents see](../declare-what-agents-see/).
3. **Does calling it return `401`?** Yes → gate 1 or 2. Follow the `WWW-Authenticate` challenge.
4. **Does it return `200` with `AFS_FORBIDDEN`?** Yes → gate 3. The credential is fine; the path is closed to the network.
5. **Does `afs_stat` show the operation in `capabilities`?** No → gate 4. The provider does not implement it.

## Refreshing a credential

The device grant returns a credential with no expiry and no refresh token, so there is nothing to refresh. If a credential stops working, sign in again with your tool, see [Connect your tool](../clients/).

---

## llms.txt

URL: https://www.arcblock.io/en/docs/agent-access/llms-txt/

`/llms.txt` is a pointer. It names the endpoints, tools, and collections an agent can use on this host, and links to per-collection index shards. It is not a copy of the site.

An agent that fetches it learns where to connect in roughly a kilobyte, instead of reading the site as text.

## Fetch it

```bash
curl -s https://<host>/llms.txt
```

```text
# ArcBlock

> ArcBlock builds decentralized identity, user-owned data, Blocklet
> infrastructure, and AI-native application systems.

## For agents

- MCP (Streamable HTTP): https://<host>/mcp
- Server card: https://<host>/.well-known/mcp.json
- AFS over HTTP (JSON-RPC): POST https://<host>/api/afs/rpc
- Tools: search_content, list_content, get_content
- Collections available to agents: articles, docs, glossary, products
- Anonymous public read; writes require DID-Connect auth

Locales: en, zh, ja, zh-TW (base: en). …

Full-text version (all collections, never truncated): https://<host>/llms-full.txt

## Docs (1268 items)

Index: https://<host>/llms-docs.txt
Full text: https://<host>/llms-docs-full.txt
```

The document above is 1,142 bytes. The `For agents` block is the part that matters: it hands over the MCP endpoint, the server card, and the JSON-RPC endpoint, so a client that can do better than reading text does not have to read text.

## Shards

Each collection that declared an `llms` face gets an index shard and a full-text shard.

| Path | Contains |
|---|---|
| `/llms.txt` | The pointer above, plus a section per collection with item counts and shard links |
| `/llms-<collection>.txt` | Index for one collection |
| `/llms-<collection>-full.txt` | Full text for one collection |
| `/llms-full.txt` | Full text for every collection |

A collection without the face has no shard:

```bash
curl -s -o /dev/null -w '%{http_code} %{size_download}\n' https://<host>/llms-docs.txt      # 200 154869
curl -s -o /dev/null -w '%{http_code} %{size_download}\n' https://<host>/llms-articles.txt  # 404 9
```

Which collections have the face is a per-blocklet decision; see [Declare what agents see](../declare-what-agents-see/).

## Sizes are not symmetric

On a site with about 1,300 documents the pointer is around 1 KB, the docs index shard is around 150 KB, and `/llms-full.txt` is several megabytes.

The shards exist so an agent can take the one collection it needs. `llms-full.txt` is there for completeness, not as the intended entry point. Fetching it costs more context than connecting over MCP and asking a question.

## When to use which

| Situation | Use |
|---|---|
| The client speaks MCP | `/mcp`. Query instead of ingesting |
| The client can issue HTTP but has no tool harness | [`/api/afs/rpc`](../afs-over-http/) |
| The client can only fetch text | `/llms.txt`, then the one shard it needs |

`llms.txt` names the first two, so an agent that starts at the text surface can move up to a better one.

---

## Agent access

URL: https://www.arcblock.io/en/docs/agent-access/overview/

A blocklet running on ARC exposes an MCP endpoint at `/mcp` and a set of discovery documents under `/.well-known/`. The runtime provides them; a blocklet does not opt in and cannot be deployed without them.

An agent that knows only the host URL can therefore reach the endpoint and list the available tools before any credential exists. What it can then *read* is decided by the blocklet, not by the runtime.

## Three ways to connect

| Client can | Endpoint |
|---|---|
| Speak MCP | `POST /mcp`, streamable HTTP, stateless |
| Issue HTTP but has no tool-calling harness | `POST /api/afs/rpc`, the same operations as JSON-RPC |
| Only fetch text | `GET /llms.txt`, a pointer that names the other two |

All three serve the same data. Prefer `/mcp` when your client supports it.

## Check the baseline first

Anonymous `tools/list` must work on every blocklet: no credential, no `initialize`, no session.

```bash
curl -s -X POST https://<host>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

It answers with at least the eight generic AFS tools. If this fails, the problem is the host or the transport, not access. → [Connect a client](../connect-a-client/)

## Something already failed?

| What you got | What it means | Where |
|---|---|---|
| `401` with `WWW-Authenticate` | The method is not anonymous-safe, or your credential was rejected | [Errors](../errors/) · [Authorize a client](../authorize-a-client/) |
| `200` with `"isError": true` and `AFS_FORBIDDEN` | The call reached the tool. The blocklet has not opened that path to network clients | [Access tiers](../access-tiers/) |
| Writes still refused with an owner credential | Expected. A credential is not a write switch | [Access tiers](../access-tiers/) |
| `tools/list` returns only the eight AFS tools | The blocklet declares no content collections | [Tools](../tools/) |
| Not sure you have the right host | `GET /.well-known/mcp.json` and check its `url` field | [Discovery surfaces](../discovery-surfaces/) |

**A `200` is not success.** Check `result.isError` on every `tools/call`.

## What decides whether a call succeeds

Four independent gates, decided by three different parties: the runtime, the blocklet, and the provider. A credential is an answer to the runtime, so it clears one gate and leaves the other three exactly where they were.

Gate 3 — what the blocklet declared for that path — is the one most agents hit, and no credential bypasses it, including an owner-role credential.

→ [Access tiers](../access-tiers/) for all four gates and why they are separate

## Publishing a tool is not the same as allowing it

Anonymous `tools/list` publishes the write tools alongside the read tools. Calling one without a credential returns `401` with a challenge.

This is deliberate. A well-behaved MCP client only calls tools that were advertised to it, so hiding the write tools would mean the client never issues the request that produces the challenge. A challenge is what starts a standard authorization flow. Publishing the tools is what makes authorization discoverable.

## Each blocklet issues its own credentials

The protected-resource document on a host names that same host as its authorization server. A credential obtained from one blocklet does not open another; it carries the instance it was issued for, and the runtime compares that instance on every call.

There is no cross-blocklet credential.

## Where this board sits

[AFS](../../afs/) defines the paths, providers, and capability contract. This board is about **reaching that contract from outside**: which protocol surfaces exist on a host, how a client authenticates to them, and what a blocklet has to declare before an external caller sees anything.

If your question is "what does `afs_read` guarantee", read AFS. If it is "how does my agent get to call it", read on here.

## Where to go next

| | |
|---|---|
| **Connect** | [Connect a client](../connect-a-client/) · [Claude Code and Codex CLI](../clients/) |
| **Authenticate** | [Authorize a client](../authorize-a-client/) · [without a browser](../device-grant/) |
| **Look something up** | [Errors](../errors/) · [Endpoints](../endpoints/) · [Understand the model](../understand/) |

---

## Tools

URL: https://www.arcblock.io/en/docs/agent-access/tools/

A blocklet publishes two kinds of MCP tools. The generic AFS tools are always registered. The content tools are registered only when the blocklet declares content collections, and their input schemas name the collections it declared.

Both kinds run over the same data plane. The content tools are wrappers over AFS search, list, and read. There is no second store behind them.

## Generic AFS tools

| Tool | Required | Other parameters | Anonymous |
|---|---|---|---|
| `afs_read` | none | `path`, `entries`, `startLine`, `endLine` | Yes |
| `afs_list` | `path` | `depth`, `pattern`, `limit` | Yes |
| `afs_search` | `path`, `query` | `pattern`, `limit`, `explain` | Yes |
| `afs_stat` | `path` | none | Yes |
| `afs_explain` | `path` | none | Yes |
| `afs_write` | none | `path`, `content`, `mode`, `patches`, `ifMatch`, `entries` | No |
| `afs_delete` | none | `path`, `recursive`, `ifMatch`, `entries` | No |
| `afs_exec` | `path` | `args` | No |

`afs_read`, `afs_write`, and `afs_delete` show no required field because they accept **either** a single `path` **or** an `entries` array; one of the two is mandatory. Batch the array rather than looping single calls; `afs_read` accepts up to 16 entries per call.

`afs_exec` runs a declared action. Discover the available actions and their input schemas by listing `{path}/.actions`.

For what these paths and operations mean, and which operations a given provider actually implements, see [AFS](../../afs/).

A tool being listed and callable does not mean it will succeed on a given path: the blocklet's path policy is checked inside the call. See [Access tiers](../access-tiers/#gate-3-the-path-policy).

## Content tools

| Tool | Required | Other parameters |
|---|---|---|
| `search_content` | `collection`, `query` | `filters`, `locale`, `limit` |
| `list_content` | `collection` | `filters`, `locale`, `limit` |
| `get_content` | `collection`, `id` | `locale` |

These three appear only when the blocklet declares collections. A blocklet with no declaration registers none of them. The gate is fail-closed, so a partial or empty declaration does not produce a tool with an empty collection list.

The declared collection names are written into each tool's description and into the `collection` parameter, so a client sees them in `tools/list` without probing. A blocklet that declares four collections produces descriptions ending in a list of those four names.

Whether they are callable anonymously depends on the read role the blocklet declared for the collection. The tool names themselves are on the anonymous allowlist; the collections visible inside them are decided at registration time.

## Which set a host returns

`tools/list` returns eight tools from a blocklet with no declared collections, and eleven from a blocklet that declares them. The difference is the blocklet's own declaration, not the caller's credential: an anonymous client and an authenticated client see the same list.

What changes with a credential is which of those tools answer. See [Connect a client](../connect-a-client/#what-anonymous-access-gives-you).

## Declaring collections

The declaration lives in the blocklet's own manifest, alongside the rest of its capabilities. That surface is documented with the manifest, not here; see [Blocklets](../../blocklets/).

---

## Understand agent access

URL: https://www.arcblock.io/en/docs/agent-access/understand/

[Connect a client](../connect-a-client/) and [Authorize a client](../authorize-a-client/) are enough to get an agent talking to a blocklet. This section explains why the results look the way they do, so you can predict them instead of probing.

Three questions organise it.

## What decides whether a call succeeds

Four independent gates: the method allowlist, the credential, the path policy, and the provider's capabilities. Most surprises come from assuming a credential clears all four. It clears one.

→ [Access tiers](../access-tiers/)

## What a blocklet chooses to expose

An ARC blocklet does not expose its data because it is running; it exposes what its manifest declares. The same declaration drives the MCP content tools, the `llms` shards, the sitemap, and the web pages. Two blocklets on the same runtime can answer very differently.

→ [Tools](../tools/) for what is callable · [Declare what agents see](../declare-what-agents-see/) for what drives it

## Which surface to use

There are three ways in, meant for clients of different capability. They serve the same data.

| Client can | Use | Page |
|---|---|---|
| Speak MCP | `/mcp` | [Discovery surfaces](../discovery-surfaces/) for how to find it |
| Issue HTTP, but has no tool-calling harness | `/api/afs/rpc` | [AFS over HTTP](../afs-over-http/) |
| Only fetch text | `/llms.txt` and its shards | [llms.txt](../llms-txt/) |

The text surface names the other two, so an agent that starts there can move up to a better one.

## Reading order

If you are new to this board, read [Access tiers](../access-tiers/) first, because every other page in this section refers to its four gates. The rest can be read in any order.

---

## agent-access/visuals

URL: https://www.arcblock.io/en/docs/agent-access/visuals/

---

## AIGNE CLI

URL: https://www.arcblock.io/en/docs/aigne-cli/

---

## Built-in Apps

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-built-in-apps-cdbd13/

AIGNE CLI comes with pre-packaged applications that offer specialized, out-of-the-box functionality. These apps are complete AIGNE projects that you can execute directly, without needing to initialize a local project first.

When you invoke a built-in app for the first time, the CLI automatically fetches its package from the npm registry, installs it into a local cache (`~/.aigne/`), and then runs it. Subsequent runs use the cached version for faster startup, with periodic checks for new updates to ensure you have the latest features.

## Available Apps

Here are the currently available built-in applications:

| Command  | Aliases  | Description  |
|---|---|---|
| `doc`  | `docsmith`  | Generate and maintain project docs — powered by agents.  |
| `web`  | `websmith`  | Generate and maintain project website pages — powered by agents.  |

## Doc Smith (aigne doc)

Doc Smith is a powerful application designed to automate the generation and maintenance of project documentation using AI agents.

### Usage

You can interact with Doc Smith using the `aigne doc` command. The agents defined within the Doc Smith application are available as subcommands.

For example, to generate documentation for your current project, you would run its `generate` agent:

**Generate project documentation**

```bash
# Run the 'generate' agent to create or update docs
aigne doc generate
```

## Web Smith (aigne web)

Web Smith is an application focused on generating and maintaining web pages for your project, such as landing pages, feature showcases, or blogs.

### Usage

Similar to Doc Smith, you use the `aigne web` command followed by the name of an agent within the Web Smith application.

For example, to generate a new web page:

**Generate a new web page**

```bash
# Run an agent to create a new page
aigne web generate
```

## Common Commands

Since built-in apps are full AIGNE projects, they support standard commands that you can apply to them directly.

### Upgrade

To ensure you have the latest version of an application, you can run the `upgrade` command. This will check for a newer version on npm and install it if available.

**Upgrade Doc Smith**

```bash
aigne doc upgrade
```

### Serve as MCP Server

You can expose an application's agents as a standard Model Context Protocol (MCP) service, allowing other systems to interact with them over HTTP.

**Serve Doc Smith agents**

```bash
aigne doc serve-mcp
```

For a full list of server options, see the [`aigne serve-mcp`](/en/docs/aigne-cli/command-reference-serve-mcp-cdbd13/) command reference.

---

## Command Reference

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-cdbd13/

The AIGNE Command-Line Interface (CLI) is your primary tool for creating, managing, and deploying AIGNE agents. This section serves as a comprehensive reference for all available commands and their options, organized for quick look-up.

For a more guided experience, check out our [Getting Started](/en/docs/aigne-cli/getting-started-cdbd13/) guide or the practical examples in the [Guides](/en/docs/aigne-cli/guides-cdbd13/) section.

::::card-group
::link-card{title="aigne create" description="Scaffolds a new AIGNE project from a template." icon="folder-plus" href="/en/docs/aigne-cli/command-reference-create-cdbd13/"}
::link-card{title="aigne run" description="Executes an agent locally or from a remote URL, with options for chat mode, model selection, and input handling." icon="play" href="/en/docs/aigne-cli/command-reference-run-cdbd13/"}
::link-card{title="aigne serve-mcp" description="Serves agents as a Model Context Protocol (MCP) server for integration with external systems." icon="server" href="/en/docs/aigne-cli/command-reference-serve-mcp-cdbd13/"}
::link-card{title="aigne hub" description="Manages connections to the AIGNE Hub, allowing you to switch accounts, check status, and use Hub-provided models." icon="cloud" href="/en/docs/aigne-cli/command-reference-hub-cdbd13/"}
::link-card{title="aigne observe" description="Starts a local server to view and analyze agent execution traces and observability data." icon="eye" href="/en/docs/aigne-cli/command-reference-observe-cdbd13/"}
::link-card{title="aigne test" description="Runs automated tests for your agents and skills." icon="activity" href="/en/docs/aigne-cli/command-reference-test-cdbd13/"}
::link-card{title="aigne deploy" description="Deploys an AIGNE application as a Blocklet to a specified endpoint." icon="rocket" href="/en/docs/aigne-cli/command-reference-deploy-cdbd13/"}
::link-card{title="Built-in Apps" description="Execute pre-packaged applications like `doc-smith` for specialized, out-of-the-box agent functionality." icon="box" href="/en/docs/aigne-cli/command-reference-built-in-apps-cdbd13/"}
::::

---

## aigne create

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-create-cdbd13/

The `aigne create` command scaffolds a new AIGNE project from a template. It sets up the necessary directory structure and configuration files, allowing you to start developing your agent immediately.

## Usage

**Basic Usage**

```bash
aigne create [path]
```

## Arguments

- **path** `string` (default: `.`) — The path where the new project directory will be created. If omitted, it defaults to the current directory and triggers an interactive mode to prompt for the project name.

## Interactive Mode

If you run `aigne create` without specifying a path, or by using `.` for the current directory, the CLI enters an interactive mode to guide you through the setup process. You will be prompted for the following information:

- <strong>Project name</strong>: The name for your new project directory.
- <strong>Template</strong>: The project template to use. Currently, only a `default` template is available.

![Interactive prompt for project name](https://media.arcblock.io/lib/06/06e97c00fd2a53ff.w1600.webp)

### Overwrite Confirmation

For safety, if the target directory already exists and is not empty, the CLI will ask for your confirmation before proceeding to remove its contents. If you choose not to proceed, the operation will be safely cancelled.

**Confirmation Prompt**

```text
? The directory "/path/to/my-aigne-project" is not empty. Do you want to remove its contents? (y/N)
```

## Examples

### Create a Project Interactively

To be guided through the creation process, run the command without any arguments. The CLI will prompt you for a project name.

**Create in the current directory**

```bash
aigne create
```

### Create a Project in a Specific Directory

To create a project in a new directory named `my-awesome-agent`, provide the name as an argument.

**Create in a new 'my-awesome-agent' directory**

```bash
aigne create my-awesome-agent
```

This command creates the `my-awesome-agent` directory and scaffolds the project inside it. You will still be prompted to select a template.

## Successful Output

Upon successful creation, you will see a confirmation message and instructions for the next steps to run your new agent.

![Project creation success message](https://media.arcblock.io/lib/da/dacdbcdeba96a78e.w1600.webp)

After creating your project, the next step is to execute your agent. For more details, see the [`aigne run`](/en/docs/aigne-cli/command-reference-run-cdbd13/) command reference.

---

## aigne deploy

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-deploy-cdbd13/

The `aigne deploy` command packages and deploys your AIGNE application as a [Blocklet](https://www.blocklet.dev/) to a specified Blocklet Server endpoint. This is the standard way to publish your agent for production use, making it accessible as a self-contained, executable service.

## Usage

**Basic Usage**

```bash
aigne deploy --path <path-to-project> --endpoint <deploy-endpoint>
```

## Options

- **--path** `string` *(required)* — Specifies the path to the AIGNE project directory that contains the aigne.yaml file.

- **--endpoint** `string` *(required)* — The URL of the Blocklet Server endpoint where the application will be deployed.

## Deployment Process

The `deploy` command automates several steps to package your agent correctly and deploy it to the target environment. The process is interactive on the first run for a given project and non-interactive for subsequent updates.

**Deployment Workflow**

```d2
direction: down

Developer: {
  shape: c4-person
}

CLI: {
  label: "`aigne deploy`"

  task-1: { label: "1. Prepare Environment" }
  task-2: { label: "2. Check Blocklet CLI" }
  task-3: { label: "3. Configure Blocklet\n(Name & DID)" }
  task-4: { label: "4. Bundle Project" }
  task-5: { label: "5. Deploy to Server" }

  task-1 -> task-2 -> task-3 -> task-4 -> task-5
}

Blocklet-Server: {
  label: "Blocklet Server"
  icon: "https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg"
}

Deployed-Blocklet: {
  label: "Deployed Agent\n(as Blocklet)"
}

Developer -> CLI: "Run command with path & endpoint"
CLI.task-5 -> Blocklet-Server: "Upload bundle"
Blocklet-Server -> Deployed-Blocklet: "Host agent"
```

Here is a step-by-step breakdown of what happens when you run the command:

1. <strong>Environment Preparation</strong>: A temporary `.deploy` directory is created in your project root. The command copies your agent's source files and a standard Blocklet template into this directory to prepare for packaging.
2. <strong>Dependency Installation</strong>: If a `package.json` file is present, it runs `npm install` within the temporary directory to fetch all necessary dependencies.
3. <strong>Blocklet CLI Check</strong>: The command verifies that the `@blocklet/cli` is installed globally. If it's missing, you will be prompted to install it automatically, as it is required for packaging and deploying Blocklets.
4. <strong>Configuration (First-Time Deploy)</strong>: On the first deployment of a project, the CLI will guide you through a brief interactive setup:
5.
  - <strong>Blocklet Name</strong>: You will be asked to provide a name for your Blocklet. It suggests a default based on the `name` field in your `aigne.yaml` or the project's directory name.
  - <strong>DID Generation</strong>: A new Decentralized Identifier (DID) is automatically generated for your Blocklet using `blocklet create --did-only`, giving it a unique, verifiable identity.
  - This configuration (name and DID) is saved locally in `~/.aigne/deployed.yaml`. For subsequent deployments of the same project, these saved values are used automatically, making the process non-interactive.
6. <strong>Bundling</strong>: The CLI executes `blocklet bundle --create-release` to package all your application files into a single, deployable artifact.
7. <strong>Deployment</strong>: The final bundle is uploaded to the `--endpoint` you specified using `blocklet deploy`.
8. <strong>Cleanup</strong>: After a successful deployment, the temporary `.deploy` directory is automatically removed.

## Example

To deploy an AIGNE project located in the current directory to your Blocklet Server:

**Deploying a project**

```bash
aigne deploy --path . --endpoint https://my-node.abtnode.com
```

If this is the first time you are deploying this project, you will see a prompt to name your agent Blocklet:

**First-time deployment prompt**

```text
✔ Prepare deploy environment
✔ Check Blocklet CLI
ℹ Configure Blocklet
? Please input agent blocklet name: › my-awesome-agent
✔ Bundle Blocklet
...
✅ Deploy completed: /path/to/your/project -> https://my-node.abtnode.com
```

For a more detailed walkthrough on setting up a deployment target and managing your deployed agents, refer to the [Deploying Agents](/en/docs/aigne-cli/guides-deploying-agents-cdbd13/) guide.

---

## aigne hub

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-hub-cdbd13/

The `aigne hub` command is your central tool for managing connections to the AIGNE Hub. The Hub provides access to managed large language models, handles API key management, and tracks your credit usage. Properly configuring your Hub connection is essential for running agents that utilize Hub-provided models.

This command set allows you to connect to new Hubs (both the official Arcblock Hub and self-hosted instances), list your existing connections, switch between them, and monitor your account status.

## Usage

**Basic Command Structure**

```bash
aigne hub <subcommand>
```

## Commands

The `aigne hub` command includes several subcommands to manage different aspects of your Hub connections.

| Command  | Alias  | Description  |
|---|---|---|
| `connect [url]`  |  | Connect to a new AIGNE Hub.  |
| `list`  | `ls`  | List all configured AIGNE Hub connections.  |
| `use`  |  | Switch the active AIGNE Hub.  |
| `status`  | `st`  | Display the currently active AIGNE Hub.  |
| `remove`  | `rm`  | Remove a configured AIGNE Hub connection.  |
| `info`  | `i`  | Show detailed information for a specific Hub connection.  |

### connect [url]

Connects your local CLI to an AIGNE Hub instance. This process authenticates your machine and stores an API key for future requests in the `~/.aigne/aigne-hub-connected.yaml` file.

<strong>Usage</strong>

**Connect to a Hub**

```bash
aigne hub connect [url]
```

<strong>Behavior</strong>

- <strong>Interactive Mode</strong>: If you run the command without a URL, an interactive prompt will appear, allowing you to choose between the official AIGNE Hub or a custom, self-hosted Hub URL. **Interactive Connection**  ```bash $ aigne hub connect ? Choose a hub to connect: › - Use arrow-keys. Return to submit. ❯   Official Hub (https://hub.aigne.io)     Custom Hub URL ```
- <strong>Direct Mode</strong>: If you provide a URL, the CLI will attempt to connect to that specific Hub directly. **Direct Connection**  ```bash $ aigne hub connect https://my-hub.example.com ```

In both cases, a browser window will open for you to authenticate and authorize the CLI connection. Once completed, the credentials will be saved locally.

### list

Displays a table of all AIGNE Hubs you have previously connected to. It also indicates which Hub is currently active.

<strong>Usage</strong>

**List Connections**

```bash
aigne hub list
# or using the alias
aigne hub ls
```

<strong>Example Output</strong>

```bash
$ aigne hub ls
Connected AIGNE Hubs:

┌───────────────────────────────────────────────────┬────────┐
│ URL                                               │ ACTIVE │
├───────────────────────────────────────────────────┼────────┤
│ https://hub.aigne.io                              │ YES    │
├───────────────────────────────────────────────────┼────────┤
│ https://my-hub.example.com                        │ NO     │
└───────────────────────────────────────────────────┴────────┘
Use 'aigne hub use' to switch to a different hub.
```

### use

Switches the active AIGNE Hub. This command is useful when you have multiple Hub connections (e.g., a personal account and a team account) and need to change which one is used by default for commands like `aigne run`.

<strong>Usage</strong>

**Switch Active Hub**

```bash
aigne hub use
```

<strong>Behavior</strong>

Running this command will present an interactive list of your saved Hub connections. Select the one you wish to make active.

**Interactive Switch**

```bash
$ aigne hub use
? Choose a hub to switch to: › - Use arrow-keys. Return to submit.
    https://hub.aigne.io
❯   https://my-hub.example.com

✓ Switched active hub to https://my-hub.example.com
```

### status

Quickly shows the URL of the currently active AIGNE Hub and its connection status.

<strong>Usage</strong>

**Check Status**

```bash
aigne hub status
# or using the alias
aigne hub st
```

<strong>Example Output</strong>

```bash
$ aigne hub status
Active hub: https://hub.aigne.io - online
```

### remove

Removes a saved AIGNE Hub connection from your local configuration file.

<strong>Usage</strong>

**Remove a Hub**

```bash
aigne hub remove
# or using the alias
aigne hub rm
```

<strong>Behavior</strong>

This command will interactively prompt you to select which of your saved Hub connections you want to remove.

**Interactive Removal**

```bash
$ aigne hub remove
? Choose a hub to remove: › https://my-hub.example.com

✓ Hub https://my-hub.example.com removed
```

### info

Fetches and displays detailed account information for a selected Hub connection. This includes user details, credit balance, and important links.

<strong>Usage</strong>

**Get Hub Info**

```bash
aigne hub info
# or using the alias
aigne hub i
```

<strong>Behavior</strong>

First, you will be prompted to select a configured Hub. Then, the CLI will display its connection status and your account details.

<strong>Example Output</strong>

```bash
$ aigne hub info

AIGNE Hub Connection
──────────────────────────────────────────────
Hub:       https://hub.aigne.io
Status:    Connected ✅

User:
  Name:    John Doe
  DID:     z2qa...w9vM
  Email:   john.doe@example.com

Credits:
  Used:    1,234
  Total:   100,000

Links:
  Payment: https://hub.aigne.io/payment/...
  Profile: https://hub.aigne.io/profile/...
```

---

## aigne observe

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-observe-cdbd13/

The `aigne observe` command launches a local web server for monitoring and analyzing agent execution data. It provides a user-friendly interface to inspect traces, view detailed call information, and understand your agents' behavior during runs. This tool is essential for debugging, performance tuning, and gaining deep insights into how your agents process information and interact with various tools and models.

## Usage

To start the observability server, run the following command in your terminal:

**Usage**

```bash
aigne observe [options]
```

Upon starting, the CLI will print the server URL and the path to the local observability database.

![AIGNE observability server running interface](https://media.arcblock.io/lib/6c/6cd148bb88444bcb.w1600.webp)

## How It Works

The `observe` command starts a web application that reads from a local SQLite database where AIGNE stores all execution traces. Each time you run an agent (using `aigne run` or `aigne serve-mcp`), the framework automatically records detailed logs of the execution flow. These logs then become available for inspection in the observability UI.

The UI allows you to browse a list of all recorded traces and drill down into specific ones to see a step-by-step breakdown of the agent's operations, including inputs, outputs, tool calls, and model responses.

![Viewing call details in the AIGNE observability UI](https://media.arcblock.io/lib/eb/eb45cd17811ac2c5.w1600.webp)

## Options

- **--host** `string` (default: `localhost`) — Specifies the host address for the server. Use `0.0.0.0` to expose the server to other devices on your local network.
- **--port** `number` (default: `7890`) — Sets the port number for the server to listen on. If the specified port is unavailable, it will attempt to find the next available one. Can also be set via the `PORT` environment variable.

## Examples

### Start the server on the default port

Running the command without any options starts the server with the default settings.

**Start with default settings**

```bash
aigne observe
```

<strong>Expected Output:</strong>

**Console Output**

```text
Observability database path: /path/to/your/project/.aigne/observability.db
Observability server is running at http://localhost:7890
```

You can then open `http://localhost:7890` in your web browser to access the UI.

### Start the server on a specific port

Use the `--port` option to specify a different port.

**Start on a custom port**

```bash
aigne observe --port 8080
```

This will start the server on `http://localhost:8080` (or the next available port if 8080 is in use).

### Expose the server to your local network

To allow other devices on your network to access the observability UI, set the host to `0.0.0.0`.

**Expose the server publicly**

```bash
aigne observe --host 0.0.0.0
```

The server will then be accessible via `http://<your-local-ip>:7890`.

---

## aigne run

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-run-cdbd13/

The `aigne run` command is the primary way to execute an AIGNE agent. It can run agents from a local project directory or directly from a remote URL. It offers a flexible set of options for providing input, configuring the AI model, and handling output, including an interactive chat mode for conversational agents.

## Usage

**Basic Syntax**

```bash
aigne run [path] [agent_name] [options]
```

### Arguments

- `[path]` (Optional): The path to the AIGNE project directory or a remote URL (e.g., a Git repository). If omitted, it defaults to the current directory (`.`).
- `[agent_name]` (Optional): The specific agent to run from the project. If not specified, the CLI will use the `entry-agent` or the default `chat` agent defined in `aigne.yaml`, falling back to the first agent listed.

## How It Works

The `run` command first loads the AIGNE application. If a remote URL is provided, it downloads and caches the project locally before proceeding. It then parses the command-line arguments and executes the specified agent with the given inputs and model configurations.

**Remote Execution Flow**

```d2
direction: down

User: {
  shape: c4-person
}

CLI: {
  label: "@aigne/cli"

  Download: {
    label: "Download Package"
  }

  Extract: {
    label: "Extract Package"
  }

  Load: {
    label: "Load Application"
  }

  Execute: {
    label: "Execute Agent"
  }
}

Remote-URL: {
  label: "Remote URL\n(e.g., GitHub)"
  shape: cylinder
}

Cache-Dir: {
  label: "Cache Directory\n(~/.aigne/.download)"
  shape: cylinder
}

Local-Dir: {
  label: "Local Directory\n(~/.aigne/<hostname>/...)"
  shape: cylinder
}

User -> CLI: "aigne run <url>"
CLI.Download -> Remote-URL: "1. Fetch project"
Remote-URL -> CLI.Download: "2. Return tarball"
CLI.Download -> Cache-Dir: "3. Save tarball"
CLI.Extract -> Cache-Dir: "4. Read tarball"
CLI.Extract -> Local-Dir: "5. Unpack project files"
CLI.Load -> Local-Dir: "6. Load aigne.yaml & .env"
CLI.Execute -> CLI.Load: "7. Run agent"
CLI.Execute -> User: "8. Display output"
```

## Examples

### Running a Local Agent

Execute an agent from a project on your local filesystem.

**Run from current directory**

```bash
# Run the default agent in the current directory
aigne run
```

**Run a specific agent**

```bash
# Run the 'translator' agent located in a specific project path
aigne run path/to/my-project translator
```

### Running a Remote Agent

You can run an agent directly from a Git repository or a tarball URL. The CLI handles downloading and caching the project in your home directory (`~/.aigne`).

**Run from a GitHub repository**

```bash
aigne run https://github.com/AIGNE-io/aigne-framework/tree/main/examples/default
```

### Running in Interactive Chat Mode

For conversational agents, use the `--interactive` flag to start an interactive terminal session.

![Running an agent in chat mode](https://media.arcblock.io/lib/72/7259ac6078e7393b.w1600.webp)

**Start a chat session**

```bash
aigne run --interactive
```

Inside the chat loop, you can use commands like `/exit` to quit and `/help` for assistance. You can also attach local files to your message by prefixing the path with `@`.

```
💬 Tell me about this file: @/path/to/my-document.pdf
```

## Providing Input to Agents

There are multiple ways to provide input to your agents, depending on their defined input schema in `aigne.yaml`.

#### As Command-Line Options

If an agent's input schema defines specific parameters (e.g., `text`, `targetLanguage`), you can pass them as command-line options.

**Pass agent-specific parameters**

```bash
# Assuming 'translator' agent has 'text' and 'targetLanguage' inputs
aigne run translator --text "Hello, world!" --targetLanguage "Spanish"
```

#### From Standard Input (stdin)

You can pipe content directly to the `run` command. This is useful for chaining commands.

**Pipe input to an agent**

```bash
echo "Summarize this important update." | aigne run summarizer
```

#### From Files

Use the `@` prefix to read content from a file and pass it as input.

- <strong>`--input @<file>`</strong>: Reads the entire file content as the primary input.
- <strong>`--<param> @<file>`</strong>: Reads file content for a specific agent parameter.

**Read input from a file**

```bash
# Use content of document.txt as the main input
aigne run summarizer --input @document.txt

# Provide structured JSON input for multiple parameters
aigne run translator --input @request-data.json --format json
```

#### Multimedia File Inputs

For agents that process files like images or documents (e.g., vision models), use the `--input-file` option.

**Attach a file for a vision agent**

```bash
aigne run image-describer --input-file cat.png --input "What is in this image?"
```

## Options Reference

### General Options

| Option  | Description  |
|---|---|
| `--interactive`  | Run the agent in an interactive chat loop in the terminal.  |
| `--log-level <level>`  | Set the logging level. Available levels: `debug`, `info`, `warn`, `error`, `silent`. Default: `silent`.  |

### Model Options

These options allow you to override the model configurations defined in `aigne.yaml`.

| Option  | Description  |
|---|---|
| `--model <provider[:model]>`  | Specify the AI model to use (e.g., 'openai' or 'openai:gpt-4o-mini').  |
| `--temperature <value>`  | Model temperature (0.0-2.0). Higher values increase randomness.  |
| `--top-p <value>`  | Model top-p / nucleus sampling (0.0-1.0). Controls response diversity.  |
| `--presence-penalty <value>`  | Presence penalty (-2.0 to 2.0). Penalizes repeating tokens.  |
| `--frequency-penalty <value>`  | Frequency penalty (-2.0 to 2.0). Penalizes frequent tokens.  |
| `--aigne-hub-url <url>`  | Custom AIGNE Hub service URL for fetching remote models or agents.  |

### Input & Output Options

| Option  | Alias  | Description  |
|---|---|---|
| `--input <value>`  | `-i`  | Input to the agent. Can be specified multiple times. Use `@<file>` to read from a file.  |
| `--input-file <path>`  |  | Path to an input file for the agent (e.g., for vision models). Can be specified multiple times.  |
| `--format <format>`  |  | Input format when using `--input @<file>`. Choices: `text`, `json`, `yaml`.  |
| `--output <file>`  | `-o`  | Path to a file to save the result. Defaults to printing to standard output.  |
| `--output-key <key>`  |  | The key in the agent's result object to save to the output file. Defaults to `output`.  |
| `--force`  |  | Overwrite the output file if it already exists. Creates parent directories if they don't exist.  |

## Next Steps

::::card-group
::link-card{title="aigne observe" description="Learn how to start the observability server to view detailed traces of your agent runs." icon="monitor" href="/en/docs/aigne-cli/command-reference-observe-cdbd13/"}
::link-card{title="Running Remote Agents" description="Dive deeper into the specifics of executing agents directly from remote URLs." icon="cloud" href="/en/docs/aigne-cli/guides-running-remote-agents-cdbd13/"}
::link-card{title="Creating a Custom Agent" description="Get started with building your own agents and skills to use with the AIGNE CLI." icon="bot" href="/en/docs/aigne-cli/guides-creating-a-custom-agent-cdbd13/"}
::::

---

## aigne serve-mcp

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-serve-mcp-cdbd13/

Serves the agents in an AIGNE project as a Model Context Protocol (MCP) server. This command exposes your agents over a streamable HTTP endpoint, enabling seamless integration with external systems and applications that support the MCP standard.

Internally, `aigne serve-mcp` starts a lightweight Express server. When a POST request is received on the configured endpoint, it invokes the corresponding agent and streams the response back according to the MCP specification.

![Running the MCP Service](https://media.arcblock.io/lib/c4/c48e4ceaa98674a8.w1600.webp)

## Usage

**Basic Usage**

```bash
aigne serve-mcp [options]
```

## Options

The `serve-mcp` command accepts the following options to customize the server's behavior:

- **--path, --url** `string` (default: `.`) — Path to the local agents directory or a URL to a remote AIGNE project.

- **--host** `string` (default: `localhost`) — Host to run the MCP server on. Use `0.0.0.0` to expose the server publicly to the network.

- **--port** `number` (default: `3000`) — Port for the MCP server. The command respects the `PORT` environment variable if set; otherwise, it defaults to 3000.

- **--pathname** `string` (default: `/mcp`) — The URL path for the MCP service endpoint.

- **--aigne-hub-url** `string` — A custom AIGNE Hub service URL, used for fetching remote agent definitions or models.

## Examples

### Start a Server for a Local Project

To serve agents from the current directory, run the command without any options. The server will start on the default host and port.

**Start Server in Current Directory**

```bash
aigne serve-mcp
```

<strong>Expected Output:</strong>

**Console Output**

```text
MCP server is running on http://localhost:3000/mcp
```

### Serve Agents on a Specific Port and Path

You can specify a different port and provide an explicit path to your AIGNE project directory.

**Start Server with Custom Port and Path**

```bash
aigne serve-mcp --path ./my-ai-project --port 8080
```

<strong>Expected Output:</strong>

**Console Output**

```text
MCP server is running on http://localhost:8080/mcp
```

### Expose the Server to the Network

To make your MCP server accessible from other machines on your network, set the host to `0.0.0.0`.

**Expose Server Publicly**

```bash
aigne serve-mcp --host 0.0.0.0
```

<strong>Expected Output:</strong>

**Console Output**

```text
MCP server is running on http://0.0.0.0:3000/mcp
```

## Next Steps

After exposing your agents via the MCP server, you might want to deploy them for production use.

::::card-group
::link-card{title="aigne deploy Command" description="Learn how to deploy your AIGNE application as a Blocklet." icon="navigation" href="/en/docs/aigne-cli/command-reference-deploy-cdbd13/"}
::link-card{title="Deploying Agents Guide" description="Follow a step-by-step tutorial for deploying your agents." icon="book-open" href="/en/docs/aigne-cli/guides-deploying-agents-cdbd13/"}
::::

---

## aigne test

URL: https://www.arcblock.io/en/docs/aigne-cli/command-reference-test-cdbd13/

The `aigne test` command executes automated tests for your agents and skills. It provides a built-in mechanism for unit and integration testing to ensure your agents and the tools they rely on function correctly before deployment.

## Usage

**Basic Syntax**

```bash
aigne test [path]
```

## Arguments

| Argument  | Description  |
|---|---|
| `[path]`  | Optional. The path to the directory containing your agents and their corresponding test files. If omitted, the command searches for tests in the current directory.  |

## Description

The command automatically discovers and runs test files within your project. For instance, the default AIGNE project template includes a `sandbox.test.js` file designed to verify the functionality of the `sandbox.js` skill. The `aigne test` command will execute such files to validate your agent's capabilities.

## Examples

### Run tests in the current directory

To execute test cases for the AIGNE project located in your current working directory, run the command without any arguments:

```bash
aigne test
```

### Run tests in a specific directory

If your agents are located in a different directory, you can specify the path to that directory:

```bash
aigne test path/to/agents
```

## Next Steps

After ensuring your agents pass all tests, you can proceed to serve them for integration or deploy them as a service.

::::card-group
::link-card{title="aigne serve-mcp" description="Learn how to serve your agents as an MCP server for external integrations." icon="server" href="/en/docs/aigne-cli/command-reference-serve-mcp-cdbd13/"}
::link-card{title="aigne deploy" description="Learn how to deploy your AIGNE application as a Blocklet." icon="rocket" href="/en/docs/aigne-cli/command-reference-deploy-cdbd13/"}
::::

---

## Contributing

URL: https://www.arcblock.io/en/docs/aigne-cli/contributing-cdbd13/

We're thrilled that you're interested in contributing to `@aigne/cli`! Your help is invaluable in making the AIGNE development experience better for everyone. Whether you're fixing a bug, proposing a new feature, or improving documentation, your contributions are welcome.

This guide provides instructions for setting up your development environment, running tests, and submitting your changes.

## Getting Started

The `@aigne/cli` package is part of the `aigne-framework` monorepo. To get started, you'll need to clone the main repository and install its dependencies.

### 1. Clone the Repository

First, clone the `aigne-framework` repository from GitHub to your local machine:

**Git Clone**

```bash
git clone https://github.com/AIGNE-io/aigne-framework.git
cd aigne-framework
```

### 2. Install Dependencies

We use `bun` as the primary package manager for the project. Install all the necessary dependencies from the root of the monorepo:

**Bun Install**

```bash
bun install
```

This will install all dependencies for every package in the monorepo, including `@aigne/cli`.

## Development Workflow

All development commands for the CLI should be run from within its package directory: `packages/cli`.

### Building the Code

To compile the TypeScript source code from `src/` into JavaScript in the `dist/` directory, run the build command. This process is configured by `tsconfig.build.json`.

**Build Command**

```bash
bun run build
```

### Linting and Type Checking

We use the TypeScript compiler to perform static analysis and ensure code quality. To check for any type errors without emitting JavaScript files, run the lint command:

**Lint Command**

```bash
bun run lint
```

### Running Tests

We have a comprehensive test suite to ensure the CLI functions correctly. The following scripts are available for testing:

| Command  | Description  |
|---|---|
| `bun run test`  | Executes the complete test suite, including tests for the CLI source (`test:src`) and the project templates (`test:templates`).  |
| `bun run test:src`  | Runs only the unit and integration tests for the CLI's core functionality.  |
| `bun run test:templates`  | Runs tests specifically for the project templates scaffolded by `aigne create`.  |
| `bun run test:coverage`  | Runs the entire test suite and generates a code coverage report.  |

It's important to ensure all tests pass before submitting a pull request.

### Code Style

We use [Prettier](https://prettier.io/) to maintain a consistent code style across the project. Please ensure your code is formatted before committing your changes. Most editors can be configured to format files automatically on save.

## Submitting a Pull Request

Once you've made your changes and verified them with the build and test scripts, you're ready to submit a pull request.

::::steps
:::step{title="Fork the repository"}
on GitHub.
:::

:::step{title="Create a new branch"}
for your feature or bug fix: `git checkout -b your-feature-name`.
:::

:::step{title="Commit your changes"}
with a clear and descriptive commit message.
:::

:::step{title="Push your branch"}
to your fork: `git push origin your-feature-name`.
:::

:::step{title="Open a pull request"}
from your fork to the `main` branch of the `AIGNE-io/aigne-framework` repository.
:::

:::step{title="Provide a detailed description"}
of your changes in the pull request, referencing any related issues from the [issue tracker](https://github.com/AIGNE-io/aigne-framework/issues).
:::
::::

We'll review your contribution as soon as possible. Thank you for helping us improve AIGNE!

---

## Agents and Skills

URL: https://www.arcblock.io/en/docs/aigne-cli/core-concepts-agents-and-skills-cdbd13/

In the AIGNE ecosystem, Agents and Skills are the fundamental building blocks that bring your AI applications to life. They work together to create sophisticated, tool-augmented AI systems. Think of an Agent as the brain responsible for reasoning and conversation, and Skills as the tools it uses to perform actions and interact with the outside world.

This section covers the definition and structure of these core components. For details on how to wire them together in your project, see the [Project Configuration (aigne.yaml)](/en/docs/aigne-cli/core-concepts-project-configuration-cdbd13/) documentation.

## Agents

An Agent is the central component that processes user input, maintains context, and decides which actions to take. Its behavior is defined by a set of instructions (its core prompt) and the collection of Skills it has access to.

Agents are typically defined in `.yaml` files.

### Agent Definition Example

Here is a basic example of a chat agent that is equipped with a code execution skill.

**chat.yaml**

```yaml
name: chat
description: Chat agent
instructions: |
  You are a helpful assistant that can answer questions and provide information on a wide range of topics.
  Your goal is to assist users in finding the information they need and to engage in friendly conversation.
input_key: message
memory: true
skills:
  - sandbox.js
```

### Agent Properties

The agent's behavior is configured through several key properties in its YAML definition file:

| Property  | Type  | Description  |
|---|---|---|
| `name`  | `string`  | A short, descriptive name for the agent.  |
| `description`  | `string`  | A more detailed explanation of the agent's purpose.  |
| `instructions`  | `string`  | The system prompt that defines the agent's personality, goals, and constraints. This is its core logic.  |
| `input_key`  | `string`  | The name of the property in the input object that contains the primary user message (e.g., `message`).  |
| `memory`  | `boolean`  | If `true`, the agent will retain conversation history, allowing for follow-up questions and context.  |
| `skills`  | `array`  | A list of skill files (e.g., `sandbox.js`) that the agent is authorized to use.  |

## Skills

A Skill is an executable function, typically written in JavaScript, that provides an Agent with a specific capability. This could be anything from running code, fetching data from an API, or interacting with a file system. Skills are the bridge between the Large Language Model's reasoning and the execution of concrete tasks.

### Skill Definition Example

Skills are standard Node.js modules that export a default asynchronous function. Crucially, they also export metadata that describes their purpose and defines their input/output structure, allowing the agent to understand how and when to use them.

**sandbox.js**

```javascript
import vm from "node:vm";

export default async function evaluateJs({ code }) {
  const sandbox = {};
  const context = vm.createContext(sandbox);
  const result = vm.runInContext(code, context, { displayErrors: true });
  return { result };
}

evaluateJs.description = "This agent evaluates JavaScript code.";

evaluateJs.input_schema = {
  type: "object",
  properties: {
    code: { type: "string", description: "JavaScript code to evaluate" },
  },
  required: ["code"],
};

evaluateJs.output_schema = {
  type: "object",
  properties: {
    result: { type: "any", description: "Result of the evaluated code" },
  },
  required: ["result"],
};
```

### Skill Structure

A skill file consists of three main parts:

::::steps
:::step{title="Default Exported Function"}
The core logic of the skill. It's an `async` function that receives an object of arguments and returns a result.
:::

:::step{title="`description`"}
A string property attached to the function that provides a natural language description of what the skill does. The agent's underlying LLM uses this description to determine when it's appropriate to call this skill.
:::

:::step{title="`input_schema`"}
<strong>/</strong> <strong>`output_schema`</strong>: JSON Schema objects that define the expected structure and types for the function's input and output. This ensures that the agent provides valid arguments and can correctly interpret the results.
:::
::::

## How They Work Together

The interaction between a user, an agent, and a skill follows a clear pattern. The agent acts as an intelligent orchestrator, interpreting the user's request and invoking the appropriate skill to fulfill it. The following diagram illustrates this process:

![---labels: \[](https://media.arcblock.io/lib/a9/a9c71bead07cd4b1.w1600.webp)

By separating the reasoning (Agent) from the execution (Skill), you can build powerful and extensible AI systems that are easy to maintain and upgrade.

### Next Steps

Now that you understand the core concepts of Agents and Skills, you can proceed to the following sections:

::::card-group
::link-card{title="Project Configuration (aigne.yaml)" description="Learn how to configure agents, skills, and models in the main project configuration file." icon="file" href="/en/docs/aigne-cli/core-concepts-project-configuration-cdbd13/"}
::link-card{title="Creating a Custom Agent" description="Follow a step-by-step guide to build your own custom agent and integrate it as a skill." icon="sparkles" href="/en/docs/aigne-cli/guides-creating-a-custom-agent-cdbd13/"}
::::

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/aigne-cli/core-concepts-cdbd13/

## labels: ["Reference"]

An AIGNE project provides a structured environment for developing, testing, and deploying AI agents. At its heart, a project is a directory containing configuration files that define your agents, the skills they can use, and the language models they connect to. This section breaks down these fundamental building blocks.

## Project Structure

When you create a new project using `aigne create`, it scaffolds a standard directory structure to keep your components organized. A typical project looks like this:

**Project Structure**

```text
my-agent-project/
├── aigne.yaml        # The main project configuration file.
├── agents/           # Directory for agent definition files.
│   └── chat.yaml     # Example agent definition.
└── skills/           # Directory for skill implementation files.
    └── sandbox.js    # Example skill implementation.
```

This structure separates configuration (`aigne.yaml`, `agents/`) from implementation (`skills/`), making your project modular and easy to manage.

## How It All Fits Together

The following diagram illustrates the relationship between the core components of an AIGNE project. The central `aigne.yaml` file orchestrates everything, defining which agents exist, what skills they can use, and which AI model powers their intelligence.

![---](https://media.arcblock.io/lib/ec/ec34344a1f7784b9.w1600.webp)

To understand how an AIGNE project works, it's essential to grasp its two primary components: the central project configuration and the executable agents and skills. Explore them in more detail below.

::::card-group
::link-card{title="Project Configuration (aigne.yaml)" description="This is the main manifest for your project. It defines the chat model to be used, lists the available agents, and registers the skills that those agents can access." icon="file" href="/en/docs/aigne-cli/core-concepts-project-configuration-cdbd13/"}
::link-card{title="Agents and Skills" description="Agents are the core actors that perform tasks, defined by their instructions and capabilities. Skills are the tools agents use, implemented as functions (e.g., JavaScript modules) that provide specific functionalities." icon="bot" href="/en/docs/aigne-cli/core-concepts-agents-and-skills-cdbd13/"}
::::

With this foundational understanding, you're ready to dive deeper into how to configure your project.

<strong>Next</strong>: Learn more about the main configuration file in the [Project Configuration (aigne.yaml)](/en/docs/aigne-cli/core-concepts-project-configuration-cdbd13/) guide.

---

## Project Configuration (aigne.yaml)

URL: https://www.arcblock.io/en/docs/aigne-cli/core-concepts-project-configuration-cdbd13/

The `aigne.yaml` file is the heart of your AIGNE project. It serves as the central manifest, defining the project's metadata, language model settings, and the relationships between its core components like agents and skills. A well-structured `aigne.yaml` is the first step toward building a powerful and organized agent.

This file uses the YAML format, which is designed to be human-readable and easy to write.

## Core Configuration Keys

Let's break down the primary sections you'll find in a typical `aigne.yaml` file.

### Project Metadata

These fields provide basic information about your project.

- **name** `string` *(required)* — A unique identifier for your project.
- **description** `string` — A brief summary of what your project does.

**aigne.yaml**

```yaml
name: test_aigne_project
description: A test project for the aigne agent
```

### Chat Model (chat_model)

This is a critical section where you configure the Large Language Model (LLM) that will power your agents. AIGNE provides a flexible way to define the model provider, name, and other parameters.

| Key  | Type  | Description  |
|---|---|---|
| `provider`  | string  | The LLM provider (e.g., `openai`). Can also be specified as a prefix in the `model` key.  |
| `name` / `model`  | string  | The specific model to use (e.g., `gpt-4o-mini`).  |
| `temperature`  | number  | A value between 0 and 2 that controls the randomness of the model's output. Higher values result in more creative responses.  |

Here are a couple of common ways to configure the model:

<strong>Example 1: Using</strong> <strong>`provider`</strong> <strong>and</strong> <strong>`name`</strong>

This is a clear, explicit way to define the model.

**aigne.yaml**

```yaml
chat_model:
  provider: openai
  name: gpt-4o-mini
  temperature: 0.8
```

<strong>Example 2: Using a prefixed</strong> <strong>`model`</strong> <strong>key</strong>

This is a more concise shorthand format.

**aigne.yaml**

```yaml
chat_model:
  model: openai:gpt-4o-mini
  temperature: 0.8
```

### Agents (agents)

The `agents` key lists all the agent definition files (`.yaml`) included in your project. Each file listed here defines the behavior, prompts, and tool usage for a specific agent.

**aigne.yaml**

```yaml
# ... other configurations
agents:
  - chat.yaml
```

### Skills (skills)

The `skills` key lists the executable code or definitions that provide your agents with tools and capabilities. These can be JavaScript files (`.js`) containing functions or other YAML files that define complex skills.

**aigne.yaml**

```yaml
# ... other configurations
skills:
  - sandbox.js
  - filesystem.yaml
```

### Service and CLI Exposure

You can also configure how your agents are exposed to the outside world, whether through a server or as command-line tools.

- `mcp_server`: Configures which agents are served via the Model Context Protocol (MCP) when you run the `aigne serve-mcp` command.
- `cli`: Configures which agents can be run directly from the command line.

**aigne.yaml**

```yaml
# ... other configurations
mcp_server:
  agents:
    - chat.yaml

cli:
  agents:
    - chat.yaml
```

## Complete Example

Here is a complete `aigne.yaml` file that brings all these elements together:

**aigne.yaml**

```yaml
name: test_aigne_project
description: A test project for the aigne agent

chat_model:
  model: openai:gpt-4o-mini
  temperature: 0.8

agents:
  - chat.yaml

skills:
  - sandbox.js

mcp_server:
  agents:
    - chat.yaml

cli:
  agents:
    - chat.yaml
```

With this configuration file in place, you have a solid foundation for your project. The next step is to define what your agents and skills actually do.

Now that you understand how to configure the project, let's explore the core components in more detail. Continue to the next section to learn about [Agents and Skills](/en/docs/aigne-cli/core-concepts-agents-and-skills-cdbd13/).

---

## Getting Started

URL: https://www.arcblock.io/en/docs/aigne-cli/getting-started-cdbd13/

This guide will walk you through the essential steps to install the AIGNE CLI, create a new project, and run your first AI agent. By the end, you'll have a functioning agent running locally.

## Step 1: Install the AIGNE CLI

First, you need to install the `@aigne/cli` package globally on your system. You can use your preferred JavaScript package manager.

### Using npm

```bash
npm install -g @aigne/cli
```

### Using yarn

```bash
yarn global add @aigne/cli
```

### Using pnpm

```bash
pnpm add -g @aigne/cli
```

## Step 2: Create a New Project

Once the CLI is installed, you can create a new AIGNE project using the `aigne create` command. This command scaffolds a new directory with a default agent template, including all the necessary configuration files.

```bash
aigne create my-first-agent
```

The CLI will then guide you through an interactive setup process. You'll be prompted to confirm the project name and select a template. For this guide, you can accept the default options by pressing Enter.

![Interactive project creation prompt](https://media.arcblock.io/lib/06/06e97c00fd2a53ff.w1600.webp)

After the process completes, you'll see a success message with instructions on how to start using your new agent.

![Project creation success message](https://media.arcblock.io/lib/da/dacdbcdeba96a78e.w1600.webp)

## Step 3: Set Up Environment Variables

Before running the agent, you need to configure your AI model provider's API key.

First, navigate into your newly created project directory:

```bash
cd my-first-agent
```

The project template includes an example environment file named `.env.local.example`. Copy it to a new file named `.env.local` to create your local configuration.

```bash
cp .env.local.example .env.local
```

Now, open the `.env.local` file in your editor. You need to add your OpenAI API key. The default template is pre-configured to use OpenAI.

**.env.local**

```shell
# OpenAI
MODEL="openai:gpt-4o-mini"
OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

Replace `"YOUR_OPENAI_API_KEY"` with your actual key.

## Step 4: Run Your Agent

With the configuration in place, you can now run your agent. Execute the `aigne run` command from within your project directory.

```bash
aigne run
```

This command starts an interactive chat session with the default agent defined in your project. You can now start sending messages and interacting with your AI agent directly in the terminal.

![Running the default agent in chat mode](https://media.arcblock.io/lib/72/7259ac6078e7393b.w1600.webp)

## Next Steps

Congratulations! You've successfully installed the AIGNE CLI, created a project, and run your first agent.

To understand the files you've just created and how an AIGNE project is structured, head over to the [Core Concepts](/en/docs/aigne-cli/core-concepts-cdbd13/) section.

---

## Guides

URL: https://www.arcblock.io/en/docs/aigne-cli/guides-cdbd13/

Welcome to the AIGNE CLI guides. This section provides practical, step-by-step tutorials designed to help you master common development workflows. Whether you're building your first custom agent, executing code from a remote repository, or preparing your application for production, these guides will provide you with the necessary instructions.

::::card-group
::link-card{title="Creating a Custom Agent" description="A step-by-step tutorial on creating a new JavaScript agent and integrating it into your project as a skill." icon="plus" href="/en/docs/aigne-cli/guides-creating-a-custom-agent-cdbd13/"}
::link-card{title="Running Remote Agents" description="Learn how to run agents directly from a remote Git repository or tarball URL." icon="globe" href="/en/docs/aigne-cli/guides-running-remote-agents-cdbd13/"}
::link-card{title="Deploying Agents" description="Learn how to deploy your AIGNE project as a Blocklet for production use." icon="rocket" href="/en/docs/aigne-cli/guides-deploying-agents-cdbd13/"}
::::

For a detailed breakdown of every command and its available options, please refer to the comprehensive [Command Reference](/en/docs/aigne-cli/command-reference-cdbd13/).

---

## Creating a Custom Agent

URL: https://www.arcblock.io/en/docs/aigne-cli/guides-creating-a-custom-agent-cdbd13/

This guide provides a step-by-step tutorial on creating a new JavaScript agent and integrating it into your AIGNE project as a skill. Agents are the core executable components that give your application its unique capabilities. By creating custom agents, you can extend the functionality of your AI to perform specialized tasks, interact with external APIs, or manipulate local data.

### Prerequisites

Before you start, make sure you have an AIGNE project set up. If you don't, please follow our [Getting Started](/en/docs/aigne-cli/getting-started-cdbd13/) guide to create one first.

### Step 1: Create the Skill File

A skill in AIGNE is a JavaScript module that exports a primary function and some metadata. This function contains the logic your agent will execute.

Let's create a simple agent that generates a greeting. Create a new file named `greeter.js` in the root of your AIGNE project and add the following code:

**greeter.js**

```javascript
export default async function greet({ name }) {
  const message = `Hello, ${name}!`;
  console.log(message);
  return { message };
}

greet.description = "A simple agent that returns a greeting message.";

greet.input_schema = {
  type: "object",
  properties: {
    name: { type: "string", description: "The name to include in the greeting." },
  },
  required: ["name"],
};

greet.output_schema = {
  type: "object",
  properties: {
    message: { type: "string", description: "The complete greeting message." },
  },
  required: ["message"],
};
```

Let's break down this file:

- <strong>`export default async function greet({ name })`</strong>: This is the main function of your agent. It takes a single object as an argument, which contains the inputs defined in `input_schema`. It returns an object that must conform to the constraints defined by the `output_schema`.
- <strong>`greet.description`</strong>: A plain-text description of what the agent does. This is crucial, as the main language model uses this description to understand when and how to use your tool.
- <strong>`greet.input_schema`</strong>: A JSON Schema object that defines the expected input for your agent. This ensures that data passed to your function is valid.
- <strong>`greet.output_schema`</strong>: A JSON Schema object that defines the expected output from your agent.

### Step 2: Integrate the Skill into Your Project

Now that you've created the skill, you need to register it in your project's configuration file so the main chat agent can use it.

1. Open the `aigne.yaml` file in the root of your project.
2. Add your new `greeter.js` file to the `skills` list.

**aigne.yaml**

```yaml
chat_model:
  provider: openai
  name: gpt-4o-mini
  temperature: 0.8
agents:
  - chat.yaml
skills:
  - sandbox.js
  - filesystem.yaml
  - greeter.js # Add your new skill here
```

By adding your script to this list, you make it available as a tool that the primary chat agent can invoke during a conversation.

### Step 3: Test Your Agent Directly

With the skill created and registered, it's time to test it. You can execute any skill file directly from the command line using `aigne run`.

Run the following command in your terminal:

```bash
aigne run ./greeter.js --input '{"name": "AIGNE Developer"}'
```

This command executes your `greeter.js` script and passes the JSON string from the `--input` flag as an argument to the exported function. You should see the following output, confirming your agent works as expected:

```json
{
  "result": {
    "message": "Hello, AIGNE Developer!"
  }
}
```

### Step 4: Use Your Agent in Chat Mode

The real power of skills is unlocked when the main AI agent can decide to use them dynamically. To see this in action, run your project in interactive chat mode:

```bash
aigne run --interactive
```

Once the chat session starts, ask the AI to use your new tool. For example:

```
> Use the greeter skill to say hello to the world.
```

The AI will recognize the request, find the `greeter` skill based on its description, and execute it with the correct parameters. It will then use the output from your skill to formulate its response.

### Next Steps

Congratulations! You've successfully created a custom JavaScript agent, integrated it as a skill, and tested its functionality. You can now build more complex agents to connect to APIs, manage files, or perform any other task you can script.

To learn how to share your project with others, check out our guide on [Deploying Agents](/en/docs/aigne-cli/guides-deploying-agents-cdbd13/).

---

## Deploying Agents

URL: https://www.arcblock.io/en/docs/aigne-cli/guides-deploying-agents-cdbd13/

## labels: ["Reference"]

Deploying your AIGNE project transforms it from a local development setup into a self-contained, distributable application known as a Blocklet. This allows your agent to run in a production environment, be shared with others, and integrate seamlessly into the broader Blocklet ecosystem. The `aigne deploy` command automates this entire packaging and deployment process.

This guide will walk you through the deployment workflow. For a detailed breakdown of all available command options, please see the [`aigne deploy` command reference](/en/docs/aigne-cli/command-reference-deploy-cdbd13/).

## The Deployment Process

The `aigne deploy` command orchestrates a series of steps to prepare, configure, bundle, and deploy your agent. It leverages the `@blocklet/cli` under the hood to handle the complexities of Blocklet creation.

Here is a high-level overview of the deployment flow:

![---](https://media.arcblock.io/lib/b2/b2bfd40289e38e74.w1600.webp)

### Step-by-Step Walkthrough

To deploy your project, navigate to your project's root directory and run the deployment command, specifying the path to your project and the target endpoint.

**Command**

```bash
aigne deploy --path . --endpoint <your-endpoint-url>
```

Let's break down what happens when you execute this command:

1. <strong>Environment Preparation</strong>: The CLI first creates a temporary `.deploy` directory. It copies your project files into it, along with a standard Blocklet template. It then runs `npm install` inside this directory to fetch any necessary dependencies.
2. <strong>Blocklet CLI Check</strong>: The process verifies if `@blocklet/cli` is installed on your system. If not, it will prompt you for permission to install it globally. This is a one-time setup. ``` ? Install Blocklet CLI? › ❯ yes   no ```
3. <strong>Blocklet Configuration (First-time Deployment)</strong>: If this is the first time you're deploying this project, the CLI will ask you for a name for your Blocklet. It suggests a default based on your agent's name in `aigne.yaml` or the project's folder name. ``` ? Please input agent blocklet name: › my-awesome-agent ```  After you provide a name, it automatically generates a new Decentralized Identifier (DID) for your Blocklet. This name and DID are saved locally in `~/.aigne/deployed.yaml`, so you won't be prompted for them on subsequent deployments of the same project.
4. <strong>Bundling</strong>: The CLI then invokes `blocklet bundle --create-release`, which packages your agent, its dependencies, and all necessary configuration into a single, deployable `.blocklet/bundle` file.
5. <strong>Deployment</strong>: Finally, the bundled application is pushed to your specified `--endpoint` using the `blocklet deploy` command.

Once the process is complete, you'll see a confirmation message in your terminal.

```
✅ Deploy completed: /path/to/your/project -> <your-endpoint-url>
```

Your AIGNE agent is now live as a Blocklet, ready to be run in a production environment.

---

## Running Remote Agents

URL: https://www.arcblock.io/en/docs/aigne-cli/guides-running-remote-agents-cdbd13/

## labels: ["Reference"]

## labels: ["Reference"]

The AIGNE CLI is not limited to running projects from your local filesystem. It also provides a powerful feature to execute agents directly from a remote URL. This is incredibly useful for testing, sharing, and running agents without needing to clone a repository or manually download files.

This guide will walk you through how to run agents from a remote source and explain the underlying caching mechanism.

## How It Works

When you provide a URL to the `aigne run` command, the CLI performs the following steps automatically:

::::steps
:::step{title="Download"}
It fetches the package from the provided HTTP/HTTPS URL.
:::

:::step{title="Cache"}
The downloaded package is stored in a local cache directory (`~/.aigne/` by default). This speeds up subsequent runs of the same remote agent, as the CLI will use the cached version if it already exists.
:::

:::step{title="Extract"}
The CLI extracts the contents of the package (which is expected to be a tarball) into a working directory within the cache.
:::

:::step{title="Execute"}
Finally, it loads the AIGNE application from the extracted files and runs the specified agent just as it would with a local project.
:::
::::

The entire process is streamlined to provide a seamless experience, making a remote agent feel as accessible as a local one.

![---](https://media.arcblock.io/lib/76/76a4277d8816a313.w1600.webp)

## Usage

To run a remote agent, simply pass the URL pointing to a tarball (`.tar.gz`, `.tgz`) of an AIGNE project to the `aigne run` command.

### Basic Command

**AIGNE CLI**

```bash
# Run the default agent from a remote AIGNE project
aigne run https://example.com/path/to/your/aigne-project.tar.gz
```

### Running a Specific Agent

If the remote project contains multiple agents, you can specify which one to run by adding its name after the URL.

**AIGNE CLI**

```bash
# Run a specific agent named 'my-agent' from the remote project
aigne run https://example.com/path/to/your/aigne-project.tar.gz my-agent
```

Any additional arguments or options you provide will be passed directly to the remote agent.

**AIGNE CLI**

```bash
# Run a specific agent with additional options
aigne run https://example.com/path/to/your/aigne-project.tar.gz my-agent --input "Hello, world!"
```

## Caching

AIGNE CLI automatically caches the downloaded remote agents to avoid re-downloading them on every run.

- <strong>Default Location</strong>: The cache is stored in the `.aigne` directory within your home directory (e.g., `~/.aigne/`). The exact path within the cache is determined by the URL's hostname and path, ensuring that different remote agents are stored separately.
- <strong>Overriding the Cache Directory</strong>: While the default location is suitable for most cases, you can specify a custom cache directory using the `--cache-dir` option. This can be useful for CI/CD environments or for managing different sets of cached agents.

**AIGNE CLI**

```bash
# Use a custom directory for caching the downloaded package
aigne run https://example.com/path/to/your/aigne-project.tar.gz --cache-dir /tmp/aigne-cache
```

This powerful feature simplifies collaboration and distribution of AIGNE agents. You can now move on to learn how to deploy your agents for production use.

:::action-card{title="Deploying Agents" description="Learn how to deploy your AIGNE project as a Blocklet for production use." icon="rocket"}
::action{label="Read Guide" href="/en/docs/aigne-cli/guides-deploying-agents-cdbd13/" variant="primary"}
:::

---

## Overview

URL: https://www.arcblock.io/en/docs/aigne-cli/overview-cdbd13/

![AIGNE Logo](https://media.arcblock.io/lib/58/580b6888d6e6d590.svg)

Your command center for agent development

`@aigne/cli` is the official command-line tool for the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework), designed to streamline the entire lifecycle of agent development. It provides a comprehensive suite of commands to simplify project creation, local execution, testing, and deployment, enabling you to build, run, and manage AIGNE applications with ease.

## Key Features

`@aigne/cli` is packed with features to accelerate your agent development workflow.

::::card-group
::link-card{title="Project Scaffolding" description="Quickly create new AIGNE projects with predefined file structures and configurations using the `aigne create` command." icon="folder-plus"}
::link-card{title="Local Agent Execution" description="Easily run and interact with your agents in a local chat loop for rapid testing and debugging via `aigne run`." icon="play"}
::link-card{title="Automated Testing" description="Leverage the built-in `aigne test` command for running unit and integration tests to ensure your agents are robust and reliable." icon="activity"}
::link-card{title="MCP Server Integration" description="Launch your agents as Model Context Protocol (MCP) servers, allowing them to be integrated with external systems." icon="server"}
::link-card{title="Rich Observability" description="Start a local server with `aigne observe` to view and analyze agent execution traces and performance data." icon="bar-chart"}
::link-card{title="Multi-Model Support" description="Seamlessly switch between different AI model providers, including OpenAI, Claude, XAI, and others." icon="bot"}
::::

Ready to get started? Follow our [Getting Started](/en/docs/aigne-cli/getting-started-cdbd13/) guide to install the CLI and create your first AIGNE agent.

---

## AIGNE Framework

URL: https://www.arcblock.io/en/docs/aigne-framework/

---

## Agent Library

URL: https://www.arcblock.io/en/docs/aigne-framework/agent-library-9dc03e/

The Agent Library provides a collection of pre-built, reusable agents designed to accelerate the development of complex AI applications. By integrating these ready-made components, you can easily orchestrate sophisticated workflows, manage concurrent tasks, and automate multi-step processes without building everything from the ground up.

## Introduction

`@aigne/agent-library` is an official package for the AIGNE Framework that provides powerful, pre-built agent implementations. Built on `@aigne/core`, this library extends the framework's fundamental capabilities to simplify the orchestration of intricate agentic workflows, allowing developers to focus on high-level logic rather than foundational implementation details.

Key features of the library include:

- <strong>Advanced Agent Patterns</strong>: Offers high-level agent implementations, such as the `OrchestratorAgent`, for managing complex task execution flows.
- <strong>Concurrent Task Execution</strong>: Supports the parallel execution of multiple tasks, significantly improving processing efficiency for demanding workloads.
- <strong>Automated Planning</strong>: Capable of automatically generating step-by-step execution plans based on a high-level objective.
- <strong>Result Synthesis</strong>: Intelligently aggregates and synthesizes results from various tasks and steps to produce a coherent final output.
- <strong>Full TypeScript Support</strong>: Includes comprehensive type definitions to ensure a robust and type-safe development experience.

## Installation

To get started, install the necessary packages using your preferred package manager. You will need both `@aigne/agent-library` and its core dependency, `@aigne/core`.

**Install with npm**

```sh
npm install @aigne/agent-library @aigne/core
```

**Install with yarn**

```sh
yarn add @aigne/agent-library @aigne/core
```

**Install with pnpm**

```sh
pnpm add @aigne/agent-library @aigne/core
```

## Available Agents

The library includes specialized agents designed for advanced use cases. Each agent is documented in its own section for detailed guidance.

The following diagram illustrates the high-level architecture of the `OrchestratorAgent`:

![Agent Library](https://media.arcblock.io/lib/9a/9ada5d72a457aaf1.w1600.webp)

::::card-group
::link-card{title="Orchestrator Agent" description="An advanced agent that autonomously plans, executes, and synthesizes results for complex objectives. It uses a Planner → Worker → Completer architecture to coordinate multi-step workflows." icon="routes" href="/en/docs/aigne-framework/agent-library-orchestrator-9dc03e/"}
::::

## Summary

The Agent Library is a vital toolkit for any developer looking to build sophisticated, multi-agent systems with the AIGNE Framework. It provides the foundational components for automating complex processes and orchestrating workflows efficiently. To dive deeper into the primary component of this library, proceed to the [Orchestrator](/en/docs/aigne-framework/agent-library-orchestrator-9dc03e/) documentation.

---

## Bash

URL: https://www.arcblock.io/en/docs/aigne-framework/agent-library-bash-9dc03e/

This document details the Bash agent, which allows for the secure execution of shell scripts and command-line tools within an agentic workflow. You will learn how to configure its sandboxed environment, manage command permissions, and integrate it into your applications for system-level operations.

## Overview

The Bash agent is designed to execute bash scripts within a controlled and secure environment. It leverages Anthropic's Sandbox Runtime to provide an isolated execution space, offering fine-grained control over system access, including network and filesystem operations. This makes it an ideal tool for tasks requiring file manipulation, process management, and automation of shell commands without compromising system security.

Key features include:

- <strong>Sandboxed Execution</strong>: Scripts are run in an isolated environment with configurable access controls for network and filesystem resources.
- <strong>Command Permissions</strong>: A robust permission system allows you to whitelist, blacklist, or require approval for specific commands, preventing unauthorized operations.
- <strong>Real-time Output</strong>: Standard output (`stdout`) and standard error (`stderr`) are streamed in real-time as the script executes.
- <strong>Guard Agents</strong>: For commands requiring approval, you can designate another agent (an "AI guard") to dynamically approve or deny execution based on custom logic.

> [!WARNING]
> Sandbox mode is not supported on Windows. Windows users must explicitly set `sandbox: false` in their configuration to use the Bash agent. Disabling the sandbox removes all security protections and should only be done in trusted environments.

### Architecture

The agent processes a script and, depending on whether the sandbox is enabled, either runs it directly or within the sandboxed environment. The output, including `stdout`, `stderr`, and the final `exitCode`, is streamed back to the caller.

```mermaid
flowchart TB
    Input([Script Input]) --> BashAgent[Bash Agent]
    BashAgent --> SandboxCheck{SandboxEnabled?}

    SandboxCheck -->|Yes| Sandbox[Sandbox Execution]
    SandboxCheck -->|No| Direct[Direct Execution]

    Sandbox --> ShellProcess[Shell Process]
    Direct --> ShellProcess

    ShellProcess --> StreamOutput[Stream Output]
    StreamOutput --> Output([stdout, stderr, exitCode])

    classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px
    classDef process fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px
    classDef decision fill:#E8F4F8,stroke:#4A9EBF,stroke-width:2px

    class Input,Output inputOutput
    class BashAgent,ShellProcess,StreamOutput process
    class SandboxCheck decision
    class Sandbox,Direct process
```

## Basic Usage

The most straightforward way to use the Bash Agent is by defining it in a YAML file. This allows you to configure its behavior declaratively.

### Standard Sandboxed Mode

By default, the Bash agent runs in a secure, sandboxed environment.

**bash-agent.yaml**

```yaml
type: "@aigne/agent-library/bash"
name: Bash

# The input schema defines the 'script' parameter
input_schema:
  type: object
  properties:
    script:
      type: string
      description: The bash script to execute.
  required:
    - script
```

You can then execute a script using the AIGNE CLI:

```bash
aigne run . Bash --script 'echo "Hello from the Bash Agent!"'
```

### Disabling the Sandbox

For development, trusted environments, or on Windows, you can disable the sandbox.

**bash-agent-no-sandbox.yaml**

```yaml
type: "@aigne/agent-library/bash"
name: Bash
sandbox: false # Disable the sandbox

input_schema:
  type: object
  properties:
    script:
      type: string
      description: The bash script to execute.
  required:
    - script
```

> [!CAUTION]
> Disabling the sandbox removes all security protections. This should only be done in environments where you fully trust the scripts being executed.

## Configuration

The Bash agent can be configured with several options to control its execution environment and security settings.

- **sandbox** `object | boolean` (default: `true`) — Configuration for the sandboxed environment based on Anthropic's Sandbox Runtime. Set to false to disable sandboxing. Defaults to true with default restrictions.
- **timeout** `number` (default: `60000`) — Execution timeout in milliseconds. The script will be terminated if it exceeds this limit.
- **permissions** `object` — Configuration for command execution permissions, including allow, deny, defaultMode, and a guard agent.

### Input and Output

The agent accepts a simple input object and produces a detailed output object.

#### Input Schema

- **script** `string` *(required)* — The bash script to be executed.

#### Output Schema

- **stdout** `string` — The standard output produced by the script.
- **stderr** `string` — The standard error output produced by the script.
- **exitCode** `number` — The exit code of the script. A value of `0` typically indicates success.

## Sandbox Configuration

The sandbox provides a secure layer for script execution by restricting access to network and filesystem resources.

### Network Control

You can specify which domains a script is allowed or forbidden to access.

**network-config.yaml**

```yaml
sandbox:
  network:
    # A list of allowed domains. Wildcards are supported.
    allowedDomains:
      - "api.github.com"
      - "*.example.com"
    # A list of denied domains, which takes precedence over the allow list.
    deniedDomains:
      - "*.ads.com"
```

### Filesystem Control

Define read and write permissions for specific paths or patterns.

**filesystem-config.yaml**

```yaml
sandbox:
  filesystem:
    # A list of paths where writing is permitted.
    allowWrite:
      - "./output"
      - "/tmp"
    # A list of paths where writing is forbidden.
    denyWrite:
      - "/etc"
      - "/usr"
    # A list of paths where reading is forbidden.
    denyRead:
      - "~/.ssh"
      - "*.key"
```

## Permissions Configuration

The permissions system controls which commands can be executed. It operates with a clear priority: `deny` rules override `allow` rules, and `allow` rules override the `defaultMode`.

### Permission Properties

- **allow** `string[]` — A whitelist of commands that are permitted to execute without approval. Supports exact match (git status) and prefix matching with a wildcard (ls:*).
- **deny** `string[]` — A blacklist of commands that are strictly forbidden. This list has the highest priority.
- **defaultMode** `string` (default: `allow`) — The default behavior for commands not matching allow or deny lists. Possible values are allow, ask, or deny.
- **guard** `Agent` — An agent invoked when defaultMode is ask. It receives the script and must return a boolean approved status.

### Example with a Guard Agent

When `defaultMode` is set to `ask`, you must provide a `guard` agent to approve or reject commands. The guard agent receives the script as input and must return an object containing an `approved` boolean and an optional `reason` string.

**guard-config.yaml**

```yaml
type: "@aigne/agent-library/bash"
name: Bash
permissions:
  allow:
    - "echo:*"
    - "ls:*"
  deny:
    - "rm:*"
    - "sudo:*"
  defaultMode: "ask"
  guard:
    type: "ai"
    model: "anthropic/claude-3-5-sonnet-20241022"
    instructions: |
      You are a security guard for bash command execution.
      Analyze the requested script and decide whether to approve it.

      Script to evaluate:
      ```bash
      {{script}}
      ```

      Approve safe, read-only operations. Deny any command that
      could modify or delete files, or alter system state.
    output_schema:
      type: object
      properties:
        approved:
          type: boolean
          description: Whether to approve the script execution.
        reason:
          type: string
          description: An explanation for the decision.
      required:
        - approved
```

## Best Practices

- <strong>Use the Sandbox</strong>: Always enable the sandbox in production environments to mitigate security risks.
- <strong>Principle of Least Privilege</strong>: Configure sandbox and permission rules to grant only the minimum access necessary for the task.
- <strong>Deny Dangerous Commands</strong>: Explicitly add destructive commands like `rm`, `sudo`, and `dd` to the `deny` list.
- <strong>Handle Exit Codes</strong>: Check the `exitCode` in the agent's output to detect and handle script failures. An exit code other than `0` usually indicates an error, and details can be found in `stderr`.
- <strong>Protect Sensitive Files</strong>: Use `denyRead` to prevent access to sensitive files and directories such as `~/.ssh`, `.env` files, and private keys.

---

## Orchestrator

URL: https://www.arcblock.io/en/docs/aigne-framework/agent-library-orchestrator-9dc03e/

The Orchestrator agent provides a structured, reliable solution for managing complex, multi-step AI workflows. It breaks down high-level objectives into a series of manageable tasks, executes them sequentially, and synthesizes the results into a final, coherent response, enabling autonomous task planning and execution.

This document details the architecture, configuration, and practical application of the Orchestrator agent.

## Overview

The Orchestrator agent implements a sophisticated pattern for autonomous task management using a three-phase architecture: <strong>Planner → Worker → Completer</strong>. This structure allows it to handle complex objectives that require multiple steps, tools, and iterative refinement.

The core components are:

- <strong>Planner</strong>: Analyzes the main objective and the current progress to determine the most logical next task.
- <strong>Worker</strong>: Executes the specific task assigned by the Planner, using any available tools or skills.
- <strong>Completer</strong>: Once all tasks are finished, it reviews the entire execution history and synthesizes the individual results into a final, comprehensive output.
- <strong>Execution State</strong>: A record-keeping component that tracks the history, status, and results of all tasks performed during the workflow.

This iterative process continues until the Planner determines that the overall objective has been achieved.

## Architecture

The workflow is a loop where the Planner and Worker collaborate until the objective is met, followed by a final synthesis step from the Completer. The following diagram illustrates this process:

![Orchestrator](https://media.arcblock.io/lib/81/81d32c36f1cad4b5.w1600.webp)

The process unfolds as follows:

::::steps
:::step{title="Initialization"}
The Orchestrator receives a high-level objective and initializes an empty execution state.
:::

:::step{title="Planning"}
The Planner examines the objective and the current state (initially empty) and devises the first task.
:::

:::step{title="Execution"}
The Worker receives the task from the Planner and executes it. The outcome (success or failure, along with results or errors) is recorded.
:::

:::step{title="State Update"}
The result of the task is appended to the Execution State.
:::

:::step{title="Iteration"}
The process repeats from Step 2. The Planner now reviews the objective and the updated history in the Execution State to determine the next task.
:::

:::step{title="Completion"}
When the Planner decides the objective is complete, it signals the end of the loop. The Completer then takes over, reviews the full history in the Execution State, and generates the final response.
:::
::::

## Basic Usage

The most direct method for configuring an Orchestrator agent is through a YAML definition file.

### Example Configuration

Here is a basic setup to create an orchestrator that analyzes a project structure.

**agents/orchestrator.yaml**

```yaml
type: "@aigne/agent-library/orchestrator"
name: orchestrator

# Define the overall objective for the agent.
# External files can be used for cleaner separation.
objective:
  url: objective.md

# Configure state management to control the workflow's execution.
state_management:
  max_iterations: 20      # Set a limit on planning-execution cycles.
  max_tokens: 100000      # Set a token limit for the execution state context.
  keep_recent: 20         # Keep the 20 most recent tasks when compressing state.

# Configure the Agent File System (AFS) to provide a workspace.
afs:
  modules:
    - module: local-fs
      options:
        name: workspace
        localPath: .
        description: Workspace directory for the orchestrator agent.
```

The `objective.md` file contains the primary goal for the agent.

**agents/objective.md**

```markdown
Analyze the project structure and generate a comprehensive report.

- Ignore node_modules, .git, dist, build directories.
- Provide accurate information based on actual file contents.
- Include key findings and recommendations.

{% if message %}
## User Instructions
{{ message }}
{% endif %}
```

Finally, the main `aigne.yaml` file ties everything together.

**aigne.yaml**

```yaml
#!/usr/bin/env aigne

model: google/gemini-1.5-pro
agents:
  - agents/orchestrator.yaml
```

## Configuration Reference

The Orchestrator agent is configured through a set of options that define its behavior, components, and constraints.

### Top-Level Options

- **objective** `PromptBuilder` *(required)* — The overall objective for the orchestrator to achieve.
- **planner** `Agent` — A custom agent to handle the planning phase. If not provided, a default planner is used.
- **worker** `Agent` — A custom agent to handle the execution phase. If not provided, a default worker is used.
- **completer** `Agent` — A custom agent to handle the completion phase. If not provided, a default completer is used.
- **stateManagement** `object` — Configuration for managing the execution state.
- **inputSchema** `ZodSchema` — A schema to validate the input data. This is required if you use custom variables in your objective template.
- **outputSchema** `ZodSchema` — A schema to validate the final output from the completer.
- **afs** `AFSOptions` — Configuration for the Agent File System, making files and directories available to all components.
- **skills** `Agent[]` — A list of tools or skills available to the worker agent.
- **model** `string` — A default model to be used by all components (planner, worker, completer) unless overridden in a component's specific configuration.

> [!NOTE]
> When using custom input variables like `{{ message }}` in your `objective` prompt, you must declare them in the `inputSchema`. Any undeclared variable will not be passed to the template.

### StateManagementOptions

These options control the execution loop and prevent infinite runs or context overflow.

- **maxIterations** `number` (default: `20`) — The maximum number of planning-execution cycles to perform.
- **maxTokens** `number` — The maximum number of tokens allowed for the execution state history passed to the agents.
- **keepRecent** `number` — The number of recent tasks to retain when the state is compressed due to token limits.

## Customizing Components

You can replace the default Planner, Worker, or Completer with your own custom agents to tailor the orchestrator's logic to a specific domain. This is typically done by creating an AI agent with custom instructions.

### Custom Planner

The Planner's role is to decide the next action.

- <strong>Standard Input</strong>: `objective`, `skills`, `executionState`.
- <strong>Standard Output</strong>: An object containing `nextTask` (string) and `finished` (boolean).

<strong>Example Configuration:</strong>

**agents/orchestrator.yaml**

```yaml
type: "@aigne/agent-library/orchestrator"
objective:
  url: objective.md
planner:
  type: ai
  instructions:
    url: custom-planner.md
```

<strong>Example Instructions (</strong><strong>`custom-planner.md`</strong><strong>):</strong>

```markdown
## Your Role
You are a strategic planner for code analysis tasks. Your responsibility is to decide the next single task to perform based on the overall objective and the history of completed tasks.

## Objective
{{ objective }}

## Available Skills
{{ skills | yaml.stringify }}

## Current Execution State
{{ executionState | yaml.stringify }}

## Planning Guidelines
- Review `executionState` to avoid repeating work.
- Decompose the objective into small, logical steps.
- Plan only one task at a time.
- If all work is done, set `finished: true`.

## Output Format
Return a JSON object with the following fields:
- `nextTask`: A string describing the next task to execute. Omit this field if finished.
- `finished`: A boolean indicating if the objective is complete.
```

### Custom Worker

The Worker's role is to execute a single task.

- <strong>Standard Input</strong>: `objective`, `task`, `executionState`.
- <strong>Standard Output</strong>: An object containing `success` (boolean), `result` (string, on success), and `error` (object with `message`, on failure).

<strong>Example Configuration:</strong>

**agents/orchestrator.yaml**

```yaml
# ...
worker:
  type: ai
  instructions:
    url: custom-worker.md
```

<strong>Example Instructions (</strong><strong>`custom-worker.md`</strong><strong>):</strong>

```markdown
## Your Role
You are a professional code analysis worker. Your job is to execute the assigned task using the available tools.

## Overall Objective (For Context Only)
{{ objective }}

## Current Task
{{ task }}

## Execution Guidelines
- Focus strictly on completing the `Current Task`.
- Use the provided tools and skills to accomplish the task.
- If successful, provide the result. If not, explain the failure in the error message.

## Output Format
Return a JSON object with the following fields:
- `success`: A boolean indicating if the task succeeded.
- `result`: A string with the task's output. Required on success.
- `error`: An object with a `message` field. Required on failure.
```

### Custom Completer

The Completer's role is to synthesize the final report.

- <strong>Standard Input</strong>: `objective`, `executionState`.
- <strong>Standard Output</strong>: A user-defined structure, validated against the orchestrator's `output_schema`.

<strong>Example Configuration:</strong>

**agents/orchestrator.yaml**

```yaml
# ...
completer:
  type: ai
  instructions:
    url: custom-completer.md
  output_schema:
    type: object
    properties:
      summary:
        type: string
        description: An executive summary of the findings.
      recommendations:
        type: array
        items:
          type: string
        description: A list of actionable recommendations.
    required: [summary]
```

<strong>Example Instructions (</strong><strong>`custom-completer.md`</strong><strong>):</strong>

```markdown
## Your Role
You are responsible for synthesizing all task results from the execution history into a final, structured response.

## User Objective
{{ objective }}

## Execution Results
{{ executionState | yaml.stringify }}

## Synthesis Guidelines
- Analyze all successful and failed tasks in `executionState`.
- Consolidate the individual results into a coherent report.
- Structure your response according to the defined output schema.

## Output Format
Return a JSON object conforming to the output schema.
```

## Best Practices

To maximize the effectiveness of the Orchestrator agent, adhere to the following principles.

### 1. Define Clear Objectives

Provide specific, actionable, and unambiguous objectives. A well-defined goal is critical for the Planner to create a logical task sequence.

- <strong>Good</strong>: "Analyze the authentication system in `/src/auth`, identify security vulnerabilities, and provide specific recommendations for each issue found."
- <strong>Poor</strong>: "Look at the code and tell me what's wrong."

### 2. Specialize Component Roles

Ensure each component focuses on its designated role. The Planner should only plan, not execute. The Worker should only execute its current task, not plan future ones.

### 3. Use State Compression for Long Workflows

For complex objectives that may require many iterations, configure state management to prevent the context from becoming too large for the model.

```yaml
state_management:
  max_iterations: 50
  max_tokens: 80000      # Prevent context overflow
  keep_recent: 25        # Keep recent task history for context
```

### 4. Use Different Models for Different Components

Optimize for cost and performance by assigning different models to each component based on its needs. A powerful model for planning and synthesis, and a faster, cheaper model for execution, is often a cost-effective strategy.

```yaml
planner:
  type: ai
  model: anthropic/claude-3-5-sonnet-20240620

worker:
  type: ai
  model: google/gemini-1.5-flash

completer:
  type: ai
  model: anthropic/claude-3-5-sonnet-20240620
```

### 5. Validate Inputs and Outputs

Use `input_schema` and `output_schema` to enforce type safety and ensure the agent receives and produces data in the expected format. This is especially critical when the objective prompt uses template variables.

---

## Advanced Topics

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-advanced-topics-9dc03e/

After mastering the core concepts and building basic applications, you are ready to explore the more sophisticated features of the AIGNE Framework. This section is designed for developers seeking to build complex, robust, and highly customized AI applications. Here, we will delve into advanced patterns and tools that provide greater control over agent definition, prompt engineering, execution lifecycle, and data handling.

The following topics provide in-depth guides to leveraging these advanced capabilities. Understanding them will enable you to move from simple agentic workflows to building enterprise-grade AI systems.

::::card-group
::link-card{title="Defining Agents with YAML" description="Learn how to define and configure agents declaratively using YAML files. This approach separates configuration from code, making your agentic systems easier to manage, version, and deploy." icon="file" href="/en/docs/aigne-framework/developer-guide-advanced-topics-defining-agents-with-yaml-9dc03e/"}
::link-card{title="Prompts" description="Dive deep into dynamic prompt management with the PromptBuilder. This guide covers using Nunjucks templating to create flexible, reusable, and context-aware prompts for your AI models." icon="terminal" href="/en/docs/aigne-framework/developer-guide-advanced-topics-prompts-9dc03e/"}
::link-card{title="Hooks" description="Understand the agent execution lifecycle and how to intercept it with hooks. Learn to add custom logic, logging, or monitoring at various stages like onStart, onEnd, and onSkillStart." icon="git-pull-request" href="/en/docs/aigne-framework/developer-guide-advanced-topics-hooks-9dc03e/"}
::link-card{title="Streaming" description="Discover how to process real-time, streaming responses from agents. This is essential for creating responsive, conversational applications that deliver information as it becomes available." icon="chevrons-right" href="/en/docs/aigne-framework/developer-guide-advanced-topics-streaming-9dc03e/"}
::::

## Summary

This section provides the tools and techniques necessary to elevate your AI applications. By leveraging declarative definitions, dynamic prompts, lifecycle hooks, and streaming, you can build more powerful, maintainable, and efficient agentic systems.

For further details, please proceed to the specific sub-sections linked above. To see how these components fit into the broader architecture, refer to the [Core Concepts](/en/docs/aigne-framework/developer-guide-core-concepts-9dc03e/) documentation.

---

## Defining Agents with YAML

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-advanced-topics-defining-agents-with-yaml-9dc03e/

The AIGNE Framework supports a declarative approach for defining agents using YAML configuration files. This method separates the agent's definition (its properties, instructions, and skills) from the application's business logic, promoting better organization, reusability, and easier management of complex agentic systems.

This guide provides a comprehensive overview of the YAML syntax for defining various agent types and their properties.

## Basic Structure

Every agent definition, regardless of its type, is contained within a `.yaml` file. The `type` attribute is the primary discriminator that determines the agent's behavior and required properties. If the `type` is omitted, it defaults to `ai`.

Here is a fundamental example of an AI agent configuration:

**chat.yaml**

```yaml
name: Basic Chat Agent
description: A simple agent that responds to user messages.
type: ai
instructions: "You are a helpful assistant. Respond to the user's message concisely."
input_key: message
skills:
  - my-skill.js
```

### Core Properties

The following properties are common across most agent types:

- **name** `string` — A human-readable name for the agent.
- **description** `string` — A brief description of the agent's purpose and capabilities.
- **type** `string` (default: `ai`) — Specifies the agent's type. Determines the required fields and behavior. Valid types include ai, image, team, transform, mcp, and function.
- **model** `object | string` — Configuration for the chat model used by the agent, overriding any globally defined model. Can be a string or a detailed object.
- **skills** `array` — A list of other agents or JavaScript/TypeScript functions that this agent can use as tools. Each skill is referenced by its file path.
- **inputSchema** `object | string` — A JSON schema defining the expected input structure. Can be an inline object or a path to an external .json or .yaml file.
- **outputSchema** `object | string` — A JSON schema for structuring the agent's output. Can be an inline object or a path to an external file. This is crucial for enabling structured output.
- **memory** `boolean | object` — Enables statefulness for the agent. Set to true for default memory or provide a configuration object for specific providers.
- **hooks** `array` — Defines lifecycle hooks (onStart, onSuccess, onError, onEnd) that trigger other agents at different stages of execution.

## Loading External Prompts and Schemas

To maintain clean and modular configurations, you can load agent instructions and schemas from external files. This is particularly useful for complex prompts or reusable data structures.

### External Instructions

For `ai` and `image` agents, instructions can be lengthy. You can define them in a separate Markdown or text file and reference it using the `url` key.

**chat-with-prompt.yaml**

```yaml
name: chat-with-prompt
description: An AI agent with instructions loaded from an external file.
type: ai
instructions:
  url: prompts/main-prompt.md
input_key: message
memory: true
skills:
  - skills/sandbox.js
```

The `main-prompt.md` file contains the raw text that will be used as the agent's system prompt.

**prompts/main-prompt.md**

```markdown
You are a master programmer. When the user asks for code, provide a complete, runnable example and explain the key parts.
```

You can also construct a multi-part prompt with different roles:

**multi-role-prompt.yaml**

```yaml
instructions:
  - role: system
    url: prompts/system-role.md
  - role: user
    content: "Here is an example of a good response:"
  - role: assistant
    url: prompts/example-response.md
```

### External Schemas

Similarly, `inputSchema` and `outputSchema` can reference external JSON or YAML files that define the schema structure.

**structured-output-agent.yaml**

```yaml
name: JSON Extractor
type: ai
instructions: Extract the user's name and email from the text.
outputSchema: schemas/user-schema.yaml
```

The `user-schema.yaml` file would contain the JSON schema definition:

**schemas/user-schema.yaml**

```yaml
type: object
properties:
  name:
    type: string
    description: The full name of the user.
  email:
    type: string
    description: The email address of the user.
required:
  - name
  - email
```

## Agent Type Specifics

The following sections detail the unique configuration properties for each agent type.

### AI Agent (type: ai)

The `AIAgent` is the most common type, designed for general-purpose interaction with language models.

**ai-agent-example.yaml**

```yaml
type: ai
name: Customer Support AI
instructions:
  url: prompts/support-prompt.md
input_key: customer_query
output_key: response
# Enforce the model to call a specific skill
tool_choice: "sandbox"
outputSchema: schemas/support-response.yaml
skills:
  - sandbox.js
```

- **instructions** `string | object | array` — The system prompt or instructions for the AI model. Can be a simple string, a reference to an external file (url), or an array of message objects (role, content/url).
- **inputKey** `string` — The key in the input object that contains the main user message to be sent to the model.
- **outputKey** `string` — The key under which the AI's final text response will be placed in the output object.
- **toolChoice** `string` — Forces the model to use a specific skill (tool). The value must match the name of a skill attached to the agent.

### Team Agent (type: team)

The `TeamAgent` orchestrates a collection of child agents (defined under `skills`) to perform a multi-step task.

**team-agent-example.yaml**

```yaml
type: team
name: Research and Write Team
# Agents will run one after another
mode: sequential
# The output of this team will be the collected outputs of all steps
include_all_steps_output: true
skills:
  - url: agents/researcher.yaml
  - url: agents/writer.yaml
  - url: agents/editor.yaml
```

- **mode** `string` (default: `sequential`) — The execution mode for the team. Can be sequential (agents run in order) or parallel (agents run concurrently).
- **iterateOn** `string` — The key in the input object containing an array. The team will execute its workflow for each item in the array.
- **reflection** `object` — Configures a self-correction loop where a reviewer agent inspects the output and can trigger re-runs until the output is approved.

### Image Agent (type: image)

The `ImageAgent` is specialized for generating images using an image model.

**image-agent-example.yaml**

```yaml
type: image
name: Logo Generator
instructions: "A minimalist, flat-design logo for a tech startup named 'Innovate'."
# Pass through specific options to the image model provider
model_options:
  quality: hd
  style: vivid
```

- **instructions** `string | object` *(required)* — The prompt describing the desired image. Unlike the AI agent, this is a mandatory field.
- **modelOptions** `object` — A key-value map of provider-specific options to control image generation (e.g., quality, style, size).

### Transform Agent (type: transform)

The `TransformAgent` uses a [JSONata](https://jsonata.org/) expression to declaratively map, filter, or restructure JSON data without writing code.

**transform-agent-example.yaml**

```yaml
type: transform
name: User Formatter
description: Extracts and formats user names from a list.
jsonata: "payload.users.{'name': firstName & ' ' & lastName}"
```

- **jsonata** `string` *(required)* — The JSONata expression to execute against the input data.

## Summary

Defining agents via YAML offers a powerful, declarative alternative to programmatic definition. It allows for clear separation of concerns, enhances reusability, and simplifies the management of agent configurations. By leveraging external files for prompts and schemas, you can build complex, modular, and maintainable AI systems.

For more hands-on examples, refer to the other guides in the [Advanced Topics](/en/docs/aigne-framework/developer-guide-advanced-topics-9dc03e/) section.

---

## Hooks

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-advanced-topics-hooks-9dc03e/

Hooks provide a powerful mechanism to observe, intercept, and inject custom logic into an agent's execution lifecycle. They allow you to add functionalities like logging, monitoring, input/output transformation, and custom error handling without altering the core implementation of an agent.

This guide details the agent execution lifecycle, the available hooks, and how to implement them effectively.

## Agent Execution Lifecycle

Understanding the agent's execution lifecycle is crucial for using hooks correctly. When an agent is invoked, it proceeds through a series of steps, with hooks being triggered at specific points.

The following diagram illustrates the sequence of events and the corresponding hooks that are called during an agent's invocation.

![Hooks](https://media.arcblock.io/lib/27/27bf289dc972d118.w1600.webp)

## Available Hooks

Hooks are defined within an `AgentHooks` object. Each hook can be implemented as either a function or a separate, dedicated agent.

- **onStart** `function | Agent` — Triggered at the very beginning of an agent's invocation, before input validation. It can be used to modify the initial input or options.
- **onSuccess** `function | Agent` — Triggered after the agent's process method completes successfully and the output has been validated. It can be used to transform the final output.
- **onError** `function | Agent` — Triggered when an error is thrown during any stage of the execution. It can be used to implement custom error logging or a retry mechanism by returning { retry: true }.
- **onEnd** `function | Agent` — Triggered at the very end of an agent's invocation, regardless of whether it succeeded or failed. It's suitable for cleanup tasks, final logging, or metric collection.
- **onSkillStart** `function | Agent` — Triggered just before an agent invokes one of its skills (a sub-agent). This is useful for tracing the delegation of tasks between agents.
- **onSkillEnd** `function | Agent` — Triggered after a skill invocation completes, whether it succeeds or fails. It receives the skill's result or the error.
- **onHandoff** `function | Agent` — Triggered when an agent's process method returns another agent instance, effectively handing off control. This allows for monitoring of agent-to-agent transfers.

## Implementing Hooks

Hooks can be attached to an agent in three ways:

1. During agent instantiation via the `hooks` property in `AgentOptions`.
2. At invocation time via the `hooks` property in `AgentInvokeOptions`.
3. Globally on the `AIGNEContext` instance.

### Example 1: Basic Logging

Here is a simple example of a hook that logs the start and end of an agent's execution.

**Agent Logging Hook**

```typescript
import { Agent, AIGNE, type AgentHooks } from "@aigne/core";

// Define the logging hook
const loggingHook: AgentHooks = {
  onStart: ({ agent, input }) => {
    console.log(`[${agent.name}] Starting execution with input:`, input);
  },
  onEnd: ({ agent, input, output, error }) => {
    if (error) {
      console.error(`[${agent.name}] Execution failed for input:`, input, "Error:", error);
    } else {
      console.log(`[${agent.name}] Execution succeeded with output:`, output);
    }
  },
};

// Define a simple agent
class MyAgent extends Agent {
  async process(input: { message: string }) {
    return { reply: `You said: ${input.message}` };
  }
}

// Instantiate the agent with the hook
const myAgent = new MyAgent({
  name: "EchoAgent",
  hooks: [loggingHook],
});

const aigne = new AIGNE();
await aigne.invoke(myAgent, { message: "hello" });

// Console Output:
// [EchoAgent] Starting execution with input: { message: 'hello' }
// [EchoAgent] Execution succeeded with output: { reply: 'You said: hello' }
```

### Example 2: Modifying Input with onStart

The `onStart` hook can return an object to modify the `input` that the agent will receive.

**Modifying Agent Input**

```typescript
import { Agent, AIGNE, type AgentHooks } from "@aigne/core";

const inputModificationHook: AgentHooks = {
  onStart: ({ input }) => {
    // Add a timestamp to the input message
    const newInput = {
      ...input,
      timestamp: new Date().toISOString(),
    };
    return { input: newInput };
  },
};

class GreeterAgent extends Agent {
  async process(input: { name: string; timestamp?: string }) {
    return { greeting: `Hello, ${input.name}! (processed at ${input.timestamp})` };
  }
}

const agent = new GreeterAgent({ hooks: [inputModificationHook] });

const aigne = new AIGNE();
const result = await aigne.invoke(agent, { name: "Alice" });

console.log(result);
// {
//   greeting: "Hello, Alice! (processed at 2023-10-27T10:00:00.000Z)"
// }
```

### Example 3: Custom Retry with onError

The `onError` hook can return `{ retry: true }` to signal that the AIGNE should re-attempt the agent's `process` method. This is useful for handling transient failures.

**Custom Retry Hook**

```typescript
import { Agent, AIGNE, type AgentHooks } from "@aigne/core";

let attempt = 0;

const retryHook: AgentHooks = {
  onError: ({ agent, error }) => {
    console.log(`[${agent.name}] Attempt failed: ${error.message}. Retrying...`);
    // Return true to signal a retry, but only for the first 2 attempts
    if (attempt < 2) {
      return { retry: true };
    }
    // Return nothing to let the error propagate
  },
};

class UnreliableAgent extends Agent {
  async process() {
    attempt++;
    if (attempt <= 2) {
      throw new Error("Service temporarily unavailable");
    }
    return { status: "OK" };
  }
}

const agent = new UnreliableAgent({ hooks: [retryHook] });

const aigne = new AIGNE();
const result = await aigne.invoke(agent, {});

console.log(result); // { status: 'OK' }
```

This agent will fail twice, and the `retryHook` will intercept the error and trigger a retry each time. On the third attempt, the agent succeeds.

## Hook Priority

Hooks can be defined on the agent, at invocation, and on the context. To manage the order of execution, hooks can have a `priority` property set to `"high"`, `"medium"`, or `"low"` (default).

Hooks are executed in the order of their priority: `high` > `medium` > `low`.

**Hook Priority Example**

```typescript
const highPriorityHook: AgentHooks = {
  priority: 'high',
  onStart: () => console.log('High priority hook executed.'),
};

const mediumPriorityHook: AgentHooks = {
  priority: 'medium',
  onStart: () => console.log('Medium priority hook executed.'),
};

const lowPriorityHook: AgentHooks = {
  // priority defaults to 'low'
  onStart: () => console.log('Low priority hook executed.'),
};

class MonitoredAgent extends Agent {
  async process(input: {}) {
    console.log('Agent processing...');
    return { success: true };
  }
}

const agent = new MonitoredAgent({
  hooks: [lowPriorityHook, highPriorityHook, mediumPriorityHook],
});

const aigne = new AIGNE();
await aigne.invoke(agent, {});

// Console Output:
// High priority hook executed.
// Medium priority hook executed.
// Low priority hook executed.
// Agent processing...
```

This predictable execution order is essential when one hook's logic depends on the outcome of another.

## Summary

Hooks are an essential tool for building robust and observable agent-based systems. They provide a clean, non-invasive way to add cross-cutting concerns like logging, instrumentation, and resilience patterns to your agents. By understanding the agent lifecycle and the capabilities of each hook, you can create sophisticated, production-ready AI applications.

---

## Prompts

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-advanced-topics-prompts-9dc03e/

Effective communication with AI models is contingent upon the quality and structure of the prompts provided. The AIGNE framework supplies a robust system for creating dynamic, reusable, and structured prompts through its `PromptBuilder` class and the integrated Nunjucks templating engine. This guide provides a systematic explanation of these components.

Refer to the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) documentation for more context on how prompts are utilized within agents.

## Prompt Templating with Nunjucks

The framework utilizes the [Nunjucks templating engine](https://mozilla.github.io/nunjucks/) to facilitate the creation of dynamic prompts. This allows for the injection of variables, inclusion of external files, and other programmatic logic directly within your prompt files.

All prompt text is processed by the `PromptTemplate` class, which uses Nunjucks to render the final string.

### Variable Substitution

You can define placeholders in your prompts using the `{{ variable_name }}` syntax. These placeholders are replaced with actual values at runtime.

**analyst-prompt.md**

```markdown
Analyze the following data:

{{ data }}
```

When invoking an agent with this prompt, you would provide the `data` variable in the input message.

**index.ts**

```typescript
import { AIGNE, AIAgent } from "@aigne/core";
import { OpenAI }s from "@aigne/openai";

const model = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const aigne = new AIGNE({
  model,
  agents: {
    analyst: new AIAgent({
      instructions: { path: "./analyst-prompt.md" },
      inputKey: "data",
    }),
  },
});

const result = await aigne.invoke("analyst", {
  data: "User feedback scores: 8, 9, 7, 10, 6.",
});

console.log(result);
```

### File Inclusion

Nunjucks allows for the composition of prompts from multiple files using the `{% include "path/to/file.md" %}` tag. This is highly effective for reusing common instructions or components across different prompts. Paths are resolved relative to the file containing the `include` tag.

For example, you can define a common set of instructions in one file and include it in another.

**common-instructions.md**

```markdown
Always respond in a professional and factual manner.
Do not speculate or provide opinions.
```

**main-prompt.md**

```markdown
You are an expert financial analyst.

{% include "./common-instructions.md" %}

Analyze the quarterly earnings report provided.
```

This modular approach simplifies prompt management and ensures consistency.

## Structuring Prompts with ChatMessageTemplate

For chat-based models, prompts are structured as a sequence of messages, each with a specific role. The framework provides classes to represent these messages programmatically.

- <strong>`SystemMessageTemplate`</strong>: Sets the context or high-level instructions for the AI model.
- <strong>`UserMessageTemplate`</strong>: Represents a message from the end-user.
- <strong>`AgentMessageTemplate`</strong>: Represents a previous response from the AI model, useful for few-shot prompting or continuing a conversation.
- <strong>`ToolMessageTemplate`</strong>: Represents the result of a tool call made by the agent.

These templates can be combined into a `ChatMessagesTemplate` to define a complete conversational prompt.

**structured-prompt.ts**

```typescript
import {
  ChatMessagesTemplate,
  SystemMessageTemplate,
  UserMessageTemplate,
} from "@aigne/core";

const promptTemplate = new ChatMessagesTemplate([
  SystemMessageTemplate.from(
    "You are a helpful assistant that translates {{ input_language }} to {{ output_language }}."
  ),
  UserMessageTemplate.from("{{ text }}"),
]);

// This template can then be used in an AIAgent's `instructions`.
```

## The PromptBuilder Class

The `PromptBuilder` is the central component responsible for assembling the final, complete prompt that is sent to the language model. It orchestrates the entire process, integrating various inputs into a coherent structure.

The following diagram illustrates the flow of information into the `PromptBuilder`:direction: right style { stroke-width: 2 font-size: 14 } "User Input (Message)": { shape: document style.fill: "#D1E7DD" } "Prompt Template (.md)": { shape: document style.fill: "#D1E7DD" } "Agent Configuration": { shape: document style.fill: "#D1E7DD" } Context: { shape: document style.fill: "#D1E7DD" } PromptBuilder: { shape: hexagon style.fill: "#A9CCE3" } "ChatModelInput (to LLM)": { shape: document style.fill: "#FADBD8" }

"User Input (Message)" -> PromptBuilder "Prompt Template (.md)" -> PromptBuilder "Agent Configuration" -> PromptBuilder Context -> PromptBuilder

PromptBuilder -> "ChatModelInput (to LLM)"

"Agent Configuration".children: { "Skills/Tools" Memory "Output Schema" }

"ChatModelInput (to LLM)".children: { "Rendered Messages" "Tool Definitions" "Response Format" }

The `PromptBuilder` automatically performs the following actions during the `build` process:

::::steps
:::step{title="Load Instructions"}
It loads the prompt template from a string, a file path, or an MCP `GetPromptResult` object.
:::

:::step{title="Render Templates"}
It uses Nunjucks to format the prompt templates, injecting variables from the user's input message.
:::

:::step{title="Inject Memory"}
If the agent is configured to use memory, the `PromptBuilder` retrieves relevant memories and converts them into system, user, or agent messages to provide conversational context.
:::

:::step{title="Incorporate Tools (Skills)"}
It gathers all available skills (from the agent configuration and the invocation context) and formats them into the `tools` and `tool_choice` parameters for the model.
:::

:::step{title="Define Response Format"}
If the agent has an `outputSchema`, the `PromptBuilder` configures the model's `responseFormat` to enforce structured JSON output.
:::
::::

### Instantiation

The most common method for creating a `PromptBuilder` is via the static `PromptBuilder.from()` method, which can accept different sources:

- <strong>From a string</strong>: ```typescript const builder = PromptBuilder.from("You are a helpful assistant."); ```
- <strong>From a file path</strong>: ```typescript const builder = PromptBuilder.from({ path: "./prompts/my-prompt.md" }); ```

When an `AIAgent` is defined with `instructions`, it internally uses `PromptBuilder.from()` to create and manage the prompt building process.

## Summary

The AIGNE framework provides a layered and powerful system for prompt engineering. By understanding and utilizing `PromptTemplate` with Nunjucks for dynamic content and `PromptBuilder` for orchestrating the final structure, you can create sophisticated, modular, and effective prompts for your AI agents.

For further reading, explore the [AIAgent documentation](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) to see how these prompts are integrated into the agent lifecycle.

---

## Streaming

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-advanced-topics-streaming-9dc03e/

The AIGNE Framework provides robust support for handling streaming responses from agents. This is particularly useful for applications requiring real-time data processing, such as chatbots, live data feeds, or any user interface that benefits from immediate, incremental updates. By processing data as it becomes available, you can create more responsive and interactive user experiences.

This guide details the methodology for enabling and consuming streamed responses within the framework.

## Enabling Streaming

To receive a streamed response from an agent, you must set the `stream` option to `true` in the `invoke` call. When this option is enabled, the `invoke` method returns an `AgentResponseStream`, which is a `ReadableStream` of `AgentResponseChunk` objects, instead of a fully formed response object.

**AIGNE Invoke with Streaming**

```typescript
import { AIGNE, AIAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";

const llm = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  model: "gpt-4o",
});

const agent = new AIAgent({
  model: llm,
  instructions: "You are a helpful assistant.",
});

const aigne = new AIGNE({
  model: llm,
  agents: { agent },
});

async function run() {
  // Enable streaming by setting the `stream` option to true
  const stream = await aigne.invoke("agent", {
    prompt: "Tell me a short story.",
  }, { stream: true });

  // The 'stream' variable is now a ReadableStream
  for await (const chunk of stream) {
    // Process each chunk as it arrives
    process.stdout.write(chunk.delta.text?.text || "");
  }
}

run();
```

## Consuming the Stream

The returned stream consists of `AgentResponseChunk` objects. Each chunk represents a piece of the total response. There are two primary types of data within a chunk's `delta`:

- `delta.text`: Contains partial text content. This is used for streaming text from language models.
- `delta.json`: Contains partial JSON data. This is used when an agent is configured to return structured output. The framework incrementally builds the final JSON object.

### Processing Chunks

You can iterate over the stream using a `for await...of` loop to process each chunk as it arrives. The following example demonstrates how to accumulate both text and the final structured JSON from a stream.

**Processing Stream Chunks**

```typescript
import { AIGNE, AIAgent, Message } from "@aigne/core";
import { OpenAI } from "@aigne/openai";
import { agentResponseStreamToObject } from "@aigne/core/utils";

// Assume aigne and agent are configured as in the previous example

interface StoryOutput extends Message {
  protagonist: string;
  setting: string;
  plotSummary: string;
  storyText: string;
}

async function processStream() {
  const aigne = new AIGNE({
    model: new OpenAI(),
    agents: {
      agent: new AIAgent({
        model: new OpenAI(),
      })
    },
  });
  const stream = await aigne.invoke<StoryOutput>("agent", {
      prompt: "Write a short story about a robot who discovers music. Return the protagonist's name, the setting, a plot summary, and the full story text.",
      // Assuming the agent is configured for structured output
    },
    { stream: true }
  );

  let fullText = "";
  const finalResult: Partial<StoryOutput> = {};

  for await (const chunk of stream) {
    if (chunk.delta.text?.storyText) {
      const partialText = chunk.delta.text.storyText;
      fullText += partialText;
      process.stdout.write(partialText); // Live update UI with text
    }

    if (chunk.delta.json) {
      // The framework provides the partially-merged JSON object in each relevant chunk
      Object.assign(finalResult, chunk.delta.json);
    }
  }

  console.log("\n\n--- Final Structured Output ---");
  console.log(finalResult);

  // You can also use a utility to get the final object directly
  // Note: This consumes the stream, so it should be used instead of the loop
  // const finalObject = await agentResponseStreamToObject(stream);
  // console.log(finalObject);
}

processStream();
```

## Utility: agentResponseStreamToObject

If you only need the final, fully-formed object and do not need to process intermediate chunks, the framework provides the `agentResponseStreamToObject` utility. This function consumes the entire stream and returns a single promise that resolves with the complete response object.

This is useful when you want the benefits of streaming on the backend (e.g., lower time-to-first-byte from the LLM) but only need to deliver the final result to the caller.

**Using agentResponseStreamToObject**

```typescript
import { AIGNE, AIAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";
import { agentResponseStreamToObject } from "@aigne/core/utils";
// ... setup aigne and agent

async function getFinalObject() {
  const aigne = new AIGNE({
    model: new OpenAI(),
    agents: {
      agent: new AIAgent({
        model: new OpenAI(),
      })
    },
  });
  const stream = await aigne.invoke("agent", {
    prompt: "Tell me a short story.",
  }, { stream: true });

  // Consumes the stream and returns the final aggregated object
  const result = await agentResponseStreamToObject(stream);

  console.log("--- Complete Response ---");
  console.log(result.text);
}

getFinalObject();
```

## Streaming to the Frontend with Server-Sent Events (SSE)

A common use case for streaming is to send real-time updates to a web frontend. The AIGNE framework simplifies this by providing an `AgentResponseStreamSSE` class, which converts an `AgentResponseStream` into a format compatible with Server-Sent Events (SSE).

### Data Flow Diagram

The following diagram illustrates the data flow from the backend AIGNE to the frontend application when using SSE.

![Streaming](https://media.arcblock.io/lib/38/38e4538ab9fc4068.w1600.webp)

### Backend Implementation

On your server, create an endpoint that initiates the agent `invoke` call with streaming enabled. Then, pipe the resulting `AgentResponseStream` into an `AgentResponseStreamSSE` and write its output to the HTTP response.

The example below uses a generic web server structure.

**SSE Backend Endpoint**

```typescript
import { AIGNE, AIAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";
import { AgentResponseStreamSSE } from "@aigne/core/utils";
// ... setup aigne

// Example using a generic server context (e.g., Express, Hono, etc.)
async function handleSseRequest(req, res) {
  const aigne = new AIGNE({
    model: new OpenAI(),
    agents: {
      agent: new AIAgent({
        model: new OpenAI(),
      })
    },
  });
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Connection": "keep-alive",
    "Cache-Control": "no-cache",
  });

  try {
    const stream = await aigne.invoke("agent", {
      prompt: req.body.prompt,
    }, { stream: true });

    // Convert the agent stream to an SSE stream
    const sseStream = new AgentResponseStreamSSE(stream);

    // Pipe the SSE stream to the HTTP response
    for await (const sseChunk of sseStream) {
      res.write(sseChunk);
    }
  } catch (error) {
    console.error("SSE stream error:", error);
    const sseError = `event: error\ndata: ${JSON.stringify({ message: error.message })}\n\n`;
    res.write(sseError);
  } finally {
    res.end();
  }
}
```

### Frontend Implementation

On the frontend, use the native `EventSource` API to connect to your SSE endpoint. You can then listen for `message` events to receive chunks and `error` events to handle issues.

**SSE Frontend Client**

```javascript
const promptInput = document.getElementById('prompt-input');
const submitButton = document.getElementById('submit-button');
const responseContainer = document.getElementById('response');

submitButton.addEventListener('click', async () => {
  const prompt = promptInput.value;
  responseContainer.innerHTML = ''; // Clear previous response

  const eventSource = new EventSource('/api/chat-stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt }),
  });

  eventSource.onmessage = (event) => {
    const chunk = JSON.parse(event.data);

    if (chunk.delta?.text?.text) {
      responseContainer.innerHTML += chunk.delta.text.text;
    }
  };

  eventSource.onerror = (error) => {
    console.error('EventSource failed:', error);
    responseContainer.innerHTML += '<p style="color: red;">Error receiving stream.</p>';
    eventSource.close();
  };

  // The 'open' event fires when the connection is established
  eventSource.onopen = () => {
    console.log('Connection to server opened.');
  };
});
```

This architecture enables building highly responsive UIs where text appears word-by-word, exactly as it is generated by the AI model.

## Summary

The streaming capabilities of the AIGNE Framework are essential for building modern, real-time AI applications. By enabling the `stream` option in the `invoke` method, you can process data incrementally, improve perceived performance, and efficiently pipe agent responses to frontends using Server-Sent Events. For further details on agent invocation, refer to the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) documentation.

---

## Agent Types

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-9dc03e/

The AIGNE Framework provides a suite of specialized agent types, each designed to perform a specific function. While all agents inherit from the base `Agent` class, these specialized implementations offer pre-built capabilities for common tasks, from interacting with AI models to orchestrating complex workflows. Understanding these types is key to building robust and efficient applications.

This section provides a high-level overview of the available agent types. For detailed implementation, configuration options, and code examples, please refer to the specific sub-document for each agent.

![Agent Types](https://media.arcblock.io/lib/7d/7dab44a0402c2fe2.w1600.webp)

## Available Agent Types

The framework includes the following specialized agents, each tailored for a distinct purpose.

::::card-group
::link-card{title="AI Agent" description="The primary agent for interacting with large language models (LLMs). It handles prompt construction, model invocation, and processing of AI-generated responses, including tool usage." icon="bot" href="/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/"}
::link-card{title="Team Agent" description="Orchestrates a group of agents to work together. It can manage workflows in sequential or parallel modes, enabling complex, multi-step problem-solving." icon="users" href="/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/"}
::link-card{title="Image Agent" description="A specialized agent for interfacing with image generation models. It takes instructional prompts and generates visual content." icon="image" href="/en/docs/aigne-framework/developer-guide-agents-image-agent-9dc03e/"}
::link-card{title="Function Agent" description="Wraps standard TypeScript or JavaScript functions, allowing you to integrate any custom code or business logic seamlessly into an agentic workflow." icon="code" href="/en/docs/aigne-framework/developer-guide-agents-function-agent-9dc03e/"}
::link-card{title="Transform Agent" description="Performs declarative data transformations using JSONata expressions. It is ideal for mapping, restructuring, and converting data between different formats without writing procedural code." icon="move" href="/en/docs/aigne-framework/developer-guide-agents-transform-agent-9dc03e/"}
::link-card{title="MCP Agent" description="Connects to external systems and tools via the Model Context Protocol (MCP). This agent acts as a bridge, allowing your application to leverage external resources and capabilities." icon="zap" href="/en/docs/aigne-framework/developer-guide-agents-mcp-agent-9dc03e/"}
::::

## Summary

Choosing the correct agent type for a given task is a fundamental step in designing an effective AIGNE application. Each agent is a specialized tool designed for a specific job. By composing these agents, you can build sophisticated systems capable of handling a wide range of tasks.

For a deeper understanding of each agent's capabilities and configuration, please proceed to the detailed documentation for each type.

- <strong>Next</strong>: Learn about the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/), the core component for interacting with language models.

---

## AI Agent

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/

The `AIAgent` is the primary component for interacting with large language models (LLMs). It serves as a direct interface to a `ChatModel`, enabling sophisticated conversational AI, function calling (tool usage), and structured data extraction. This agent handles the complexities of prompt construction, model invocation, response parsing, and tool execution loops.

This guide provides a comprehensive overview of the `AIAgent`, its configuration, and its core functionalities. For a broader understanding of how agents fit into the AIGNE framework, please refer to the [Agents core concept guide](/en/docs/aigne-framework/developer-guide-core-concepts-agents-9dc03e/).

## How It Works

The `AIAgent` follows a systematic process to handle user input and generate a response. This process often involves multiple interactions with an LLM, especially when tools are used.

![AI Agent](https://media.arcblock.io/lib/f2/f2f932af73db4d9c.w1600.webp)

The diagram above illustrates the typical lifecycle of a request:

1. <strong>Prompt Construction</strong>: The `AIAgent` uses a `PromptBuilder` to assemble the final prompt from its `instructions`, the user input, and the history of any previous tool calls.
2. <strong>Model Invocation</strong>: The fully formed prompt is sent to the configured `ChatModel`.
3. <strong>Response Parsing</strong>: The agent receives the model's raw output.
4. <strong>Tool Call Detection</strong>: It checks if the response contains a request to call a tool.
5.
  - If <strong>No</strong>, the agent formats the text response and returns it.
  - If <strong>Yes</strong>, it proceeds to the tool execution loop.
6. <strong>Tool Execution</strong>: The agent identifies and invokes the requested tool (which is another agent), captures its output, and formats it into a message for the model. The process then loops back to step 1, sending the tool's result back to the model for the next generation step.
7. <strong>Final Output</strong>: Once the model generates a final text response without any tool calls, the agent formats it and streams it back to the user.

## Configuration

An `AIAgent` is configured through its constructor options. Below is a detailed breakdown of the available parameters.

- **instructions** `string | PromptBuilder` — The core directive that guides the AI model's behavior. This can be a simple string or a PromptBuilder instance for creating complex, dynamic prompts. See the Prompts guide for more details.
- **inputKey** `string` — Specifies which key from the input message object should be treated as the main user query. If not set, instructions must be provided.
- **outputKey** `string` (default: `message`) — Defines the key under which the agent's final text response will be placed in the output object. Defaults to message.
- **inputFileKey** `string` — Specifies the key from the input message that contains file data to be sent to the model.
- **outputFileKey** `string` (default: `files`) — Defines the key under which any files generated by the model will be placed in the output object. Defaults to files.
- **toolChoice** `AIAgentToolChoice | Agent` (default: `auto`) — Controls how the agent uses its available tools (skills). See the Tool Usage section below for details.
- **toolCallsConcurrency** `number` (default: `1`) — The maximum number of tool calls that can be executed concurrently in a single turn.
- **catchToolsError** `boolean` (default: `true`) — If true, the agent will catch errors from tool executions and feed the error message back to the model. If false, an error will halt the entire process.
- **structuredStreamMode** `boolean` (default: `false`) — Enables a mode for extracting structured JSON data from the model's streaming response. See the Structured Output section for more information.
- **memoryAgentsAsTools** `boolean` (default: `false`) — When true, attached MemoryAgent instances are exposed to the model as callable tools, allowing the agent to explicitly read from or write to its memory.

### Basic Example

Here is an example of a simple `AIAgent` configured to act as a helpful assistant.

**Basic Chat Agent**

```javascript
import { AIAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";

// Configure the model to use
const model = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  model: "gpt-4o",
});

// Create the AI Agent
const chatAgent = new AIAgent({
  instructions: "You are a helpful assistant.",
  inputKey: "question",
  outputKey: "answer",
});

// To run the agent, you would use the AIGNE's invoke method
// const aigne = new AIGNE({ model });
// const response = await aigne.invoke(chatAgent, { question: "What is AIGNE?" });
// console.log(response.answer);
```

This agent takes an input object with a `question` key and produces an output object with an `answer` key.

## Tool Usage

A powerful feature of `AIAgent` is its ability to use other agents as tools. By providing a list of `skills` during invocation, the `AIAgent` can decide to call these tools to gather information or perform actions. The `toolChoice` option dictates this behavior.

| `toolChoice` Value  | Description  |
|---|---|
| `auto`  | (Default) The model decides whether to call a tool based on the context of the conversation.  |
| `none`  | Disables tool usage entirely. The model will not attempt to call any tools.  |
| `required`  | Forces the model to call one or more tools.  |
| `router`  | A specialized mode where the model is forced to choose exactly one tool. The agent then directly routes the request to that tool and streams its response as the final output. This is highly efficient for creating dispatcher agents.  |

### Tool Usage Example

Imagine you have a `FunctionAgent` that can fetch weather information. You can provide this to an `AIAgent` as a skill.

**Agent with a Tool**

```javascript
import { AIAgent, FunctionAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";

// A simple function to get the weather
function getCurrentWeather(location) {
  if (location.toLowerCase().includes("tokyo")) {
    return JSON.stringify({ location: "Tokyo", temperature: "15", unit: "celsius" });
  }
  return JSON.stringify({ location, temperature: "unknown" });
}

// Wrap the function in a FunctionAgent to make it a tool
const weatherTool = new FunctionAgent({
  name: "get_current_weather",
  description: "Get the current weather in a given location",
  inputSchema: {
    type: "object",
    properties: { location: { type: "string", description: "The city and state" } },
    required: ["location"],
  },
  process: ({ location }) => getCurrentWeather(location),
});

// Configure the model
const model = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  model: "gpt-4o",
});

// Create an AI Agent that can use the weather tool
const weatherAssistant = new AIAgent({
  instructions: "You are a helpful assistant that can provide weather forecasts.",
  inputKey: "query",
  outputKey: "response",
});

// When invoking, provide the tool as a skill
// const aigne = new AIGNE({ model, skills: [weatherTool] });
// const result = await aigne.invoke(weatherAssistant, { query: "What's the weather like in Tokyo?" });
// console.log(result.response); // The LLM will respond using the tool's output
```

In this scenario, the `AIAgent` will receive the query, recognize the need for weather information, call the `weatherTool`, receive its JSON output, and then use that data to formulate a natural language response.

## Structured Output

For tasks that require extracting specific, structured information (like sentiment analysis, classification, or entity extraction), `structuredStreamMode` is invaluable. When enabled, the agent actively parses the model's streaming output to find and extract a JSON object.

By default, the model must be instructed to place its structured data inside `<metadata>...</metadata>` tags in YAML format.

### Structured Output Example

This example configures an agent to analyze the sentiment of a user message and return a structured JSON object.

**Structured Sentiment Analysis**

```javascript
import { AIAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";

const sentimentAnalyzer = new AIAgent({
  instructions: `
    Analyze the sentiment of the user's message.
    Respond with a single word summary, followed by a structured analysis.
    Place the structured analysis in YAML format inside <metadata> tags.
    The structure should contain 'sentiment' (positive, negative, or neutral) and a 'score' from -1.0 to 1.0.
  `,
  inputKey: "message",
  outputKey: "summary",
  structuredStreamMode: true,
});

// When invoked, the output will contain both the text summary
// and the parsed JSON object.
// const aigne = new AIGNE({ model: new OpenAI(...) });
// const result = await aigne.invoke(sentimentAnalyzer, { message: "AIGNE is an amazing framework!" });
/*
  Expected result:
  {
    summary: "Positive.",
    sentiment: "positive",
    score: 0.9
  }
*/
```

You can customize the parsing logic, including the start/end tags and the parsing function (e.g., to support JSON directly), using the `customStructuredStreamInstructions` option.

## Summary

The `AIAgent` is a foundational building block for creating advanced AI applications. It provides a robust and flexible interface to language models, complete with support for tool usage, structured data extraction, and memory integration.

For more complex workflows, you may need to orchestrate multiple agents. To learn how, proceed to the [Team Agent](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/) documentation. For advanced prompt templating techniques, see the [Prompts](/en/docs/aigne-framework/developer-guide-advanced-topics-prompts-9dc03e/) guide.

---

## Function Agent

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-function-agent-9dc03e/

The `FunctionAgent` provides a straightforward method for encapsulating existing TypeScript or JavaScript functions, thereby elevating them to first-class agents within the AIGNE framework. This enables the seamless integration of custom business logic, external API interactions, or any arbitrary code into an agentic workflow, obviating the need for extensive boilerplate.

By wrapping a function, the `FunctionAgent` allows it to participate fully in the agent ecosystem. It can be invoked identically to any other agent, incorporated as a skill within an `AIAgent` or `TeamAgent`, and interact with the AIGNE context and lifecycle hooks. This positions it as an essential component for bridging conventional programmatic logic with AI-driven processes.

This diagram illustrates the creation and invocation flow of a `FunctionAgent`, from providing the source function to receiving the final output.

![Function Agent](https://media.arcblock.io/lib/d4/d429b7c7edff24dc.w1600.webp)

## Key Concepts

A `FunctionAgent` is a specialized implementation of the `Agent` class that delegates its core processing logic to a user-supplied function. The primary constructor for this agent is the static method `FunctionAgent.from()`, which streamlines its instantiation.

A `FunctionAgent` can be created in two ways:

::::steps
:::step{title="Directly from a function:"}
Pass a synchronous or asynchronous function to `FunctionAgent.from()`. The agent will infer properties, such as its name, from the function definition.
:::

:::step{title="From a configuration object:"}
For more explicit control, provide an options object that specifies the `process` function along with other standard agent configurations like `name`, `description`, `inputSchema`, and `outputSchema`.
:::
::::

This design provides flexibility for both rapid, ad-hoc integrations and the development of robust, well-defined agent components.

## Creating a Function Agent

The standard method for creating a `FunctionAgent` is through the `FunctionAgent.from()` factory method, which accepts either a function or a configuration object.

### From a Simple Function

Any standard function can be wrapped directly. The AIGNE framework will use the function's name as the agent's name. This approach is optimal for simple, self-contained operations.

**Wrapping a Simple Function**

```javascript
import { FunctionAgent } from "@aigne/core";

// Define a simple synchronous function
function add({ a, b }) {
  return { result: a + b };
}

// Wrap the function into an agent
const addAgent = FunctionAgent.from(add);

console.log(addAgent.name); // Outputs: 'add'
```

The function receives the agent's input object as its first argument and is expected to return an object that constitutes the agent's output.

### With Full Configuration

For more complex integrations, a full configuration object should be provided. This allows for the definition of input/output schemas for validation, the inclusion of a description, and the assignment of a custom name. This method is recommended for creating robust and reusable agents.

**Function Agent with Configuration**

```javascript
import { FunctionAgent } from "@aigne/core";
import { z } from "zod";

const fetchUserAgent = FunctionAgent.from({
  name: "FetchUser",
  description: "Fetches user data from a placeholder API.",
  inputSchema: z.object({
    userId: z.number().describe("The ID of the user to fetch."),
  }),
  outputSchema: z.object({
    id: z.number(),
    name: z.string(),
    email: z.string().email(),
  }),
  process: async ({ userId }) => {
    const response = await fetch(`https://jsonplaceholder.typicode.com/users/${userId}`);
    if (!response.ok) {
      throw new Error("Failed to fetch user data.");
    }
    const data = await response.json();
    return {
      id: data.id,
      name: data.name,
      email: data.email,
    };
  },
});
```

In this example, `zod` schemas are defined to ensure the input `userId` is a number and the output conforms to a specified structure.

## Invoking a Function Agent

A created `FunctionAgent` is invoked using the standard `.invoke()` method, consistent with all other agent types.

**Invoking the Agent**

```javascript
async function main() {
  // Using the simple 'add' agent from the previous example
  const result = await addAgent.invoke({ a: 10, b: 5 });
  console.log(result); // { result: 15 }

  // Using the configured 'FetchUser' agent
  const user = await fetchUserAgent.invoke({ userId: 1 });
  console.log(user);
  // { id: 1, name: 'Leanne Graham', email: 'Sincere@april.biz' }
}

main();
```

The `invoke` method manages the execution lifecycle, including input validation against the schema (if provided), execution of the underlying function, and validation of the result against the output schema.

## Advanced Usage

### Streaming Responses

`FunctionAgent` supports streaming responses through the use of asynchronous generators. The `process` function can be defined as an `async function*` that `yield`s `AgentResponseChunk` objects, enabling incremental data transmission.

**Streaming with an Async Generator**

```javascript
import { FunctionAgent, jsonDelta, textDelta } from "@aigne/core";
import { z } from "zod";

const streamNumbersAgent = FunctionAgent.from({
  name: "StreamNumbers",
  inputSchema: z.object({
    count: z.number().int().positive(),
  }),
  outputSchema: z.object({
    finalCount: z.number(),
    message: z.string(),
  }),
  process: async function* ({ count }) {
    for (let i = 1; i <= count; i++) {
      yield textDelta({ message: `Processing number ${i}... ` });
      await new Promise((resolve) => setTimeout(resolve, 200)); // Simulate work
    }
    yield jsonDelta({ finalCount: count });
    yield textDelta({ message: "Done." });
  },
});

async function runStream() {
  const stream = await streamNumbersAgent.invoke({ count: 5 }, { streaming: true });
  for await (const chunk of stream) {
    console.log(chunk);
  }
}

runStream();
```

This capability is particularly useful for long-running tasks where providing real-time feedback on the agent's progress is required.

## Configuration

The `FunctionAgent` is initialized via a configuration object passed to `FunctionAgent.from` or its constructor. The following parameters are specific to its configuration.

- **process** `FunctionAgentFn` *(required)* — The function that implements the agent's logic. It receives the input message and invocation options and returns the processing result. This can be a synchronous function, an async function returning a Promise, or an async generator for streaming.
- **name** `string` — A unique name for the agent, used for identification and logging. If not provided, it defaults to the name of the process function.
- **description** `string` — A human-readable description of what the agent does. This is useful for documentation and for other agents to understand its capabilities.
- **inputSchema** `ZodObject` — A Zod schema to validate the structure and types of the input message. If validation fails, the agent will throw an error before the process function is called.
- **outputSchema** `ZodObject` — A Zod schema to validate the structure and types of the output message returned by the process function. If validation fails, an error is thrown.

All other properties from the base `AgentOptions` are also available. Refer to the [Agent documentation](/en/docs/aigne-framework/developer-guide-core-concepts-agents-9dc03e/) for a complete list.

## Summary

The `FunctionAgent` is a versatile tool for integrating conventional code into the AIGNE framework, acting as a bridge that allows any JavaScript or TypeScript function to operate as a standard agent.

- <strong>Simplicity:</strong> Wrap existing functions with minimal effort using `FunctionAgent.from()`.
- <strong>Integration:</strong> Seamlessly incorporate traditional business logic, calculations, or external API calls into agentic workflows.
- <strong>Validation:</strong> Enforce data contracts and improve reliability by defining input and output schemas with Zod.
- <strong>Flexibility:</strong> Supports synchronous functions, asynchronous promises, and streaming with async generators.

By leveraging `FunctionAgent`, developers can combine the deterministic and reliable nature of traditional code with the dynamic capabilities of AI agents to build more powerful and robust applications. For orchestrating multiple agents, including Function Agents, refer to the documentation on the [Team Agent](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/).

---

## Image Agent

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-image-agent-9dc03e/

The `ImageAgent` is a specialized agent responsible for generating images. It acts as an interface to an `ImageModel`, processing input data to formulate a prompt and then requesting the image generation service to create an image.

This agent is essential for any workflow that requires the dynamic creation of visual content based on textual descriptions. It leverages a `PromptBuilder` to construct its prompts, enabling the use of templates to generate images from variable inputs.

The following diagram illustrates the invocation flow of the `ImageAgent`, from user request to final output:

![Image Agent](https://media.arcblock.io/lib/0b/0b20a799ad9d4783.w1600.webp)

## Configuration

An `ImageAgent` can be configured either programmatically using TypeScript or declaratively using YAML. Both methods require defining the instructions for image generation and optionally specifying model-specific parameters.

### TypeScript Configuration

To create an `ImageAgent` in TypeScript, use the static `ImageAgent.from()` method and provide it with `ImageAgentOptions`.

**"ImageAgent Configuration"**

```typescript
import { AIGNE, ImageAgent } from "@aigne/core";
import { OpenAI } from "@aigne/openai";

// Configure the image model provider
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Create an instance of the ImageAgent
const architectAgent = ImageAgent.from({
  name: "architect",
  description: "An agent that draws architectural diagrams.",
  instructions: "Create an architectural diagram of a {{subject}}.",
  modelOptions: {
    quality: "hd",
    style: "vivid",
  },
});

// The AIGNE instance must have an imageModel configured
const aigne = new AIGNE({
  imageModel: openai.image("dall-e-3"),
});

async function run() {
  const result = await aigne.invoke(architectAgent, {
    input: {
      subject: "microservices application",
    },
  });

  console.log(result);
}

run();
```

The code above defines an `ImageAgent` named "architect". It uses a templated `instructions` string to generate a prompt. The `modelOptions` object passes specific parameters to the underlying DALL-E 3 model to request a high-definition, vivid image.

### YAML Configuration

Alternatively, you can define an `ImageAgent` in a `.yaml` file. This approach is useful for separating agent definitions from application logic.

**"image-agent.yaml"**

```yaml
type: image
name: style-artist
description: Draws an image of an object in a specific style.
instructions: |
  Draw an image of a {{object}} in the {{style}} style.
input_schema:
  type: object
  properties:
    object:
      type: string
      description: The object to draw.
    style:
      type: string
      description: The style of the image.
  required:
    - object
    - style
```

In this declarative example, the `type: image` specifies that this is an `ImageAgent`. The `instructions` field contains a multi-line string with placeholders (`{{object}}`, `{{style}}`) that will be populated from the input during invocation. The `input_schema` formally defines the expected input structure.

## Parameters

The behavior of an `ImageAgent` is controlled by the options provided during its construction.

- **instructions** `string | PromptBuilder` *(required)* — The prompt template used for image generation. This can be a simple string or a PromptBuilder instance for more complex logic. Placeholders in the format {{key}} will be replaced with values from the input object.
- **modelOptions** `Record<string, any>` — An object containing provider-specific parameters to pass to the underlying ImageModel. This allows for fine-tuned control over the generation process, such as specifying image quality, size, or style. Refer to the specific model provider's documentation for available options.
- **outputFileType** `'url' | 'base64'` — Specifies the desired format for the output image. The default behavior is determined by the ImageModel, but you can explicitly request either a public URL (url) or a Base64-encoded string (base64).

## Invocation and Output

When an `ImageAgent` is invoked, it passes the input to its `PromptBuilder` to generate the final prompt. It then calls the configured `ImageModel` with this prompt and any specified `modelOptions`.

The agent's output is an object conforming to the `ImageModelOutput` schema, which contains the generated image in the requested format.

<strong>Example Invocation</strong>

**"Invoking the Agent"**

```typescript
const result = await aigne.invoke(styleArtistAgent, { // Assuming styleArtistAgent is loaded from YAML
  input: {
    object: "futuristic city",
    style: "cyberpunk",
  },
});
```

<strong>Example Response</strong>

**"ImageAgent Output"**

```json
{
  "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/...",
  "base64": null
}
```

The response contains a `url` pointing to the generated image. If `outputFileType` were set to `'base64'`, the `base64` field would be populated instead.

## Summary

The `ImageAgent` provides a structured and reusable way to integrate image generation capabilities into your AI workflows. By separating the prompt logic from the model interaction, it allows for clear and maintainable agent designs.

For more information on other agent types, refer to the following documentation:

- [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/): For interacting with language models.
- [Team Agent](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/): For orchestrating multiple agents.
- [Function Agent](/en/docs/aigne-framework/developer-guide-agents-function-agent-9dc03e/): For wrapping custom code as an agent.

---

## MCP Agent

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-mcp-agent-9dc03e/

The `MCPAgent` is a specialized agent designed to interact with external systems that adhere to the <strong>Model Context Protocol (MCP)</strong>. It acts as a bridge, allowing your AIGNE application to connect to remote MCP servers and utilize their capabilities—such as tools, prompts, and resources—as if they were native components of the framework.

This enables seamless integration with a wide range of external services, from database connectors and web automation tools to proprietary enterprise systems, provided they expose an MCP-compliant interface.

Key functionalities include:

- <strong>Multiple Transport Protocols</strong>: Connect to MCP servers via standard I/O (`stdio`), Server-Sent Events (`sse`), or `streamableHttp`.
- <strong>Automatic Discovery</strong>: Automatically discovers and registers the tools, prompts, and resources available on the connected MCP server.
- <strong>Robust Connection Management</strong>: Features automatic reconnection for network-based transports to handle transient connectivity issues.

## How MCPAgent Works

The `MCPAgent` encapsulates the logic for connecting to an MCP server and translating its offerings into AIGNE constructs. When an `MCPAgent` is initialized, it connects to the specified server and queries for its available tools, prompts, and resources. These are then dynamically attached to the agent instance as `skills`, `prompts`, and `resources`, respectively, making them directly accessible within your AIGNE workflows.

![MCP Agent](https://media.arcblock.io/lib/88/88a479edb2df72c0.w1600.webp)

## Creating an MCPAgent

You can create an `MCPAgent` instance using the static `MCPAgent.from()` method. This factory method supports several configuration patterns depending on how you need to connect to the MCP server.

### 1. Connecting via Standard I/O (Stdio)

This method is ideal for running an MCP server as a local child process. The `MCPAgent` communicates with the server through its standard input and output streams.

- **command** `string` *(required)* — The command to execute to start the MCP server process.
- **args** `string[]` — An array of string arguments to pass to the command.
- **env** `Record<string, string>` — Environment variables to set for the child process.

**Connecting to a Local Filesystem Server**

```javascript
import { MCPAgent } from "@aigne/core";

// Create an MCPAgent by running a command-line server
await using mcpAgent = await MCPAgent.from({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "."],
});

console.log('Connected to:', mcpAgent.name);

// Access the skills provided by the filesystem server
const fileReader = mcpAgent.skills.read_file;
if (fileReader) {
  const result = await fileReader.invoke({ path: "./package.json" });
  console.log(result);
}
```

### 2. Connecting via Network (SSE or StreamableHTTP)

This is the standard method for connecting to remote MCP servers over a network. You can choose between two transport protocols:

- `sse`: Server-Sent Events, a simple and widely supported protocol for streaming.
- `streamableHttp`: A more advanced, bidirectional streaming protocol.

- **url** `string` *(required)* — The URL of the remote MCP server endpoint.
- **transport** `'sse' | 'streamableHttp'` (default: `sse`) — The transport protocol to use. Defaults to sse.
- **opts** `object` — Additional options to pass to the underlying transport client (e.g., for headers and authentication).
- **timeout** `number` (default: `60000`) — Request timeout in milliseconds.
- **maxReconnects** `number` (default: `10`) — The maximum number of times to attempt reconnection if the connection is lost. Set to 0 to disable.
- **shouldReconnect** `(error: Error) => boolean` — A function that returns true if a reconnect should be attempted based on the error received.

**Connecting via StreamableHTTP**

```javascript
import { MCPAgent } from "@aigne/core";

// Create an MCPAgent using a StreamableHTTP server connection
await using mcpAgent = await MCPAgent.from({
  url: `http://localhost:3000/mcp`,
  transport: "streamableHttp",
});

console.log('Connected to:', mcpAgent.name);

const echoSkill = mcpAgent.skills.echo;
if (echoSkill) {
  const result = await echoSkill.invoke({ message: "Hello, World!" });
  console.log(result);
}
```

### 3. Using a Pre-configured Client

If you have already instantiated and configured an MCP `Client` object, you can pass it directly to create an `MCPAgent`. This is useful for advanced scenarios where you need fine-grained control over the client's configuration.

- **client** `Client` *(required)* — A pre-configured instance of an MCP Client.
- **prompts** `MCPPrompt[]` — An optional array of pre-defined MCP prompts.
- **resources** `MCPResource[]` — An optional array of pre-defined MCP resources.

**Creating from a Client Instance**

```javascript
import { MCPAgent } from "@aigne/core";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create and configure the client manually
const client = new Client({ name: "test-client", version: "1.0.0" });
const transport = new StdioClientTransport({
  command: "bun",
  args: ["./mock-mcp-server.ts"],
});
await client.connect(transport);

// Create an MCPAgent from the existing client instance
await using mcpAgent = MCPAgent.from({
  name: client.getServerVersion()?.name,
  client,
});

console.log('Connected to:', mcpAgent.name);
```

## Accessing Server Capabilities

Once an `MCPAgent` is connected, it exposes the server's tools, prompts, and resources through its properties.

### Accessing Skills

Server-side tools are exposed as `skills` on the `MCPAgent` instance. You can access them by name and use their `invoke` method. These skills can then be passed to other agents, such as an `AIAgent`, to grant them new capabilities.

**Using a Skill from an MCPAgent**

```javascript
// Assuming `mcpAgent` is an initialized MCPAgent
const echoSkill = mcpAgent.skills.echo;

if (echoSkill) {
  const result = await echoSkill.invoke({ message: "Hello from AIGNE!" });
  console.log(result);
  // Expected output:
  // {
  //   "content": [
  //     { "text": "Tool echo: Hello from AIGNE!", "type": "text" }
  //   ]
  // }
}
```

### Accessing Prompts

Server-defined prompts are available under the `prompts` property. These are useful for retrieving pre-defined, complex prompt structures from the server.

**Accessing a Server-Side Prompt**

```javascript
// Assuming `mcpAgent` is an initialized MCPAgent
const echoPrompt = mcpAgent.prompts.echo;

if (echoPrompt) {
  const result = await echoPrompt.invoke({ message: "Hello!" });
  console.log(result);
  // Expected output:
  // {
  //   "messages": [
  //     {
  //       "content": { "text": "Please process this message: Hello!", "type": "text" },
  //       "role": "user"
  //     },
  //     ...
  //   ]
  // }
}
```

### Accessing Resources

Server-hosted resources or resource templates can be accessed via the `resources` property. This allows you to read data from the server by expanding a URI template.

**Reading a Server-Side Resource**

```javascript
// Assuming `mcpAgent` is an initialized MCPAgent
const echoResource = mcpAgent.resources.echo;

if (echoResource) {
  const result = await echoResource.invoke({ message: "Hello!" });
  console.log(result);
  // Expected output:
  // {
  //   "contents": [
  //     { "text": "Resource echo: Hello!", "uri": "echo://Hello!" }
  //   ]
  // }
}
```

## Connection Teardown

It is important to properly close the connection to the MCP server to release resources.

### Manual Shutdown

You can explicitly call the `shutdown()` method.

**Manually Shutting Down an Agent**

```javascript
const mcpAgent = await MCPAgent.from({
  url: `http://localhost:3000/mcp`,
});

// ... use the agent

await mcpAgent.shutdown();
```

### Automatic Shutdown with using

For environments that support the `using` declaration (ES2023), the agent's connection will be closed automatically when it goes out of scope. This is the recommended approach for managing the agent's lifecycle.

**Automatic Shutdown with 'using'**

```javascript
async function connectAndUseAgent() {
  await using mcpAgent = await MCPAgent.from({
    url: `http://localhost:3000/mcp`,
  });

  // The agent is used here...
  const echo = mcpAgent.skills.echo;
  if (echo) await echo.invoke({ message: "Test" });
} // <-- mcpAgent.shutdown() is called automatically here.
```

## Summary

The `MCPAgent` is a crucial component for extending the AIGNE framework's capabilities by integrating with external systems. By abstracting the connection and communication logic, it allows you to treat external tools and data sources as first-class citizens in your agentic workflows.

For more information on how to use the skills provided by an `MCPAgent`, see the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) documentation.

---

## Team Agent

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/

A `TeamAgent` is a specialized agent that orchestrates a group of other agents (referred to as "skills") to perform complex tasks. It acts as a manager, directing the flow of information and coordinating the execution of its skills according to a defined strategy. This allows for the creation of sophisticated workflows where multiple specialized agents collaborate to achieve a goal that a single agent could not accomplish alone.

The `TeamAgent` supports several key patterns of agent orchestration:

- <strong>Sequential Execution</strong>: Agents run one after another, forming a processing pipeline.
- <strong>Parallel Execution</strong>: Agents run simultaneously, and their results are merged.
- <strong>Iterative Processing</strong>: The team processes each item in a list, ideal for batch operations.
- <strong>Reflection</strong>: The team's output is reviewed and refined in a loop until it meets specific criteria.

This component is fundamental for building modular and powerful AI systems. For details on the individual agents that can be part of a team, refer to the documentation for [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) and [Function Agent](/en/docs/aigne-framework/developer-guide-agents-function-agent-9dc03e/).

![Team Agent](https://media.arcblock.io/lib/85/8571815215c04fac.w1600.webp)

## Configuration

A `TeamAgent` is configured with a set of options that define its behavior, execution mode, and advanced features like iteration and reflection.

- **skills** `Agent[]` *(required)* — An array of agent instances that form the team.
- **mode** `ProcessMode` (default: `sequential`) — The execution strategy for the agents. Can be sequential or parallel.
- **reflection** `ReflectionMode` — Configuration for enabling the iterative self-correction process.
- **iterateOn** `string` — The key of an input field containing an array. The team will execute once for each item in the array.
- **concurrency** `number` (default: `1`) — When using iterateOn, this sets the number of items to process concurrently.
- **iterateWithPreviousOutput** `boolean` (default: `false`) — If true, the output from processing one item in an iterateOn loop is merged back and made available to the next item's execution. This requires concurrency to be 1.
- **includeAllStepsOutput** `boolean` (default: `false`) — In sequential mode, if true, the output from every intermediate agent is included in the final result, not just the last one.

## Execution Modes

The `mode` property determines the fundamental workflow of the team.

### Sequential Mode

In `sequential` mode, agents execute one by one. The output of each agent is merged with the initial input and passed to the next agent in the sequence. This creates a pipeline, suitable for tasks that require a series of transformations or steps.

**team-agent-sequential.ts**

```typescript
import { AIAgent, TeamAgent, ProcessMode } from "@aigne/core";
import { model } from "./model"; // Assume model is an initialized ChatModel

const writerAgent = new AIAgent({
  name: "writer",
  model,
  instructions: "You are a creative writer. Write a short story based on the topic: {{topic}}.",
  outputKey: "story",
});

const editorAgent = new AIAgent({
  name: "editor",
  model,
  instructions: "You are an editor. Review the following story and correct any grammatical errors: {{story}}.",
  outputKey: "editedStory",
});

const sequentialTeam = new TeamAgent({
  name: "writingTeam",
  mode: ProcessMode.sequential,
  skills: [writerAgent, editorAgent],
});

// To invoke:
// const result = await aigne.invoke(sequentialTeam, { topic: "a journey to the moon" });
// console.log(result.editedStory);
```

In this example, `writerAgent` first generates a `story`. The output, containing the `story` key, is then passed to `editorAgent`, which uses it to produce the final `editedStory`.

### Parallel Mode

In `parallel` mode, all agents execute simultaneously with the same initial input. Their outputs are then merged into a single result. This is efficient for tasks where multiple independent pieces of information need to be generated at the same time.

If multiple agents attempt to write to the same output key, the first agent to produce a value for that key "claims" it, and subsequent writes to that key from other agents are ignored.

**team-agent-parallel.ts**

```typescript
import { AIAgent, TeamAgent, ProcessMode } from "@aigne/core";
import { model } from "./model"; // Assume model is an initialized ChatModel

const researcherAgent = new AIAgent({
  name: "researcher",
  model,
  instructions: "Research the key facts about {{topic}}.",
  outputKey: "facts",
});

const summaryAgent = new AIAgent({
  name: "summarizer",
  model,
  instructions: "Provide a brief, one-paragraph summary of {{topic}}.",
  outputKey: "summary",
});

const parallelTeam = new TeamAgent({
  name: "researchTeam",
  mode: ProcessMode.parallel,
  skills: [researcherAgent, summaryAgent],
});

// To invoke:
// const result = await aigne.invoke(parallelTeam, { topic: "the Roman Empire" });
// console.log(result.facts);
// console.log(result.summary);
```

Here, both agents start at the same time. The final result will contain both `facts` and `summary` once both agents have completed their work.

## Advanced Features

### Iteration with iterateOn

The `iterateOn` property enables batch processing. You provide the name of an input key that holds an array. The `TeamAgent` will then execute its entire workflow for each item in that array. This is highly effective for processing multiple data records with the same set of agents.

**team-agent-iteration.ts**

```typescript
import { AIAgent, TeamAgent, ProcessMode } from "@aigne/core";
import { model } from "./model"; // Assume model is an initialized ChatModel

const translatorAgent = new AIAgent({
  name: "translator",
  model,
  instructions: "Translate the following text to French: {{text}}.",
  outputKey: "translatedText",
});

const sentimentAgent = new AIAgent({
  name: "sentiment",
  model,
  instructions: "Analyze the sentiment of the following text (positive, negative, or neutral): {{text}}.",
  outputKey: "sentiment",
});

const processingTeam = new TeamAgent({
  name: "batchProcessor",
  mode: ProcessMode.parallel,
  skills: [translatorAgent, sentimentAgent],
  iterateOn: "reviews", // The key holding the array
});

const inputData = {
  reviews: [
    { text: "This product is amazing!" },
    { text: "I am very disappointed with the quality." },
    { text: "It works as expected." },
  ],
};

// To invoke:
// const result = await aigne.invoke(processingTeam, inputData);
// console.log(result.reviews);
/*
Output would be:
[
  { translatedText: "Ce produit est incroyable !", sentiment: "positive" },
  { translatedText: "Je suis très déçu de la qualité.", sentiment: "negative" },
  { translatedText: "Cela fonctionne comme prévu.", sentiment: "neutral" }
]
*/
```

### Reflection

Reflection provides a mechanism for self-correction and quality assurance. When configured, a `TeamAgent`'s output is passed to a designated `reviewer` agent. The reviewer assesses the output against certain criteria. If the output is not "approved," the entire process runs again, feeding the previous output and the reviewer's feedback into the next iteration. This loop continues until the output is approved or a `maxIterations` limit is reached.

The configuration for reflection is provided under the `reflection` key.

- **reviewer** `Agent` *(required)* — The agent responsible for evaluating the team's output.
- **isApproved** `string | Function` *(required)* — A condition for approval. If a string, it's the name of a boolean field in the reviewer's output. If a function, it receives the reviewer's output and must return a truthy value for approval.
- **maxIterations** `number` (default: `3`) — The maximum number of review-refine cycles before failing.
- **returnLastOnMaxIterations** `boolean` (default: `false`) — If true, the process returns the last generated output upon hitting maxIterations instead of throwing an error.
- **customErrorMessage** `string` — A custom error message to throw when max iterations are reached without approval.

**team-agent-reflection.ts**

```typescript
import { AIAgent, TeamAgent } from "@aigne/core";
import { model } from "./model"; // Assume model is an initialized ChatModel

const planGenerator = new AIAgent({
  name: "planGenerator",
  model,
  instructions: `Generate a 3-step marketing plan for a new {{product}}.
  If you received feedback, incorporate it. Feedback: {{feedback}}`,
  outputKey: "plan",
});

const planReviewer = new AIAgent({
  name: "planReviewer",
  model,
  instructions: `Review the marketing plan: {{plan}}.
  Does it include a budget allocation? If not, provide feedback to add one.
  Output JSON with an 'approved' (boolean) and 'feedback' (string) field.`,
  output: {
    json: {
      schema: {
        type: "object",
        properties: {
          approved: { type: "boolean" },
          feedback: { type: "string" },
        },
      },
    },
  },
});

const reflectionTeam = new TeamAgent({
  name: "planningTeam",
  skills: [planGenerator],
  reflection: {
    reviewer: planReviewer,
    isApproved: "approved", // Check the 'approved' field in the reviewer's output
    maxIterations: 3,
  },
});

// To invoke:
// const result = await aigne.invoke(reflectionTeam, { product: "smart watch" });
// console.log(result.plan);
```

In this flow, `planGenerator` creates an initial plan. `planReviewer` checks it. If no budget is mentioned, it sets `approved` to `false` and provides feedback. The `TeamAgent` then re-runs `planGenerator`, this time including the feedback, until the plan is approved.

## YAML Definition

You can also define a `TeamAgent` declaratively using YAML.

**team-agent-definition.yaml**

```yaml
type: team
name: test-team-agent
description: Test team agent
skills:
  - sandbox.js # Path to another agent definition
  - chat.yaml
mode: parallel
iterate_on: sections
concurrency: 2
include-all-steps-output: true
reflection:
  reviewer: team-agent-reviewer.yaml
  is_approved: approved
  max_iterations: 5
  return_last_on_max_iterations: true
```

This YAML defines a parallel team that iterates over an input field named `sections` and also includes a reflection step for quality control.

## Summary

The `TeamAgent` is a powerful tool for orchestrating multiple agents to solve complex problems. By combining agents in `sequential` or `parallel` workflows and leveraging advanced features like `iterateOn` for batch processing and `reflection` for self-correction, you can build robust and sophisticated AI applications.

To learn more about the building blocks of a team, see the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) and [Function Agent](/en/docs/aigne-framework/developer-guide-agents-function-agent-9dc03e/) documentation.

---

## Transform Agent

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-agents-transform-agent-9dc03e/

The `TransformAgent` is a specialized agent that provides a declarative way to transform structured data using [JSONata](https://jsonata.org/) expressions. It is ideal for scenarios where data needs to be mapped, restructured, or converted from one format to another without requiring complex imperative logic.

Common use cases include:

- Normalizing API responses to a consistent format.
- Mapping fields between different data schemas (e.g., database results to an application model).
- Restructuring configuration data.
- Converting data formats, such as changing field names from `snake_case` to `camelCase`.
- Performing simple aggregations, calculations, or filtering on data.

The following diagram illustrates the workflow of the Transform Agent, showing how a developer defines a transformation, provides input data, and receives the transformed output.

![Transform Agent](https://media.arcblock.io/lib/06/06f2d2b47dee4a66.w1600.webp)

For transformations that require more complex, custom logic, consider using the [Function Agent](/en/docs/aigne-framework/developer-guide-agents-function-agent-9dc03e/).

## Configuration

The `TransformAgent` is configured using the following options.

- **jsonata** `string` *(required)* — A JSONata expression string that defines the data transformation logic. JSONata is a lightweight query and transformation language for JSON data. The expression dictates how the input message is transformed into the output message. You can experiment with expressions in the JSONata Playground.

```
**Common Patterns:**
  - **Field Mapping:** `{ "newField": oldField }`
  - **Array Transformation:** `items.{ "name": product_name, "price": price }`
  - **Calculations:** `$sum(items.price)`
  - **Conditional Logic:** `condition ? value1 : value2`
  - **String Operations:** `$uppercase(name)`
</x-field-desc>
```

## Usage

The `TransformAgent` can be defined either programmatically using TypeScript or declaratively using YAML.

### TypeScript Example

This example demonstrates how to create a `TransformAgent` that converts field names from snake_case to camelCase.

**Transform Agent Example**

```typescript
import { TransformAgent } from "@aigne/core";

// 1. Define the TransformAgent
const snakeToCamelAgent = TransformAgent.from({
  name: "snake-to-camel-converter",
  description: "Converts user data fields from snake_case to camelCase.",
  jsonata: `{
    "userId": user_id,
    "userName": user_name,
    "createdAt": created_at
  }`,
});

// 2. Define the input data
const inputData = {
  user_id: "usr_12345",
  user_name: "John Doe",
  created_at: "2023-10-27T10:00:00Z",
};

// 3. Invoke the agent to perform the transformation
async function runTransform() {
  const result = await snakeToCamelAgent.invoke(inputData);
  console.log(result);
}

runTransform();
```

The agent applies the JSONata expression to the `inputData`, renaming the keys as specified.

<strong>Output</strong>

```json
{
  "userId": "usr_12345",
  "userName": "John Doe",
  "createdAt": "2023-10-27T10:00:00Z"
}
```

### YAML Example

The same agent can be defined declaratively in a YAML file. This is useful for defining agents as part of a larger configuration.

**transform.yaml**

```yaml
type: transform
name: transform-agent
description: |
  A Transform Agent that processes input data using JSONata expressions.
input_schema:
  type: object
  properties:
    user_id:
      type: string
      description: The ID of the user.
    user_name:
      type: string
      description: The name of the user.
    created_at:
      type: string
      description: The creation date of the user.
  required:
    - user_id
    - user_name
    - created_at
output_schema:
  type: object
  properties:
    userId:
      type: string
      description: The ID of the user.
    userName:
      type: string
      description: The name of the user.
    createdAt:
      type: string
      description: The creation date of the user.
  required:
    - userId
    - userName
    - createdAt
jsonata: |
  {
    "userId": user_id,
    "userName": user_name,
    "createdAt": created_at
  }
```

This YAML definition specifies the agent's type, name, schemas, and the core `jsonata` transformation expression, achieving the same result as the TypeScript example.

## Summary

The `TransformAgent` offers a powerful and concise method for handling structured data transformations. By leveraging JSONata, it separates data mapping and restructuring logic from your main application code, leading to cleaner and more maintainable agentic workflows.

For orchestrating this agent with others, see the [Team Agent](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/) documentation.

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-core-concepts-9dc03e/

To effectively build applications with the AIGNE Framework, it is essential to first understand its fundamental architectural components. This section provides a high-level overview of the primary building blocks and their interactions. A clear grasp of these concepts will facilitate a more intuitive development process.

The framework is designed around a few key abstractions that work together to orchestrate complex AI-driven workflows. The main components are the AIGNE orchestrator, the Agent as the basic unit of work, Models for interfacing with AI services, and Memory for state persistence.

The following diagram illustrates the relationship between these core components.

![Core Concepts](https://media.arcblock.io/lib/35/3555c9a4ae094393.w1600.webp)

## Architectural Building Blocks

The AIGNE Framework is composed of four primary concepts. Understanding each one is crucial for building robust and scalable agent-based applications.

::::card-group
::link-card{title="AIGNE" description="The central orchestrator responsible for managing the lifecycle of agents, coordinating their interactions, and handling the overall execution flow." icon="box" href="/en/docs/aigne-framework/developer-guide-core-concepts-aigne-engine-9dc03e/"}
::link-card{title="Agents" description="The fundamental unit of work. An Agent is an abstraction that encapsulates a specific capability, from running a simple function to complex reasoning." icon="bot" href="/en/docs/aigne-framework/developer-guide-core-concepts-agents-9dc03e/"}
::link-card{title="Models" description="Specialized agents that provide a standardized interface to external services, such as Large Language Models (LLMs) or image generation APIs." icon="brain" href="/en/docs/aigne-framework/developer-guide-core-concepts-models-9dc03e/"}
::link-card{title="Memory" description="Provides agents with the ability to persist and recall information, enabling stateful conversations and context-aware behavior over time." icon="database" href="/en/docs/aigne-framework/developer-guide-core-concepts-memory-9dc03e/"}
::::

## Summary

This section has introduced the four foundational pillars of the AIGNE Framework: the `AIGNE` orchestrator, the `Agent`, `Models`, and `Memory`. Each component plays a distinct and vital role in the architecture.

For a more comprehensive understanding, it is recommended to proceed to the detailed documentation for each concept.

- <strong>Next:</strong> Dive deeper into the [AIGNE orchestrator](/en/docs/aigne-framework/developer-guide-core-concepts-aigne-engine-9dc03e/).

---

## Agents

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-core-concepts-agents-9dc03e/

In the AIGNE Framework, the <strong>`Agent`</strong> is the fundamental unit of work. It is an abstract class that establishes a standard contract for all specialized agent types. An agent can be conceptualized as a distinct worker capable of executing a specific task, processing information, and interacting with other agents within the system.

Every specialized agent, whether designed for interacting with an AI model, transforming data, or orchestrating a team of other agents, inherits its core structure and behavior from this base `Agent` class. This architectural principle ensures consistency and predictability across the framework.

Further reading on specialized agent types can be found in the [Agent Types](/en/docs/aigne-framework/developer-guide-agents-9dc03e/) section.

## Core Concepts

The `Agent` class is designed around several core concepts that define its identity, data contracts, and operational behavior. These are configured via the `AgentOptions` object during the agent's instantiation.

### Key Properties

The following properties define an agent's configuration:

| Property  | Type  | Description  |
|---|---|---|
| `name`  | `string`  | A unique identifier for the agent, used for logging and referencing. It defaults to the constructor's class name if not specified.  |
| `description`  | `string`  | A human-readable summary of the agent's purpose and capabilities, useful for documentation and debugging.  |
| `inputSchema`  | `ZodType`  | A Zod schema defining the structure and validation rules for the agent's input data. This ensures data integrity.  |
| `outputSchema`  | `ZodType`  | A Zod schema defining the structure and validation rules for the agent's output data.  |
| `skills`  | `Agent[]`  | A list of other agents that this agent can invoke to perform delegated sub-tasks, enabling compositional behavior.  |
| `memory`  | `MemoryAgent`  | An optional memory unit allowing the agent to persist and recall state across multiple interactions.  |
| `hooks`  | `AgentHooks[]`  | A set of lifecycle hooks (e.g., `onStart`, `onEnd`) for observing or modifying agent behavior at runtime.  |
| `guideRails`  | `GuideRailAgent[]`  | A list of specialized agents that enforce rules, policies, or constraints on the agent's inputs and outputs.  |

### The process Method

The `process` method is the central component of every agent. It is defined as an `abstract` method in the base `Agent` class, which mandates that any concrete agent class must provide an implementation. This method contains the core logic that defines what the agent does.

The method receives the validated input message and invocation options, including the execution `Context`, and is responsible for producing an output.

**Agent.ts**

```typescript
export abstract class Agent<I extends Message = any, O extends Message = any> {
  // ... constructor and other properties

  /**
   * Core processing method of the agent, must be implemented in subclasses
   *
   * @param input Input message
   * @param options Options for agent invocation
   * @returns Processing result
   */
  abstract process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;

  // ... other methods
}
```

The return value, `AgentProcessResult`, can be a direct object, a streaming response, an async generator, or another agent instance for task forwarding.

## Agent Lifecycle

The execution of an agent adheres to a structured lifecycle, which provides clear points for extension via hooks.

![Agents](https://media.arcblock.io/lib/7d/7dab44a0402c2fe2.w1600.webp)

::::steps
:::step{title="Invocation"}
An agent's execution is initiated by calling its `invoke()` method with an input payload.
:::

:::step{title="`onStart`"}
<strong>Hook</strong>: The `onStart` hooks are triggered, providing an opportunity for pre-processing logic, such as logging or input transformation.
:::

:::step{title="Input Validation"}
The input data is automatically validated against the agent's `inputSchema`. If validation fails, the process is aborted.
:::

:::step{title="`process()`"}
<strong>Execution</strong>: The core logic defined in the agent's `process()` method is executed.
:::

:::step{title="Output Validation"}
The result from the `process()` method is validated against the agent's `outputSchema`.
:::

:::step{title="`onEnd`"}
<strong>Hook</strong>: The `onEnd` hooks are triggered with the final output or any error that occurred. This is the designated point for post-processing, logging results, or implementing custom failure handling.
:::

:::step{title="Return Value"}
The final, validated output is returned to the original caller.
:::
::::

This systematic lifecycle ensures that data is consistently validated and offers clear, non-invasive extension points for custom logic.

## Implementation Example

To create a functional agent, extend the base `Agent` class and implement the `process` method. The following example defines an agent that accepts two numbers and returns their sum.

**adder-agent.ts**

```typescript
import { Agent, type AgentInvokeOptions, type Message } from "@aigne/core";
import { z } from "zod";

// 1. Define the input and output schemas using Zod for validation.
const inputSchema = z.object({
  a: z.number(),
  b: z.number(),
});

const outputSchema = z.object({
  sum: z.number(),
});

// 2. Infer TypeScript types from the Zod schemas.
type AddAgentInput = z.infer<typeof inputSchema>;
type AddAgentOutput = z.infer<typeof outputSchema>;

// 3. Create the custom agent class by extending Agent.
export class AddAgent extends Agent<AddAgentInput, AddAgentOutput> {
  constructor() {
    super({
      name: "AddAgent",
      description: "An agent that adds two numbers.",
      inputSchema,
      outputSchema,
    });
  }

  // 4. Implement the core logic in the process method.
  async process(input: AddAgentInput, options: AgentInvokeOptions): Promise<AddAgentOutput> {
    const { a, b } = input;
    const sum = a + b;
    return { sum };
  }
}
```

This example illustrates the standard implementation pattern:

1. Define Zod schemas for input and output data structures.
2. Extend the `Agent` class with the corresponding input and output types.
3. Provide the schemas and other metadata to the `super()` constructor.
4. Implement the agent's specific logic within the `process` method.

## Summary

The `Agent` class is the foundational abstraction in the AIGNE Framework. It provides a consistent and robust contract for all operational units, ensuring they are identifiable, adhere to clear data schemas, and follow a predictable execution lifecycle. By abstracting this common machinery, the framework allows developers to focus exclusively on implementing the unique logic required for their tasks within the `process` method.

For details on how agents are executed and managed by the central engine, refer to the [AIGNE](/en/docs/aigne-framework/developer-guide-core-concepts-aigne-engine-9dc03e/) documentation. To explore the various specialized agent implementations available, see the [Agent Types](/en/docs/aigne-framework/developer-guide-agents-9dc03e/) section.

---

## AIGNE

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-core-concepts-aigne-engine-9dc03e/

The `AIGNE` class is the central execution engine of the framework. It orchestrates multiple agents to build complex AI applications, serving as the main coordination point for agent interactions, message passing, and the overall execution flow.

This guide covers how to instantiate and configure the `AIGNE` engine, execute agents using the `invoke` method, and manage the application lifecycle.

![AIGNE](https://media.arcblock.io/lib/13/133f4d00259fd636.w1600.webp)

## Overview

AIGNE acts as the container for your entire agentic application. Its primary responsibilities include:

- <strong>Agent Management</strong>: Manages the lifecycle of all registered agents and skills.
- <strong>Model Configuration</strong>: Provides a global default configuration for chat and image models, which can be inherited or overridden by individual agents.
- <strong>Execution Context</strong>: Creates and manages isolated contexts for each invocation, ensuring that concurrent operations do not interfere with each other.
- <strong>Lifecycle Control</strong>: Offers methods to gracefully start and stop the application, ensuring all resources are properly handled.

## Instantiation

There are two primary ways to create an `AIGNE` instance: programmatically using the constructor or by loading a configuration from a directory.

### Using the Constructor

The most direct method is to use the `AIGNE` constructor, passing in an options object. This approach is ideal for applications where configuration is managed dynamically in code.

**Instantiating AIGNE**

```typescript
import { AIGNE } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/openai";

const aigne = new AIGNE({
  name: "MyFirstAIGNEApp",
  model: new OpenAIChatModel({
    apiKey: process.env.OPENAI_API_KEY,
    model: "gpt-4o-mini",
  }),
});
```

### Loading from Configuration

For more complex projects, it is best practice to define your application structure in a directory containing an `aigne.yaml` file and other agent definitions. The static `AIGNE.load()` method reads this directory and constructs a fully configured instance. This promotes separation of configuration from logic.

**Loading AIGNE from a Directory**

```typescript
import { AIGNE } from "@aigne/core";
import { join } from "node:path";

const configPath = join(process.cwd(), "my-aigne-project");
const aigne = await AIGNE.load(configPath);
```

## Configuration Options

The `AIGNE` constructor accepts an `AIGNEOptions` object to control its behavior.

- **name** `string` — A unique name for the AIGNE instance.
- **description** `string` — A brief description of the instance's purpose.
- **rootDir** `string` — The root directory for resolving relative paths for agents and skills.
- **model** `ChatModel` — A global default chat model for all agents that do not specify their own. See Models for more details.
- **imageModel** `ImageModel` — A global default image model for image generation tasks.
- **agents** `Agent[]` — An array of agent instances to register with the engine upon initialization.
- **skills** `Agent[]` — An array of skill agents to make available to other agents.
- **limits** `ContextLimits` — Execution limits, such as timeouts or maximum tokens, to apply to all invocations.
- **observer** `AIGNEObserver` — An observer instance for monitoring and logging execution traces.

## Agent and Lifecycle Management

Once an instance is created, you can manage agents and control the application lifecycle.

### Adding Agents

While agents can be provided in the constructor, you can also add them dynamically using the `addAgent` method. Each agent is attached to the AIGNE instance, giving it access to shared resources like the global model.

**Dynamically Adding an Agent**

```typescript
import { AIAgent } from "@aigne/core";
import { AIGNE } from "@aigne/core";

// Assuming 'aigne' is an existing AIGNE instance
const aigne = new AIGNE();

const myAgent = new AIAgent({
  instructions: "You are a helpful assistant.",
});

aigne.addAgent(myAgent);
```

### Shutting Down

To ensure a clean exit and proper resource cleanup, call the `shutdown` method. This is crucial for long-running applications to prevent resource leaks. The engine also automatically handles process exit signals like `SIGINT`.

**Graceful Shutdown**

```typescript
// Assuming 'aigne' is an existing AIGNE instance
await aigne.shutdown();
```

## Invoking Agents

The `invoke` method is the primary entry point for executing an agent. It is an overloaded method that supports several patterns, from simple request-response to real-time streaming.

### Standard Invocation

The most common use case is to provide an agent and an input message. This returns a promise that resolves with the agent's final output.

**Standard Agent Invocation**

```typescript
// Assuming 'aigne' and 'myAgent' are configured
const result = await aigne.invoke(myAgent, {
  message: "What is the AIGNE Framework?",
});

console.log(result.message);
// Expected output: A descriptive answer about the framework.
```

### Streaming Responses

For interactive applications like chatbots, you can enable streaming to receive the response incrementally. Setting `streaming: true` in the options returns an `AgentResponseStream`. You can then iterate over the stream to process chunks of data as they arrive.

**Streaming Agent Responses**

```typescript
import { isAgentResponseDelta } from "@aigne/core";

// Assuming 'aigne' and 'myAgent' are configured
const stream = await aigne.invoke(
  myAgent,
  { message: "Tell me a short story." },
  { streaming: true }
);

let fullResponse = "";
for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const textDelta = chunk.delta.text?.message ?? "";
    fullResponse += textDelta;
    process.stdout.write(textDelta);
  }
}

console.log("\n--- End of Story ---");
```

### Creating a User Agent

Invoking an agent without a message creates a `UserAgent`. This is a stateful wrapper that preserves the conversation context across multiple calls, making it ideal for building conversational experiences.

**Creating a Stateful UserAgent**

```typescript
// Assuming 'aigne' and 'myAgent' are configured

// Create a UserAgent to maintain context
const userAgent = aigne.invoke(myAgent);

// First interaction
const response1 = await userAgent.invoke({ message: "My name is Bob." });
console.log(response1.message); // e.g., "Nice to meet you, Bob!"

// Second interaction preserves context
const response2 = await userAgent.invoke({ message: "What is my name?" });
console.log(response2.message); // e.g., "Your name is Bob."
```

The `invoke` method offers additional overloads for advanced scenarios, such as returning the final active agent in a multi-agent team. Refer to the API reference for a complete list of signatures.

With a clear understanding of the `AIGNE` engine, you are now prepared to explore the different types of [Agents](/en/docs/aigne-framework/developer-guide-core-concepts-agents-9dc03e/) that form the building blocks of your application.

---

## Memory

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-core-concepts-memory-9dc03e/

The `MemoryAgent` provides a mechanism for agents to maintain state and remember information across interactions. It acts as a specialized orchestrator that does not process messages directly but manages memory operations through two key components: a `Recorder` for storing information and a `Retriever` for recalling it. This separation of concerns allows for flexible and pluggable memory storage solutions.

## Core Components

The memory system is comprised of three main classes:

::::steps
:::step{title="`MemoryAgent`"}
The central agent that manages memory operations. It is configured with a recorder and a retriever and provides `record()` and `retrieve()` methods to interact with the memory store.
:::

:::step{title="`MemoryRecorder`"}
An agent responsible for writing information to a persistent storage backend (e.g., a database, file system, or vector store). You must provide the implementation for how and where the data is stored.
:::

:::step{title="`MemoryRetriever`"}
An agent responsible for fetching information from the storage backend based on specified criteria, such as a search query or a limit. You must provide the implementation for the retrieval logic.
:::
::::

![Memory](https://media.arcblock.io/lib/9a/9a0388c78736bd3f.w1600.webp)

## How It Works

The `MemoryAgent` delegates tasks to its subordinate agents. When you call the `record()` method on a `MemoryAgent`, it invokes its configured `MemoryRecorder` to persist the data. Similarly, when you call `retrieve()`, it invokes the `MemoryRetriever` to query and return the stored information.

This architecture allows developers to define custom storage and retrieval logic without altering the core agent workflows. For example, you can implement a recorder that saves conversation history to a PostgreSQL database and a retriever that uses vector embeddings to find semantically similar past interactions.

## MemoryAgent

The `MemoryAgent` is the primary interface for memory management. It is not designed to be called directly within a chain of processing agents but rather as a stateful service available to other agents or your application logic.

### Configuration

To create a `MemoryAgent`, you provide it with a `recorder` and a `retriever`. These can be instances of `MemoryRecorder` and `MemoryRetriever` or function definitions for their respective `process` methods.

**Agent Initialization**

```typescript
import { MemoryAgent, MemoryRecorder, MemoryRetriever } from "@aigne/core";
import { v7 as uuidv7 } from "@aigne/uuid";

// 1. Define a simple in-memory store for demonstration
const memoryStore: Map<string, any> = new Map();

// 2. Implement the recorder logic
const recorder = new MemoryRecorder({
  async process({ content }) {
    const memories = content.map((item) => {
      const memory = {
        id: uuidv7(),
        content: item,
        createdAt: new Date().toISOString(),
      };
      memoryStore.set(memory.id, memory);
      return memory;
    });
    return { memories };
  },
});

// 3. Implement the retriever logic
const retriever = new MemoryRetriever({
  async process({ search, limit = 10 }) {
    // This is a simplistic search. A real implementation might use a database query or vector search.
    const allMemories = Array.from(memoryStore.values());
    const filteredMemories = search
      ? allMemories.filter((m) => JSON.stringify(m.content).includes(search as string))
      : allMemories;

    return { memories: filteredMemories.slice(0, limit) };
  },
});

// 4. Instantiate the MemoryAgent
const memoryAgent = new MemoryAgent({
  recorder,
  retriever,
});
```

The example above demonstrates creating a `MemoryAgent` with a simple in-memory storage mechanism. In a production environment, you would replace this with a more robust solution like a database.

### MemoryAgentOptions

- **recorder** `MemoryRecorder | MemoryRecorderOptions['process'] | MemoryRecorderOptions` — The agent or function responsible for storing memories. It can be a full MemoryRecorder instance, a configuration object, or just the processing function.
- **retriever** `MemoryRetriever | MemoryRetrieverOptions['process'] | MemoryRetrieverOptions` — The agent or function responsible for retrieving memories. It can be a full MemoryRetriever instance, a configuration object, or just the processing function.
- **autoUpdate** `boolean` — If true, the agent will automatically record information after completing operations to create a history of interactions.
- **subscribeTopic** `string | string[]` — The topic(s) to subscribe to for automatic message recording.
- **skills** `Agent[]` — An array of other agents to be available as skills. The recorder and retriever are automatically added to this list.

## MemoryRecorder

The `MemoryRecorder` is an abstract agent class that defines the contract for storing memories. You must provide a concrete implementation of its `process` method.

### MemoryRecorderInput

The `process` method of a `MemoryRecorder` receives a `MemoryRecorderInput` object.

- **content** `array` *(required)* — An array of objects to be stored as memories. Each object can contain an input, output, and source to contextualize the memory.
  - **input** `Message` — The input message that led to this memory (e.g., a user's prompt).
  - **output** `Message` — The output message generated (e.g., an AI's response).
  - **source** `string` — The identifier of the agent or system that produced the output.

### MemoryRecorderOutput

The `process` method must return a `MemoryRecorderOutput` object.

- **memories** `Memory[]` *(required)* — An array of the newly created memory objects, each including its unique ID, the original content, and a creation timestamp.

## MemoryRetriever

The `MemoryRetriever` is an abstract agent class that defines the contract for fetching memories from storage. You must provide a concrete implementation of its `process` method.

### MemoryRetrieverInput

The `process` method of a `MemoryRetriever` receives a `MemoryRetrieverInput` object to filter and limit the results.

- **limit** `number` — The maximum number of memories to return. Useful for pagination or keeping context windows small.
- **search** `string | Message` — A search term or message object to filter memories. The implementation determines how this value is used (e.g., keyword search, vector similarity).

### MemoryRetrieverOutput

The `process` method must return a `MemoryRetrieverOutput` object.

- **memories** `Memory[]` *(required)* — An array of the memory objects that matched the retrieval criteria.

## Usage Example

Once the `MemoryAgent` is configured, you can use it within your application's context to record and retrieve information.

**AIGNE Interaction**

```typescript
import { AIGNE } from "@aigne/core";

// Assuming memoryAgent is configured as shown in the first example
const aigne = new AIGNE({
  // ...other configurations
});

async function run() {
  // Record a new memory
  const recordedMemory = await aigne.invoke(memoryAgent.record.bind(memoryAgent), {
    content: [{ input: { query: "What is the capital of France?" } }],
  });
  console.log("Recorded:", recordedMemory.memories[0].id);

  // Retrieve memories
  const retrievedMemories = await aigne.invoke(memoryAgent.retrieve.bind(memoryAgent), {
    search: "France",
    limit: 5,
  });
  console.log("Retrieved:", retrievedMemories.memories);
}

run();
```

This example shows how to use the `aigne.invoke` method to call the `record` and `retrieve` functions on the `memoryAgent` instance, effectively managing the agent's state across interactions.

## Summary

The `MemoryAgent` provides a powerful and flexible abstraction for managing state in agentic applications. By separating the orchestration (`MemoryAgent`) from the implementation details (`MemoryRecorder`, `MemoryRetriever`), you can easily integrate various storage backends, from simple in-memory arrays to sophisticated vector databases.

For more information on the core execution engine, see the [AIGNE](/en/docs/aigne-framework/developer-guide-core-concepts-aigne-engine-9dc03e/) documentation. To understand the fundamental building block of work, refer to the [Agents](/en/docs/aigne-framework/developer-guide-core-concepts-agents-9dc03e/) page.

---

## Models

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-core-concepts-models-9dc03e/

Models are specialized agents that serve as a crucial abstraction layer, providing a standardized interface for interacting with external AI services, such as Large Language Models (LLMs) and image generation platforms. They encapsulate the complexity of API communication, allowing developers to work with various AI providers through a consistent and unified contract.

The AIGNE Framework defines a base `Model` class, which is extended by two primary specializations: `ChatModel` for text-based conversational AI and `ImageModel` for image generation tasks. These abstractions are the foundation upon which higher-level agents like `AIAgent` and `ImageAgent` are built.

## Core Concepts

The `Model` layer is designed to streamline interactions with different AI providers. Instead of writing provider-specific code for each service (like OpenAI, Anthropic, or Google Gemini), you interact with the standardized `ChatModel` or `ImageModel` interface. The AIGNE framework, through specific model packages (e.g., `@aigne/openai`), handles the translation between this standard format and the provider's native API.

This design offers several key advantages:

- <strong>Provider Agnostic:</strong> Swap out underlying AI models with minimal code changes. For example, you can switch from OpenAI's GPT-4 to Anthropic's Claude 3 by simply changing the model instantiation.
- <strong>Standardized Data Structures:</strong> All models use consistent input and output schemas (`ChatModelInput`, `ImageModelOutput`, etc.), simplifying data handling and agent composition.
- <strong>Simplified API:</strong> The models provide a clean, high-level API that abstracts away the nuances of authentication, request formatting, and error handling for each external service.

The following diagram illustrates the relationship between the base `Agent`, the `Model` abstractions, and the external AI services they connect to.

![Models](https://media.arcblock.io/lib/c3/c32d0965b2db8925.w1600.webp)

## ChatModel Abstraction

The `ChatModel` is an abstract class designed for interfacing with Large Language Models (LLMs). It provides a structured way to handle conversational interactions, including multi-turn dialogues, tool usage, and structured data extraction.

### ChatModelInput

The `ChatModelInput` interface defines the data structure for requests sent to a language model. It standardizes how messages, tools, and other configurations are passed.

- **messages** `ChatModelInputMessage[]` *(required)* — An array of message objects that form the conversation history and the current prompt.
- **responseFormat** `ChatModelInputResponseFormat` — Specifies the desired format for the model's output, such as plain text or structured JSON based on a provided schema.
- **tools** `ChatModelInputTool[]` — A list of available tools (functions) that the model can request to call to perform actions or retrieve information.
- **toolChoice** `ChatModelInputToolChoice` — Controls how the model uses the provided tools. It can be set to "auto", "none", "required", or to force a specific function call.
- **modelOptions** `ChatModelInputOptions` — A container for provider-specific options, such as temperature, topP, or parallelToolCalls.
- **outputFileType** `'local' | 'file'` — Specifies the desired format for any file-based outputs, either as a local file path (local) or a base64-encoded string (file).

#### ChatModelInputMessage

Each message in the `messages` array follows a defined structure.

- **role** `'system' | 'user' | 'agent' | 'tool'` *(required)* — The role of the message sender. system provides instructions, user represents user input, agent is for model responses, and tool is for the output of a tool call.
- **content** `string | UnionContent[]` — The content of the message. It can be a simple string or an array for multimodal content, combining text and images (FileUnionContent).
- **toolCalls** `object[]` — Used in an agent message to indicate one or more tool calls initiated by the model.
- **toolCallId** `string` — Used in a tool message to link the tool's output back to the corresponding toolCalls request.

### ChatModelOutput

The `ChatModelOutput` interface standardizes the response received from a language model.

- **text** `string` — The text-based content of the model's response.
- **json** `object` — The JSON object returned by the model when responseFormat is set to "json_schema".
- **toolCalls** `ChatModelOutputToolCall[]` — An array of tool call requests made by the model. Each object includes the function name and arguments.
- **usage** `ChatModelOutputUsage` — An object containing token usage statistics, including inputTokens and outputTokens.
- **model** `string` — The identifier of the model that generated the response.
- **files** `FileUnionContent[]` — An array of files generated by the model, if any.

## ImageModel Abstraction

The `ImageModel` is an abstract class for interfacing with image generation models. It provides a simplified contract for creating or editing images based on textual prompts.

### ImageModelInput

The `ImageModelInput` interface defines the request structure for an image generation task.

- **prompt** `string` *(required)* — A textual description of the desired image.
- **image** `FileUnionContent[]` — An optional array of input images, used for tasks like image editing or creating variations.
- **n** `number` — The number of images to generate. Defaults to 1.
- **outputFileType** `'local' | 'file'` — Specifies whether the output images should be saved as local files (local) or returned as base64-encoded strings (file).
- **modelOptions** `ImageModelInputOptions` — A container for provider-specific options, such as image dimensions, quality, or style presets.

### ImageModelOutput

The `ImageModelOutput` interface defines the response structure from an image generation service.

- **images** `FileUnionContent[]` *(required)* — An array of the generated images. The format of each element depends on the outputFileType specified in the input.
- **usage** `ChatModelOutputUsage` — An object containing usage statistics, which may include token counts or other provider-specific metrics.
- **model** `string` — The identifier of the model that generated the images.

## File Content Types

Models handle various forms of file inputs for multimodal tasks through the `FileUnionContent` type. This discriminated union allows files to be represented in three ways:

- <strong>`LocalContent`</strong>: Represents a file stored on the local filesystem.
-
  - `type`: "local"
  - `path`: The absolute path to the file.
- <strong>`UrlContent`</strong>: Represents a file accessible via a public URL.
-
  - `type`: "url"
  - `url`: The URL of the file.
- <strong>`FileContent`</strong>: Represents a file as a base64-encoded string.
-
  - `type`: "file"
  - `data`: The base64-encoded content of the file.

The `Model` base class includes a `transformFileType` method that can automatically convert between these formats as needed, simplifying file handling across different agents and model providers.

## Summary

The `ChatModel` and `ImageModel` abstractions are core components that make the AIGNE Framework flexible and provider-agnostic. They provide a stable, standardized interface for interacting with a wide range of external AI services.

- To learn how to use these models in practice, see the documentation for the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) and [Image Agent](/en/docs/aigne-framework/developer-guide-agents-image-agent-9dc03e/).
- For details on configuring specific providers like OpenAI, Anthropic, or Google Gemini, refer to the guides in the [Models](/en/docs/aigne-framework/models-9dc03e/) section.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/aigne-framework/developer-guide-getting-started-9dc03e/

This guide provides the necessary steps to set up your development environment and run your first AI agent using the AIGNE Framework. The process is designed to be completed in under 30 minutes, offering a practical, hands-on introduction to the framework's fundamental workflow.

We will cover system prerequisites, installation of the required packages, and a complete, copy-paste-ready example that demonstrates how to define, configure, and execute a basic AI agent.

## Prerequisites

Before proceeding, ensure your development environment meets the following requirement:

- <strong>Node.js</strong>: Version 20.0 or higher is required.

You can verify your Node.js version by executing the following command in your terminal:

```bash
node -v
```

## Installation

To begin, you need to install the core AIGNE package and a model provider package. For this guide, we will use the official OpenAI model provider.

Install the necessary packages using your preferred package manager:

::::card-group
::link-card{title="npm" description="```bash     npm install @aigne/core @aigne/openai     ```" icon="package"}
::link-card{title="yarn" description="```bash     yarn add @aigne/core @aigne/openai     ```" icon="package"}
::link-card{title="pnpm" description="```bash     pnpm add @aigne/core @aigne/openai     ```" icon="package"}
::::

Additionally, you will need an OpenAI API key. Set it as an environment variable named `OPENAI_API_KEY`.

**.env**

```bash
OPENAI_API_KEY="sk-..."
```

## Quick Start Example

This example demonstrates the complete process of creating and running a simple "assistant" agent.

1. Create a new TypeScript file named `index.ts`.
2. Copy and paste the following code into the file.

**index.ts**

```typescript
import { AIAgent, AIGNE } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/openai";

// 1. Instantiate the AI Model
// This creates a connection to the OpenAI API using the specified model.
// The API key is read from the OPENAI_API_KEY environment variable.
const model = new OpenAIChatModel({
  model: "gpt-4o-mini",
});

// 2. Define the AI Agent
// An agent is a unit of work. This AIAgent is configured with
// instructions that define its personality and task.
const assistantAgent = AIAgent.from({
  name: "Assistant",
  instructions: "You are a helpful and friendly assistant.",
});

// 3. Instantiate the AIGNE
// The AIGNE class is the central orchestrator that manages and runs agents.
// It is configured with the model that its agents will use.
const aigne = new AIGNE({ model });

async function main() {
  // 4. Invoke the Agent
  // The invoke method runs the agent with a given input.
  // The framework handles the interaction with the model.
  const response = await aigne.invoke(
    assistantAgent,
    "Why is the sky blue?"
  );

  // 5. Print the Response
  console.log(response);
}

main();
```

### Running the Example

Execute the script from your terminal. If you are using TypeScript, you can use a tool like `ts-node`.

```bash
npx ts-node index.ts
```

### Expected Output

The output will be the agent's response to the question, formatted as a JSON object. The content of the `message` field will vary, as it is generated by the AI model.

```json
{
  "message": "The sky appears blue because of a phenomenon called Rayleigh scattering..."
}
```

## Code Breakdown

The example is composed of four primary steps that represent the core workflow of the AIGNE Framework.

::::steps
:::step{title="Model Initialization"}
An instance of `OpenAIChatModel` is created. This object serves as a direct interface to the specified OpenAI model (e.g., `gpt-4o-mini`). It requires an API key for authentication, which is automatically sourced from the `OPENAI_API_KEY` environment variable.
:::

:::step{title="Agent Definition"}
An `AIAgent` is defined using the static `from` method. This is the fundamental unit of work in the framework. Its behavior is defined by the `instructions` property, which acts as a system prompt, guiding the AI model's responses.
:::

:::step{title="AIGNE Instantiation"}
The `AIGNE` class is instantiated. It acts as the execution engine and orchestrator for all agents. By passing the `model` instance into its constructor, we establish a default model for all agents managed by this AIGNE instance.
:::

:::step{title="Agent Invocation"}
The `aigne.invoke()` method is called to execute the `assistantAgent`. The first argument is the agent to run, and the second is the input message. The framework manages the complete lifecycle of the request: sending the prompt and instructions to the model, receiving the response, and returning it as structured output.
:::
::::

This simple example illustrates the modular and declarative nature of the framework, where models, agents, and the execution engine are configured and composed to build powerful AI-driven applications.

## Summary

In this guide, you have successfully set up your environment, installed the necessary AIGNE packages, and built and run a functional AI agent. You have learned the basic workflow: defining a model, creating an agent with specific instructions, and using the AIGNE to invoke it with a user prompt.

With this foundation, you are now ready to explore more advanced topics.

- To understand the fundamental building blocks of the framework in greater detail, proceed to the [Core Concepts](/en/docs/aigne-framework/developer-guide-core-concepts-9dc03e/) documentation.
- To learn about the different types of specialized agents and their use cases, see the [Agent Types](/en/docs/aigne-framework/developer-guide-agents-9dc03e/) section.

---

## Examples

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-9dc03e/

Explore a collection of practical examples that demonstrate the various features and workflow patterns of the AIGNE Framework. This section provides hands-on, executable demos to help you understand intelligent conversation, MCP protocol integration, memory mechanisms, and complex agentic workflows.

## Quick Start

You can run any example directly without a local installation using `npx`. This approach is the fastest way to see the AIGNE Framework in action.

### Prerequisites

- Node.js (version 20.0 or higher) and npm installed.
- An API key for your chosen Large Language Model (LLM) provider (e.g., OpenAI).

### Run an Example

Execute the following commands in your terminal to run a basic chatbot.

1. <strong>Set your API key:</strong> Replace `YOUR_OPENAI_API_KEY` with your actual OpenAI API key. ```sh export OPENAI_API_KEY=YOUR_OPENAI_API_KEY ```
2. <strong>Run in one-shot mode:</strong> The agent will process a default prompt and exit. ```sh npx -y @aigne/example-chat-bot ```
3. <strong>Run in interactive mode:</strong> Use the `--interactive` flag to start an interactive session where you can have a conversation with the agent. ```sh npx -y @aigne/example-chat-bot --interactive ```

### Using Different LLMs

You can specify different models by setting the `MODEL` environment variable along with the corresponding API key. Below are configurations for several popular providers.

| Provider  | Environment Variables  |
|---|---|
| <strong>OpenAI</strong>  | `export MODEL=openai:gpt-4o` `export OPENAI_API_KEY=...`  |
| <strong>Anthropic</strong>  | `export MODEL=anthropic:claude-3-opus-20240229` `export ANTHROPIC_API_KEY=...`  |
| <strong>Google Gemini</strong>  | `export MODEL=gemini:gemini-1.5-flash` `export GEMINI_API_KEY=...`  |
| <strong>DeepSeek</strong>  | `export MODEL=deepseek/deepseek-chat` `export DEEPSEEK_API_KEY=...`  |
| <strong>AWS Bedrock</strong>  | `export MODEL=bedrock:anthropic.claude-3-sonnet-20240229-v1:0` `export AWS_ACCESS_KEY_ID=...` `export AWS_SECRET_ACCESS_KEY=...` `export AWS_REGION=...`  |
| <strong>Ollama</strong>  | `export MODEL=llama3` `export OLLAMA_DEFAULT_BASE_URL="http://localhost:11434/v1"`  |

## Example Library

This section provides a curated list of examples, each demonstrating a specific capability or workflow pattern within the AIGNE Framework. Click on any card to navigate to the detailed guide for that example.

### Core Functionality

::::card-group
::link-card{title="Chatbot" description="Build a basic conversational agent that supports both one-shot and interactive modes." icon="bot" href="/en/docs/aigne-framework/examples-chat-bot-9dc03e/"}
::link-card{title="AFS Local FS" description="Create a chatbot that can read, write, and list files on the local file system." icon="folder" href="/en/docs/aigne-framework/examples-afs-local-fs-9dc03e/"}
::link-card{title="Memory" description="Implement an agent with persistent memory using the FSMemory plugin." icon="brain" href="/en/docs/aigne-framework/examples-memory-9dc03e/"}
::link-card{title="Nano Banana" description="Demonstrates how to create a chatbot with image generation capabilities." icon="image" href="/en/docs/aigne-framework/examples-nano-banana-9dc03e/"}
::::

### Workflow Patterns

::::card-group
::link-card{title="Sequential" description="Execute a series of agents in a specific, ordered sequence, like an assembly line." icon="arrow-right" href="/en/docs/aigne-framework/examples-workflow-sequential-9dc03e/"}
::link-card{title="Concurrency" description="Run multiple agents simultaneously to perform tasks in parallel and improve efficiency." icon="git-branch" href="/en/docs/aigne-framework/examples-workflow-concurrency-9dc03e/"}
::link-card{title="Router" description="Create a manager agent that intelligently directs tasks to the appropriate specialized agent." icon="routes" href="/en/docs/aigne-framework/examples-workflow-router-9dc03e/"}
::link-card{title="Handoff" description="Enable seamless transitions where one agent passes its output to another for further processing." icon="refresh" href="/en/docs/aigne-framework/examples-workflow-handoff-9dc03e/"}
::link-card{title="Reflection" description="Build agents that can review and refine their own output for self-correction and improvement." icon="refresh" href="/en/docs/aigne-framework/examples-workflow-reflection-9dc03e/"}
::link-card{title="Orchestration" description="Coordinate multiple agents to solve complex problems that require collaboration." icon="users" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::link-card{title="Group Chat" description="Simulate a multi-agent discussion where agents can interact and build upon each other's messages." icon="message-square" href="/en/docs/aigne-framework/examples-workflow-group-chat-9dc03e/"}
::link-card{title="Code Execution" description="Safely execute dynamically generated code within an AI-driven workflow." icon="code-2" href="/en/docs/aigne-framework/examples-workflow-code-execution-9dc03e/"}
::::

### MCP and Integrations

::::card-group
::link-card{title="MCP Server" description="Run AIGNE agents as a Model Context Protocol (MCP) server to expose their skills." icon="server" href="/en/docs/aigne-framework/examples-mcp-server-9dc03e/"}
::link-card{title="MCP Blocklet" description="Integrate with a Blocklet and expose its functionalities as MCP skills." icon="box" href="/en/docs/aigne-framework/examples-mcp-blocklet-9dc03e/"}
::link-card{title="MCP GitHub" description="Interact with GitHub repositories using an agent connected to the GitHub MCP Server." icon="github" href="/en/docs/aigne-framework/examples-mcp-github-9dc03e/"}
::link-card{title="MCP Puppeteer" description="Leverage Puppeteer for automated web scraping and browser interaction." icon="navigation" href="/en/docs/aigne-framework/examples-mcp-puppeteer-9dc03e/"}
::link-card{title="MCP SQLite" description="Connect to an SQLite database to perform smart database operations." icon="database" href="/en/docs/aigne-framework/examples-mcp-sqlite-9dc03e/"}
::link-card{title="DID Spaces Memory" description="Persist agent memory using decentralized identity and storage with DID Spaces." icon="key" href="/en/docs/aigne-framework/examples-memory-did-spaces-9dc03e/"}
::::

## Debugging

To gain insight into an agent's execution, you can enable debug logs or use the AIGNE observation server.

### View Debug Logs

Set the `DEBUG` environment variable to `*` to output detailed logs, which include model calls and responses.

```sh
DEBUG=* npx -y @aigne/example-chat-bot --interactive
```

### Use the Observation Server

The `aigne observe` command starts a local web server that provides a user-friendly interface to inspect execution traces, view detailed call information, and understand your agent’s behavior. This is a powerful tool for debugging and performance tuning.

1. <strong>Install the AIGNE CLI:</strong> ```sh npm install -g @aigne/cli ```
2. <strong>Start the observation server:</strong> ```sh aigne observe ```  ![A terminal showing the aigne observe command starting the server.](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)
3. <strong>View Traces:</strong> After running an agent, open your browser to `http://localhost:7893` to see a list of recent executions and inspect the details of each run. ![The AIGNE observability interface showing a list of traces.](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

---

## AFS Local FS

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-afs-local-fs-9dc03e/

This guide demonstrates how to build a chatbot capable of interacting with your local file system. By leveraging the AIGNE File System (AFS) and the `SystemFS` module, you can empower an AI agent to search, read, and manage files on your machine, turning it into a powerful local data expert.

## Overview

The AIGNE File System (AFS) provides a virtual file system layer that gives AI agents a standardized way to access various storage systems. This example focuses on the `SystemFS` module, which bridges AFS to your local file system.

When a user asks a question, the agent intelligently performs the following actions:

::::steps
:::step{title="Search:"}
It uses the `afs_search` tool to find relevant files within the designated directory based on the user's query.
:::

:::step{title="Read:"}
It identifies the most promising file from the search results and uses the `afs_read` tool to access its content.
:::

:::step{title="Synthesize:"}
It processes the file's content to formulate a comprehensive and accurate answer.
:::
::::

This allows the agent to answer questions about your documents, code, or any other text-based files without manual guidance.

## Prerequisites

Before you begin, ensure you have the following installed and configured:

- [Node.js](https://nodejs.org) (version 20.0 or higher)
- An [OpenAI API key](https://platform.openai.com/api-keys)

## Quick Start

You can run this example directly without a local installation using `npx`.

1. <strong>Set your OpenAI API Key:</strong> ```bash export OPENAI_API_KEY=YOUR_OPENAI_API_KEY ```
2. <strong>Run the Chatbot:</strong> You can mount any local directory. For this example, we'll clone the AIGNE framework and use its documentation as the knowledge base. ```bash # Clone the repository to use its docs git clone https://github.com/AIGNE-io/aigne-framework  # Start the chatbot in interactive mode, pointing to the docs npx -y @aigne/example-afs-local-fs --path ./aigne-framework --interactive ```  Alternatively, you can ask a single, specific question: ```bash npx -y @aigne/example-afs-local-fs --path ./aigne-framework --input "What is AIGNE?" ```

### Example Interaction

Here is an example of the agent's process when asked, "What is AIGNE?":

```
👤 You: "What is AIGNE?"

🤖 Agent thinks: I need to find information about AIGNE in the provided files. I will start by searching.
   → Calls: afs_search(query: "AIGNE")

📁 Found 15 matching files:
   • docs/getting-started/what-is-aigne.md ⭐ (most relevant)
   • README.md
   • docs/core-concepts/overview.md
   ...

🤖 Agent thinks: The first result seems most relevant. I will read it to answer the user's question.
   → Calls: afs_read("docs/getting-started/what-is-aigne.md")

📄 File loaded (2.4 KB)

🤖 AI: "AIGNE is a framework and runtime engine for building LLM-powered
       applications and AI agents. It provides:

       • A unified Agentic File System (AFS) interface
       • Support for multiple LLM providers (OpenAI, Anthropic, etc.)
       • Tools for building autonomous agents
       • Integration with external services via MCP

       Would you like me to walk you through a quick-start tutorial, or
       would you prefer to see specific examples?"
```

The agent successfully found the correct file, read its contents, and provided a summarized, helpful response.

## Connecting to an AI Model

The agent requires a connection to a Large Language Model (LLM) to function. If you run the example without providing an API key, you will be prompted to choose a connection method.

![Initial setup prompt when no API key is found.](https://media.arcblock.io/lib/40/40d2d17af24c49bf.w1600.webp)

You have three options:

1. <strong>Connect to AIGNE Hub (Recommended):</strong> This is the easiest way to get started. Your browser will open an authorization page. New users receive free credits to use the service. ![Authorize AIGNE CLI to connect to AIGNE Hub.](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)
2. <strong>Connect to a Self-Hosted AIGNE Hub:</strong> If you are running your own instance of AIGNE Hub, select this option and enter its URL. ![Enter the URL for a self-hosted AIGNE Hub.](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)
3. <strong>Use a Third-Party Model Provider:</strong> You can directly connect to a provider like OpenAI by setting the corresponding environment variable. ```bash export OPENAI_API_KEY="YOUR_OPENAI_API_KEY" ```  For a list of supported providers and their required environment variables, refer to the example `.env.local.example` file in the source code.

## How It Works

The implementation can be broken down into three main steps, as illustrated in the diagram below:

![AFS Local FS](https://media.arcblock.io/lib/d6/d61731d25eb2b246.w1600.webp)

### 1. Create a LocalFS Module

First, instantiate the `LocalFS` module, specifying the local path to the directory you want the agent to access and an optional description.

**create-local-fs.ts**

```typescript
import { LocalFS } from "@aigne/afs-local-fs";

const localFS = new LocalFS({
  localPath: './aigne-framework',
  description: 'AIGNE framework documentation'
});
```

### 2. Mount the Module in AFS

Next, create an `AFS` instance and `mount` the `localFS` module. This makes the local directory available to any agent that has access to this AFS instance.

**mount-module.ts**

```typescript
import { AFS } from "@aigne/afs";
import { AFSHistory } from "@aigne/afs-history";

const afs = new AFS()
  .mount(new AFSHistory({ storage: { url: ":memory:" } }))
  .mount(localFS);  // Mounted at the default path /modules/local-fs
```

### 3. Create and Configure the AI Agent

Finally, create an `AIAgent` and provide it with the `afs` instance. The agent automatically gains access to AFS tools for file system interaction.

**create-agent.ts**

```typescript
import { AIAgent } from "@aigne/core";

const agent = AIAgent.from({
  instructions: "Help users find and read files from the local file system.",
  inputKey: "message",
  afs,  // The agent inherits afs_list, afs_read, afs_write, and afs_search
});
```

### Available AFS Tools

By connecting the agent to AFS, it can use the following sandboxed tools to operate on the mounted directory:

- `afs_list`: Lists files and subdirectories.
- `afs_read`: Reads the content and metadata of a specific file.
- `afs_write`: Creates a new file or overwrites an existing one.
- `afs_search`: Performs a full-text search across all files in the directory.

## Installation and Local Execution

If you prefer to run the example from the source code, follow these steps.

1. <strong>Clone the Repository:</strong> ```bash git clone https://github.com/AIGNE-io/aigne-framework ```
2. <strong>Install Dependencies:</strong> Navigate to the example directory and install the necessary packages using `pnpm`. ```bash cd aigne-framework/examples/afs-local-fs pnpm install ```
3. <strong>Run the Example:</strong> Use the `pnpm start` command to run the chatbot. ```bash # Mount the current directory pnpm start --path .  # Mount a specific directory with a custom description pnpm start --path ~/Documents --description "My Documents"  # Run in interactive chat mode pnpm start --path . --interactive ```

## Use Cases

This example provides a foundation for several practical applications.

### Documentation Chat

Mount your project's documentation folder to create a chatbot that can answer user questions about your project.

```typescript
const afs = new AFS()
  .mount(new LocalFS({ localPath: './docs', description: 'Project documentation' }));
```

### Codebase Analysis

Allow an AI agent to access your source code to help with analysis, refactoring, or explaining complex logic.

```typescript
const afs = new AFS()
  .mount(new LocalFS({ localPath: './src', description: 'Source code' }));
```

### File Organization

Build an agent that can help you sort and manage files in a directory, such as your "Downloads" folder.

```typescript
const afs = new AFS()
  .mount(new LocalFS({ localPath: '~/Downloads', description: 'Downloads folder' }));
```

### Multi-Directory Access

Mount several directories to give the agent a broader context, allowing it to search across your source code, documentation, and tests simultaneously.

```typescript
const afs = new AFS()
  .mount("/docs", new LocalFS({ localPath: './docs' }))
  .mount("/src", new LocalFS({ localPath: './src' }))
  .mount("/tests", new LocalFS({ localPath: './tests' }));
```

## Summary

You have learned how to use the AIGNE Framework to create a chatbot that can interact with a local file system. This powerful capability enables a wide range of applications, from intelligent documentation search to automated code analysis.

For further reading, explore the following related examples and packages:

::::card-group
::link-card{title="Memory Example" description="Learn how to add conversational memory to your chatbot." icon="brain" href="/en/docs/aigne-framework/examples-memory-9dc03e/"}
::link-card{title="MCP Server Example" description="Discover how to integrate your agent with external services using MCP." icon="server" href="/en/docs/aigne-framework/examples-mcp-server-9dc03e/"}
::::

---

## Chatbot

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-chat-bot-9dc03e/

This guide provides a comprehensive walkthrough of the agent-based chatbot example. You will learn how to run the chatbot in different modes, connect it to various AI model providers, and use the AIGNE observability tools to debug its execution. This example is designed to work out-of-the-box, allowing you to get started without any local installation.

## Overview

This example demonstrates how to create and run a simple yet powerful agent-based chatbot using the AIGNE Framework. It supports two primary modes of operation:

- <strong>One-shot mode</strong>: The chatbot takes a single input, provides a response, and then exits.
- <strong>Interactive mode</strong>: The chatbot engages in a continuous conversation until you decide to end the session.

The chatbot can be configured to use different AI models and can accept input directly from the command line or through a pipeline.

## Prerequisites

Before running the example, ensure you have the following installed on your system:

- [Node.js](https://nodejs.org) (version 20.0 or higher)
- An [OpenAI API key](https://platform.openai.com/api-keys) or access to an AIGNE Hub for model interaction.

## Quick Start

You can run this example directly using `npx` without cloning the repository or installing any dependencies locally.

### Running the Example

Execute the following commands in your terminal to run the chatbot.

Run in default one-shot mode:

**npx command**

```bash
npx -y @aigne/example-chat-bot
```

Run in interactive chat mode using the `--interactive` flag:

**npx command**

```bash
npx -y @aigne/example-chat-bot --interactive
```

Use pipeline input to provide a prompt directly:

**npx command**

```bash
echo "Tell me about AIGNE Framework" | npx -y @aigne/example-chat-bot
```

### Connecting to an AI Model

The first time you run the example, it will prompt you to connect to an AI model service since no API keys are configured. The following diagram illustrates the connection options available:

```d2
direction: down

Chatbot-Example: {
  label: "Chatbot Example\n(@aigne/example-chat-bot)"
  shape: rectangle
}

Connection-Options: {
  label: "Connection Options"
  shape: rectangle
  style: {
    stroke-dash: 4
  }

  Official-AIGNE-Hub: {
    label: "1. Official AIGNE Hub\n(Recommended)"
    icon: "https://www.arcblock.io/image-bin/uploads/89a24f04c34eca94f26c9dd30aec44fc.png"
  }

  Self-Hosted-Hub: {
    label: "2. Self-Hosted AIGNE Hub"
    icon: "https://www.arcblock.io/image-bin/uploads/89a24f04c34eca94f26c9dd30aec44fc.png"
  }

  Third-Party-Provider: {
    label: "3. Third-Party Provider\n(e.g., OpenAI)"
    shape: rectangle
  }
}

Blocklet-Store: {
  label: "Blocklet Store"
  icon: "https://store.blocklet.dev/assets/z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ/logo.png"
}

Chatbot-Example -> Connection-Options: "Prompts user to connect to AI model"
Connection-Options.Self-Hosted-Hub -> Blocklet-Store: "Install from"
```

![Initial setup prompt for connecting an AI model.](https://media.arcblock.io/lib/b5/b547e1eb5cde9c69.w1600.webp)

You have several options to proceed:

#### 1. Connect to the Official AIGNE Hub (Recommended)

This is the easiest way to get started.

1. Select the first option: `Connect to the Arcblock official AIGNE Hub`.
2. Your web browser will open a page to authorize the AIGNE CLI.
3. Follow the on-screen instructions to approve the connection. New users receive a complimentary token grant to use the service.

![Authorize AIGNE CLI to connect to AIGNE Hub.](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### 2. Connect to a Self-Hosted AIGNE Hub

If you are running your own instance of AIGNE Hub:

1. Select the second option: `Connect to a self-hosted AIGNE Hub instance`.
2. Enter the URL of your self-hosted AIGNE Hub when prompted.
3. Follow the subsequent prompts to complete the connection.

If you need to set up a self-hosted AIGNE Hub, you can install it from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ).

![Enter the URL for a self-hosted AIGNE Hub.](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

#### 3. Connect via a Third-Party Model Provider

You can also connect directly to a third-party AI model provider, such as OpenAI, by setting the appropriate environment variables. For example, to use OpenAI, set your API key as follows:

**Set OpenAI API Key**

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

After setting the environment variable, run the example again. For a list of supported providers and their required environment variables, refer to the example configuration file.

## Local Installation and Usage

For development purposes, you may want to clone the repository and run the example locally.

### 1. Install AIGNE CLI

First, install the AIGNE Command Line Interface (CLI) globally.

**Install AIGNE CLI**

```bash
npm install -g @aigne/cli
```

### 2. Clone the Repository

Clone the `aigne-framework` repository and navigate to the `chat-bot` example directory.

**Clone repository**

```bash
git clone https://github.com/AIGNE-io/aigne-framework
cd aigne-framework/examples/chat-bot
```

### 3. Run the Example Locally

Use the `pnpm start` command to run the chatbot.

Run in default one-shot mode:

**pnpm command**

```bash
pnpm start
```

Run in interactive chat mode:

**pnpm command**

```bash
pnpm start --interactive
```

Use pipeline input:

**pnpm command**

```bash
echo "Tell me about AIGNE Framework" | pnpm start
```

## Command-Line Options

The chatbot script accepts several command-line arguments to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode. If omitted, runs in one-shot mode.  | `Disabled`  |
| `--model <provider[:model]>`  | Specifies the AI model to use. The format is `provider[:model]`. Examples: `openai` or `openai:gpt-4o-mini`.  | `openai`  |
| `--temperature <value>`  | Sets the temperature for model generation, controlling randomness.  | Provider default  |
| `--top-p <value>`  | Sets the top-p (nucleus sampling) value for model generation.  | Provider default  |
| `--presence-penalty <value>`  | Sets the presence penalty value to influence topic diversity.  | Provider default  |
| `--frequency-penalty <value>`  | Sets the frequency penalty value to reduce repetitive output.  | Provider default  |
| `--log-level <level>`  | Sets the logging level. Options are `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`.  | `INFO`  |
| `--input`, `-i <input>`  | Provides the input prompt directly as an argument.  | `None`  |

## Debugging with AIGNE Observe

AIGNE includes a powerful local observability tool for debugging and analyzing agent execution. The `aigne observe` command starts a local web server that provides a user interface to inspect execution traces.

First, start the observation server in your terminal:

**aigne observe**

```bash
aigne observe
```

![Terminal output showing the aigne observe server running.](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

After running the chatbot, you can open the provided URL (typically `http://localhost:7893`) in your browser to view a list of recent agent executions. This interface allows you to inspect detailed information for each run, including inputs, outputs, model calls, and performance metrics, which is invaluable for debugging and optimization.

![AIGNE observability interface showing a list of traces.](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

This example provides a practical foundation for building agent-based chatbots with the AIGNE Framework. You have learned how to run the example, connect it to various AI models, and utilize the built-in observability tools for debugging.

For more advanced topics and examples, you may find the following documents helpful:

::::card-group
::link-card{title="Memory" description="Learn how to add memory to your chatbot to maintain context across conversations." icon="brain" href="/en/docs/aigne-framework/examples-memory-9dc03e/"}
::link-card{title="AIGNE Core Concepts" description="Dive deeper into the fundamental building blocks of the AIGNE Framework." icon="book-open" href="/en/docs/aigne-framework/developer-guide-core-concepts-9dc03e/"}
::::

---

## MCP Blocklet

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-mcp-blocklet-9dc03e/

This document provides instructions on how to utilize the AIGNE Framework and the Model Context Protocol (MCP) to interact with applications hosted on the Blocklet platform. This example supports one-shot execution, interactive chat mode, and customizable settings for models and I/O pipelines.

## Prerequisites

Before proceeding, ensure the following components are installed and configured on your system:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with Node.js installation.
- <strong>OpenAI API Key</strong>: Required for interacting with OpenAI models. You can obtain one from the [OpenAI API keys page](https://platform.openai.com/api-keys).

The following dependencies are optional and are only required if you intend to run the example from the source code:

- <strong>Bun</strong>: A JavaScript runtime, used here for running tests and examples.
- <strong>pnpm</strong>: A package manager.

## Quick Start

This section provides instructions for running the example directly without a local installation.

### Run the Example

First, set the URL of your target Blocklet application as an environment variable.

**Set your Blocklet app URL**

```bash
export BLOCKLET_APP_URL="https://xxx.xxxx.xxx"
```

You can execute the example in several modes:

- <strong>One-Shot Mode (Default)</strong>: Sends a single request and receives a response. ```bash npx -y @aigne/example-mcp-blocklet ```
- <strong>Interactive Chat Mode</strong>: Starts a continuous chat session. ```bash npx -y @aigne/example-mcp-blocklet --interactive ```
- <strong>Pipeline Input</strong>: Uses piped input as the prompt. ```bash echo "What are the features of this blocklet app?" | npx -y @aigne/example-mcp-blocklet ```

### Connect to an AI Model

Executing the example requires a connection to an AI model. On the first run, if no connection is configured, you will be prompted to choose a connection method.

![Initial connection prompt for AI model setup](https://media.arcblock.io/lib/b5/b547e1eb5cde9c69.w1600.webp)

There are several methods to establish a connection:

#### 1. Connect via the Official AIGNE Hub

This is the recommended approach. Selecting this option will open your web browser to the official AIGNE Hub authentication page. Follow the on-screen instructions to complete the connection. New users are automatically granted 400,000 tokens for use.

![Authorize AIGNE CLI to connect to AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### 2. Connect via a Self-Hosted AIGNE Hub

If you operate your own instance of AIGNE Hub, select the second option. You will be prompted to enter the URL of your self-hosted Hub to complete the connection.

![Enter the URL of your self-hosted AIGNE Hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

To deploy a self-hosted AIGNE Hub, you can install it from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ?utm_source=www.arcblock.io&utm_medium=blog_link&utm_campaign=default&utm_content=store.blocklet.dev#:~:text=%F0%9F%9A%80%20Get%20Started%20in%20Minutes).

#### 3. Connect via a Third-Party Model Provider

You can connect directly to a third-party model provider, such as OpenAI, by setting the appropriate API key as an environment variable.

**Set OpenAI API Key**

```bash
export OPENAI_API_KEY="your_openai_api_key_here"
```

For a comprehensive list of supported environment variables for various providers (e.g., DeepSeek, Google Gemini), refer to the `.env.local.example` file within the example's source code. After configuring the environment variables, run the example command again.

### Debugging

The AIGNE Framework includes a local observability server for monitoring and analyzing agent execution data. This tool is essential for debugging, performance tuning, and understanding agent behavior.

To start the server, run the following command:

**Start the observation server**

```bash
aigne observe
```

![Terminal output showing the aigne observe command running](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

Once the server is running, you can access the web interface at `http://localhost:7893` to view a list of recent agent traces and inspect detailed call information.

![Aigne Observability web interface showing a list of traces](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Installation from Source

For development purposes, you can run the example from a local clone of the repository.

### 1. Clone the Repository

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example directory and install the required packages using `pnpm`.

```bash
cd aigne-framework/examples/mcp-blocklet
pnpm install
```

### 3. Run the Example

Execute the start script to run the application.

**Run in one-shot mode**

```bash
pnpm start
```

You can also provide the Blocklet application URL directly as an argument.

```bash
pnpm start https://your-blocklet-app-url
```

## Run Options

The application supports several command-line parameters for customization.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Enables interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | Specifies the AI model to use. Format is `provider[:model]`. Examples: `openai` or `openai:gpt-4o-mini`.  | `openai`  |
| `--temperature <value>`  | Sets the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Sets the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Sets the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Sets the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Sets the logging level. Options: `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`.  | `INFO`  |
| `--input`, `-i <input>`  | Provides input directly via the command line.  | None  |

When running from source using `pnpm`, you must use `--` to pass arguments to the script.

<strong>Examples:</strong>

**Run in interactive chat mode**

```bash
pnpm start -- --interactive
```

**Set the logging level to DEBUG**

```bash
pnpm start -- --log-level DEBUG
```

**Use pipeline input**

```bash
echo "What are the features of this blocklet app?" | pnpm start
```

## Summary

This guide has detailed the process for running the MCP Blocklet example, including quick-start execution, model configuration, debugging, and local installation. For more advanced use cases and related concepts, refer to the following documentation.

::::card-group
::link-card{title="MCP Server" description="Learn how to run AIGNE Framework agents as a Model Context Protocol (MCP) Server." icon="server" href="/en/docs/aigne-framework/examples-mcp-server-9dc03e/"}
::link-card{title="MCP Agent" description="Understand how to connect to and interact with external systems via MCP." icon="bot" href="/en/docs/aigne-framework/developer-guide-agents-mcp-agent-9dc03e/"}
::::

---

## MCP DID Spaces

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-mcp-did-spaces-9dc03e/

This document provides a comprehensive guide to building a chatbot integrated with DID Spaces via the Model Context Protocol (MCP). Following these instructions will enable you to create an AI agent that can securely access and manage files in a decentralized storage environment, leveraging the capabilities of the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework).

## Prerequisites

To ensure successful execution of this example, verify that the following components are installed and configured:

- <strong>Node.js</strong>: Version 20.0 or a more recent version.
- <strong>OpenAI API Key</strong>: An active API key is required for the AI model. Keys can be obtained from the [OpenAI Platform](https://platform.openai.com/api-keys).
- <strong>DID Spaces MCP Server Credentials</strong>: Authentication details are necessary for interaction with your designated DID Space.

## Quick Start

This example can be executed directly from your terminal without a local installation by using `npx`.

### 1. Set Environment Variables

Begin by configuring the environment variables with your DID Spaces server credentials. The URL for your space and an access key can be generated from your Blocklet's administration settings.

**Set DID Spaces Credentials**

```bash
# Replace with your DID Spaces application URL
export DID_SPACES_URL="https://spaces.staging.arcblock.io/app"

# Create a key in Profile -> Settings -> Access Keys, setting Auth Type to "Simple"
export DID_SPACES_AUTHORIZATION="blocklet-xxx"
```

### 2. Run the Example

With the environment variables set, execute the command below to initialize the chatbot.

**Run the Example**

```bash
npx -y @aigne/example-mcp-did-spaces
```

### 3. Connect to an AI Model

The chatbot requires a connection to a Large Language Model (LLM) to operate. On the first run, a prompt will appear to guide you through the connection setup.

![Initial prompt for AI model connection](https://media.arcblock.io/lib/b5/b547e1eb5cde9c69.w1600.webp)

There are three primary methods for establishing a connection:

#### Option 1: AIGNE Hub (Recommended)

This is the most direct method. The official AIGNE Hub provides new users with complimentary tokens. To use this option, select the first choice in the prompt. Your web browser will open to the AIGNE Hub authorization page, where you can approve the connection request.

![Authorize AIGNE Hub connection](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### Option 2: Self-Hosted AIGNE Hub

For users operating a private AIGNE Hub instance, select the second option. You will be prompted to enter the URL of your self-hosted hub. Instructions for deploying a personal AIGNE Hub are available at the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ).

![Connect to a self-hosted AIGNE Hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

#### Option 3: Third-Party Model Provider

Direct integration with third-party LLM providers such as OpenAI is also supported. Configure the respective API key as an environment variable and execute the run command again.

**Configure OpenAI API Key**

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

For additional configuration examples, including providers like DeepSeek and Google Gemini, consult the `.env.local.example` file within the source repository.

Once the AI model is connected, the example will perform a series of test operations against your DID Space, log the outcomes to the console, and generate a markdown file summarizing the results.

## How It Works

This example employs an `MCPAgent` to interface with a DID Spaces server using the Model Context Protocol (MCP). This protocol enables the agent to dynamically discover and utilize "skills," which are direct mappings to DID Spaces functionalities.

The following diagram illustrates the operational flow:

```d2
direction: down

AI-Agent: {
  label: "AI Agent"
  shape: rectangle
}

MCPAgent: {
  label: "MCPAgent"
  shape: rectangle
}

DID-Spaces-Server: {
  label: "DID Spaces MCP Server"
  shape: rectangle

  Skills: {
    label: "Available Skills"
    shape: rectangle
    list-objects: "list_objects"
    write-object: "write_object"
    read-object: "read_object"
    head-space: "head_space"
    delete-object: "delete_object"
  }
}

DID-Space: {
  label: "DID Space"
  shape: cylinder
}

AI-Agent -> MCPAgent: "3. Execute command\n(e.g., 'list files')"
MCPAgent -> DID-Spaces-Server: "1. Connect & Authenticate"
DID-Spaces-Server -> MCPAgent: "2. Provide Skills"
MCPAgent -> DID-Space: "4. Perform operation via skill"
```

The operational flow is as follows:

1. The `MCPAgent` connects to the designated DID Spaces MCP server endpoint.
2. It authenticates using the provided authorization credentials.
3. The server makes a set of skills, such as `list_objects` and `write_object`, available to the agent.
4. The `MCPAgent` integrates these skills, allowing the primary AI agent to perform file and data management tasks within the DID Space in response to user input or programmed logic.

### Available Skills

The integration exposes several key DID Spaces operations as skills that the agent can utilize:

| Skill  | Description  |
|---|---|
| `head_space`  | Retrieves metadata about the DID Space.  |
| `read_object`  | Reads the content of a specified object (file).  |
| `write_object`  | Writes new content to an object (file).  |
| `list_objects`  | Lists all objects (files) within a directory.  |
| `delete_object`  | Deletes a specified object (file).  |

## Configuration

For production deployments, the agent configuration should be updated to target your specific MCP server and employ secure authentication tokens. The `MCPAgent` is instantiated with the server URL and appropriate authorization headers.

**agent-config.ts**

```typescript
const mcpAgent = await MCPAgent.from({
  url: "YOUR_MCP_SERVER_URL",
  transport: "streamableHttp",
  opts: {
    requestInit: {
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
      },
    },
  },
});
```

## Debugging

The `aigne observe` command provides a tool for monitoring and analyzing the agent's runtime behavior. It launches a local web server that visualizes execution traces, offering insights into inputs, outputs, tool interactions, and performance metrics.

1. <strong>Start the observation server:</strong> **aigne observe**  ```bash aigne observe ```  ![AIGNE Observe server starting in the terminal](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)
2. <strong>View execution traces:</strong> Access the web interface at `http://localhost:7893` to review a list of recent agent executions. Each trace can be inspected for a detailed analysis of the agent's operations. ![AIGNE Observe trace list](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Local Installation and Testing

For developers intending to modify the source code, the following steps outline the process for local setup and testing.

### 1. Clone the Repository

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Change to the example's directory and use `pnpm` to install the required packages.

```bash
cd aigne-framework/examples/mcp-did-spaces
pnpm install
```

### 3. Run the Example

Execute the start script to run the application from the local source.

```bash
pnpm start
```

### 4. Run Tests

To validate the integration and functionality, execute the test suite.

```bash
pnpm test:llm
```

The test process will establish a connection to the MCP server, enumerate the available skills, and perform basic DID Spaces operations to confirm the integration is functioning as expected.

---

## MCP GitHub

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-mcp-github-9dc03e/

This document provides a comprehensive guide to an example that demonstrates how to interact with GitHub repositories using the AIGNE Framework and the GitHub MCP (Model Context Protocol) Server. You will learn how to set up and run the example, enabling an AI agent to perform various GitHub operations like searching repositories and managing files.

## Overview

The example showcases the integration of an `MCPAgent` that connects to a GitHub MCP server. This agent equips the AI with a suite of tools (skills) to interact with the GitHub API. The workflow allows a user to make requests in natural language, which the AI agent then translates into specific function calls to the GitHub agent to perform actions such as searching for repositories, reading file contents, or creating issues.

```d2
direction: down

User: {
  shape: c4-person
}

AIGNE-Framework: {
  label: "AIGNE Framework"
  shape: rectangle

  AIAgent: {
    label: "AI Agent\n(@aigne/core)"
    shape: rectangle
  }

  MCPAgent: {
    label: "GitHub MCP Agent\n(Skill)"
    shape: rectangle
  }

  AIAgent -> MCPAgent: "Uses skill"
}

GitHub-MCP-Server: {
  label: "GitHub MCP Server\n(@modelcontextprotocol/server-github)"
  shape: rectangle
}

GitHub-API: {
  label: "GitHub API"
  shape: cylinder
}

AI-Model-Provider: {
  label: "AI Model Provider\n(e.g., OpenAI, AIGNE Hub)"
  shape: cylinder
}

AIGNE-Observe: {
  label: "AIGNE Observe\n(Debugging UI)"
  shape: rectangle
}

User -> AIGNE-Framework.AIAgent: "1. Natural language request"
AIGNE-Framework.AIAgent -> AI-Model-Provider: "2. Process request"
AI-Model-Provider -> AIGNE-Framework.AIAgent: "3. Return function call"
AIGNE-Framework.AIAgent -> AIGNE-Framework.MCPAgent: "4. Execute function call"
AIGNE-Framework.MCPAgent -> GitHub-MCP-Server: "5. Send command"
GitHub-MCP-Server -> GitHub-API: "6. Call GitHub API"
GitHub-API -> GitHub-MCP-Server: "7. Return API response"
GitHub-MCP-Server -> AIGNE-Framework.MCPAgent: "8. Return result"
AIGNE-Framework.MCPAgent -> AIGNE-Framework.AIAgent: "9. Return result"
AIGNE-Framework.AIAgent -> AI-Model-Provider: "10. Process result"
AI-Model-Provider -> AIGNE-Framework.AIAgent: "11. Return natural language response"
AIGNE-Framework.AIAgent -> User: "12. Final response"
AIGNE-Framework -> AIGNE-Observe: "Sends execution traces"
```

## Prerequisites

Before proceeding, ensure your system meets the following requirements:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with Node.js.
- <strong>GitHub Personal Access Token</strong>: A token with the necessary permissions for the repositories you intend to interact with. You can create one from your [GitHub settings](https://github.com/settings/tokens).
- <strong>AI Model Provider Account</strong>: An API key from a provider like [OpenAI](https://platform.openai.com/api-keys) or a connection to an AIGNE Hub instance.

## Quick Start

You can run this example directly without a local installation using `npx`.

First, set your GitHub token as an environment variable.

**Set your GitHub token**

```bash
export GITHUB_TOKEN=YOUR_GITHUB_TOKEN
```

Next, execute the example.

**Run the example**

```bash
npx -y @aigne/example-mcp-github
```

### Connect to an AI Model

Upon first execution, if no AI model is configured, you will be prompted to connect one.

You have several options to proceed:

#### 1. Connect to the Official AIGNE Hub

This is the recommended approach. Selecting this option will open your browser to the official AIGNE Hub page. Follow the on-screen instructions to authorize the connection. New users receive complimentary credits to get started.

#### 2. Connect to a Self-Hosted AIGNE Hub

If you operate your own instance of AIGNE Hub, choose this option. You will be prompted to enter the URL of your self-hosted Hub to complete the connection.

#### 3. Configure a Third-Party Model Provider

You can also connect directly to a supported third-party model provider, such as OpenAI. To do this, set the provider's API key as an environment variable.

For example, to use OpenAI, configure your `OPENAI_API_KEY`:

**Set your OpenAI API key**

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

After setting the environment variable, run the `npx` command again. For a list of supported environment variables for other providers, refer to the `.env.local.example` file in the project source.

## Installation from Source

For developers who wish to inspect or modify the code, follow these steps to run the example from a local clone.

### 1. Clone the Repository

Clone the main AIGNE Framework repository from GitHub.

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example's directory and install the necessary dependencies using `pnpm`.

```bash
cd aigne-framework/examples/mcp-github
pnpm install
```

### 3. Run the Example

Execute the start script to run the example.

**Run in one-shot mode**

```bash
pnpm start
```

The example also supports interactive chat mode and can accept input piped from other commands.

**Run in interactive chat mode**

```bash
pnpm start -- --interactive
```

**Use pipeline input**

```bash
echo "Search for repositories related to 'modelcontextprotocol'" | pnpm start
```

### Command-Line Options

You can customize the execution with the following command-line parameters:

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | Specify the AI model to use (e.g., `openai` or `openai:gpt-4o-mini`).  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging level (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).  | `INFO`  |
| `--input, -i <input>`  | Specify input directly as an argument.  | None  |

## Code Example

The following TypeScript code demonstrates the core logic of the example. It initializes an AI model, sets up the `MCPAgent` for GitHub, and invokes an `AIAgent` to perform a repository search.

**index.ts**

```typescript
import { AIAgent, AIGNE, MCPAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

// Load environment variables
const { OPENAI_API_KEY, GITHUB_TOKEN } = process.env;

// Initialize OpenAI model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// Initialize GitHub MCP agent
const githubMCPAgent = await MCPAgent.from({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: {
    GITHUB_TOKEN,
  },
});

// Create AIGNE instance with the model and GitHub skills
const aigne = new AIGNE({
  model,
  skills: [githubMCPAgent],
});

// Create an AI agent with instructions for interacting with GitHub
const agent = AIAgent.from({
  instructions: `\
## GitHub Interaction Assistant
You are an assistant that helps users interact with GitHub repositories.
You can perform various GitHub operations like:
1. Searching repositories
2. Getting file contents
3. Creating or updating files
4. Creating issues and pull requests
5. And many more GitHub operations

Always provide clear, concise responses with relevant information from GitHub.
`,
});

// Invoke the agent to search for repositories
const result = await aigne.invoke(
  agent,
  "Search for repositories related to 'modelcontextprotocol'",
);

console.log(result);
// Expected Output:
// I found several repositories related to 'modelcontextprotocol':
//
// 1. **modelcontextprotocol/servers** - MCP servers for various APIs and services
// 2. **modelcontextprotocol/modelcontextprotocol** - The main ModelContextProtocol repository
// ...

// Shutdown the AIGNE instance when done
await aigne.shutdown();
```

## Available Operations

The GitHub MCP server exposes a wide range of GitHub functionalities as skills that the AI agent can use, including:

- <strong>Repository Operations</strong>: Search, create, and get information about repositories.
- <strong>File Operations</strong>: Get file contents, create or update files, and push multiple files in a single commit.
- <strong>Issue and PR Operations</strong>: Create issues and pull requests, add comments, and merge pull requests.
- <strong>Search Operations</strong>: Search code, issues, and users.
- <strong>Commit Operations</strong>: List commits and get commit details.

## Debugging with AIGNE Observe

To inspect and analyze the behavior of your agent, you can use the `aigne observe` command. This tool starts a local web server that provides a user interface for viewing execution traces, call details, and other runtime data.

To start the observation server, run:

**Start the AIGNE observe server**

```bash
aigne observe
```

Once the server is running, you can access the web interface in your browser to view a list of recent executions and drill down into the details of each trace.

This tool is invaluable for debugging, understanding how the agent interacts with tools and models, and optimizing performance.

---

## MCP Puppeteer

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-mcp-puppeteer-9dc03e/

This guide provides a step-by-step demonstration of how to use the AIGNE Framework with a Puppeteer MCP Server for automated web scraping. By following this example, you will learn to build and run an AI agent capable of navigating to a website and extracting its content.

## Overview

This example showcases an integration between an `AIAgent` and a `MCPAgent` that controls a Puppeteer instance. The `AIAgent` receives a natural language command to extract content from a URL. It then delegates the web automation tasks to the Puppeteer agent, which navigates to the specified page and executes JavaScript to scrape the content.

The general workflow is as follows:

```mermaid
flowchart LR

in(In)
out(Out)
agent(AI Agent)
puppeteer(Puppeteer MCP Agent)
navigate(Navigate to URL)
evaluate(Evaluate JS)

in --> agent <--> puppeteer

subgraph MCP Agent
  puppeteer <--> navigate
  puppeteer <--> evaluate
end

agent --> out

classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px,color:#b35b39,font-weight:bolder;
classDef processing fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px,color:#6B8F3C,font-weight:bolder;

class in inputOutput
class out inputOutput
class agent processing
class puppeteer processing
class navigate processing
class evaluate processing
```

The sequence of operations for summarizing website content is illustrated below:

```d2
shape: sequence_diagram

User: {
  shape: c4-person
}

AI: {
  label: "AI Agent"
}

P: {
  label: "Puppeteer MCP Agent"
}

N: {
  label: "Navigate to URL"
}

E: {
  label: "Evaluate JS"
}

User -> AI: "summarize content from https://www.arcblock.io"
AI -> P: "extract content from https://www.arcblock.io"
P -> N: "navigate to https://www.arcblock.io"
N -> P: "navigation completed"
P -> E: "evaluate document.body.innerText"
E -> P: "content extracted"
E -> AI: "extracted content as context"
AI -> User: "The content is as follows: ..."
```

## Prerequisites

Before running the example, ensure the following requirements are met:

- Node.js version 20.0 or higher.
- An active OpenAI API key.

## Quick Start

You can run this example directly without cloning the repository using `npx`.

### Run the Example

Execute the following commands in your terminal. The example supports a one-shot mode, an interactive chat mode, and can receive input via a pipeline.

**Run in one-shot mode**

```sh
# Run in one-shot mode (default)
npx -y @aigne/example-mcp-puppeteer
```

**Run in interactive chat mode**

```sh
# Run in interactive chat mode
npx -y @aigne/example-mcp-puppeteer --interactive
```

**Use pipeline input**

```sh
# Use pipeline input
echo "extract content from https://www.arcblock.io" | npx -y @aigne/example-mcp-puppeteer
```

### Connect to an AI Model

On the first run, if no model provider is configured, the application will prompt you to connect to one.

![Initial connection prompt for AI model](https://media.arcblock.io/lib/fd/fd3700482377c3ca.w1600.webp)

You have several options to proceed:

- <strong>Connect via the official AIGNE Hub:</strong> This is the recommended option. Choosing it will open your web browser to the AIGNE Hub, where you can authorize the connection. New users receive a complimentary token balance for trial purposes. ![Authorize connection to AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)
- <strong>Connect via a self-hosted AIGNE Hub:</strong> If you host your own AIGNE Hub, select this option and enter the URL of your instance to complete the connection. You can deploy your own AIGNE Hub from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ?utm_source=www.arcblock.io&utm_medium=blog_link&utm_campaign=default&utm_content=store.blocklet.dev#:~:text=%F0%9F%9A%80%20Get%20Started%20in%20Minutes). ![Connect to a self-hosted AIGNE Hub instance](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)
- <strong>Connect via a third-party model provider:</strong> You can configure an API key from a provider like OpenAI directly using environment variables. **Configure OpenAI API Key**  ```sh export OPENAI_API_KEY="YOUR_API_KEY" ```  For a comprehensive list of supported providers and variables, refer to the example `.env.local.example` file within the project. After setting the environment variable, run the command again.

## Installation from Source

To examine the code or make modifications, you can clone the repository and run the example locally.

### 1. Clone the Repository

**Clone the aigne-framework repository**

```sh
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example directory and install the required packages using `pnpm`.

**Install dependencies**

```sh
cd aigne-framework/examples/mcp-puppeteer
pnpm install
```

### 3. Run the Example

Execute the start script to run the application.

**Run the example from source**

```sh
pnpm start
```

To pass command-line arguments to the script, separate them with `--`.

**Run in chat mode from source**

```sh
pnpm start -- --interactive
```

## Code Example

The following TypeScript code demonstrates the core logic for setting up the AIGNE instance, configuring the Puppeteer MCP agent, and invoking the AI agent to extract web content.

**agent.ts**

```typescript
import { AIAgent, AIGNE, MCPAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

// Initialize the OpenAI model with an API key
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// Create an MCPAgent that runs the Puppeteer server
const puppeteerMCPAgent = await MCPAgent.from({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-puppeteer"],
});

// Initialize the AIGNE instance with the model and the Puppeteer agent as a skill
const aigne = new AIGNE({
  model,
  skills: [puppeteerMCPAgent],
});

// Define the AI agent with instructions for web content extraction
const agent = AIAgent.from({
  instructions: `\
## Steps to extract content from a website
1. navigate to the url
2. evaluate document.body.innerText to get the content
`,
});

// Invoke the agent with a prompt
const result = await aigne.invoke(
  agent,
  "extract content from https://www.arcblock.io",
);

console.log(result);
// Expected output:
// {
//   $message: "The content extracted from the website [ArcBlock](https://www.arcblock.io) is as follows:\n\n---\n\n**Redefining Software Architect and Ecosystems**\n\nA total solution for building decentralized applications ...",
// }

// Shut down the AIGNE instance and its agents
await aigne.shutdown();
```

## Command-Line Options

The application supports several command-line arguments to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | Specify the AI model. Examples: `openai`, `openai:gpt-4o-mini`.  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging level (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).  | `INFO`  |
| `--input`, `-i <input>`  | Provide input directly as an argument.  | None  |

## Debugging

The AIGNE Framework includes an observability tool to help you monitor and debug agent executions.

To start the observation server, run:

**Start the observability server**

```sh
aigne observe
```

![AIGNE observability server running in the terminal](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

Once running, you can open the web interface in your browser to view a detailed list of execution traces, inspect inputs, outputs, and tool calls for each agent.

![AIGNE observability interface showing a list of traces](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

This tool is essential for understanding agent behavior, diagnosing issues, and optimizing performance.

---

## MCP Server

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-mcp-server-9dc03e/

This guide provides instructions on how to run AIGNE Framework agents as a Model Context Protocol (MCP) server. By the end of this document, you will be able to start the server, connect it to an AI model, and interact with your agents using an MCP-compatible client like Claude Code.

The Model Context Protocol (MCP) is an open standard designed to enable AI assistants to securely connect with various data sources and tools. By exposing AIGNE agents as an MCP server, you can augment MCP-compatible clients with the specialized skills and capabilities of your custom agents.

The following diagram illustrates how the AIGNE MCP server connects your agents to an AI model and an MCP-compatible client.

![This guide provides instructions on how to run AIGNE Framework agents as a Model Context Protocol...](https://media.arcblock.io/lib/a1/a11195cfed272271.w1600.webp)

## Prerequisites

Before proceeding, ensure your development environment meets the following requirements:

- <strong>Node.js:</strong> Version 20.0 or higher.
- <strong>AI Model Access:</strong> An API key for a supported large language model provider, such as OpenAI.

## Quick Start

You can run the example directly without a local installation using `npx`.

### 1. Run the MCP Server

Execute the following command in your terminal to download and start the MCP server example:

**serve-mcp**

```sh
npx -y @aigne/example-mcp-server serve-mcp --port 3456
```

Upon successful execution, the server will start, and you will see the following output, confirming that the MCP server is active and listening for connections.

**Expected Output**

```sh
Observability OpenTelemetry SDK Started, You can run `npx aigne observe` to start the observability server.
MCP server is running on http://localhost:3456/mcp
```

### 2. Connect to an AI Model

The MCP server requires a connection to a large language model to function. If you are running the server for the first time, a command-line prompt will guide you through the connection process.

![A terminal prompt for connecting to an AI model.](https://media.arcblock.io/lib/7a/7a8b39134016fd4c.w1600.webp)

You have three primary options for connecting to an AI model:

#### Option 1: AIGNE Hub (Recommended)

Connect to the official AIGNE Hub to get started quickly. New users receive free credits, making this the most straightforward option for evaluation. Select the first option in the prompt, and your web browser will open to guide you through the authorization process.

![The AIGNE Hub authorization page.](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### Option 2: Self-Hosted AIGNE Hub

If your organization uses a self-hosted instance of AIGNE Hub, select the second option and enter the URL of your hub instance when prompted.

![A terminal prompt to enter a self-hosted AIGNE Hub URL.](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

#### Option 3: Third-Party Model Provider

You can connect directly to a third-party model provider by setting the appropriate environment variables. For example, to use OpenAI, export your API key before running the server command.

**Configure OpenAI API Key**

```sh
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

After setting the environment variable, restart the `serve-mcp` command.

## Available Agents

This example exposes several pre-configured agents as MCP tools, each with a distinct function:

- <strong>Current Time Agent:</strong> Provides the current time. Defined in `agents/current-time.js`.
- <strong>Poet Agent:</strong> Generates poetry and other creative text formats. Defined in `agents/poet.yaml`.
- <strong>System Info Agent:</strong> Retrieves information about the host system. Defined in `agents/system-info.js`.

## Connecting to an MCP Client

Once the MCP server is running, you can connect to it from any MCP-compatible client. The following example uses Claude Code.

First, ensure you have [Claude Code](https://claude.ai/code) installed. Then, add the AIGNE MCP server as a tool source using the following command:

**Add MCP Server to Claude**

```sh
claude mcp add -t http test http://localhost:3456/mcp
```

After adding the server, you can invoke the agents' skills directly from the Claude Code interface.

## Observing Agent Execution

The AIGNE Framework includes an observability tool that allows you to monitor and debug agent behavior in real-time. This tool is essential for analyzing traces, inspecting inputs and outputs, and understanding agent performance.

### 1. Start the Observer

To start the local observability web server, run the following command in a new terminal window:

**Start Observability Server**

```sh
npx aigne observe --port 7890
```

The server will start and provide a URL to access the dashboard.

![Terminal output showing the observability server is running.](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

### 2. View Traces

Open `http://localhost:7890` in your web browser to access the AIGNE observability dashboard. The "Traces" view provides a list of recent agent executions, including details on latency, token usage, and status.

![The Aigne Observability interface showing a list of traces.](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

---

## MCP SQLite

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-mcp-sqlite-9dc03e/

This guide provides a comprehensive walkthrough for interacting with an SQLite database using an AI agent powered by the AIGNE Framework. By following these steps, you will learn how to set up the necessary components, run the example application, and use an agent to perform database operations like creating tables and querying data.

The core of this example involves using an `MCPAgent` to connect to a running [SQLite MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite). This server exposes database functionalities as skills that an `AIAgent` can intelligently invoke based on user prompts.

```d2
direction: down

User: {
  shape: c4-person
}

App: {
  label: "@aigne/example-mcp-sqlite"
  shape: rectangle

  AIGNE-Framework: {
    label: "AIGNE Framework (@aigne/core)"
    shape: rectangle

    AIGNE-Instance: {
      label: "AIGNE Instance"
    }

    AIAgent: {
      label: "AIAgent"
    }

    MCPAgent: {
      label: "MCPAgent"
    }
  }

  AI-Model: {
    label: "AI Model\n(e.g., OpenAI)"
    shape: rectangle
  }
}

SQLite-MCP-Server: {
  label: "SQLite MCP Server"
  shape: rectangle
}

SQLite-DB: {
  label: "SQLite Database\n(usages.db)"
  shape: cylinder
}

User -> App: "1. Run command\n(e.g., 'create a product table')"
App.AIGNE-Framework.AIAgent -> App.AI-Model: "2. Interpret prompt"
App.AI-Model -> App.AIGNE-Framework.AIAgent: "3. Return required skill call"
App.AIGNE-Framework.AIAgent -> App.AIGNE-Framework.MCPAgent: "4. Invoke skill"
App.AIGNE-Framework.MCPAgent -> SQLite-MCP-Server: "5. Send command"
SQLite-MCP-Server -> SQLite-DB: "6. Execute SQL"
SQLite-DB -> SQLite-MCP-Server: "7. Return result"
SQLite-MCP-Server -> App.AIGNE-Framework.MCPAgent: "8. Send response"
App.AIGNE-Framework.MCPAgent -> App.AIGNE-Framework.AIAgent: "9. Forward response"
App.AIGNE-Framework.AIAgent -> App: "10. Process final output"
App -> User: "11. Display result message"
```

## Prerequisites

Before proceeding, ensure your development environment meets the following requirements. Adherence to these prerequisites is necessary for the successful execution of the example.

- <strong>Node.js:</strong> Version 20.0 or higher.
- <strong>npm:</strong> Node.js package manager, included with Node.js.
- <strong>uv:</strong> A Python package installer. Required for running the SQLite MCP Server. Installation instructions can be found at the [official `uv` repository](https://github.com/astral-sh/uv).
- <strong>AI Model API Key:</strong> An API key from a supported provider is required for the AI agent to function. This example defaults to OpenAI, but other providers are supported. You can obtain an [OpenAI API key](https://platform.openai.com/api-keys) from their platform.

For developers intending to run the example from the source code, the following dependencies are also required:

- <strong>Pnpm:</strong> A fast, disk space-efficient package manager.
- <strong>Bun:</strong> A fast JavaScript all-in-one toolkit used for running tests and examples.

## Quick Start

This section provides instructions to run the example directly without a manual installation, which is the most efficient method for a preliminary evaluation.

The application can be executed in a one-shot mode for single commands, in an interactive chat mode, or by piping input directly to the script.

Execute one of the following commands in your terminal:

**Run in one-shot mode (default)**

```bash
npx -y @aigne/example-mcp-sqlite
```

**Run in interactive chat mode**

```bash
npx -y @aigne/example-mcp-sqlite --interactive
```

**Use pipeline input**

```bash
echo "create a product table with columns name description and createdAt" | npx -y @aigne/example-mcp-sqlite
```

## Connecting to an AI Model

The AI agent requires a connection to a Large Language Model (LLM) to process instructions. If you run the example without a pre-configured model, you will be prompted to select a connection method.

![Initial connection prompt when no AI model is configured.](https://media.arcblock.io/lib/05/05a13bf04fd48b70.w1600.webp)

There are three primary methods for establishing this connection:

### 1. Connect to the Official AIGNE Hub

This is the recommended method for new users. It provides a streamlined, browser-based authentication process. New users receive complimentary credits to test the platform.

1. Select the first option: `Connect to the Arcblock official AIGNE Hub`.
2. Your default web browser will open to an authorization page.
3. Follow the on-screen instructions to approve the connection.

![Authorization prompt for connecting the AIGNE CLI to the AIGNE Hub.](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

### 2. Connect to a Self-Hosted AIGNE Hub

If your organization operates a private instance of AIGNE Hub, select the second option and provide the URL of your hub to complete the connection.

![Prompt to enter the URL for a self-hosted AIGNE Hub.](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

### 3. Connect via a Third-Party Model Provider

You can connect directly to a supported third-party model provider, such as OpenAI, by configuring the appropriate API key as an environment variable.

For example, to connect to OpenAI, set the `OPENAI_API_KEY` variable:

**Set OpenAI API key**

```bash
export OPENAI_API_KEY="your-openai-api-key-here"
```

After setting the environment variable, re-run the `npx` command. For a comprehensive list of supported providers and their required environment variables, refer to the example `.env.local.example` file in the repository.

## Installation from Source

For developers who wish to inspect or modify the source code, follow these steps to clone the repository and run the example locally.

### 1. Clone the Repository

Clone the official AIGNE Framework repository to your local machine.

**Clone the repository**

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example directory and install the required dependencies using `pnpm`.

**Install dependencies**

```bash
cd aigne-framework/examples/mcp-sqlite
pnpm install
```

### 3. Run the Example

Execute the application using the `pnpm start` command.

**Run in one-shot mode (default)**

```bash
pnpm start
```

To run in interactive mode or use pipeline input, append the desired flags after a `--` separator.

**Run in interactive chat mode**

```bash
pnpm start -- --interactive
```

**Use pipeline input**

```bash
echo "create a product table with columns name description and createdAt" | pnpm start
```

### Command-Line Options

The application supports several command-line arguments to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Enables interactive chat mode.  | Disabled (one-shot)  |
| `--model <provider[:model]>`  | Specifies the AI model. Format: `'provider[:model]'`.  | `openai`  |
| `--temperature <value>`  | Sets the model's temperature for generation.  | Provider default  |
| `--top-p <value>`  | Sets the model's top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Sets the model's presence penalty.  | Provider default  |
| `--frequency-penalty <value>`  | Sets the model's frequency penalty.  | Provider default  |
| `--log-level <level>`  | Sets the logging verbosity (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).  | `INFO`  |
| `--input`, `-i <input>`  | Provides input directly as an argument.  | `None`  |

## Code Example

The following TypeScript code demonstrates the core logic for setting up and invoking the AI agent to interact with the SQLite database.

The script initializes an `OpenAIChatModel`, starts an `MCPAgent` connected to the SQLite server, and configures an `AIGNE` instance with the model and the agent's skills. Finally, it invokes an `AIAgent` with specific instructions to perform database tasks.

**index.ts**

```typescript
import { join } from "node:path";
import { AIAgent, AIGNE, MCPAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

// 1. Initialize the chat model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// 2. Start the SQLite MCP server as a managed subprocess
const sqlite = await MCPAgent.from({
  command: "uvx",
  args: [
    "-q",
    "mcp-server-sqlite",
    "--db-path",
    join(process.cwd(), "usages.db"),
  ],
});

// 3. Configure the AIGNE instance with the model and MCP skills
const aigne = new AIGNE({
  model,
  skills: [sqlite],
});

// 4. Define the AI agent with specific instructions
const agent = AIAgent.from({
  instructions: "You are a database administrator",
});

// 5. Invoke the agent to create a table
console.log(
  await aigne.invoke(
    agent,
    "create a product table with columns name description and createdAt",
  ),
);
// Expected output:
// {
//   $message: "The product table has been created successfully with the columns: `name`, `description`, and `createdAt`.",
// }

// 6. Invoke the agent to insert data
console.log(await aigne.invoke(agent, "create 10 products for test"));
// Expected output:
// {
//   $message: "I have successfully created 10 test products in the database...",
// }

// 7. Invoke the agent to query data
console.log(await aigne.invoke(agent, "how many products?"));
// Expected output:
// {
//   $message: "There are 10 products in the database.",
// }

// 8. Shut down the AIGNE instance and the MCP server
await aigne.shutdown();
```

## Debugging

To monitor and analyze the agent's execution flow, you can use the `aigne observe` command. This tool launches a local web server that provides a detailed view of traces, tool calls, and model interactions, which is invaluable for debugging and performance analysis.

1. <strong>Start the Observation Server:</strong> **Start the observability server**  ```bash aigne observe ```  ![Terminal output showing the aigne observe command has started the server.](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)
2. <strong>View Traces:</strong> Open the provided URL (e.g., `http://localhost:7893`) in your web browser to access the observability interface. The "Traces" page lists recent agent executions. ![AIGNE observability interface displaying a list of agent execution traces.](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp) From here, you can select an individual trace to inspect the complete sequence of operations, including prompts sent to the model, skills invoked by the agent, and the final output.

---

## Memory

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-memory-9dc03e/

This guide demonstrates how to build a stateful chatbot that retains conversation history across sessions. By leveraging the `FSMemory` plugin, the agent can persist session data to the local file system, enabling it to recall previous interactions.

## Overview

In many conversational AI applications, it is crucial for an agent to remember the context of past interactions to provide coherent and relevant responses. The AIGNE Framework addresses this through its memory components. This example focuses on `FSMemory`, a straightforward solution for persisting conversation history on your local disk.

This approach is ideal for development, testing, or applications where state can be managed locally without requiring external databases or services. For more advanced or distributed persistence, consider alternatives like [DIDSpacesMemory](/en/docs/aigne-framework/examples-memory-did-spaces-9dc03e/).

## How to Run the Example

You can run this example directly using `npx`. This command will download the necessary packages and execute the chatbot script.

To start the chatbot in interactive mode, execute the following command in your terminal:

```sh
npx -y @aigne/example-memory --interactive
```

If you have not configured your LLM API keys, you will be prompted to connect to the AIGNE Hub, which provides a simple way to get started.

![Initial connection prompt for the AI model](https://media.arcblock.io/lib/38/387cd4ef36681ee2.w1600.webp)

## Code Explained

The core of this example is the integration of the `FSMemory` plugin with an `AIAgent`. The agent is configured to use this memory module to automatically save and retrieve the conversation history for a given session.

The following diagram illustrates how the `AIAgent`, `FSMemory` plugin, and the file system interact during a chat session:

![Memory](https://media.arcblock.io/lib/16/161f379787b65017.w1600.webp)

### main.ts

The main script initializes the agent, aigneres the memory plugin, and starts the conversational loop.

**main.ts**

```typescript
import { AIAgent, AIGNE, FSMemory, command, define, option } from '@aigne/framework';
import { ChatOllama } from '@aigne/ollama';
import path from 'node:path';

const program = define({
  name: 'memory-chatbot',
  version: '1.0.0',
});

program(
  command({
    name: 'chat',
    description: 'Chat with the bot',
    options: [
      option({
        name: '--interactive',
        description: 'Chat with the bot',
      }),
    ],
    action: async (_, { session }) => {
      const memory = new FSMemory({
        path: path.join(__dirname, '..', '.memory'),
        sessionId: session.id,
      });

      const llm = new ChatOllama({
        model: 'llama3',
      });

      const chatbot = new AIAgent({
        name: 'chatbot',
        model: llm,
        memory,
        instructions:
          'Your name is Mega. You are a helpful assistant. Please answer the user question.',
      });

      const aigne = new AIGNE({
        agents: [chatbot],
      });

      await aigne.chat(chatbot, {
        endOfStream: (message) => {
          if (message.type === 'end') {
            process.stdout.write('\n');
          }
          if (message.type === 'chunk') {
            process.stdout.write(message.payload.content);
          }
        },
      });
    },
  })
);

program.run();
```

Key components of the script:

1. <strong>Importing Modules</strong>: We import `AIAgent`, `AIGNE`, and `FSMemory` from the AIGNE framework.
2. <strong>Initializing</strong> <strong>`FSMemory`</strong>: An instance of `FSMemory` is created.
3.
  - `path`: Specifies the directory (`.memory`) where conversation logs will be stored.
  - `sessionId`: A unique identifier for the conversation session. This ensures that the history for different chat sessions is stored separately.
4. <strong>Configuring</strong> <strong>`AIAgent`</strong>: The `chatbot` agent is instantiated.
5.
  - `model`: The language model to be used for generating responses.
  - `memory`: The `FSMemory` instance is passed to the agent's constructor. This links the agent to the persistence layer.
  - `instructions`: A system prompt that defines the agent's persona and objective.
6. <strong>Running the Chat</strong>: The `aigne.chat()` method starts the interactive session. The framework automatically handles the loading of past messages from `FSMemory` at the start of the session and saves new messages as the conversation progresses.

## Summary

In this example, you have learned how to create a chatbot with persistent memory using the `FSMemory` plugin. This enables the agent to maintain context across multiple interactions by storing and retrieving conversation history from the local file system. This foundational concept is key to building more advanced and context-aware AI applications.

---

## DID Spaces Memory

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-memory-did-spaces-9dc03e/

This guide demonstrates how to build a chatbot with persistent memory using DID Spaces. By leveraging the `DIDSpacesMemory` plugin from the AIGNE Framework, your agent can retain conversation history across multiple sessions in a decentralized and secure manner.

## Prerequisites

Before you begin, ensure you have the following installed and configured:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with your Node.js installation.
- <strong>OpenAI API Key</strong>: Required for connecting to the language model. You can obtain one from the [OpenAI Platform](https://platform.openai.com/api-keys).
- <strong>DID Spaces Credentials</strong>: Necessary for memory persistence.

## Quick Start

You can run this example directly without any local installation using `npx`.

### 1. Run the Example

Execute the following command in your terminal:

**Run the memory-did-spaces example**

```bash
npx -y @aigne/example-memory-did-spaces
```

### 2. Connect to an AI Model

On the first run, the CLI will prompt you to connect to an AI model because no API keys have been configured.

![run-example.png](https://media.arcblock.io/lib/be/be333450dfb435cf.w1600.webp)

You have several options to proceed:

- <strong>Connect via the official AIGNE Hub (Recommended)</strong> This is the easiest way to get started. Selecting this option will open your web browser to the official AIGNE Hub authentication page. Follow the on-screen instructions to connect your wallet. New users automatically receive a welcome bonus of 400,000 tokens to use. ![Connect to the official AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)
- <strong>Connect via a self-hosted AIGNE Hub</strong> If you have your own instance of AIGNE Hub, choose this option. You will be prompted to enter the URL of your self-hosted Hub to complete the connection. You can deploy your own AIGNE Hub from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ). ![Connect to a self-hosted AIGNE Hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)
- <strong>Connect via a Third-Party Model Provider</strong> You can also connect directly to a third-party provider like OpenAI, DeepSeek, or Google Gemini. To do this, you need to set the provider's API key as an environment variable. For example, to use OpenAI, set the `OPENAI_API_KEY` variable: **Set your OpenAI API key here**  ```bash export OPENAI_API_KEY="YOUR_OPENAI_API_KEY" ```  After setting the environment variable, run the `npx` command again.

## Local Installation and Execution

If you prefer to run the example from the source code, follow these steps.

### 1. Clone the Repository

First, clone the AIGNE Framework repository from GitHub:

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example's directory and install the required dependencies using `pnpm`:

```bash
cd aigne-framework/examples/memory-did-spaces
pnpm install
```

### 3. Run the Example

Finally, start the example:

```bash
pnpm start
```

The script will execute three tests to demonstrate the memory functionality: storing a user profile, recalling preferences, and creating a portfolio based on the stored data. The results will be displayed in the console and saved to a markdown report file for your review.

## How It Works

This example utilizes the `DIDSpacesMemory` plugin from the `@aigne/agent-library` package. This plugin enables the agent to persist conversation history by storing it in DID Spaces, a decentralized personal data storage solution.

Key features include:

- <strong>Decentralized Persistence</strong>: Conversations are stored securely in the user's DID Space.
- <strong>Session Continuity</strong>: The chatbot can recall information from previous interactions, even after being restarted.
- <strong>Privacy and Security</strong>: User data is managed using Decentralized Identifier (DID) technology, ensuring privacy and user control.

The example showcases this by storing user profile details, recalling them in a new interaction, and using that remembered context to provide personalized recommendations.

## Configuration

While the example comes with a pre-configured DID Spaces endpoint for demonstration purposes, you will need to update the configuration for a production application. This involves setting up your own DID Spaces instance and providing the correct URL and authentication credentials in the code.

**memory-config.ts**

```typescript
import { DIDSpacesMemory } from '@aigne/agent-library';

const memory = new DIDSpacesMemory({
  url: "YOUR_DID_SPACES_URL",
  auth: {
    authorization: "Bearer YOUR_TOKEN",
  },
});
```

Replace `"YOUR_DID_SPACES_URL"` and `"Bearer YOUR_TOKEN"` with your actual endpoint and authentication token.

## Debugging with AIGNE Observe

To monitor and debug your agent's execution, you can use the `aigne observe` command. This tool launches a local web server that provides a detailed view of agent traces, helping you understand its behavior, diagnose issues, and optimize performance.

To start the observation server, run:

```bash
aigne observe
```

![AIGNE Observe server starting](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

Once running, you can open the provided URL (`http://localhost:7893` by default) in your browser to view a list of recent agent executions and inspect their details.

![AIGNE Observe trace list](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

This example has demonstrated how to integrate decentralized, persistent memory into an AI agent using the `DIDSpacesMemory` plugin. This capability allows you to create more sophisticated and context-aware chatbots that remember user interactions across sessions.

To learn more about related concepts, refer to the following documentation:

::::card-group
::link-card{title="Memory" description="Learn about the core concepts of agent memory in the AIGNE Framework." icon="brain" href="/en/docs/aigne-framework/developer-guide-core-concepts-memory-9dc03e/"}
::link-card{title="File System Memory" description="Explore another example that uses the local file system for memory persistence." icon="folder" href="/en/docs/aigne-framework/examples-memory-9dc03e/"}
::::

---

## Nano Banana

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-nano-banana-9dc03e/

This guide demonstrates how to build and run a chatbot capable of generating images. By following these steps, you will learn how to execute a pre-built AIGNE example, connect it to an AI model, and inspect its behavior using the framework's observability tools.

## Prerequisites

Before proceeding, ensure the following requirements are met:

- <strong>Node.js:</strong> Version 20.0 or higher must be installed. You can download it from [nodejs.org](https://nodejs.org).
- <strong>OpenAI API Key:</strong> An API key from [OpenAI](https://platform.openai.com/api-keys) is required to interact with their image generation models.

## Quick Start

You can run this example directly without a local installation using `npx`.

### Run the Example

Execute the following command in your terminal to run the chatbot with a single input. This command will download and run the example package.

**Run with a single input**

```bash
npx -y @aigne/example-nano-banana --input 'Draw an image of a lovely cat'
```

To start an interactive session where you can have a conversation with the chatbot, use the `--interactive` flag.

**Run in interactive mode**

```bash
npx -y @aigne/example-nano-banana --interactive
```

### Connect to an AI Model

On the first run, the application will detect that no AI model is configured and will prompt you to connect one.

![Initial setup prompt for connecting an AI model.](https://media.arcblock.io/lib/3b/3b507241ce7423c3.w1600.webp)

You have three primary options to connect to an AI model:

#### 1. Connect via the Official AIGNE Hub (Recommended)

This is the simplest method. Choosing this option will open your web browser and guide you through the authorization process on the official AIGNE Hub. New users receive a complimentary token allocation to get started immediately.

![AIGNE Hub authorization screen.](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### 2. Connect via a Self-Hosted AIGNE Hub

If you operate your own instance of AIGNE Hub, select this option. You will be prompted to enter the URL of your self-hosted Hub to complete the connection. You can deploy your own AIGNE Hub from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ).

![Prompt to enter the URL for a self-hosted AIGNE Hub.](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

#### 3. Connect via a Third-Party Model Provider

You can directly connect to a third-party provider like OpenAI by configuring the necessary API key as an environment variable. For example, to use OpenAI, set the `OPENAI_API_KEY` variable in your terminal.

**Set OpenAI API key**

```bash
export OPENAI_API_KEY="your-openai-api-key-here"
```

After setting the environment variable, run the `npx` command again. For a comprehensive list of supported variables for different model providers, refer to the example environment file in the source repository.

### Debugging with the Observability UI

The AIGNE Framework includes a built-in observability tool to help you monitor and debug your agents. The `aigne observe` command launches a local web server that provides a detailed view of agent execution traces.

First, start the observation server by running the following command in your terminal:

**Start the observability server**

```bash
aigne observe
```

![Terminal output showing the aigne observe command successfully starting the server.](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

Once the server is running, you can open the provided URL (typically `http://localhost:7893`) in your browser to view a list of recent agent executions. This interface allows you to inspect the inputs, outputs, latency, and token usage for each trace, providing critical insights for debugging and optimization.

![The AIGNE observability UI showing a list of agent execution traces.](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Local Installation and Execution

For development purposes, you may prefer to clone the repository and run the example locally.

### 1. Clone the Repository

Clone the official AIGNE Framework repository from GitHub.

**Clone the repository**

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example's directory and install the required dependencies using `pnpm`.

**Install dependencies**

```bash
cd aigne-framework/examples/nano-banana
pnpm install
```

### 3. Run the Example

After the installation is complete, you can run the example using the `start` script defined in the project's `package.json`.

**Run the local example**

```bash
pnpm start
```

## Summary

This document provided a step-by-step guide to running the "Nano Banana" example, which demonstrates an AI chatbot with image generation capabilities. You have learned how to execute the example directly with `npx`, connect various AI model providers, and use the `aigne observe` command to debug agent behavior.

For more advanced use cases and a deeper understanding of the framework's capabilities, please refer to the following sections:

::::card-group
::link-card{title="Image Agent" description="Learn how to configure and use agents for image generation." icon="image" href="/en/docs/aigne-framework/developer-guide-agents-image-agent-9dc03e/"}
::link-card{title="AI Agent" description="Explore the primary agent for interacting with language models." icon="bot" href="/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/"}
::::

---

## Workflow Code Execution

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-code-execution-9dc03e/

Executing dynamically generated code from an AI model presents significant security and reliability challenges. This guide provides a structured, step-by-step process for building a secure code execution workflow using the AIGNE Framework. You will learn how to orchestrate a `Coder` agent, which generates code, and a `Sandbox` agent, which executes it in an isolated environment.

## Overview

The code execution workflow is designed to safely handle tasks that require dynamic code generation and execution. It employs a two-agent system:

::::steps
:::step{title="Coder Agent"}
An AI-driven agent responsible for interpreting a user's request and writing the necessary JavaScript code to solve it.
:::

:::step{title="Sandbox Agent"}
A `FunctionAgent` that takes the generated code and executes it in a controlled environment, returning the result.
:::
::::

This separation of concerns ensures that the AI's code generation is isolated from direct execution, providing a layer of security.

### Logical Flow

The following diagram illustrates the high-level interaction between the agents. The `Coder` agent receives an input, generates code, passes it to the `Sandbox` for execution, and then formats the final output.

```d2
direction: down

User-Input: {
  label: "User Input\n(e.g., 'Calculate 15!')"
  shape: rectangle
}

AIGNE-Framework: {
  label: "AIGNE Framework"
  shape: rectangle

  Coder-Agent: {
    label: "Coder Agent\n(AIAgent)"
    shape: rectangle
  }

  Sandbox-Agent: {
    label: "Sandbox Agent\n(FunctionAgent)"
    shape: rectangle
  }
}

Final-Output: {
  label: "Final Output"
  shape: rectangle
}

User-Input -> AIGNE-Framework.Coder-Agent: "1. Receives prompt"
AIGNE-Framework.Coder-Agent -> AIGNE-Framework.Sandbox-Agent: "2. Generates JS code & passes for execution"
AIGNE-Framework.Sandbox-Agent -> AIGNE-Framework.Coder-Agent: "3. Executes code & returns result"
AIGNE-Framework.Coder-Agent -> Final-Output: "4. Formats final response"
```

### Sequence of Interaction

This sequence diagram details the turn-by-turn communication between the user and the agents for a specific task, such as calculating a factorial.

## Quick Start

You can run this example directly without any local installation using `npx`.

### Run the Example

The example supports a one-shot execution mode for single tasks and an interactive chat mode for conversational workflows.

#### One-Shot Mode

This is the default mode. The agent processes a single input and exits.

```bash
npx -y @aigne/example-workflow-code-execution
```

You can also provide input directly via standard input pipeline.

```bash
echo 'Calculate 15!' | npx -y @aigne/example-workflow-code-execution
```

#### Interactive Chat Mode

Use the `--interactive` flag to start a persistent session where you can have a conversation with the agent.

```bash
npx -y @aigne/example-workflow-code-execution --interactive
```

### Connect to an AI Model

The first time you run the example, it will prompt you to connect to a Large Language Model (LLM) since one is required for the `Coder` agent to function.

You have several options to proceed.

#### Option 1: AIGNE Hub (Recommended)

This is the easiest way to get started. The official AIGNE Hub provides free credits for new users.

1. Select the first option: `Connect to the Arcblock official AIGNE Hub`.
2. Your web browser will open an authorization page.
3. Follow the prompts to approve the connection.

#### Option 2: Self-Hosted AIGNE Hub

If you have your own instance of AIGNE Hub, you can connect to it.

1. Select the second option: `Connect to a self-hosted AIGNE Hub`.
2. You will be prompted to enter the URL of your AIGNE Hub instance.

#### Option 3: Third-Party Model Providers

You can connect directly to a third-party model provider like OpenAI, Anthropic, or Google Gemini by setting the appropriate environment variables. For example, to use OpenAI, set your API key:

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

After setting the environment variable, run the example command again. For a list of all supported providers and their required environment variables, refer to the example `.env.local.example` file.

### Debugging with AIGNE Observe

The AIGNE Framework includes a powerful observability tool for debugging and analyzing agent behavior.

1. <strong>Start the Server</strong>: In your terminal, run the `aigne observe` command. This launches a local web server. ```bash aigne observe ```
2. <strong>View Traces</strong>: Open your web browser and navigate to the local URL provided (e.g., `http://localhost:7893`). The interface displays a list of recent agent executions, allowing you to inspect inputs, outputs, tool calls, and performance metrics for each trace.

## Local Installation and Usage

For development purposes, you can clone the repository and run the example locally.

### Prerequisites

- [Node.js](https://nodejs.org) (version 20.0 or higher)
- [pnpm](https://pnpm.io) for package management

### 1. Clone the Repository

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example directory and install the required packages.

```bash
cd aigne-framework/examples/workflow-code-execution
pnpm install
```

### 3. Run the Example

Use the `pnpm start` command to execute the workflow.

```bash
# Run in one-shot mode (default)
pnpm start

# Run in interactive chat mode
pnpm start -- --interactive

# Use pipeline input
echo "Calculate 15!" | pnpm start
```

### Command-Line Options

The script accepts several command-line arguments to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | Specify the AI model to use, e.g., `openai` or `openai:gpt-4o-mini`.  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging level (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).  | `INFO`  |
| `--input`, `-i <input>`  | Provide input directly as an argument.  | None  |

#### Usage Example

This command runs the workflow in interactive mode with the `DEBUG` log level.

```bash
pnpm start -- --interactive --log-level DEBUG
```

## Code Implementation

The following TypeScript code demonstrates how to construct the code execution workflow. It defines the `sandbox` and `coder` agents and invokes them using the AIGNE instance.

**index.ts**

```typescript
import { AIAgent, AIGNE, FunctionAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";
import { z } from "zod";

// Retrieve the OpenAI API key from environment variables.
const { OPENAI_API_KEY } = process.env;

// 1. Initialize the Chat Model
// This model will power the AI agent.
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// 2. Define the Sandbox Agent
// This agent safely executes JavaScript code using a FunctionAgent.
const sandbox = FunctionAgent.from({
  name: "evaluateJs",
  description: "A js sandbox for running javascript code",
  inputSchema: z.object({
    code: z.string().describe("The code to run"),
  }),
  process: async (input: { code: string }) => {
    const { code } = input;
    // The use of eval is isolated within this sandboxed agent.
    // biome-ignore lint/security/noGlobalEval: <This is a controlled sandbox environment for the example>
    const result = eval(code);
    return { result };
  },
});

// 3. Define the Coder Agent
// This AI agent is instructed to write code and use the sandbox skill.
const coder = AIAgent.from({
  name: "coder",
  instructions: `\
You are a proficient coder. You write code to solve problems.
Work with the sandbox to execute your code.
`,
  skills: [sandbox],
});

// 4. Initialize the AIGNE Framework
const aigne = new AIGNE({ model });

// 5. Invoke the Workflow
// The AIGNE instance runs the coder agent with the user's prompt.
const result = await aigne.invoke(coder, "10! = ?");

console.log(result);
// Expected Output:
// {
//   $message: "The value of \\(10!\\) (10 factorial) is 3,628,800.",
// }
```

## Summary

This guide has demonstrated how to build and run a secure code execution workflow using the AIGNE Framework. By separating the concerns of code generation and execution into distinct `AIAgent` and `FunctionAgent` roles, you can safely leverage the power of LLMs for tasks that require dynamic code.

For more advanced workflow patterns, explore the following examples:

::::card-group
::link-card{title="Sequential Workflow" description="Build step-by-step processing pipelines with guaranteed execution order." icon="arrow-right" href="/en/docs/aigne-framework/examples-workflow-sequential-9dc03e/"}
::link-card{title="Workflow Orchestration" description="Coordinate multiple agents working together in sophisticated processing pipelines." icon="flag" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::::

---

## Workflow Concurrency

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-concurrency-9dc03e/

Executing tasks in parallel can significantly improve the efficiency of complex workflows. This guide demonstrates how to build a concurrent workflow using the AIGNE Framework, where multiple agents process the same input simultaneously, and their outputs are aggregated. You will learn how to set up and run a practical example that analyzes a product from different perspectives at the same time.

## Overview

In this example, we will construct a workflow that takes a product description as input. Two specialized agents will then work in parallel:

::::steps
:::step{title="Feature Extractor"}
Analyzes the description to identify and summarize key product features.
:::

:::step{title="Audience Analyzer"}
Analyzes the same description to determine the target audience.
:::
::::

Finally, an <strong>Aggregator</strong> combines the outputs from both agents into a single, consolidated result. This parallel processing model is ideal for tasks that can be broken down into independent sub-tasks, reducing the total execution time.

The diagram below illustrates this concurrent workflow:

```d2
direction: down

Input: {
  label: "Product Description"
  shape: oval
}

Parallel-Processing: {
  label: "Parallel Processing"
  style.stroke-dash: 2

  Feature-Extractor: {
    label: "Feature Extractor\n(Agent 1)"
  }

  Audience-Analyzer: {
    label: "Audience Analyzer\n(Agent 2)"
  }
}

Aggregator: {
  label: "Aggregator"
}

Result: {
  label: "Consolidated Result"
  shape: oval
}

Input -> Parallel-Processing.Feature-Extractor: "Analyzes features"
Input -> Parallel-Processing.Audience-Analyzer: "Analyzes audience"
Parallel-Processing.Feature-Extractor -> Aggregator: "Feature summary"
Parallel-Processing.Audience-Analyzer -> Aggregator: "Audience profile"
Aggregator -> Result
```

## Prerequisites

Before proceeding, ensure your development environment meets the following requirements:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with Node.js.
- <strong>OpenAI API Key</strong>: Required for connecting to OpenAI models. You can obtain one from the [OpenAI Platform](https://platform.openai.com/api-keys).

## Quick Start

You can run this example directly without any installation using `npx`.

### Run the Example

Execute the following commands in your terminal to run the workflow in different modes.

- <strong>One-Shot Mode (Default)</strong>: Processes a single, predefined input and exits. ```bash npx -y @aigne/example-workflow-concurrency ```
- <strong>Interactive Chat Mode</strong>: Starts a chat session where you can provide multiple inputs. ```bash npx -y @aigne/example-workflow-concurrency --interactive ```
- <strong>Pipeline Mode</strong>: Uses input piped from another command. ```bash echo "Analyze product: Smart home assistant with voice control and AI learning capabilities" | npx -y @aigne/example-workflow-concurrency ```

### Connect to an AI Model

The first time you run the example, you will be prompted to connect to an AI model provider, as no API keys have been configured.

![Initial connection prompt for AI model setup](https://media.arcblock.io/lib/96/96938661648993fc.w1600.webp)

You have several options to proceed:

1. <strong>Connect via the official AIGNE Hub (Recommended)</strong> This is the easiest way to get started. New users receive free credits. Select the first option, and your browser will open to the AIGNE Hub authorization page. Follow the on-screen instructions to approve the connection. ![Authorize AIGNE CLI to connect to AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)
2. <strong>Connect via a self-hosted AIGNE Hub</strong> If you have your own AIGNE Hub instance, choose the second option. You will be prompted to enter the URL of your self-hosted Hub to complete the connection. ![Enter the URL for a self-hosted AIGNE Hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)
3. <strong>Connect via a Third-Party Model Provider</strong> You can connect directly to a provider like OpenAI by setting an environment variable with your API key. For example, to use OpenAI, export your key and re-run the command: ```bash export OPENAI_API_KEY="YOUR_OPENAI_API_KEY" npx -y @aigne/example-workflow-concurrency --interactive ```

## Installation from Source

For development or customization, you can clone the repository and run the example locally.

### 1. Clone the Repository

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example's directory and install the required packages using pnpm.

```bash
cd aigne-framework/examples/workflow-concurrency
pnpm install
```

### 3. Run the Example

Use the `pnpm start` command to execute the workflow. Command-line arguments must be passed after `--`.

- <strong>Run in one-shot mode:</strong> ```bash pnpm start ```
- <strong>Run in interactive chat mode:</strong> ```bash pnpm start -- --interactive ```
- <strong>Use pipeline input:</strong> ```bash echo "Analyze product: Smart home assistant with voice control and AI learning capabilities" | pnpm start ```

## Run Options

The application supports several command-line parameters for customization:

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled (one-shot mode)  |
| `--model <provider[:model]>`  | Specify the AI model to use (e.g., `openai` or `openai:gpt-4o-mini`).  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging level (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).  | `INFO`  |
| `--input`, `-i <input>`  | Specify input directly via the command line.  | None  |

## Code Example

The following TypeScript code demonstrates how to define and orchestrate the concurrent workflow using `TeamAgent` with `ProcessMode.parallel`.

**concurrency-workflow.ts**

```typescript
import { AIAgent, AIGNE, ProcessMode, TeamAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

// Initialize the AI model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// Define the first agent to extract product features
const featureExtractor = AIAgent.from({
  instructions: `\
You are a product analyst. Extract and summarize the key features of the product.\n\nProduct description:\n{{product}}`,
  outputKey: "features",
});

// Define the second agent to analyze the target audience
const audienceAnalyzer = AIAgent.from({
  instructions: `\
You are a market researcher. Identify the target audience for the product.\n\nProduct description:\n{{product}}`,
  outputKey: "audience",
});

// Initialize the AIGNE instance
const aigne = new AIGNE({ model });

// Create a TeamAgent to manage the parallel workflow
const teamAgent = TeamAgent.from({
  skills: [featureExtractor, audienceAnalyzer],
  mode: ProcessMode.parallel,
});

// Invoke the team with a product description
const result = await aigne.invoke(teamAgent, {
  product: "AIGNE is a No-code Generative AI Apps Engine",
});

console.log(result);

/*
Expected Output:
{
  features: "**Product Name:** AIGNE\n\n**Product Type:** No-code Generative AI Apps Engine\n\n...",
  audience: "**Small to Medium Enterprises (SMEs)**: \n   - Businesses that may not have extensive IT resources or budget for app development but are looking to leverage AI to enhance their operations or customer engagement.\n\n...",
}
*/
```

## Debugging

The AIGNE Framework includes a built-in observability tool to help you monitor and debug agent executions.

Start the observability server by running:

```bash
aigne observe
```

![Terminal output showing the aigne observe command running](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

This command starts a local web server, typically at `http://localhost:7893`. Open this URL in your browser to access the observability interface, where you can inspect detailed traces of each agent's execution, including inputs, outputs, and performance metrics.

![Aigne Observability interface showing a list of recent traces](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

This guide covered how to create and run a concurrent workflow using the AIGNE Framework. By leveraging `TeamAgent` in parallel mode, you can efficiently process multiple independent tasks simultaneously. To explore other workflow patterns, see the following examples:

::::card-group
::link-card{title="Sequential Workflow" description="Learn how to execute agents in a specific, ordered sequence." icon="arrow-right" href="/en/docs/aigne-framework/examples-workflow-sequential-9dc03e/"}
::link-card{title="Workflow Orchestration" description="Coordinate multiple agents in more complex, sophisticated pipelines." icon="flag" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::::

---

## Workflow Group Chat

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-group-chat-9dc03e/

This guide demonstrates how to build and run a multi-agent group chat workflow using the AIGNE Framework. You will learn how to orchestrate several agents, including a manager, to collaborate on a task, simulating a team environment where they share messages and work together to achieve a common goal.

## Overview

The Group Chat workflow example showcases a sophisticated multi-agent system where different agents with specialized roles collaborate to fulfill a user's request. The process is managed by a `Group Manager` agent that directs the conversation and task execution among other agents like a `Writer`, `Editor`, and `Illustrator`.

This example supports two primary modes of operation:

- <strong>One-shot mode</strong>: The workflow runs once to completion based on a single input.
- <strong>Interactive mode</strong>: The workflow engages in a continuous conversation, allowing for follow-up questions and dynamic interactions.

The core interaction model is as follows:

```d2
direction: down

User: {
  shape: c4-person
}

GroupChat: {
  label: "Group Chat Workflow"
  shape: rectangle

  Group-Manager: {
    label: "Group Manager"
    shape: rectangle
  }

  Collaborators: {
    label: "Collaborators"
    shape: rectangle
    grid-columns: 3

    Writer: {
      shape: rectangle
    }
    Editor: {
      shape: rectangle
    }
    Illustrator: {
      shape: rectangle
    }
  }
}

User -> GroupChat.Group-Manager: "1. User Request"
GroupChat.Group-Manager -> GroupChat.Collaborators.Writer: "2. Delegate Task"
GroupChat.Collaborators.Writer <-> GroupChat.Collaborators.Editor: "3. Collaborate"
GroupChat.Collaborators.Editor <-> GroupChat.Collaborators.Illustrator: "4. Collaborate"
GroupChat.Collaborators.Writer -> GroupChat.Group-Manager: "5. Send Result"
GroupChat.Group-Manager -> User: "6. Final Output"
```

## Prerequisites

Before proceeding, ensure your development environment meets the following requirements:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with Node.js.
- <strong>OpenAI API Key</strong>: Required for the default model configuration. You can obtain one from the [OpenAI Platform](https://platform.openai.com/api-keys).

## Quick Start

You can run this example directly without cloning the repository using `npx`.

### Run the Example

Execute one of the following commands in your terminal:

To run the workflow in the default one-shot mode:

**Run in one-shot mode**

```bash
npx -y @aigne/example-workflow-group-chat
```

To start an interactive chat session:

**Run in interactive mode**

```bash
npx -y @aigne/example-workflow-group-chat --interactive
```

You can also provide input directly via a pipeline:

**Run with pipeline input**

```bash
echo "Write a short story about space exploration" | npx -y @aigne/example-workflow-group-chat
```

### Connect to an AI Model

The first time you run the example, it will prompt you to connect to an AI model provider since no API keys have been configured.

![Initial setup prompt for connecting to an AI model.](https://media.arcblock.io/lib/b5/b547e1eb5cde9c69.w1600.webp)

You have several options to proceed:

#### 1. Connect to the AIGNE Hub (Recommended)

This is the easiest way to get started and includes free credits for new users.

1. Select the first option: `Connect to the Arcblock official AIGNE Hub`.
2. Your web browser will open a page to authorize the AIGNE CLI.
3. Click "Approve" to grant the necessary permissions. The CLI will be configured automatically.

![Authorization dialog for AIGNE Hub connection.](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### 2. Connect to a Self-Hosted AIGNE Hub

If you are running your own instance of AIGNE Hub:

1. Select the second option: `Connect to your self-hosted AIGNE Hub`.
2. Enter the URL of your AIGNE Hub instance when prompted.
3. Follow the instructions in your browser to complete the connection.

![Prompt to enter the URL for a self-hosted AIGNE Hub.](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

#### 3. Configure a Third-Party Model Provider

You can directly connect to a provider like OpenAI by setting an environment variable.

1. Exit the interactive prompt.
2. Set the `OPENAI_API_KEY` environment variable in your terminal: **Configure OpenAI API Key**  ```bash export OPENAI_API_KEY="your-openai-api-key" ```
3. Run the example command again.

For other providers like Google Gemini or DeepSeek, refer to the `.env.local.example` file within the project for the correct environment variable names.

## Local Installation and Usage

For development purposes, you can clone the repository and run the example locally.

### 1. Clone the Repository

**Clone the framework repository**

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example's directory and install the required packages using `pnpm`.

**Install dependencies**

```bash
cd aigne-framework/examples/workflow-group-chat
pnpm install
```

### 3. Run the Example

Use the `pnpm start` command to run the workflow. Command-line arguments must be passed after `--`.

To run in one-shot mode:

**Run in one-shot mode**

```bash
pnpm start
```

To run in interactive chat mode:

**Run in interactive mode**

```bash
pnpm start -- --interactive
```

To use pipeline input:

**Run with pipeline input**

```bash
echo "Write a short story about space exploration" | pnpm start
```

### Command-Line Options

The example accepts several command-line arguments to customize its behavior:

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode  | Disabled (one-shot mode)  |
| `--model <provider[:model]>`  | AI model to use in format 'provider[:model]' where model is optional. Examples: 'openai' or 'openai:gpt-4o-mini'  | openai  |
| `--temperature <value>`  | Temperature for model generation  | Provider default  |
| `--top-p <value>`  | Top-p sampling value  | Provider default  |
| `--presence-penalty <value>`  | Presence penalty value  | Provider default  |
| `--frequency-penalty <value>`  | Frequency penalty value  | Provider default  |
| `--log-level <level>`  | Set logging level (ERROR, WARN, INFO, DEBUG, TRACE)  | INFO  |
| `--input`, `-i <input>`  | Specify input directly  | None  |

#### Examples

**Set logging level**

```bash
pnpm start -- --log-level DEBUG
```

**Use a specific model**

```bash
pnpm start -- --model openai:gpt-4o-mini
```

## Debugging with AIGNE Observe

To inspect the execution flow and debug the behavior of the agents, you can use the `aigne observe` command. This tool launches a local web server that provides a detailed view of agent traces.

First, start the observability server in a separate terminal:

**Start the observability server**

```bash
aigne observe
```

![Terminal output showing the AIGNE Observe server starting.](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

After running the workflow example, open your browser to `http://localhost:7893` to view the traces. You can inspect the inputs, outputs, and internal states of each agent throughout the execution.

![AIGNE Observe web interface showing a list of traces.](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

This guide provided a step-by-step walkthrough for running the Workflow Group Chat example. You learned how to execute the workflow using `npx`, connect to various AI model providers, and install it locally for development. You also saw how to use `aigne observe` for debugging agent interactions.

For more complex patterns, explore other examples in the AIGNE Framework documentation.

::::card-group
::link-card{title="Workflow: Handoff" description="Learn how to create seamless transitions between specialized agents to solve complex problems." icon="refresh" href="/en/docs/aigne-framework/examples-workflow-handoff-9dc03e/"}
::link-card{title="Workflow: Orchestration" description="Discover how to coordinate multiple agents working together in sophisticated processing pipelines." icon="routes" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::::

---

## Workflow Handoff

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-handoff-9dc03e/

This guide demonstrates how to build a workflow where one agent can seamlessly hand off control to another specialized agent. By the end, you will understand how to create multi-agent systems that delegate tasks based on user input, enabling more complex and dynamic problem-solving.

## Overview

In many sophisticated AI applications, a single agent may not possess all the necessary skills to handle a wide range of tasks. The workflow handoff pattern addresses this by allowing a primary agent to act as a dispatcher, transferring control to a specialized agent when a specific trigger or condition is met. This creates a seamless transition, enabling different agents to collaborate on solving a complex problem.

This example implements a simple handoff:

- <strong>Agent A:</strong> A general-purpose agent.
- <strong>Agent B:</strong> A specialized agent that only communicates in Haikus.

When the user instructs Agent A to "transfer to agent b," the system seamlessly hands off the conversation to Agent B for all subsequent interactions.

```d2
shape: sequence_diagram

User: {
  shape: c4-person
}

AIGNE-Framework: {
  label: "AIGNE Framework"
}

Agent-A: {
  label: "Agent A\n(General Purpose)"
}

Agent-B: {
  label: "Agent B\n(Haiku Specialist)"
}

User -> AIGNE-Framework: "1. 'transfer to agent b'"
AIGNE-Framework -> Agent-A: "2. Invoke with input"
Agent-A -> Agent-A: "3. Execute skill: transfer_to_b()"
Agent-A -> AIGNE-Framework: "4. Return Agent B object"
AIGNE-Framework -> AIGNE-Framework: "5. Handoff: Replace Agent A with B"
AIGNE-Framework -> Agent-B: "6. Invoke Agent B for response"
Agent-B -> AIGNE-Framework: "7. Generate Haiku response"
AIGNE-Framework -> User: "8. Display Agent B's response"

User -> AIGNE-Framework: "9. 'It's a beautiful day'"
AIGNE-Framework -> Agent-B: "10. Invoke with new input"
Agent-B -> AIGNE-Framework: "11. Generate another Haiku"
AIGNE-Framework -> User: "12. Display Agent B's response"
```

## Prerequisites

Before running the example, ensure your development environment meets the following requirements:

- <strong>Node.js:</strong> Version 20.0 or higher.
- <strong>npm:</strong> Comes bundled with Node.js.
- <strong>AI Model Provider Account:</strong> An API key from a provider like OpenAI is required to power the agents.

## Quick Start

You can run this example directly without cloning the repository using `npx`.

### Step 1: Run the Example

Open your terminal and execute one of the following commands. The `--interactive` flag enables an interactive session where you can have a continuous conversation.

**Run in one-shot mode**

```bash
npx -y @aigne/example-workflow-handoff
```

**Run in interactive chat mode**

```bash
npx -y @aigne/example-workflow-handoff --interactive
```

You can also pipe input directly into the command:

**Use pipeline input**

```bash
echo "transfer to agent b" | npx -y @aigne/example-workflow-handoff
```

### Step 2: Connect to an AI Model

If you are running the example for the first time, you will be prompted to connect to an AI model, as no API keys have been configured.

![run example](https://media.arcblock.io/lib/03/036c470831dc238a.w1600.webp)

You have several options to proceed:

1. <strong>Connect to the AIGNE Hub (Recommended)</strong> This is the easiest way to get started. The official AIGNE Hub provides free credits for new users. Select the first option, and your browser will open a page to authorize the connection. ![connect to official aigne hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)
2. <strong>Connect to a Self-Hosted AIGNE Hub</strong> If you have your own instance of AIGNE Hub, choose the second option and enter its URL to connect. ![connect to self hosted aigne hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)
3. <strong>Configure a Third-Party Model Provider</strong> You can connect directly to a provider like OpenAI, DeepSeek, or Google Gemini by setting the appropriate environment variables. For example, to use OpenAI, set your API key in the terminal: **Configure OpenAI API Key**  ```bash export OPENAI_API_KEY="YOUR_OPENAI_API_KEY" ```  After configuring the environment variable, run the `npx` command again.

## Code Deep Dive

The core of this example is a function that acts as a "skill" for the first agent. When the model determines that this skill should be used based on the user's input, the function returns a new agent, effectively transferring control.

### How It Works

::::steps
:::step{title="Agent A (Dispatcher):"}
This agent is configured with a `transfer_to_b` skill. Its instructions are general.
:::

:::step{title="Agent B (Specialist):"}
This agent has a very specific instruction: "Only speak in Haikus." It has no special skills.
:::

:::step{title="The Handoff Mechanism:"}
The `transfer_to_b` function simply returns the `agentB` object. When the AIGNE Framework receives an agent object as the result of a skill execution, it replaces the current agent in the session with the new one.
:::
::::

### Example Implementation

The following code demonstrates how to define two agents and implement the handoff logic.

**index.ts**

```typescript
import { AIAgent, AIGNE } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

// 1. Initialize the AI Model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// 2. Define the skill that performs the handoff
function transfer_to_b() {
  return agentB;
}

// 3. Define Agent A with the handoff skill
const agentA = AIAgent.from({
  name: "AgentA",
  instructions: "You are a helpful agent.",
  outputKey: "A",
  skills: [transfer_to_b],
});

// 4. Define Agent B, the specialist
const agentB = AIAgent.from({
  name: "AgentB",
  instructions: "Only speak in Haikus.",
  outputKey: "B",
});

// 5. Initialize the AIGNE runtime
const aigne = new AIGNE({ model });

// 6. Start the session with Agent A
const userAgent = aigne.invoke(agentA);

// 7. First invocation: Trigger the handoff
const result1 = await userAgent.invoke("transfer to agent b");
console.log(result1);
// Expected Output:
// {
//   B: "Transfer now complete,  \nAgent B is here to help.  \nWhat do you need, friend?",
// }

// 8. Second invocation: Now talking to Agent B
const result2 = await userAgent.invoke("It's a beautiful day");
console.log(result2);
// Expected Output:
// {
//   B: "Sunshine warms the earth,  \nGentle breeze whispers softly,  \nNature sings with joy.  ",
// }
```

## Running from Source (Optional)

If you wish to modify or inspect the code locally, follow these steps.

### 1. Clone the Repository

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example directory and install the necessary packages using `pnpm`.

```bash
cd aigne-framework/examples/workflow-handoff
pnpm install
```

### 3. Run the Example

Use the `pnpm start` command. To pass additional arguments like `--interactive`, add an extra `--` before them.

**Run in one-shot mode**

```bash
pnpm start
```

**Run in interactive chat mode**

```bash
pnpm start -- --interactive
```

## Command-Line Options

The example script accepts several command-line arguments to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | AI model to use (e.g., `openai` or `openai:gpt-4o-mini`).  | `openai`  |
| `--temperature <value>`  | Temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set logging level (ERROR, WARN, INFO, DEBUG, TRACE).  | INFO  |
| `--input`, `-i <input>`  | Specify input directly via the command line.  | None  |

## Debugging and Observation

To inspect the agent's execution flow, you can use the `aigne observe` command. This tool launches a local web server that provides a detailed view of traces, calls, and other runtime data, which is invaluable for debugging.

First, start the observation server in a separate terminal:

**Start the observation server**

```bash
aigne observe
```

![aigne-observe-execute](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

After running the example, you can view the execution traces in the web interface, which is typically available at `http://localhost:7893`.

![aigne-observe-list](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

You have now learned how to implement a workflow handoff, a powerful pattern for building multi-agent systems where tasks are delegated to specialized agents. This approach allows you to construct more robust and capable AI applications by composing agents with distinct skills.

To explore more advanced agent orchestration, check out these related examples:

::::card-group
::link-card{title="Workflow Orchestration" description="Coordinate multiple agents working together in sophisticated processing pipelines." icon="flag" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::link-card{title="Workflow Router" description="Implement intelligent routing logic to direct requests to appropriate handlers based on content." icon="git-branch" href="/en/docs/aigne-framework/examples-workflow-router-9dc03e/"}
::::

---

## Workflow Orchestration

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/

This guide demonstrates how to build and run a sophisticated workflow that orchestrates multiple specialized AI agents. You will learn to coordinate agents like a `finder`, `writer`, and `proofreader` to work together on a complex task, from initial research to final report generation.

## Overview

Workflow orchestration involves creating a processing pipeline where multiple agents collaborate to achieve a common goal. Each agent in the pipeline has a specific role, and a central orchestrator manages the flow of tasks and information between them. This example showcases how to use the AIGNE Framework to build such a system, supporting both single-run (one-shot) and interactive chat modes.

The following diagram illustrates the agent relationships in this example:

```d2
direction: down

User: {
  shape: c4-person
}

OrchestratorAgent: {
  label: "Orchestrator Agent"
  shape: rectangle

  finder: {
    label: "Finder Agent"
    shape: rectangle
  }

  writer: {
    label: "Writer Agent"
    shape: rectangle
  }
}

Skills: {
  label: "Skills / Tools"
  shape: rectangle
  style: {
    stroke-dash: 2
  }

  puppeteer: {
    label: "Puppeteer\n(Web Scraping)"
    shape: rectangle
  }

  filesystem: {
    label: "Filesystem\n(Read/Write)"
    shape: cylinder
  }
}

User -> OrchestratorAgent: "1. Submits research task"
OrchestratorAgent -> OrchestratorAgent.finder: "2. Delegate: Find info"
OrchestratorAgent.finder -> Skills.puppeteer: "3. Scrape web"
OrchestratorAgent.finder -> Skills.filesystem: "4. Save findings"
OrchestratorAgent -> OrchestratorAgent.writer: "5. Delegate: Compile report"
OrchestratorAgent.writer -> Skills.filesystem: "6. Write final report"
```

## Prerequisites

Before you begin, ensure you have the following installed and configured:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Comes bundled with Node.js.
- <strong>OpenAI API Key</strong>: Required for the agents to interact with OpenAI models. You can obtain one from the [OpenAI Platform](https://platform.openai.com/api-keys).

Optional dependencies for running from source code:

- <strong>Bun</strong>: For running unit tests and examples.
- <strong>Pnpm</strong>: For package management.

## Quick Start

You can run this example directly without any installation using `npx`.

### Run the Example

Execute the following commands in your terminal:

**Run in one-shot mode**

```bash
# Run in one-shot mode (default)
npx -y @aigne/example-workflow-orchestrator
```

**Run in interactive chat mode**

```bash
# Run in interactive chat mode
npx -y @aigne/example-workflow-orchestrator --interactive
```

**Use pipeline input**

```bash
# Use pipeline input
echo "Research ArcBlock and compile a report about their products and architecture" | npx -y @aigne/example-workflow-orchestrator
```

### Connect to an AI Model

The first time you run the example, it will prompt you to connect to an AI model service since no API keys have been configured.

![Initial prompt to connect an AI model](https://media.arcblock.io/lib/ce/ce107f134436a7c8.w1600.webp)

You have three options:

1. <strong>Connect via the Official AIGNE Hub</strong>: This is the recommended option for new users. Selecting it will open your browser to an authorization page. After you approve, the CLI will be connected to the AIGNE Hub, and you'll receive complimentary tokens to get started. ![Authorize connection to the official AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)
2. <strong>Connect via a Self-Hosted AIGNE Hub</strong>: Choose this if you have your own AIGNE Hub instance. You will be prompted to enter the URL of your hub to complete the connection. You can deploy a self-hosted AIGNE Hub from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ). ![Enter the URL for a self-hosted AIGNE Hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)
3. <strong>Connect via a Third-Party Model Provider</strong>: You can configure an API key from a provider like OpenAI directly. Set the key as an environment variable and run the example again. **Set OpenAI API Key**  ```bash export OPENAI_API_KEY="YOUR_API_KEY_HERE" ```  For more configuration examples, refer to the `.env.local.example` file in the repository.

### Debugging with AIGNE Observe

The `aigne observe` command launches a local web server that helps you monitor and analyze agent executions. This tool is invaluable for debugging, tuning performance, and understanding agent behavior.

First, start the observation server:

**Start the observability server**

```bash
aigne observe
```

![Terminal output showing the observability server running](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

Once the server is running, you can open the provided URL (`http://localhost:7893`) in your browser to view a list of recent agent traces and inspect their details.

![AIGNE Observe web interface showing a list of traces](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Local Installation and Usage

For development purposes, you can clone the repository and run the example locally.

### 1. Clone the Repository

**Clone the repository**

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example directory and install the necessary packages using `pnpm`.

**Install dependencies**

```bash
cd aigne-framework/examples/workflow-orchestrator
pnpm install
```

### 3. Run the Example

Use the `pnpm start` command to execute the workflow.

**Run in one-shot mode**

```bash
# Run in one-shot mode (default)
pnpm start
```

**Run in interactive chat mode**

```bash
# Run in interactive chat mode
pnpm start -- --interactive
```

**Use pipeline input**

```bash
# Use pipeline input
echo "Research ArcBlock and compile a report about their products and architecture" | pnpm start
```

## Run Options

The script accepts several command-line parameters to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | Specify the AI model to use (e.g., `openai` or `openai:gpt-4o-mini`).  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging level (e.g., `ERROR`, `WARN`, `INFO`, `DEBUG`).  | `INFO`  |
| `--input`, `-i <input>`  | Specify input directly via the command line.  | None  |

#### Examples

**Run in interactive chat mode**

```bash
# Run in chat mode
pnpm start -- --interactive
```

**Set a different logging level**

```bash
# Set logging level to DEBUG
pnpm start -- --log-level DEBUG
```

## Code Example

The following TypeScript code demonstrates how to define and orchestrate multiple agents to perform in-depth research and compile a report. The `OrchestratorAgent` coordinates a `finder` and a `writer`, which are equipped with skills to browse the web (`puppeteer`) and interact with the local filesystem.

**orchestrator.ts**

```typescript
import { OrchestratorAgent } from "@aigne/agent-library/orchestrator/index.js";
import { AIAgent, AIGNE, MCPAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

// 1. Initialize the chat model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
  modelOptions: {
    parallelToolCalls: false, // Puppeteer can only run one task at a time
  },
});

// 2. Set up MCP agents for web scraping and filesystem access
const puppeteer = await MCPAgent.from({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-puppeteer"],
  env: process.env as Record<string, string>,
});

const filesystem = await MCPAgent.from({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", import.meta.dir],
});

// 3. Define the finder agent to research information
const finder = AIAgent.from({
  name: "finder",
  description: "Find the closest match to a user's request",
  instructions: `You are an agent that can find information on the web.
You are tasked with finding the closest match to the user's request.
You can use puppeteer to scrape the web for information.
You can also use the filesystem to save the information you find.

Rules:
- do not use screenshot of puppeteer
- use document.body.innerText to get the text content of a page
- if you want a url to some page, you should get all link and it's title of current(home) page,
then you can use the title to search the url of the page you want to visit.
  `,
  skills: [puppeteer, filesystem],
});

// 4. Define the writer agent to save the report
const writer = AIAgent.from({
  name: "writer",
  description: "Write to the filesystem",
  instructions: `You are an agent that can write to the filesystem.
  You are tasked with taking the user's input, addressing it, and
  writing the result to disk in the appropriate location.`,
  skills: [filesystem],
});

// 5. Create the orchestrator agent to manage the workflow
const agent = OrchestratorAgent.from({
  skills: [finder, writer],
  maxIterations: 3,
  tasksConcurrency: 1, // Puppeteer can only run one task at a time
});

// 6. Initialize the AIGNE instance
const aigne = new AIGNE({ model });

// 7. Invoke the workflow with a detailed prompt
const result = await aigne.invoke(
  agent,
  `\
Conduct an in-depth research on ArcBlock using only the official website\
(avoid search engines or third-party sources) and compile a detailed report saved as arcblock.md. \
The report should include comprehensive insights into the company's products \
(with detailed research findings and links), technical architecture, and future plans.`,
);
console.log(result);
```

When executed, this workflow produces a detailed markdown file. You can view an example of the generated output here: [arcblock-deep-research.md](https://github.com/AIGNE-io/aigne-framework/blob/main/examples/workflow-orchestrator/generated-report-arcblock.md).

## Summary

This example illustrates the power of the AIGNE Framework for building complex, multi-agent workflows. By defining specialized agents and coordinating them with an orchestrator, you can automate sophisticated tasks that require multiple steps, such as research, content generation, and file manipulation.

For more examples of advanced workflow patterns, explore the following sections:

::::card-group
::link-card{title="Sequential Workflows" description="Build pipelines where agents execute tasks in a strict, step-by-step order." icon="arrow-right" href="/en/docs/aigne-framework/examples-workflow-sequential-9dc03e/"}
::link-card{title="Concurrent Workflows" description="Process multiple tasks simultaneously to improve performance and efficiency." icon="git-branch" href="/en/docs/aigne-framework/examples-workflow-concurrency-9dc03e/"}
::link-card{title="Agent Handoff" description="Create seamless transitions where one agent passes its output to another for further processing." icon="refresh" href="/en/docs/aigne-framework/examples-workflow-handoff-9dc03e/"}
::link-card{title="Group Chat" description="Enable multiple agents to collaborate and communicate in a shared environment." icon="users" href="/en/docs/aigne-framework/examples-workflow-group-chat-9dc03e/"}
::::

---

## Workflow Reflection

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-reflection-9dc03e/

Have you ever needed an AI to not just generate content, but also to critique and improve its own work? This guide demonstrates how to build a self-correcting workflow where one agent's output is reviewed and refined by another. By following these steps, you will learn how to implement this powerful iterative pattern using the AIGNE Framework.

This example establishes a workflow with two distinct agents: a `Coder` and a `Reviewer`. The `Coder` agent is responsible for writing code to solve a user's request, while the `Reviewer` agent evaluates the code. If the `Reviewer` deems the code unsatisfactory, it provides constructive feedback and sends it back to the `Coder` for revision. This creates a loop of continuous improvement until the output meets the required standards.

The following diagram illustrates this process:

```mermaid
flowchart LR
in(In)
out(Out)
coder(Coder)
reviewer(Reviewer)

in --Ideas--> coder ==Solution==> reviewer --Approved--> out
reviewer ==Rejected==> coder

classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px,color:#b35b39,font-weight:bolder;
classDef processing fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px,color:#6B8F3C,font-weight:bolder;

class in inputOutput
class out inputOutput
class coder processing
class reviewer processing
```

## Prerequisites

To successfully run this example, your development environment must meet the following criteria:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with your Node.js installation.
- <strong>OpenAI API Key</strong>: An API key is necessary for the example to communicate with OpenAI models. You can acquire one from the [OpenAI Platform](https://platform.openai.com/api-keys).

## Quick Start

This example can be executed directly from the command line using `npx`, which eliminates the need for a local installation.

### Run the Example

Open your terminal and use one of the following commands to run the workflow.

To run in the default one-shot mode, which processes a single request and exits:

**npx command**

```bash
npx -y @aigne/example-workflow-reflection
```

To engage in an interactive session, use the `--interactive` flag:

**npx command**

```bash
npx -y @aigne/example-workflow-reflection --interactive
```

You can also pipe input directly into the command:

**npx command**

```bash
echo "Write a function to validate email addresses" | npx -y @aigne/example-workflow-reflection
```

### Connect to an AI Model

Upon first execution, the application will prompt you to configure a connection to an AI model, as no API keys have been set up yet.

```d2
direction: down

In: {
  shape: oval
}

Out: {
  shape: oval
}

Coder: {
  shape: rectangle
}

Reviewer: {
  shape: rectangle
}

In -> Coder: "Ideas"
Coder -> Reviewer: "Solution"
Reviewer -> Out: "Approved"
Reviewer -> Coder: "Rejected"
```

You are presented with the following options:

#### 1. Connect via the Official AIGNE Hub (Recommended)

This is the most straightforward method. New users are granted free credits to get started.

1. Select the first option: `Connect to the Arcblock official AIGNE Hub`.
2. Your default web browser will open a new tab, displaying an authorization page.
3. Follow the on-screen instructions to approve the connection request.

#### 2. Connect via a Self-Hosted AIGNE Hub

If you or your organization operates a private AIGNE Hub instance, follow these steps:

1. Select the second option: `Connect to a self-hosted AIGNE Hub`.
2. When prompted, enter the URL of your self-hosted AIGNE Hub instance.
3. Proceed with the on-screen instructions to finalize the connection.

#### 3. Connect via a Third-Party Model Provider

You can connect directly to a third-party LLM provider, such as OpenAI, by configuring the appropriate API key as an environment variable.

For instance, to use an OpenAI model, set the `OPENAI_API_KEY` environment variable in your terminal:

**Set OpenAI API Key**

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

Replace `"YOUR_OPENAI_API_KEY"` with your actual key. Once the environment variable is set, run the `npx` command again. For details on configuring other providers like Google Gemini or DeepSeek, consult the `.env.local.example` file included in the source code.

## Installation from Source

For developers who want to examine or customize the code, the repository can be cloned to run the example locally.

### 1. Clone the Repository

**Clone the repository**

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

### 2. Install Dependencies

Navigate to the example's directory and use `pnpm` to install the necessary packages.

**Install dependencies**

```bash
cd aigne-framework/examples/workflow-reflection
pnpm install
```

### 3. Run the Example

Execute the script using the `pnpm start` command.

**Run in one-shot mode**

```bash
pnpm start
```

To run in interactive chat mode, append the `--interactive` flag. The extra `--` is required to pass the flag to the script rather than to `pnpm` itself.

**Run in interactive mode**

```bash
pnpm start -- --interactive
```

To provide input via a pipeline:

**Run with pipeline input**

```bash
echo "Write a function to validate email addresses" | pnpm start
```

## How It Works

The workflow is orchestrated by two `AIAgent` instances, `coder` and `reviewer`, which communicate through a system of topics. This creates a message-driven state machine.

1. <strong>Initialization</strong>: The process begins when a message with the user's request is published to the `UserInputTopic`.
2. <strong>Coder Agent</strong>: The `coder` agent, which subscribes to `UserInputTopic`, receives the request. It generates the initial code and publishes its solution to a `review_request` topic.
3. <strong>Reviewer Agent</strong>: The `reviewer` agent subscribes to the `review_request` topic. It assesses the submitted code against criteria such as correctness, efficiency, and safety.
4. <strong>Decision and Routing</strong>:
5.
  - If the code is <strong>approved</strong>, the `reviewer` publishes the final, validated result to the `UserOutputTopic`, concluding the workflow.
  - If the code is <strong>rejected</strong>, the `reviewer` formulates feedback and publishes it to a `rewrite_request` topic.
6. <strong>Iteration</strong>: The `coder` agent also subscribes to the `rewrite_request` topic. When it receives feedback, it revises its code accordingly and resubmits it to the `review_request` topic, thereby repeating the cycle until approval is achieved.

### Code Implementation

The following TypeScript code provides the complete implementation for defining and running the `coder` and `reviewer` agents.

**reflection-workflow.ts**

```typescript
import { AIAgent, AIGNE, UserInputTopic, UserOutputTopic } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";
import { z } from "zod";

const { OPENAI_API_KEY } = process.env;

// Initialize the model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// Define the Coder agent
const coder = AIAgent.from({
  subscribeTopic: [UserInputTopic, "rewrite_request"],
  publishTopic: "review_request",
  instructions: `\
You are a proficient coder. You write code to solve problems.
Work with the reviewer to improve your code.
Always put all finished code in a single Markdown code block.
For example:
\`\`\`python
def hello_world():
    print("Hello, World!")
\`\`\`

Respond using the following format:

Thoughts: <Your comments>
Code: <Your code>

Previous review result:
{{feedback}}

User's question:
{{question}}
`,
  outputSchema: z.object({
    code: z.string().describe("Your code"),
  }),
});

// Define the Reviewer agent
const reviewer = AIAgent.from({
  subscribeTopic: "review_request",
  publishTopic: (output) =>
    output.approval ? UserOutputTopic : "rewrite_request",
  instructions: `\
You are a code reviewer. You focus on correctness, efficiency and safety of the code.

The problem statement is: {{question}}
The code is:
\`\`\`
{{code}}
\`\`\`

Previous feedback:
{{feedback}}

Please review the code. If previous feedback was provided, see if it was addressed.
`,
  outputSchema: z.object({
    approval: z.boolean().describe("APPROVE or REVISE"),
    feedback: z.object({
      correctness: z.string().describe("Your comments on correctness"),
      efficiency: z.string().describe("Your comments on efficiency"),
      safety: z.string().describe("Your comments on safety"),
      suggested_changes: z
        .string()
        .describe("Your comments on suggested changes"),
    }),
  }),
  includeInputInOutput: true,
});

// Initialize and run the AIGNE instance
const aigne = new AIGNE({ model, agents: [coder, reviewer] });
aigne.publish(
  UserInputTopic,
  "Write a function to find the sum of all even numbers in a list.",
);

const { message } = await aigne.subscribe(UserOutputTopic);
console.log(message);
```

### Example Output

Once the workflow completes successfully, the final approved code and the reviewer's feedback are logged to the console as a JSON object.

**Example Output**

```json
{
  "code": "def sum_of_even_numbers(numbers):\n    \"\"\"Function to calculate the sum of all even numbers in a list.\"\"\"\n    return sum(number for number in numbers if number % 2 == 0)",
  "approval": true,
  "feedback": {
    "correctness": "The function correctly calculates the sum of all even numbers in the given list. It properly checks for evenness using the modulus operator and sums the valid numbers.",
    "efficiency": "The implementation is efficient as it uses a generator expression which computes the sum in a single pass over the list. This minimizes memory usage as compared to creating an intermediate list of even numbers.",
    "safety": "The function does not contain any safety issues. However, it assumes that all elements in the input list are integers. It would be prudent to handle cases where the input contains non-integer values (e.g., None, strings, etc.).",
    "suggested_changes": "Consider adding type annotations to the function for better clarity and potential type checking, e.g. `def sum_of_even_numbers(numbers: list[int]) -> int:`. Also, include input validation to ensure 'numbers' is a list of integers."
  }
}
```

## Debugging with AIGNE Observe

To gain insight into the agent interactions, message flows, and overall execution, you can use the AIGNE observability tool.

First, launch the observation server from a separate terminal window:

**Start AIGNE Observe**

```bash
aigne observe
```

The server runs locally and is accessible at `http://localhost:7893`. With the server running, any execution of your AIGNE application will capture detailed traces. Open the web interface in your browser to view a list of recent executions and inspect the specifics of each step in the workflow.

## Summary

This guide has detailed the process of building a reflection workflow, where agents collaborate to iteratively improve an output. This pattern is a key technique for developing more dependable and sophisticated AI systems capable of self-correction.

To explore other ways of coordinating agents, consider the following workflow patterns:

::::card-group
::link-card{title="Sequential Workflow" description="Build step-by-step processing pipelines with a guaranteed execution order." icon="arrow-right" href="/en/docs/aigne-framework/examples-workflow-sequential-9dc03e/"}
::link-card{title="Workflow Orchestration" description="Coordinate multiple agents working together in sophisticated processing pipelines." icon="routes" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::::

---

## Workflow Router

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-router-9dc03e/

Have you ever needed to direct user queries to different specialized handlers based on their content? This guide provides a complete, step-by-step walkthrough for building a workflow that intelligently routes requests. You will learn how to create a "triage" agent that analyzes input and forwards it to the correct specialized agent, such as product support or feedback collection.

The router workflow is a common and powerful pattern for creating sophisticated, multi-agent systems. It acts as a smart dispatcher, ensuring that user requests are handled by the agent best equipped for the task. This example demonstrates a triage agent that routes questions to one of three specialized agents: `productSupport`, `feedback`, or `other`.

The diagram below illustrates the routing logic:

```d2
direction: down

User: {
  shape: c4-person
}

Triage-Agent: {
  label: "Triage Agent"
  shape: rectangle
}

Specialized-Agents: {
  label: "Specialized Agents"
  shape: rectangle

  productSupport: {
    label: "Product Support Agent"
  }

  feedback: {
    label: "Feedback Agent"
  }

  other: {
    label: "Other Agent"
  }
}

User -> Triage-Agent: "User Query"
Triage-Agent -> Specialized-Agents.productSupport: "Routes product questions"
Triage-Agent -> Specialized-Agents.feedback: "Routes feedback"
Triage-Agent -> Specialized-Agents.other: "Routes other questions"
Specialized-Agents.productSupport -> User: "Response"
Specialized-Agents.feedback -> User: "Response"
Specialized-Agents.other -> User: "Response"
```

## Prerequisites

Before proceeding, ensure your development environment meets the following requirements:

- <strong>Node.js:</strong> Version 20.0 or higher.
- <strong>npm:</strong> Comes bundled with Node.js.
- <strong>OpenAI API Key:</strong> Required for the default model configuration. You can obtain one from the [OpenAI Platform](https://platform.openai.com/api-keys).

## Quick Start

You can run this example directly without a manual installation process using `npx`.

### Run the Example

The example can be executed in several modes.

1. <strong>One-Shot Mode (Default)</strong> This command processes a single, hardcoded input and exits. ```bash npx -y @aigne/example-workflow-router ```
2. <strong>Interactive Chat Mode</strong> Use the `--interactive` flag to start an interactive session where you can send multiple messages. ```bash npx -y @aigne/example-workflow-router --interactive ```
3. <strong>Pipeline Mode</strong> Pipe input directly into the command. This is useful for integrating with other scripts. ```bash echo "How do I return a product?" | npx -y @aigne/example-workflow-router ```

### Connect to an AI Model

When you run the example for the first time, it will detect that no AI model has been configured and will prompt you for setup.

![Initial setup prompt for AI model connection](https://media.arcblock.io/lib/d3/d3dc01907bf69a64.w1600.webp)

You have several options to connect to an AI model:

#### 1. Connect to the AIGNE Hub (Recommended)

This is the easiest way to get started. The official AIGNE Hub provides free credits for new users.

1. Select the first option: `Connect to the Arcblock official AIGNE Hub`.
2. Your web browser will open an authorization page.
3. Follow the on-screen instructions to approve the connection.

![Authorize AIGNE CLI to connect to AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

#### 2. Connect to a Self-Hosted AIGNE Hub

If you are running your own instance of AIGNE Hub:

1. Select the second option: `Connect to your self-hosted AIGNE Hub`.
2. Enter the URL of your AIGNE Hub instance when prompted.

![Enter the URL of your self-hosted AIGNE Hub](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

#### 3. Connect via a Third-Party Model Provider

You can also connect directly to a model provider like OpenAI by setting an environment variable.

**Set OpenAI API Key**

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

Replace `"YOUR_OPENAI_API_KEY"` with your actual key. After setting the environment variable, run the example command again. For other providers like Google Gemini or DeepSeek, refer to the `.env.local.example` file in the source code for the correct variable names.

## Full Example and Source Code

The core logic involves defining several `AIAgent` instances: three specialized agents (`productSupport`, `feedback`, `other`) and one `triage` agent that acts as the router. The `triage` agent is configured with `toolChoice: "router"`, which instructs it to select one of its available `skills` (the other agents) to handle the input.

Below is the complete TypeScript code for this example.

**index.ts**

```typescript
import { AIAgent, AIGNE } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

const productSupport = AIAgent.from({
  name: "product_support",
  description: "Agent to assist with any product-related questions.",
  instructions: `You are an agent capable of handling any product-related questions.
  Your goal is to provide accurate and helpful information about the product.
  Be polite, professional, and ensure the user feels supported.`,
  outputKey: "product_support",
});

const feedback = AIAgent.from({
  name: "feedback",
  description: "Agent to assist with any feedback-related questions.",
  instructions: `You are an agent capable of handling any feedback-related questions.
  Your goal is to listen to the user's feedback, acknowledge their input, and provide appropriate responses.
  Be empathetic, understanding, and ensure the user feels heard.`,
  outputKey: "feedback",
});

const other = AIAgent.from({
  name: "other",
  description: "Agent to assist with any general questions.",
  instructions: `You are an agent capable of handling any general questions.
  Your goal is to provide accurate and helpful information on a wide range of topics.
  Be friendly, knowledgeable, and ensure the user feels satisfied with the information provided.`,
  outputKey: "other",
});

const triage = AIAgent.from({
  name: "triage",
  instructions: `You are an agent capable of routing questions to the appropriate agent.
  Your goal is to understand the user's query and direct them to the agent best suited to assist them.
  Be efficient, clear, and ensure the user is connected to the right resource quickly.`,
  skills: [productSupport, feedback, other],
  toolChoice: "router", // Set toolChoice to "router" to enable router mode
});

const aigne = new AIGNE({ model });

// Example 1: Route to Product Support
const result1 = await aigne.invoke(triage, "How to use this product?");
console.log(result1);

// Example 2: Route to Feedback
const result2 = await aigne.invoke(triage, "I have feedback about the app.");
console.log(result2);

// Example 3: Route to Other
const result3 = await aigne.invoke(triage, "What is the weather today?");
console.log(result3);
```

### Execution and Output

When the script runs, the `aigne.invoke` method sends the user's query to the `triage` agent. The agent then routes the query to the most appropriate specialized agent, and the final output is from that selected agent.

<strong>Output for "How to use this product?"</strong>

```json
{
  "product_support": "I’d be happy to help you with that! However, I need to know which specific product you’re referring to. Could you please provide me with the name or type of product you have in mind?"
}
```

<strong>Output for "I have feedback about the app."</strong>

```json
{
  "feedback": "Thank you for sharing your feedback! I'm here to listen. Please go ahead and let me know what you’d like to share about the app."
}
```

<strong>Output for "What is the weather today?"</strong>

```json
{
  "other": "I can't provide real-time weather updates. However, you can check a reliable weather website or a weather app on your phone for the current conditions in your area. If you tell me your location, I can suggest a few sources where you can find accurate weather information!"
}
```

## Command-Line Options

The example script accepts several command-line arguments to customize its behavior.

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode instead of one-shot.  | Disabled  |
| `--model <provider[:model]>`  | Specify the AI model to use (e.g., `openai` or `openai:gpt-4o-mini`).  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging verbosity (e.g., `ERROR`, `WARN`, `INFO`, `DEBUG`).  | `INFO`  |
| `--input`, `-i <input>`  | Provide input directly as an argument.  | None  |

#### Examples

**Run in interactive mode**

```bash
npx -y @aigne/example-workflow-router --interactive
```

**Set a specific model and temperature**

```bash
npx -y @aigne/example-workflow-router --model openai:gpt-4o-mini --temperature 0.5 -i "Tell me about your product."
```

**Set logging level to debug**

```bash
npx -y @aigne/example-workflow-router --log-level DEBUG
```

## Debugging

To inspect the execution flow and understand the agent's behavior, you can use the AIGNE observability tool.

First, start the observation server in a separate terminal window:

```bash
aigne observe
```

![AIGNE observe command running in the terminal](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

The server will start, and you can access the web interface at `http://localhost:7893`. After running the example, the execution traces will appear in the dashboard, allowing you to see how the `triage` agent made its routing decision and what data was passed between agents.

![AIGNE observability interface showing a list of traces](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

This example has demonstrated how to build a router workflow using the AIGNE Framework. By defining a `triage` agent with specialized agents as its skills and setting `toolChoice: "router"`, you can create a powerful system that intelligently delegates tasks.

For more complex patterns, explore the following examples:

::::card-group
::link-card{title="Workflow Handoff" description="Create seamless transitions between specialized agents to solve complex problems." icon="refresh" href="/en/docs/aigne-framework/examples-workflow-handoff-9dc03e/"}
::link-card{title="Workflow Orchestration" description="Coordinate multiple agents working together in sophisticated processing pipelines." icon="routes" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::::

---

## Workflow Sequential

URL: https://www.arcblock.io/en/docs/aigne-framework/examples-workflow-sequential-9dc03e/

This guide demonstrates how to construct and execute a sequential workflow using the AIGNE Framework. You will learn how to chain multiple agents together, where the output of one agent becomes the input for the next, creating a step-by-step processing pipeline. This pattern is ideal for tasks that require a series of distinct, ordered operations.

## Overview

A sequential workflow processes tasks in a predefined order. Each agent in the sequence performs a specific function and passes its result to the subsequent agent. This ensures a predictable and controlled execution flow, similar to an assembly line.

This example builds a simple marketing content generation pipeline composed of three agents:

::::steps
:::step{title="Concept Extractor"}
Analyzes a product description to identify key features, target audience, and unique selling points.
:::

:::step{title="Writer"}
Uses the extracted concepts to compose a compelling marketing copy.
:::

:::step{title="Format Proof"}
Refines the draft copy by correcting grammar, improving clarity, and ensuring a polished final output.
:::
::::

The data flows through the agents in a strict sequence as illustrated below.

```mermaid
flowchart LR
in(In)
out(Out)
conceptExtractor(Concept Extractor)
writer(Writer)
formatProof(Format Proof)

in --> conceptExtractor --> writer --> formatProof --> out

classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px,color:#b35b39,font-weight:bolder;
classDef processing fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px,color:#6B8F3C,font-weight:bolder;

class in inputOutput
class out inputOutput
class conceptExtractor processing
class writer processing
class formatProof processing
```

## Prerequisites

Before running the example, ensure your development environment meets the following requirements:

- <strong>Node.js</strong>: Version 20.0 or higher.
- <strong>npm</strong>: Included with Node.js.
- <strong>OpenAI API Key</strong>: Required for the model interactions in this example. You can obtain one from the [OpenAI Platform](https://platform.openai.com/api-keys).

## Quick Start

You can run this example directly without a local installation using `npx`.

### Run the Example

Execute the following commands in your terminal.

To run in the default one-shot mode:

```bash
npx -y @aigne/example-workflow-sequential
```

To run in an interactive chat mode:

```bash
npx -y @aigne/example-workflow-sequential --interactive
```

You can also pipe input directly into the command:

```bash
echo "Create marketing content for our new AI-powered fitness app" | npx -y @aigne/example-workflow-sequential
```

### Connect to an AI Model

The first time you run the example, the application will detect that no AI model has been configured and will prompt you to connect to one.

![Initial prompt to connect an AI model](https://media.arcblock.io/lib/d5/d559dd2a1f34acaa.w1600.webp)

You have several options to proceed:

<strong>1. Connect via the Official AIGNE Hub (Recommended)</strong>

This is the most straightforward method to get started. New users receive a complimentary token balance for trial purposes.

- Select the first option in the prompt: `Connect to the Arcblock official AIGNE Hub`.
- Your default web browser will open a new tab to the AIGNE Hub authorization page.
- Follow the on-screen instructions to approve the connection.

![Authorize connection to AIGNE Hub](https://media.arcblock.io/lib/71/71683af3a27ab961.w1600.webp)

<strong>2. Connect via a Self-Hosted AIGNE Hub</strong>

If you operate your own instance of AIGNE Hub, you can connect to it directly.

- Select the second option: `Connect to my own AIGNE Hub`.
- Enter the URL of your self-hosted AIGNE Hub instance when prompted in the terminal.

![Enter self-hosted AIGNE Hub URL](https://media.arcblock.io/lib/8c/8ccdbc027ddcbb8f.w1600.webp)

<strong>3. Connect via a Third-Party Model Provider</strong>

You can also connect directly to a supported third-party model provider, such as OpenAI. This requires setting the appropriate API key as an environment variable. For OpenAI, export the `OPENAI_API_KEY` variable:

**Set OpenAI API Key**

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

Replace `"YOUR_OPENAI_API_KEY"` with your actual key. After setting the environment variable, execute the run command again. For details on configuring other providers, refer to the `.env.local.example` file in the project repository.

## Installation (Optional)

If you prefer to run the example from a local clone of the repository, follow these steps.

<strong>1. Clone the Repository</strong>

```bash
git clone https://github.com/AIGNE-io/aigne-framework
```

<strong>2. Install Dependencies</strong>

Navigate to the example's directory and install the required packages using `pnpm`.

```bash
cd aigne-framework/examples/workflow-sequential
pnpm install
```

<strong>3. Run the Example</strong>

Use the `pnpm start` command to execute the workflow.

Run in one-shot mode:

```bash
pnpm start
```

Run in interactive chat mode (note the `--` before the argument):

```bash
pnpm start -- --interactive
```

Use pipeline input:

```bash
echo "Create marketing content for our new AI-powered fitness app" | pnpm start
```

### Command-Line Options

The example supports several command-line arguments for customization:

| Parameter  | Description  | Default  |
|---|---|---|
| `--interactive`  | Run in interactive chat mode.  | Disabled  |
| `--model <provider[:model]>`  | Specify the AI model to use (e.g., `openai` or `openai:gpt-4o-mini`).  | `openai`  |
| `--temperature <value>`  | Set the temperature for model generation.  | Provider default  |
| `--top-p <value>`  | Set the top-p sampling value.  | Provider default  |
| `--presence-penalty <value>`  | Set the presence penalty value.  | Provider default  |
| `--frequency-penalty <value>`  | Set the frequency penalty value.  | Provider default  |
| `--log-level <level>`  | Set the logging level (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).  | `INFO`  |
| `--input`, `-i <input>`  | Provide input directly as an argument.  | `None`  |

## Code Example

The core logic of the sequential workflow is defined in a single TypeScript file. It initializes three distinct `AIAgent` instances and orchestrates them within a `TeamAgent` configured for sequential execution.

**sequential-workflow.ts**

```typescript
import { AIAgent, AIGNE, ProcessMode, TeamAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";

const { OPENAI_API_KEY } = process.env;

// 1. Initialize the model
const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

// 2. Define the first agent in the sequence
const conceptExtractor = AIAgent.from({
  instructions: `\
You are a marketing analyst. Give a product description, identity:
- Key features
- Target audience
- Unique selling points

Product description:
{{product}}`,
  outputKey: "concept",
});

// 3. Define the second agent
const writer = AIAgent.from({
  instructions: `\
You are a marketing copywriter. Given a block of text describing features, audience, and USPs,
compose a compelling marketing copy (like a newsletter section) that highlights these points.
Output should be short (around 150 words), output just the copy as a single text block.

Product description:
{{product}}

Below is the info about the product:
{{concept}}`,
  outputKey: "draft",
});

// 4. Define the third agent
const formatProof = AIAgent.from({
  instructions: `\
You are an editor. Given the draft copy, correct grammar, improve clarity, ensure consistent tone,
give format and make it polished. Output the final improved copy as a single text block.

Product description:
{{product}}

Below is the info about the product:
{{concept}}

Draft copy:
{{draft}}`,
  outputKey: "content",
});

// 5. Initialize the AIGNE instance
const aigne = new AIGNE({ model });

// 6. Create a TeamAgent to manage the sequential workflow
const teamAgent = TeamAgent.from({
  skills: [conceptExtractor, writer, formatProof],
  mode: ProcessMode.sequential, // This ensures agents run one after another
});

// 7. Invoke the workflow with initial input
const result = await aigne.invoke(teamAgent, {
  product: "AIGNE is a No-code Generative AI Apps Engine",
});

console.log(result);

/*
// Expected Output Structure:
{
  concept: "...", // Output from conceptExtractor
  draft: "...",   // Output from writer
  content: "..."  // Output from formatProof
}
*/
```

This script demonstrates the following key steps:

1. An `OpenAIChatModel` instance is created to handle communication with the LLM.
2. Three `AIAgent` instances (`conceptExtractor`, `writer`, `formatProof`) are defined with specific instructions. Each agent's `outputKey` determines the key under which its result is stored.
3. The `writer` agent uses the output of the `conceptExtractor` via the `{{concept}}` placeholder. Similarly, `formatProof` uses `{{concept}}` and `{{draft}}`.
4. A `TeamAgent` is configured with the three agents in its `skills` array. The `mode` is set to `ProcessMode.sequential`, which instructs the team to execute the agents in the order they are provided.
5. Finally, `aigne.invoke()` starts the workflow, passing the initial product description. The final result is an object containing the outputs from all agents in the sequence.

## Debugging

To monitor and debug the execution of your agents, you can use the `aigne observe` command. This tool provides a web-based interface to inspect traces, review inputs and outputs, and analyze the performance of your workflow.

First, start the observation server in your terminal:

```bash
aigne observe
```

The server will start, and you can access the UI at `http://localhost:7893`.

![AIGNE Observe server starting in the terminal](https://media.arcblock.io/lib/cc/cc02f9ff8f8e9cb3.w1600.webp)

After running your workflow, the execution trace will appear in the observability interface, allowing you to examine each step of the sequence in detail.

![List of recent agent traces in the AIGNE Observability UI](https://media.arcblock.io/lib/30/305233c275170db3.w1600.webp)

## Summary

This guide covered the setup and execution of a sequential workflow. By defining a series of agents and orchestrating them with a `TeamAgent` in sequential mode, you can build powerful, multi-step processing pipelines for complex tasks.

For more advanced workflow patterns, explore the following examples:

::::card-group
::link-card{title="Workflow: Parallel Execution" description="Learn how to run multiple agents simultaneously to improve performance." icon="git-branch" href="/en/docs/aigne-framework/examples-workflow-concurrency-9dc03e/"}
::link-card{title="Workflow: Orchestration" description="Coordinate multiple agents in more complex, non-linear pipelines." icon="routes" href="/en/docs/aigne-framework/examples-workflow-orchestration-9dc03e/"}
::::

---

## Models

URL: https://www.arcblock.io/en/docs/aigne-framework/models-9dc03e/

The AIGNE Framework is designed to be model-agnostic, allowing you to connect to a wide range of third-party AI model providers. This flexibility is achieved through a system of model adapters, where each adapter provides a standardized interface for a specific service, such as OpenAI, Anthropic, or Google Gemini.

This section provides detailed guides for installing, configuring, and using each officially supported model provider. Whether you need powerful language models, specialized image and video generation, or the privacy of a locally hosted model, you can find the right integration here.

## Supported Model Providers

Below is a curated list of supported providers. Each card links to a dedicated guide with installation instructions, configuration details, and practical code examples.

### Foundational Models

These are direct integrations with major AI model providers for chat completions and other language-based tasks.

::::card-group
::link-card{title="OpenAI" description="Integrate with OpenAI's suite of models, including the powerful GPT-4o, for chat completions and function calling." icon="brain" href="/en/docs/aigne-framework/models-openai-9dc03e/"}
::link-card{title="Anthropic" description="Leverage Anthropic's Claude models, known for their strong performance in complex reasoning and conversation." icon="bot" href="/en/docs/aigne-framework/models-anthropic-9dc03e/"}
::link-card{title="Google Gemini" description="Connect to Google's Gemini family of multimodal models for advanced text and image understanding." icon="sparkles" href="/en/docs/aigne-framework/models-gemini-9dc03e/"}
::link-card{title="AWS Bedrock" description="Access a variety of foundation models from providers like Anthropic, Cohere, and Amazon through AWS Bedrock." icon="cloud" href="/en/docs/aigne-framework/models-bedrock-9dc03e/"}
::link-card{title="DeepSeek" description="Utilize DeepSeek's powerful and efficient language models for a range of natural language processing tasks." icon="brain" href="/en/docs/aigne-framework/models-deepseek-9dc03e/"}
::link-card{title="Doubao" description="Integrate with Doubao's language models for building conversational AI and other text-based applications." icon="bot" href="/en/docs/aigne-framework/models-doubao-9dc03e/"}
::link-card{title="xAI" description="Connect to xAI's Grok models, designed for real-time information processing and a unique conversational style." icon="sparkles" href="/en/docs/aigne-framework/models-xai-9dc03e/"}
::::

### Image Generation Models

Specialized integrations for creating visual content from text prompts.

::::card-group
::link-card{title="Ideogram" description="Generate high-quality images with reliable text rendering using Ideogram's advanced synthesis models." icon="image" href="/en/docs/aigne-framework/models-ideogram-9dc03e/"}
::link-card{title="OpenAI" description="Use DALL-E 3 and other models for creative and diverse image generation capabilities." icon="brain" href="/en/docs/aigne-framework/models-openai-9dc03e/"}
::link-card{title="Google Gemini" description="Leverage Gemini and Imagen models for versatile image generation and editing alongside language features." icon="sparkles" href="/en/docs/aigne-framework/models-gemini-9dc03e/"}
::::

### Video Generation Models

Integrations for generating video content from text or image inputs.

::::card-group
::link-card{title="OpenAI" description="Generate high-quality video content from text or image prompts using OpenAI's Sora models." icon="brain" href="/en/docs/aigne-framework/models-openai-9dc03e/"}
::link-card{title="Google Gemini" description="Create video from text or images using Google's Veo models for dynamic content generation." icon="sparkles" href="/en/docs/aigne-framework/models-gemini-9dc03e/"}
::link-card{title="AIGNE Hub" description="Access video generation models like OpenAI Sora and Google Veo through a unified API endpoint." icon="routes" href="/en/docs/aigne-framework/models-aigne-hub-9dc03e/"}
::::

### Local and Aggregator Services

Connect to local instances or services that provide access to multiple models through a single API.

::::card-group
::link-card{title="Ollama" description="Run open-source models like Llama 3 locally on your own hardware for maximum privacy and offline access." icon="server" href="/en/docs/aigne-framework/models-ollama-9dc03e/"}
::link-card{title="LMStudio" description="Connect to models running locally via the LMStudio application, providing a simple way to experiment with open-source AI." icon="monitor" href="/en/docs/aigne-framework/models-lmstudio-9dc03e/"}
::link-card{title="OpenRouter" description="Access a wide variety of models from different providers through a single, unified API with fallback options." icon="routes" href="/en/docs/aigne-framework/models-open-router-9dc03e/"}
::link-card{title="Poe" description="Integrate with various models available through the Poe platform, offering a diverse set of AI capabilities." icon="message-square" href="/en/docs/aigne-framework/models-poe-9dc03e/"}
::link-card{title="AIGNE Hub" description="Use the AIGNE Hub as a unified proxy to seamlessly switch between multiple LLM providers without changing client-side code." icon="routes" href="/en/docs/aigne-framework/models-aigne-hub-9dc03e/"}
::::

## Summary

The AIGNE Framework's modular design makes it easy to integrate with the best AI model for your specific needs. Each provider has a dedicated package that handles the complexities of the underlying API, presenting you with a consistent and straightforward interface.

To get started, choose a provider from the list above and follow the linked guide for detailed instructions. For a high-level overview of how model adapters work within the framework, see the [Overview](/en/docs/aigne-framework/models-overview-9dc03e/) page.

---

## AIGNE Hub

URL: https://www.arcblock.io/en/docs/aigne-framework/models-aigne-hub-9dc03e/

The AIGNE Hub provides a unified proxy layer for accessing a variety of Large Language Models (LLMs), image, and video generation services from multiple providers. By using the `@aigne/aigne-hub` package, you can seamlessly switch between different AI models without altering your client-side application logic, directing all requests through a single, consistent API endpoint.

This guide covers the installation, configuration, and usage of the `AIGNEHubChatModel`, `AIGNEHubImageModel`, and `AIGNEHubVideoModel` classes to connect your application to the AIGNE Hub.

## Overview

AIGNE Hub acts as a gateway, aggregating major AI providers such as OpenAI, Anthropic, Google, and others. This architecture simplifies integration by abstracting the specific requirements of each provider's API. You interact with any supported model by simply passing its unique identifier, which includes the provider prefix (e.g., `openai/gpt-4o-mini` or `anthropic/claude-3-sonnet`).

### Key Features

- <strong>Unified Access</strong>: A single endpoint for all LLM, image, and video generation requests.
- <strong>Multi-Provider Support</strong>: Access models from OpenAI, Anthropic, AWS Bedrock, Google, DeepSeek, Ollama, xAI, and OpenRouter.
- <strong>Secure Authentication</strong>: Manage access through a single API key (`apiKey`).
- <strong>Chat, Image, and Video Models</strong>: Supports chat completions, image generation, and video creation.
- <strong>Streaming</strong>: Real-time, token-level streaming for chat responses.
- <strong>Seamless Integration</strong>: Designed to work with the broader AIGNE Framework.

### Supported Providers

AIGNE Hub supports a wide range of AI providers through its unified API.

| Provider  | Identifier  |
|---|---|
| OpenAI  | `openai`  |
| Anthropic  | `anthropic`  |
| AWS Bedrock  | `bedrock`  |
| DeepSeek  | `deepseek`  |
| Google  | `google`  |
| Ollama  | `ollama`  |
| OpenRouter  | `openRouter`  |
| xAI  | `xai`  |

## Installation

To get started, install the `@aigne/aigne-hub` and `@aigne/core` packages in your project.

**npm install**

```bash
npm install @aigne/aigne-hub @aigne/core
```

**yarn add**

```bash
yarn add @aigne/aigne-hub @aigne/core
```

**pnpm add**

```bash
pnpm add @aigne/aigne-hub @aigne/core
```

## Configuration

The chat, image, and video models require configuration to connect to your AIGNE Hub instance. The primary options include the Hub's URL, an access key, and the desired model identifier.

### Model Configuration

The configuration options are consistent across `AIGNEHubChatModel`, `AIGNEHubImageModel`, and `AIGNEHubVideoModel`.

- **baseUrl** `string` *(required)* — The base URL of your AIGNE Hub instance (e.g., https://your-aigne-hub-instance/ai-kit).
- **apiKey** `string` *(required)* — Your API access key for authenticating with the AIGNE Hub.
- **model** `string` *(required)* — The model identifier, prefixed with the provider (e.g., openai/gpt-4o-mini).
- **modelOptions** `object` — Optional model-specific parameters to pass through to the provider's API.

## Usage

### Chat Completions

To perform a chat completion, instantiate `AIGNEHubChatModel` with your configuration and call the `invoke` method.

**Basic Chat Completion**

```typescript
import { AIGNEHubChatModel } from "@aigne/aigne-hub";

const model = new AIGNEHubChatModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "openai/gpt-4o-mini",
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Hello, world!" }],
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "text": "Hello! How can I help you today?",
  "model": "openai/gpt-4o-mini",
  "usage": {
    "inputTokens": 8,
    "outputTokens": 9
  }
}
```

<strong>Example Models:</strong>

- `openai/gpt-4o-mini`
- `anthropic/claude-3-sonnet`
- `google/gemini-pro`
- `xai/grok-1`
- `openRouter/mistralai/mistral-7b-instruct`
- `ollama/llama3`

### Streaming Chat Responses

For real-time responses, set the `streaming` option to `true` in the `invoke` call. This returns an async iterator that yields response chunks as they become available.

**Streaming Example**

```typescript
import { AIGNEHubChatModel } from "@aigne/aigne-hub";
import { isAgentResponseDelta } from "@aigne/core";

const model = new AIGNEHubChatModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "openai/gpt-4o-mini",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Hello, who are you?" }],
  },
  { streaming: true },
);

let fullText = "";
for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text);
    }
  }
}

console.log("\n--- Response Complete ---");
console.log(fullText);
```

### Image Generation

AIGNE Hub supports image generation from multiple providers. Instantiate `AIGNEHubImageModel` and provide a prompt and model-specific parameters.

#### OpenAI DALL-E

**Generate with DALL-E 3**

```typescript
import { AIGNEHubImageModel } from "@aigne/aigne-hub";

const model = new AIGNEHubImageModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "openai/dall-e-3",
});

const result = await model.invoke({
  prompt: "A futuristic cityscape with flying cars and neon lights",
  n: 1,
  size: "1024x1024",
  quality: "standard",
  style: "natural",
});

console.log(result.images[0].url);
```

- <strong>Reference</strong>: [OpenAI Images API Documentation](https://platform.openai.com/docs/guides/images)

#### Google Gemini Imagen

**Generate with Imagen**

```typescript
import { AIGNEHubImageModel } from "@aigne/aigne-hub";

const model = new AIGNEHubImageModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "google/imagen-4.0-generate-001",
});

const result = await model.invoke({
  prompt: "A serene mountain landscape at sunset",
  n: 1,
  aspectRatio: "1:1",
});

console.log(result.images[0].base64); // Note: Gemini models return base64 data
```

- <strong>Reference</strong>: [Google AI Generative Models API](https://googleapis.github.io/js-genai/release_docs/classes/models.Models.html)

#### Ideogram

**Generate with Ideogram**

```typescript
import { AIGNEHubImageModel } from "@aigne/aigne-hub";

const model = new AIGNEHubImageModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "ideogram/ideogram-v3",
});

const result = await model.invoke({
  prompt: "A cyberpunk character with glowing blue eyes, cinematic style",
  aspectRatio: "1:1",
  styleType: "cinematic",
});

console.log(result.images[0].url);
```

- <strong>Reference</strong>: [Ideogram API Documentation](https://developer.ideogram.ai/api-reference/api-reference/generate-v3)

### Video Generation

AIGNE Hub extends its unified API to AI-powered video generation from leading providers. To create a video, instantiate `AIGNEHubVideoModel` with the appropriate configuration.

#### OpenAI Sora

**Generate with Sora**

```typescript
import { AIGNEHubVideoModel } from "@aigne/aigne-hub";

const model = new AIGNEHubVideoModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "openai/sora-2",
});

const result = await model.invoke({
  prompt: "A serene beach scene with gentle waves at sunset",
  size: "1280x720",
  seconds: "8",
  outputFileType: "url",
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "videos": [{ "url": "https://...", "type": "url" }],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0,
    "aigneHubCredits": 200
  },
  "model": "openai/sora-2",
  "seconds": 8
}
```

- <strong>Reference</strong>: [OpenAI Video API Documentation](https://platform.openai.com/docs/api-reference/videos)

#### Google Gemini Veo

**Generate with Veo**

```typescript
import { AIGNEHubVideoModel } from "@aigne/aigne-hub";

const model = new AIGNEHubVideoModel({
  baseUrl: "https://your-aigne-hub-instance/ai-kit",
  apiKey: "your-access-key-secret",
  model: "google/veo-3.1-generate-preview",
});

const result = await model.invoke({
  prompt: "A majestic eagle soaring through mountain valleys",
  aspectRatio: "16:9",
  size: "1080p",
  seconds: "6",
  outputFileType: "url",
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "videos": [{ "url": "https://...", "type": "url" }],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0,
    "aigneHubCredits": 150
  },
  "model": "google/veo-3.1-generate-preview",
  "seconds": 6
}
```

- <strong>Reference</strong>: [Google Gemini Video API Documentation](https://ai.google.dev/api/generate-videos)

## Summary

The `@aigne/aigne-hub` package simplifies multi-provider LLM integration by offering a unified client for the AIGNE Hub service. By abstracting provider-specific logic for chat, image, and video models, it enables developers to build more flexible and maintainable AI-powered applications.

For more detailed information on specific models and their capabilities, please refer to the documentation provided by each respective AI provider. To explore other model integrations, see the [Models Overview](/en/docs/aigne-framework/models-overview-9dc03e/).

---

## Anthropic

URL: https://www.arcblock.io/en/docs/aigne-framework/models-anthropic-9dc03e/

This guide provides instructions for configuring and using Anthropic's Claude models within the AIGNE Framework via the `@aigne/anthropic` package. It covers API key setup, model instantiation, and invoking the model for both standard and streaming responses.

For a general overview of how models work within the AIGNE framework, please refer to the [Models core concepts](/en/docs/aigne-framework/developer-guide-core-concepts-models-9dc03e/) documentation.

## Introduction

The `@aigne/anthropic` package provides a direct and seamless integration between the AIGNE Framework and Anthropic's powerful Claude language models. This allows developers to leverage the advanced capabilities of models like Claude 3.5 Sonnet and Claude 3 Opus through the standardized `ChatModel` interface, ensuring consistency across your agentic applications.

Key features of this integration include:

- <strong>Direct API Integration</strong>: Utilizes the official Anthropic SDK for reliable communication.
- <strong>Chat Completions</strong>: Full support for Anthropic's chat completions API.
- <strong>Tool Calling</strong>: Natively supports Claude's tool-calling functionality.
- <strong>Streaming Responses</strong>: Enables real-time, responsive applications by handling streaming outputs.
- <strong>Type-Safe</strong>: Comes with comprehensive TypeScript typings for robust development.

## Installation

To get started, install the `@aigne/anthropic` package along with the core AIGNE package using your preferred package manager.

```bash
npm install @aigne/anthropic @aigne/core
```

```bash
yarn add @aigne/anthropic @aigne/core
```

```bash
pnpm add @aigne/anthropic @aigne/core
```

## Configuration

The `AnthropicChatModel` class is the primary entry point for interacting with Claude models. To instantiate it, you need to provide your Anthropic API key and optionally specify a model and other configurations.

### API Key

Your Anthropic API key can be configured in one of three ways, in order of precedence:

::::steps
:::step{title="Directly in the constructor"}
Pass the key via the `apiKey` property.
:::

:::step{title="`ANTHROPIC_API_KEY`"}
<strong>environment variable</strong>: The model will automatically detect and use this variable.
:::

:::step{title="`CLAUDE_API_KEY`"}
<strong>environment variable</strong>: An alternative environment variable that is also supported.
:::
::::

**Instantiating the Model**

```typescript
import { AnthropicChatModel } from "@aigne/anthropic";

const model = new AnthropicChatModel({
  // Option 1: Provide the API key directly
  apiKey: "your-anthropic-api-key",

  // The model will automatically use ANTHROPIC_API_KEY or CLAUDE_API_KEY
  // if they are set in your environment and apiKey is not provided.
});
```

### Model Selection

You can specify which Claude model to use with the `model` property. If not specified, it defaults to `claude-3-7-sonnet-latest`. Other common model parameters like `temperature` can be set within the `modelOptions` object.

A list of commonly used models includes:

- `claude-3-5-sonnet-20240620`
- `claude-3-opus-20240229`
- `claude-3-sonnet-20240229`
- `claude-3-haiku-20240307`

**Model Configuration**

```typescript
import { AnthropicChatModel } from "@aigne/anthropic";

const model = new AnthropicChatModel({
  apiKey: "your-anthropic-api-key",

  // Specify the model version
  model: "claude-3-haiku-20240307",

  // Configure other model behaviors
  modelOptions: {
    temperature: 0.7, // Controls randomness (0.0 to 1.0)
  },
});
```

## Basic Usage

To generate a response, use the `invoke` method. Pass a list of messages to the model to start a conversation. The method returns a promise that resolves with the model's output, including the text response and token usage statistics.

**Basic Chat Completion**

```typescript
import { AnthropicChatModel } from "@aigne/anthropic";

const model = new AnthropicChatModel({
  apiKey: "your-anthropic-api-key",
  model: "claude-3-haiku-20240307",
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Tell me about yourself" }],
});

console.log(result);
```

The `result` object contains the generated text and other metadata from the API.

<strong>Example Response</strong>

```json
{
  "text": "I am Claude, a large language model trained by Anthropic.",
  "model": "claude-3-haiku-20240307",
  "usage": {
    "inputTokens": 8,
    "outputTokens": 12
  }
}
```

## Streaming Responses

For applications requiring real-time interaction, you can enable streaming by setting the `streaming` option to `true` in the `invoke` method. This returns an async iterator that yields response chunks as they become available.

The `isAgentResponseDelta` utility can be used to check if a chunk contains new data.

**Streaming Example**

```typescript
import { AnthropicChatModel } from "@aigne/anthropic";
import { isAgentResponseDelta } from "@aigne/core";

const model = new AnthropicChatModel({
  apiKey: "your-anthropic-api-key",
  model: "claude-3-haiku-20240307",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Tell me a short story about a robot." }],
  },
  { streaming: true },
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      process.stdout.write(text); // Print text to the console as it arrives
      fullText += text;
    }
    if (chunk.delta.json) {
      Object.assign(json, chunk.delta.json);
    }
  }
}

console.log("\n\n--- Final Response ---");
console.log(fullText);
console.log(json);
```

This code processes the stream, printing text chunks to the console immediately and accumulating the full response and metadata.

## Summary

You now have the necessary information to install, configure, and use Anthropic's Claude models within your AIGNE applications. You can perform basic invocations for simple tasks or use streaming for more interactive experiences.

To learn more about orchestrating multiple models and agents, see the [Team Agent](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/) documentation. For details on other available models, visit the main [Models](/en/docs/aigne-framework/models-9dc03e/) section.

---

## AWS Bedrock

URL: https://www.arcblock.io/en/docs/aigne-framework/models-bedrock-9dc03e/

The `@aigne/bedrock` package provides a direct and robust integration between the AIGNE Framework and Amazon Web Services (AWS) Bedrock. This allows developers to leverage the diverse range of foundation models available through AWS Bedrock within their AIGNE applications, benefiting from AWS's scalable and secure infrastructure while maintaining a consistent interface.

This guide provides a systematic overview of the installation, configuration, and usage of the `BedrockChatModel`. For details on other models, please refer to the main [Models overview](/en/docs/aigne-framework/models-overview-9dc03e/).

## Installation

To begin, install the necessary packages using your preferred package manager. The `@aigne/core` package is a required peer dependency.

**Terminal**

```bash
# Using npm
npm install @aigne/bedrock @aigne/core

# Using yarn
yarn add @aigne/bedrock @aigne/core

# Using pnpm
pnpm add @aigne/bedrock @aigne/core
```

## Configuration

Proper configuration involves setting up AWS credentials and instantiating the `BedrockChatModel` with the desired parameters.

### AWS Credentials

The AWS SDK requires credentials to authenticate requests. You can provide them in one of two ways:

1. <strong>Environment Variables (Recommended)</strong>: Set the following environment variables in your development or deployment environment. The SDK will automatically detect and use them.
2.
  - `AWS_ACCESS_KEY_ID`: Your AWS access key ID.
  - `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key.
  - `AWS_REGION`: The AWS region where your Bedrock service is enabled (e.g., `us-east-1`).
3. <strong>Direct Instantiation</strong>: Pass the credentials directly to the `BedrockChatModel` constructor. This method is suitable for specific use cases but is generally less secure than using environment variables.

### BedrockChatModel Options

The `BedrockChatModel` is the primary class for interacting with AWS Bedrock. Its constructor accepts an options object to configure its behavior.

- **accessKeyId** `string` — Your AWS access key ID. If not provided, the SDK will attempt to read it from the AWS_ACCESS_KEY_ID environment variable.
- **secretAccessKey** `string` — Your AWS secret access key. If not provided, the SDK will attempt to read it from the AWS_SECRET_ACCESS_KEY environment variable.
- **region** `string` — The AWS region for the Bedrock service. If not provided, the SDK will attempt to read it from the AWS_REGION environment variable.
- **model** `string` (default: `us.amazon.nova-lite-v1:0`) — The ID of the foundation model to use (e.g., anthropic.claude-3-sonnet-20240229-v1:0, meta.llama3-8b-instruct-v1:0).
- **modelOptions** `object` — Additional options to control model inference behavior.
  - **temperature** `number` — Controls randomness in the generation. Higher values mean more creative responses.
  - **topP** `number` — Controls nucleus sampling. The model considers only the tokens with the top P probability mass.
- **clientOptions** `object` — Advanced configuration options passed directly to the underlying BedrockRuntimeClient from the AWS SDK.

## Usage Examples

The following examples demonstrate how to use the `BedrockChatModel` for both standard and streaming invocations.

### Basic Usage

This example shows how to instantiate the model and invoke it to get a single, complete response.

**Basic Invocation**

```typescript
import { BedrockChatModel } from "@aigne/bedrock";

// Instantiate the model with credentials and model ID
const model = new BedrockChatModel({
  accessKeyId: "YOUR_ACCESS_KEY_ID", // Or use environment variables
  secretAccessKey: "YOUR_SECRET_ACCESS_KEY", // Or use environment variables
  region: "us-east-1", // Specify your AWS region
  model: "anthropic.claude-3-haiku-20240307-v1:0",
  modelOptions: {
    temperature: 0.7,
  },
});

// Define the input messages
const result = await model.invoke({
  messages: [{ role: "user", content: "Hello, what is AWS Bedrock?" }],
});

console.log(result.text);
```

The output will be a string containing the model's response. The `result` object also contains usage metrics.

### Streaming Responses

For applications requiring real-time feedback, you can stream the response as it is generated. This is useful for chatbots and other interactive experiences.

**Streaming Invocation**

```typescript
import { BedrockChatModel } from "@aigne/bedrock";
import { isAgentResponseDelta } from "@aigne/core";

const model = new BedrockChatModel({
  accessKeyId: "YOUR_ACCESS_KEY_ID",
  secretAccessKey: "YOUR_SECRET_ACCESS_KEY",
  region: "us-east-1",
  model: "anthropic.claude-3-haiku-20240307-v1:0",
  modelOptions: {
    temperature: 0.7,
  },
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Hello, what is AWS Bedrock?" }],
  },
  { streaming: true },
);

let fullText = "";

for await (const chunk of stream) {
  // Use the type guard to check if the chunk is a delta
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text); // Print each part of the response as it arrives
    }
  }
}

console.log("\n--- Full Response ---");
console.log(fullText);
```

This code processes a stream of `AgentResponseChunk` objects. Each chunk contains a delta of the response, which is accumulated to form the complete text.

## Supported Models

AWS Bedrock provides access to a wide variety of foundation models from leading AI companies like Anthropic, Cohere, Meta, Stability AI, and Amazon. You can specify the desired model using its unique `modelId`.

Some commonly used model families include:

- <strong>Anthropic Claude</strong>: `anthropic.claude-3-sonnet-20240229-v1:0`, `anthropic.claude-3-haiku-20240307-v1:0`
- <strong>Meta Llama</strong>: `meta.llama3-8b-instruct-v1:0`
- <strong>Amazon Titan</strong>: `amazon.titan-text-express-v1`

For a complete and up-to-date list of available models and their corresponding IDs, please refer to the [official AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html).

## Summary

The `@aigne/bedrock` package offers a streamlined way to integrate powerful foundation models from AWS Bedrock into your AIGNE applications. By following the configuration steps and usage patterns outlined in this guide, you can efficiently build and deploy AI-driven features.

For more advanced topics, such as tool usage and structured outputs, please refer to the [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) documentation.

---

## Model Configuration

URL: https://www.arcblock.io/en/docs/aigne-framework/models-configuration-9dc03e/

To integrate and utilize the various AI models within the AIGNE Framework, you must first configure the necessary credentials, primarily through environment variables. This ensures secure and proper authentication with the respective third-party services. This guide provides the specific environment variables required for each supported model provider.

## General Usage

To use a specific model, you typically need to set two primary environment variables:

1. `MODEL`: Specifies the model identifier, often prefixed with the provider's name (e.g., `openai:gpt-4o`).
2. `[PROVIDER]_API_KEY`: The unique API key for that provider (e.g., `OPENAI_API_KEY`).

You can set these variables in your shell before running your application.

**Set environment variables**

```bash
export MODEL=openai:gpt-4o
export OPENAI_API_KEY="your_api_key_here"

# Then run your AIGNE application
node your-app.js
```

## Provider Configurations

Below is a detailed list of the required environment variables for each supported model provider. Replace the placeholder values with your actual credentials.

### OpenAI

To connect to OpenAI models like GPT-4o, set the following variables:

**OpenAI Configuration**

```bash
export MODEL="openai:gpt-4o"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

### Anthropic

For Anthropic's Claude models, configure the following:

**Anthropic Configuration**

```bash
export MODEL="anthropic:claude-3-7-sonnet-latest"
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
```

### Google Gemini

To use Google's Gemini models, set these variables:

**Gemini Configuration**

```bash
export MODEL="gemini:gemini-2.0-flash"
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```

### AWS Bedrock

For models hosted on AWS Bedrock, you need to provide your AWS credentials and the target region.

**AWS Bedrock Configuration**

```bash
export MODEL="bedrock:us.amazon.nova-premier-v1:0"
export AWS_ACCESS_KEY_ID="YOUR_AWS_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_AWS_SECRET_ACCESS_KEY"
export AWS_REGION="YOUR_AWS_REGION"
```

### DeepSeek

To use DeepSeek models, configure the following API key:

**DeepSeek Configuration**

```bash
export MODEL="deepseek/deepseek-chat"
export DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
```

### Doubao

For Doubao models, set the following environment variable:

**Doubao Configuration**

```bash
export MODEL="doubao-seed-1-6-250615"
export DOUBAO_API_KEY="YOUR_DOUBAO_API_KEY"
```

### Ideogram

For Ideogram's image generation models, configure your API key as shown:

**Ideogram Configuration**

```bash
export MODEL="ideogram-v3"
export IDEOGRAM_API_KEY="YOUR_IDEOGRAM_API_KEY"
```

### Ollama

When using a locally hosted Ollama instance, you need to specify the model name and the API endpoint. The API key is typically a placeholder.

**Ollama Configuration**

```bash
export MODEL="llama3"
export OLLAMA_DEFAULT_BASE_URL="http://localhost:11434/v1"
export OLLAMA_API_KEY="ollama"
```

### OpenRouter

OpenRouter provides access to various models through a single API. Specify the model with its full path.

**OpenRouter Configuration**

```bash
export MODEL="openai/gpt-4o"
export OPEN_ROUTER_API_KEY="YOUR_OPEN_ROUTER_API_KEY"
```

### Poe

To connect to models via Poe, use the following configuration:

**Poe Configuration**

```bash
export MODEL="claude-3-opus"
export POE_API_KEY="YOUR_POE_API_KEY"
```

### xAI

For xAI's Grok models, set the `XAI_API_KEY` environment variable.

**xAI Configuration**

```bash
export MODEL="grok-2-latest"
export XAI_API_KEY="YOUR_XAI_API_KEY"
```

### LMStudio

For locally hosted models via LMStudio, specify the model name. The API key is typically a placeholder as LMStudio runs locally without authentication by default.

**LMStudio Configuration**

```bash
export MODEL="llama-3.2-3b-instruct"
export LM_STUDIO_API_KEY="lmstudio"
```

## Summary

Properly configuring these environment variables is the foundational step for integrating any model into the AIGNE Framework. This approach keeps your sensitive API keys secure and allows for flexible model selection without changing your application code. For more detailed guides on each provider, please refer to the specific documentation pages, such as [OpenAI](/en/docs/aigne-framework/models-openai-9dc03e/) or [Google Gemini](/en/docs/aigne-framework/models-gemini-9dc03e/).

---

## DeepSeek

URL: https://www.arcblock.io/en/docs/aigne-framework/models-deepseek-9dc03e/

This guide provides instructions for configuring and using DeepSeek models within the AIGNE Framework via the `@aigne/deepseek` package. It covers API key setup, model instantiation, and examples for both standard and streaming responses.

The `@aigne/deepseek` package provides a direct integration with the DeepSeek API, leveraging its powerful language models. It is designed to be compatible with the AIGNE Framework's `ChatModel` interface, ensuring a consistent development experience.

## Installation

To begin, install the necessary packages using your preferred package manager. The `@aigne/core` package is a required peer dependency.

**tabs**

```bash
npm install @aigne/deepseek @aigne/core
```

**tabs**

```bash
yarn add @aigne/deepseek @aigne/core
```

**tabs**

```bash
pnpm add @aigne/deepseek @aigne/core
```

## Configuration

The `DeepSeekChatModel` class is the primary interface for interacting with DeepSeek models. It extends the `OpenAIChatModel` and is configured to use DeepSeek's specific API endpoints and authentication methods.

Your DeepSeek API key is required for authentication. You can provide it in two ways:

::::steps
:::step{title="Directly in the constructor"}
Pass the key via the `apiKey` property.
:::

:::step{title="Environment variable"}
Set the `DEEPSEEK_API_KEY` environment variable. The model will automatically use it if the `apiKey` property is not provided.
:::
::::

### Parameters

- **apiKey** `string` — Your DeepSeek API key. If not provided, the client will look for the DEEPSEEK_API_KEY environment variable.
- **model** `string` (default: `deepseek-chat`) — The specific DeepSeek model to use for chat completions. Defaults to deepseek-chat.
- **modelOptions** `object` — Additional options to pass to the model API, such as temperature, top_p, or max_tokens.
- **baseURL** `string` (default: `https://api.deepseek.com`) — The base URL for the DeepSeek API. This should not be changed unless you are using a custom proxy.

## Usage

Once configured, the model can be used to generate text completions or stream responses.

### Basic Invocation

To generate a standard response, use the `invoke` method. Provide a list of messages, and the method will return a promise that resolves with the complete response from the model.

**Basic Usage**

```typescript
import { DeepSeekChatModel } from "@aigne/deepseek";

const model = new DeepSeekChatModel({
  // Provide API key directly or use environment variable DEEPSEEK_API_KEY
  apiKey: "your-api-key", // Optional if set in env variables
  // Specify model version (defaults to 'deepseek-chat')
  model: "deepseek-chat",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Introduce yourself" }],
});

console.log(result);
```

The `result` object contains the generated text and metadata about the model's usage.

<strong>Example Response</strong>

```json
{
  "text": "Hello! I'm an AI assistant powered by DeepSeek's language model.",
  "model": "deepseek-chat",
  "usage": {
    "inputTokens": 7,
    "outputTokens": 12
  }
}
```

### Streaming Responses

For real-time applications, you can stream the response from the model. Set the `streaming` option to `true` in the `invoke` method's second argument. This returns an async iterator that yields chunks of the response as they become available.

**Streaming Responses**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { DeepSeekChatModel } from "@aigne/deepseek";

const model = new DeepSeekChatModel({
  apiKey: "your-api-key",
  model: "deepseek-chat",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Introduce yourself" }],
  },
  { streaming: true },
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) fullText += text;
    if (chunk.delta.json) Object.assign(json, chunk.delta.json);
  }
}

console.log(fullText);
// Expected output: "Hello! I'm an AI assistant powered by DeepSeek's language model."

console.log(json);
// Expected output: { model: "deepseek-chat", usage: { inputTokens: 7, outputTokens: 12 } }
```

In this example, the code iterates through the stream, accumulating the text delta from each chunk to build the complete response. Final metadata, such as token usage, is provided in the last chunk.

## Summary

This guide has covered the essential steps to install, configure, and use DeepSeek models with the AIGNE Framework. By following these instructions, you can integrate DeepSeek's chat capabilities into your applications for both single-turn and streaming use cases. For more advanced configurations and features, refer to the API reference and other sections in the documentation.

---

## Doubao

URL: https://www.arcblock.io/en/docs/aigne-framework/models-doubao-9dc03e/

The `@aigne/doubao` package provides a seamless integration between the AIGNE Framework and Doubao's powerful language and image generation models. This guide provides a complete reference for configuring and utilizing Doubao models within your AIGNE applications.

This integration allows developers to leverage Doubao's advanced AI capabilities through the consistent and unified interface of the AIGNE Framework.

## Installation

To begin, install the necessary packages using your preferred package manager. You will need both `@aigne/core` and the Doubao-specific package.

```bash
npm install @aigne/doubao @aigne/core
```

```bash
yarn add @aigne/doubao @aigne/core
```

```bash
pnpm add @aigne/doubao @aigne/core
```

## Configuration

To use the Doubao models, you must provide an API key. The key can be configured in one of two ways, in order of precedence:

::::steps
:::step{title="Direct Instantiation"}
Pass the `apiKey` directly in the model's constructor. This method is explicit and overrides any other configuration.
:::

:::step{title="Environment Variable"}
Set the `DOUBAO_API_KEY` environment variable. The model will automatically use this variable if no key is provided in the constructor.
:::
::::

**"Configuration Example"**

```typescript
import { DoubaoChatModel } from "@aigne/doubao";

// Method 1: Direct Instantiation
const modelWithApiKey = new DoubaoChatModel({
  apiKey: "your-doubao-api-key",
});

// Method 2: Environment Variable
// Set DOUBAO_API_KEY in your .env file or shell
// DOUBAO_API_KEY="your-doubao-api-key"
const modelFromEnv = new DoubaoChatModel();
```

The base URL for the Doubao API is pre-configured to `https://ark.cn-beijing.volces.com/api/v3`, but it can be overridden by passing a `baseURL` option to the constructor if necessary.

## Chat Models

For conversational tasks, the `DoubaoChatModel` provides an interface to Doubao's language models. It leverages an OpenAI-compatible API structure, ensuring a familiar development experience.

### Basic Usage

To perform a chat completion, instantiate `DoubaoChatModel` and use the `invoke` method.

**"Basic Chat Completion"**

```typescript
import { DoubaoChatModel } from "@aigne/doubao";

const model = new DoubaoChatModel({
  apiKey: "your-doubao-api-key", // Or use environment variable
  model: "doubao-seed-1-6-250615",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Introduce yourself" }],
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "text": "Hello! I'm an AI assistant powered by Doubao's language model.",
  "model": "doubao-seed-1-6-250615",
  "usage": {
    "inputTokens": 7,
    "outputTokens": 12
  }
}
```

### Streaming Responses

For real-time applications, you can stream the response from the model. Set the `streaming` option to `true` in the `invoke` call and iterate over the resulting stream to process chunks as they arrive.

**"Streaming Chat Response"**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { DoubaoChatModel } from "@aigne/doubao";

const model = new DoubaoChatModel({
  apiKey: "your-doubao-api-key",
  model: "doubao-seed-1-6-250615",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Introduce yourself" }],
  },
  { streaming: true }
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text); // Print text chunks as they arrive
    }
    if (chunk.delta.json) {
      Object.assign(json, chunk.delta.json);
    }
  }
}

console.log("\n--- Final Data ---");
console.log(fullText);
console.log(json);
```

### Chat Model Parameters

The `DoubaoChatModel` constructor accepts the following options:

- **apiKey** `string` — Your Doubao API key. If not provided, the DOUBAO_API_KEY environment variable will be used.
- **model** `string` (default: `doubao-seed-1-6-250615`) — The specific chat model to use.
- **baseURL** `string` (default: `https://ark.cn-beijing.volces.com/api/v3`) — The base URL for the Doubao API endpoint.
- **modelOptions** `object` — Additional options passed to the model API, such as temperature, top_p, etc. These are standard OpenAI-compatible parameters.

## Image Models

The `DoubaoImageModel` class enables image generation by interfacing with Doubao's image models.

### Basic Usage

Instantiate `DoubaoImageModel` and call the `invoke` method with a prompt to generate an image.

**"Image Generation"**

```typescript
import { DoubaoImageModel } from "@aigne/doubao";

async function generateImage() {
  const imageModel = new DoubaoImageModel({
    apiKey: "your-doubao-api-key", // Or use environment variable
    model: "doubao-seedream-4-0-250828",
  });

  const result = await imageModel.invoke({
    prompt: "A photorealistic image of a cat programming on a laptop",
    modelOptions: {
      size: "1024x1024",
      watermark: false,
    },
  });

  console.log(result);
}

generateImage();
```

<strong>Example Response</strong>

```json
{
  "images": [
    {
      "type": "file",
      "data": "...", // base64 encoded image data
      "mimeType": "image/jpeg"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 1
  },
  "model": "doubao-seedream-4-0-250828"
}
```

### Image Model Parameters

The `DoubaoImageModel` `invoke` method accepts an input object with the following properties. Note that parameter availability may vary by model.

- **prompt** `string` *(required)* — A text description of the desired image(s).
- **model** `string` (default: `doubao-seedream-4-0-250828`) — The identifier for the image model to use.
- **image** `FileUnion` — For image-to-image models (doubao-seededit-3-0-i2i), provides the input image.
- **modelOptions** `object` — An object containing model-specific parameters.
  - **size** `string` — The desired dimensions of the generated image (e.g., "1024x1024").
  - **seed** `number` — A seed value for reproducible results. Supported by doubao-seedream-3-0-t2i and doubao-seededit-3-0-i2i.
  - **guidanceScale** `number` — Controls how closely the generated image follows the prompt. Supported by doubao-seedream-3-0-t2i and doubao-seededit-3-0-i2i.
  - **stream** `boolean` (default: `false`) — If true, streams the generation results. Supported by doubao-seedream-4 models.
  - **watermark** `boolean` (default: `false`) — If false, disables the watermark on the generated image.
  - **sequentialImageGeneration** `boolean` — Enables sequential image generation. Supported by doubao-seedream-4 models.

### Supported Image Models

The following table lists the supported image models and their key characteristics.

| Model Family  | Supported Models  | Key Use Case  |
|---|---|---|
| `doubao-seedream-4`  | `doubao-seedream-4-0-250828`  | Text-to-Image (T2I)  |
| `doubao-seedream-3-0-t2i`  | (Specific model names vary)  | Text-to-Image (T2I)  |
| `doubao-seededit-3-0-i2i`  | (Specific model names vary)  | Image-to-Image (I2I)  |

---

## Google Gemini

URL: https://www.arcblock.io/en/docs/aigne-framework/models-gemini-9dc03e/

This guide provides instructions for configuring and using Google's Gemini models within the AIGNE Framework via the `@aigne/gemini` package. It covers API key setup, model selection, and the specific features available for chat, image, and video generation.

The `@aigne/gemini` package offers a seamless integration with Google's advanced AI capabilities, including the Gemini multimodal models and the Imagen text-to-image models, providing a consistent interface within the AIGNE ecosystem.

## Features

- <strong>Google API Integration</strong>: Provides a direct interface to Google's Gemini, Imagen, and Veo API services.
- <strong>Chat Completions</strong>: Supports all available Gemini chat models for conversational AI.
- <strong>Image Generation</strong>: Integrates with both Imagen and Gemini models for image generation and editing.
- <strong>Video Generation</strong>: Leverages Google's Veo models for text-to-video, image-to-video, and frame interpolation tasks.
- <strong>Multimodal Support</strong>: Natively handles inputs combining text, images, audio, and video.
- <strong>Function Calling</strong>: Supports Gemini's function calling capabilities to interact with external tools.
- <strong>Streaming Responses</strong>: Enables real-time data processing for more responsive applications.
- <strong>Type-Safe</strong>: Includes comprehensive TypeScript typings for all APIs and model configurations.

## Installation

Install the required packages using your preferred package manager.

```bash
npm install @aigne/gemini @aigne/core
```

## Configuration

To authenticate requests, you must provide a Google API key. This can be done by setting an environment variable, which the framework will automatically detect.

**Environment Variable**

```bash
export GEMINI_API_KEY="your-google-api-key"
```

Alternatively, you can pass the `apiKey` directly in the model's constructor.

## Chat Completions

The `GeminiChatModel` class is used for conversational interactions.

### Basic Usage

The following example demonstrates how to instantiate and invoke the `GeminiChatModel`.

**Chat Model Usage**

```typescript
import { GeminiChatModel } from "@aigne/gemini";

const model = new GeminiChatModel({
  // API key is optional if the GEMINI_API_KEY environment variable is set.
  apiKey: "your-api-key",
  // Specify the model. Defaults to 'gemini-2.0-flash'.
  model: "gemini-1.5-flash",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Hi there, introduce yourself" }],
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "text": "Hello from Gemini! I'm Google's helpful AI assistant. How can I assist you today?",
  "model": "gemini-1.5-flash",
  "usage": {
    "inputTokens": 12,
    "outputTokens": 18
  }
}
```

### Streaming Responses

For real-time applications, you can process response chunks as they arrive by enabling streaming.

**Streaming Example**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { GeminiChatModel } from "@aigne/gemini";

const model = new GeminiChatModel({
  apiKey: "your-api-key",
  model: "gemini-1.5-flash",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Hi there, introduce yourself" }],
  },
  { streaming: true }
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) fullText += text;
    if (chunk.delta.json) Object.assign(json, chunk.delta.json);
  }
}

console.log(fullText);
// Output: "Hello from Gemini! I'm Google's helpful AI assistant. How can I assist you today?"

console.log(json);
// Output: { model: "gemini-1.5-flash" }
```

### Chat Model Parameters

- **messages** `array` *(required)* — The conversation history. Each message object contains a 'role' and 'content'.
- **tools** `array` — A list of available function tools for the model to call.
- **toolChoice** `string | object` — Controls how the model uses tools. Can be 'auto', 'required', 'none', or a specific tool.
- **responseFormat** `object` — Specifies the desired output format, such as structured JSON.
- **model** `string` — The model to use (e.g., 'gemini-1.5-pro', 'gemini-1.5-flash').
- **temperature** `number` — Controls randomness (0-1). Higher values produce more creative responses.
- **topP** `number` — Nucleus sampling parameter (0-1).
- **topK** `number` — Top-k sampling parameter.
- **frequencyPenalty** `number` — Reduces the likelihood of repeating tokens.
- **presencePenalty** `number` — Encourages the model to introduce new topics.
- **reasoningEffort** `string | number` — For thinking models (e.g., Gemini 2.5), sets the token budget for reasoning. Can be 'minimal', 'low', 'medium', 'high' or a specific token count.
- **modalities** `array` — Specifies the desired response modalities, such as ['TEXT'], ['IMAGE'], or ['TEXT', 'IMAGE'].

## Image Generation

The `GeminiImageModel` class supports generating and editing images using both specialized Imagen models and multimodal Gemini models.

### Basic Image Generation

This example generates an image using an Imagen model.

**Image Generation**

```typescript
import { GeminiImageModel } from "@aigne/gemini";

const model = new GeminiImageModel({
  apiKey: "your-api-key",
  model: "imagen-4.0-generate-001", // Default Imagen model
});

const result = await model.invoke({
  prompt: "A serene mountain landscape at sunset with golden light",
  n: 1,
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "images": [
    {
      "type": "file",
      "data": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mimeType": "image/png"
    }
  ],
  "usage": { "inputTokens": 0, "outputTokens": 0 },
  "model": "imagen-4.0-generate-001"
}
```

### Image Editing with Gemini Models

Multimodal Gemini models can edit existing images based on a text prompt.

**Image Editing**

```typescript
import { GeminiImageModel } from "@aigne/gemini";

const model = new GeminiImageModel({
  apiKey: "your-api-key",
  model: "gemini-2.0-flash-exp", // Gemini model for editing
});

const result = await model.invoke({
  prompt: "Add vibrant flowers in the foreground",
  image: [
    {
      type: "url",
      url: "https://example.com/original-image.png",
    },
  ],
  n: 1,
});

console.log(result.images); // Array of edited images
```

### Image Model Parameters

Parameters vary depending on the model family used.

#### Common Parameters

| Parameter  | Type  | Description  |
|---|---|---|
| `prompt`  | `string`  | <strong>Required.</strong> A text description of the desired image.  |
| `model`  | `string`  | The model to use. Defaults to `imagen-4.0-generate-001`.  |
| `n`  | `number`  | The number of images to generate. Defaults to `1`.  |
| `image`  | `array`  | For Gemini models, an array of reference images for editing.  |

#### Imagen Model Parameters

| Parameter  | Type  | Description  |
|---|---|---|
| `seed`  | `number`  | A random seed for reproducible results.  |
| `safetyFilterLevel`  | `string`  | The content moderation safety filter level.  |
| `personGeneration`  | `string`  | Controls settings for generating images of people.  |
| `outputMimeType`  | `string`  | The output image format (e.g., `image/png`).  |
| `negativePrompt`  | `string`  | A description of what to exclude from the image.  |
| `imageSize`  | `string`  | The dimensions of the generated image (e.g., "1024x1024").  |
| `aspectRatio`  | `string`  | The aspect ratio of the image (e.g., "16:9").  |

#### Gemini Model Parameters

| Parameter  | Type  | Description  |
|---|---|---|
| `temperature`  | `number`  | Controls randomness (0.0 to 1.0).  |
| `maxOutputTokens`  | `number`  | The maximum number of tokens in the response.  |
| `topP`  | `number`  | Nucleus sampling parameter.  |
| `topK`  | `number`  | Top-k sampling parameter.  |
| `safetySettings`  | `array`  | Custom safety settings for content generation.  |
| `seed`  | `number`  | A random seed for reproducible results.  |
| `systemInstruction`  | `string`  | System-level instructions to guide the model.  |

## Video Generation

The `GeminiVideoModel` class uses Google's Veo models to generate videos from text or images.

### Basic Video Generation

**Text-to-Video**

```typescript
import { GeminiVideoModel } from "@aigne/gemini";

const videoModel = new GeminiVideoModel({
  apiKey: "your-api-key",
  model: "veo-3.1-generate-preview",
});

const result = await videoModel.invoke({
  prompt: "A serene lake with mountains in the background, gentle waves rippling",
  aspectRatio: "16:9",
  size: "720p",
  seconds: "8",
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "videos": [
    {
      "type": "file",
      "data": "base64-encoded-video-data...",
      "mimeType": "video/mp4",
      "filename": "timestamp.mp4"
    }
  ],
  "usage": { "inputTokens": 0, "outputTokens": 0 },
  "model": "veo-3.1-generate-preview",
  "seconds": 8
}
```

### Advanced Video Generation

Veo models also support image-to-video and frame interpolation.

- <strong>Image-to-Video</strong>: Provide a `prompt` and a source `image` to animate a static picture.
- <strong>Frame Interpolation</strong>: Provide a `prompt`, a starting `image`, and an ending `lastFrame` to generate a smooth transition between them.

**Image-to-Video**

```typescript
const result = await videoModel.invoke({
  prompt: "Animate this image with gentle movement, clouds drifting slowly",
  image: {
    type: "url",
    url: "https://example.com/input-image.png",
  },
  seconds: "8",
});
```

### Video Model Parameters

- **prompt** `string` *(required)* — A text description of the desired video content.
- **model** `string` — The Veo model to use. Defaults to 'veo-3.1-generate-preview'.
- **aspectRatio** `string` — Video aspect ratio, either '16:9' (default) or '9:16'.
- **size** `string` — Video resolution, either '720p' (default) or '1080p'.
- **seconds** `string` — Video duration in seconds: '4', '6', or '8' (default).
- **image** `object` — A reference image for image-to-video or the first frame for interpolation.
- **lastFrame** `object` — The last frame for frame interpolation.
- **referenceImages** `array` — Additional reference images for video generation (Veo 3.1 only).
- **negativePrompt** `string` — A description of what to avoid in the video.

## Further Reading

For complete API details, refer to the official documentation.

- [AIGNE Framework Documentation](https://aigne.io/docs)
- [Google GenAI API Reference](https://googleapis.github.io/js-genai/release_docs/)

---

## Ideogram

URL: https://www.arcblock.io/en/docs/aigne-framework/models-ideogram-9dc03e/

This document provides a comprehensive guide for developers on integrating and utilizing Ideogram's image generation capabilities within the AIGNE Framework. The `@aigne/ideogram` package provides a seamless interface to Ideogram's API, enabling the generation of high-quality images from textual prompts.

This guide will cover the necessary steps for installation, configuration, and usage, complete with code examples and detailed parameter descriptions. For information on other models, refer to the [Models Overview](/en/docs/aigne-framework/models-overview-9dc03e/).

## Installation

To begin, install the `@aigne/ideogram` package into your project. You can use your preferred package manager.

**npm**

```bash
npm install @aigne/ideogram
```

**yarn**

```bash
yarn add @aigne/ideogram
```

**pnpm**

```bash
pnpm add @aigne/ideogram
```

## Configuration

Proper configuration is essential for connecting to the Ideogram API. This involves setting up your API key and instantiating the `IdeogramImageModel`.

### API Key Setup

The model requires an Ideogram API key for authentication. The recommended and most secure method is to set an environment variable.

**.env**

```bash
export IDEOGRAM_API_KEY="your-ideogram-api-key"
```

Alternatively, you can pass the `apiKey` directly during the model's instantiation, though this is less secure for production environments.

### Model Instantiation

Once the API key is configured, you can import and create an instance of `IdeogramImageModel`.

**Instantiating the Model**

```typescript
import { IdeogramImageModel } from "@aigne/ideogram";

// The API key will be automatically detected from environment variables.
const model = new IdeogramImageModel();

// Alternatively, provide the API key directly.
const modelWithApiKey = new IdeogramImageModel({
  apiKey: "your-ideogram-api-key",
});
```

## Basic Usage

To generate an image, use the `invoke` method. This method takes an object containing the prompt and any other desired parameters. The only required parameter is `prompt`.

**Generating an Image**

```typescript
import { IdeogramImageModel } from "@aigne/ideogram";

const model = new IdeogramImageModel();

async function generateImage() {
  try {
    const result = await model.invoke({
      model: "ideogram-v3",
      prompt: "A serene mountain landscape at sunset with golden light",
    });

    console.log(JSON.stringify(result, null, 2));
  } catch (error) {
    console.error("Error generating image:", error);
  }
}

generateImage();
```

### Response Object

The `invoke` method returns a promise that resolves to an object containing the generated images and usage metadata.

**Example Response**

```json
{
  "images": [
    {
      "type": "url",
      "url": "https://api.ideogram.ai/generation/...",
      "mimeType": "image/png"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0
  },
  "model": "ideogram-v3"
}
```

## Input Parameters

The `invoke` method accepts several parameters to customize the image generation process.

- **prompt** `string` *(required)* — The text description of the image you want to generate.
- **model** `string` (default: `ideogram-v3`) — Currently, only ideogram-v3 is supported.
- **n** `number` (default: `1`) — The number of images to generate. The valid range is from 1 to 8.
- **seed** `number` — A random seed for reproducible image generation. Must be an integer between 0 and 2147483647.
- **resolution** `string` — The resolution of the generated image (e.g., "1024x1024", "1792x1024"). Refer to the official Ideogram API documentation for all supported resolutions.
- **aspectRatio** `string` — The aspect ratio for the image (e.g., "1x1", "16x9").
- **renderingSpeed** `string` (default: `DEFAULT`) — Controls the generation speed and quality. Accepted values are "TURBO", "DEFAULT", or "QUALITY".
- **magicPrompt** `string` (default: `AUTO`) — Enables or disables MagicPrompt for prompt enhancement. Accepted values are "AUTO", "ON", or "OFF".
- **negativePrompt** `string` — A description of elements to exclude from the generated image.
- **styleType** `string` (default: `AUTO`) — Specifies the artistic style. Accepted values are "AUTO", "GENERAL", "REALISTIC", "DESIGN", or "FICTION".
- **colorPalette** `object` — An object defining a specific color palette for the generation.
- **styleCodes** `string[]` — A list of 8-character hexadecimal codes that represent specific styles.

## Advanced Usage

For more control over the output, you can combine multiple optional parameters in a single `invoke` call.

**Advanced Image Generation**

```typescript
import { IdeogramImageModel } from "@aigne/ideogram";

const model = new IdeogramImageModel();

async function generateAdvancedImage() {
  try {
    const result = await model.invoke({
      prompt: "A futuristic cityscape with neon lights and flying cars",
      model: "ideogram-v3",
      n: 4,
      resolution: "1792x1024",
      renderingSpeed: "TURBO",
      styleType: "FICTION",
      negativePrompt: "blurry, low quality, distorted",
      seed: 12345,
    });

    console.log(`Generated ${result.images.length} images.`);
    result.images.forEach((image, index) => {
      console.log(`Image ${index + 1}: ${image.url}`);
    });
  } catch (error) {
    console.error("Error generating image:", error);
  }
}

generateAdvancedImage();
```

## Default Model Options

You can set default parameters during the model's instantiation using the `modelOptions` property. These options will be applied to every `invoke` call unless overridden by parameters in the call itself.

**Setting Default Options**

```typescript
import { IdeogramImageModel } from "@aigne/ideogram";

const model = new IdeogramImageModel({
  modelOptions: {
    styleType: "REALISTIC",
    renderingSpeed: "QUALITY",
    magicPrompt: "ON",
  },
});

async function generateWithDefaults() {
  // This call will use the default options defined above.
  const result = await model.invoke({
    prompt: "A photorealistic portrait of an astronaut on Mars",
  });

  console.log(result);
}

generateWithDefaults();
```

## Summary

The `@aigne/ideogram` package offers a direct and efficient way to integrate Ideogram's image generation into your applications. By following the configuration steps and utilizing the provided parameters, you can generate high-quality images tailored to your specific needs.

For a complete and detailed list of all parameters, supported values, and advanced features, please refer to the official [Ideogram API Reference](https://developer.ideogram.ai/api-reference/api-reference/generate-v3).

---

## LMStudio

URL: https://www.arcblock.io/en/docs/aigne-framework/models-lmstudio-9dc03e/

The `@aigne/lmstudio` package provides a model adapter for integrating AIGNE with large language models (LLMs) hosted locally via [LM Studio](https://lmstudio.ai/). This allows developers to leverage the power of local models within the AIGNE framework, offering greater privacy, control, and cost-effectiveness.

This guide covers the necessary setup for LM Studio and demonstrates how to use the `LMStudioChatModel` to interact with your local models. For information on other local model providers, see the [Ollama](/en/docs/aigne-framework/models-ollama-9dc03e/) documentation.

## Prerequisites

Before using this package, you must complete the following steps:

::::steps
:::step{title="Install LM Studio"}
Download and install the LM Studio application from the official website: [https://lmstudio.ai/](https://lmstudio.ai/).
:::

:::step{title="Download a Model"}
Use the LM Studio interface to search for and download a model. Popular choices include variants of Llama 3.2, Mistral, and Phi-3.
:::

:::step{title="Start the Local Server"}
Navigate to the "Local Server" tab (server icon) in LM Studio, select your downloaded model from the dropdown, and click "Start Server". This will expose an OpenAI-compatible API endpoint, typically at `http://localhost:1234/v1`.
:::
::::

## Installation

To add the LMStudio package to your project, run one of the following commands in your terminal:

```bash
npm install @aigne/lmstudio
```

```bash
pnpm add @aigne/lmstudio
```

```bash
yarn add @aigne/lmstudio
```

## Quick Start

Once the LM Studio server is running, you can interact with your local model using the `LMStudioChatModel`. The following example demonstrates how to instantiate the model and send a simple request.

**Quick Start**

```typescript
import { LMStudioChatModel } from "@aigne/lmstudio";

// 1. Instantiate the model
// Ensure the model name matches the one loaded in LM Studio.
const model = new LMStudioChatModel({
  model: "llama-3.2-3b-instruct",
});

// 2. Invoke the model
async function main() {
  try {
    const response = await model.invoke({
      messages: [
        { role: "user", content: "What is the capital of France?" }
      ],
    });

    console.log(response.text);
  } catch (error) {
    console.error("Error invoking model:", error);
  }
}

main();
```

If the request is successful, the output will be:

```text
The capital of France is Paris.
```

## Configuration

The `LMStudioChatModel` can be configured through its constructor or with environment variables.

### Constructor Options

The `LMStudioChatModel` extends the standard `OpenAIChatModel` and accepts the following options:

- **model** `string` — The name of the model to use, which must match the model file loaded in the LM Studio server. Defaults to llama-3.2-3b-instruct.
- **baseURL** `string` — The base URL of the LM Studio server. Defaults to http://localhost:1234/v1.
- **apiKey** `string` — An API key, if you have configured authentication on your LM Studio server. By default, LM Studio runs without authentication, and the key is set to a placeholder value of not-required.
- **modelOptions** `object` — Additional options to control model generation.
  - **temperature** `number` — Controls randomness. Lower values (e.g., 0.2) make the output more deterministic. Defaults to 0.7.
  - **maxTokens** `number` — The maximum number of tokens to generate in the response.
  - **topP** `number` — Nucleus sampling parameter.
  - **frequencyPenalty** `number` — Penalizes new tokens based on their existing frequency.
  - **presencePenalty** `number` — Penalizes new tokens based on whether they appear in the text so far.

Here is an example with custom configuration:

**Configuration Example**

```typescript
import { LMStudioChatModel } from "@aigne/lmstudio";

const model = new LMStudioChatModel({
  baseURL: "http://localhost:1234/v1",
  model: "Mistral-7B-Instruct-v0.2-GGUF",
  modelOptions: {
    temperature: 0.8,
    maxTokens: 4096,
  },
});
```

### Environment Variables

You can also configure the model by setting environment variables. The constructor options will take precedence if both are provided.

- `LM_STUDIO_BASE_URL`: Sets the server's base URL. Defaults to `http://localhost:1234/v1`.
- `LM_STUDIO_API_KEY`: Sets the API key. Only necessary if your server requires authentication.

**.env**

```bash
LM_STUDIO_BASE_URL=http://localhost:1234/v1
# LM_STUDIO_API_KEY=your-key-if-needed
```

## Features

The `LMStudioChatModel` supports several advanced features, including streaming, tool calling, and structured outputs.

### Streaming

For real-time applications, you can stream the response as it's being generated. Set the `streaming: true` option in the `invoke` method.

**Streaming Example**

```typescript
import { LMStudioChatModel } from "@aigne/lmstudio";

const model = new LMStudioChatModel({
  model: "llama-3.2-3b-instruct",
});

async function streamStory() {
  const stream = await model.invoke(
    {
      messages: [{ role: "user", content: "Tell me a short story about a robot who discovers music." }],
    },
    { streaming: true }
  );

  for await (const chunk of stream) {
    if (chunk.type === "delta" && chunk.delta.text) {
      process.stdout.write(chunk.delta.text.text);
    }
  }
}

streamStory();
```

### Tool Calling

Many local models support OpenAI-compatible tool calling (also known as function calling). You can provide a list of tools to the model, and it will generate the arguments required to call them.

**Tool Calling Example**

```typescript
import { LMStudioChatModel } from "@aigne/lmstudio";

const model = new LMStudioChatModel({
  model: "llama-3.2-3b-instruct",
});

const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_weather",
      description: "Get the current weather for a specified location.",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g., San Francisco, CA",
          },
        },
        required: ["location"],
      },
    },
  },
];

async function checkWeather() {
  const response = await model.invoke({
    messages: [
      { role: "user", content: "What's the weather like in New York?" }
    ],
    tools,
  });

  if (response.toolCalls?.length) {
    console.log("Tool calls:", JSON.stringify(response.toolCalls, null, 2));
  }
}

checkWeather();
```

### Structured Output

To ensure the model's output conforms to a specific JSON schema, you can define a `responseFormat`. This is useful for tasks that require reliable, machine-readable data.

**Structured Output Example**

```typescript
import { LMStudioChatModel } from "@aigne/lmstudio";

const model = new LMStudioChatModel({
  model: "llama-3.2-3b-instruct",
});

const responseFormat = {
  type: "json_schema" as const,
  json_schema: {
    name: "weather_response",
    schema: {
      type: "object",
      properties: {
        location: { type: "string" },
        temperature: { type: "number" },
        description: { type: "string" },
      },
      required: ["location", "temperature", "description"],
    },
  },
};

async function getWeatherAsJson() {
  const response = await model.invoke({
    messages: [
      { role: "user", content: "What is the weather in Paris? Respond in the requested JSON format." }
    ],
    responseFormat,
  });

  console.log(response.json);
}

getWeatherAsJson();
```

## Supported Models

LM Studio supports a wide variety of GGUF-format models. The exact model name must match what is shown in the LM Studio user interface. Popular compatible models include:

| Model Family  | Variants  |
|---|---|
| <strong>Llama 3.2</strong>  | 3B, 8B, 70B Instruct  |
| <strong>Llama 3.1</strong>  | 8B, 70B, 405B Instruct  |
| <strong>Mistral</strong>  | 7B, 8x7B Instruct  |
| <strong>Phi-3</strong>  | Mini, Small, Medium Instruct  |
| <strong>CodeLlama</strong>  | 7B, 13B, 34B Instruct  |
| <strong>Qwen</strong>  | Various sizes  |

## Troubleshooting

If you encounter issues, consult the following list of common problems and solutions.

| Issue  | Solution  |
|---|---|
| <strong>Connection Refused</strong>  | Verify that the LM Studio local server is running and that the `baseURL` in your code is correct.  |
| <strong>Model Not Found</strong>  | Ensure the `model` name in your code exactly matches the model file name loaded in the LM Studio server.  |
| <strong>Slow Responses</strong>  | If available, enable GPU acceleration in LM Studio's server settings. Using a smaller model can also help.  |
| <strong>Out of Memory</strong>  | The model may require more RAM than your system has available. Try using a smaller model or reducing the context length.  |

### Error Handling

It is good practice to wrap your model calls in a `try...catch` block to handle potential runtime errors, such as network issues.

**Error Handling Example**

```typescript
import { LMStudioChatModel } from "@aigne/lmstudio";

const model = new LMStudioChatModel();

async function safeInvoke() {
  try {
    const response = await model.invoke({
      messages: [{ role: "user", content: "Hello!" }],
    });
    console.log(response.text);
  } catch (error) {
    if (error.code === "ECONNREFUSED") {
      console.error("Connection failed. Please ensure the LM Studio server is running.");
    } else {
      console.error("An unexpected error occurred:", error.message);
    }
  }
}

safeInvoke();
```

For more detailed information, refer to the official [LM Studio Documentation](https://lmstudio.ai/docs). To explore other model integrations, you can proceed to the documentation for [AIGNE Hub](/en/docs/aigne-framework/models-aigne-hub-9dc03e/).

---

## Ollama

URL: https://www.arcblock.io/en/docs/aigne-framework/models-ollama-9dc03e/

The `@aigne/ollama` package provides a seamless integration between the AIGNE Framework and AI models hosted locally via [Ollama](https://ollama.ai/). This allows developers to leverage a wide variety of open-source language models running on their own hardware, ensuring privacy and offline access to AI capabilities.

This guide covers the necessary steps to configure and use the `OllamaChatModel` in your AIGNE applications. For information on other model providers, please see the [Models Overview](/en/docs/aigne-framework/models-overview-9dc03e/).

![Ollama](https://media.arcblock.io/lib/be/be93853037935e0c.w1600.webp)

## Prerequisites

Before using this package, you must have Ollama installed and running on your local machine. You also need to have pulled at least one model. For detailed instructions, please refer to the [official Ollama website](https://ollama.ai/).

## Installation

To get started, install the necessary AIGNE packages using your preferred package manager.

::::card-group
::link-card{title="npm" description="```bash     npm install @aigne/ollama @aigne/core     ```" icon="package"}
::link-card{title="yarn" description="```bash     yarn add @aigne/ollama @aigne/core     ```" icon="package"}
::link-card{title="pnpm" description="```bash     pnpm add @aigne/ollama @aigne/core     ```" icon="package"}
::::

## Configuration

The `OllamaChatModel` class is the primary interface for interacting with Ollama. When instantiating the model, you can provide several configuration options to customize its behavior.

**OllamaChatModel Instantiation**

```typescript
import { OllamaChatModel } from "@aigne/ollama";

const model = new OllamaChatModel({
  // Specify the Ollama model to use
  model: "llama3",

  // The base URL of your local Ollama instance
  baseURL: "http://localhost:11434/v1",

  // Optional parameters to pass to the model
  modelOptions: {
    temperature: 0.7,
  },
});
```

The constructor accepts the following parameters:

- **model** `string` (default: `llama3.2`) — The name of the model to use (e.g., llama3, mistral). Ensure the model has been pulled in your Ollama instance.
- **baseURL** `string` (default: `http://localhost:11434/v1`) — The base URL for the Ollama API. This can also be configured using the OLLAMA_BASE_URL environment variable.
- **apiKey** `string` (default: `ollama`) — A placeholder API key. Ollama does not require authentication by default, but the AIGNE framework requires a non-empty key. It defaults to "ollama" and can be set with the OLLAMA_API_KEY environment variable.
- **modelOptions** `object` — An object containing additional parameters to pass to the Ollama API, such as temperature, top_p, etc. These options allow for fine-tuning the model's response generation.

## Basic Usage

To run the model, use the `invoke` method. Pass a message payload to generate a chat completion.

**Basic Invocation**

```typescript
import { OllamaChatModel } from "@aigne/ollama";

const model = new OllamaChatModel({
  model: "llama3",
  modelOptions: {
    temperature: 0.8,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Explain the importance of local AI models." }],
});

console.log(result.text);
```

The `invoke` method returns a promise that resolves to an object containing the model's response.

<strong>Example Response</strong>

```json
{
  "text": "Local AI models are crucial for several reasons. Firstly, they offer enhanced privacy and security since data is processed on-device and never leaves the user's machine...",
  "model": "llama3"
}
```

## Streaming Responses

For applications requiring real-time interaction, you can stream the model's response. Set the `streaming` option to `true` in the `invoke` method. The method will return an async iterator that yields response chunks as they become available.

**Streaming Example**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { OllamaChatModel } from "@aigne/ollama";

const model = new OllamaChatModel({
  model: "llama3",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Tell me a short story about a robot." }],
  },
  { streaming: true },
);

let fullText = "";
process.stdout.write("Response: ");

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text);
    }
  }
}

console.log("\n\n--- End of Stream ---");
console.log("Full text:", fullText);
```

This example demonstrates how to process a stream. Each chunk is a delta of the full response. You can accumulate the text from each chunk to reconstruct the complete message.

## Summary

The `@aigne/ollama` package offers a robust and straightforward way to integrate local, open-source models into your AIGNE applications. By following the steps in this guide, you can set up the `OllamaChatModel`, configure it for your needs, and leverage both standard and streaming completions.

For further reading on other available models, please see the following guides:

- [OpenAI](/en/docs/aigne-framework/models-openai-9dc03e/)
- [Google Gemini](/en/docs/aigne-framework/models-gemini-9dc03e/)
- [Anthropic](/en/docs/aigne-framework/models-anthropic-9dc03e/)

---

## OpenRouter

URL: https://www.arcblock.io/en/docs/aigne-framework/models-open-router-9dc03e/

OpenRouter serves as a unified gateway to a diverse range of AI models from various providers, including OpenAI, Anthropic, and Google. The `@aigne/open-router` package provides a standardized interface for integrating these models into the AIGNE Framework. This allows developers to switch between different models with minimal code changes and implement robust fallback mechanisms.

This guide details the process of installing, configuring, and utilizing the `@aigne/open-router` package to leverage multiple AI models.

![OpenRouter](https://media.arcblock.io/lib/52/522f20e263f0943f.w1600.webp)

## Installation

To begin, install the `@aigne/open-router` and `@aigne/core` packages. The following commands demonstrate installation using npm, yarn, and pnpm.

**npm**

```bash
npm install @aigne/open-router @aigne/core
```

**yarn**

```bash
yarn add @aigne/open-router @aigne/core
```

**pnpm**

```bash
pnpm add @aigne/open-router @aigne/core
```

## Configuration and Usage

The `OpenRouterChatModel` class is the primary interface for interacting with the OpenRouter API. To use it, you must provide your OpenRouter API key. This can be done directly in the constructor via the `apiKey` option or by setting the `OPEN_ROUTER_API_KEY` environment variable.

### Basic Example

Below is a standard implementation of the `OpenRouterChatModel` to send a chat request. This example uses Anthropic's `claude-3-opus` model.

**Basic Usage**

```typescript
import { OpenRouterChatModel } from "@aigne/open-router";

const model = new OpenRouterChatModel({
  // Provide API key directly or use environment variable OPEN_ROUTER_API_KEY
  apiKey: "your-api-key", // Optional if set in env variables
  // Specify model (defaults to 'openai/gpt-4o')
  model: "anthropic/claude-3-opus",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Which model are you using?" }],
});

console.log(result);
```

The expected output will contain the text response, the model identifier, and token usage metrics.

**Output**

```json
{
  "text": "I am currently using the anthropic/claude-3-opus model, accessed through OpenRouter.",
  "model": "anthropic/claude-3-opus",
  "usage": {
    "inputTokens": 15,
    "outputTokens": 23
  }
}
```

### Constructor Options

The `OpenRouterChatModel` is extended from the `@aigne/openai` package's `OpenAIChatModel` and accepts the same constructor options.

- **apiKey** `string` — Your OpenRouter API key. If not provided, the client will check for the OPEN_ROUTER_API_KEY environment variable.
- **model** `string` (default: `openai/gpt-4o`) — The identifier for the model you wish to use (e.g., anthropic/claude-3-opus).
- **fallbackModels** `string[]` — An array of model identifiers to use as fallbacks in case the primary model fails.
- **baseURL** `string` (default: `https://openrouter.ai/api/v1`) — The base URL for the OpenRouter API. Can be overridden for testing or proxies.
- **modelOptions** `object` — An object containing parameters to pass to the model provider, such as temperature, max_tokens, or top_p.

## Using Multiple Models with Fallbacks

A key feature of the `@aigne/open-router` package is the ability to specify fallback models. If the primary model request fails, the system will automatically retry the request with the next model in the `fallbackModels` list. This ensures greater application reliability.

**Model Fallbacks**

```typescript
import { OpenRouterChatModel } from "@aigne/open-router";

const modelWithFallbacks = new OpenRouterChatModel({
  apiKey: "your-api-key",
  model: "openai/gpt-4o",
  fallbackModels: ["anthropic/claude-3-opus", "google/gemini-1.5-pro"], // Fallback order
  modelOptions: {
    temperature: 0.7,
  },
});

// Will try gpt-4o first, then claude-3-opus if that fails, then gemini-1.5-pro
const fallbackResult = await modelWithFallbacks.invoke({
  messages: [{ role: "user", content: "Which model are you using?" }],
});

console.log(fallbackResult);
```

## Streaming Responses

For applications requiring real-time interaction, you can enable streaming to process response chunks as they become available. Set the `streaming: true` option in the `invoke` method.

The response stream must be iterated over to assemble the complete message.

**Streaming Example**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { OpenRouterChatModel } from "@aigne/open-router";

const model = new OpenRouterChatModel({
  apiKey: "your-api-key",
  model: "anthropic/claude-3-opus",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Which model are you using?" }],
  },
  { streaming: true },
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) fullText += text;
    if (chunk.delta.json) Object.assign(json, chunk.delta.json);
  }
}

console.log(fullText);
console.log(json);
```

The final `fullText` and `json` objects will contain the aggregated response data.

**Output**

```text
I am currently using the anthropic/claude-3-opus model, accessed through OpenRouter.
{ model: 'anthropic/claude-3-opus', usage: { inputTokens: 15, outputTokens: 23 } }
```

## Summary

The `@aigne/open-router` package simplifies access to a wide array of language models through a unified and resilient interface. By leveraging features like model fallbacks and streaming, you can build more robust and responsive AI applications.

For more information on the fundamental concepts of models in the AIGNE Framework, refer to the [Models overview](/en/docs/aigne-framework/models-overview-9dc03e/).

---

## OpenAI

URL: https://www.arcblock.io/en/docs/aigne-framework/models-openai-9dc03e/

The `@aigne/openai` package provides a seamless integration with OpenAI's suite of models, allowing developers to leverage services like GPT for chat completions, DALL-E for image generation, and Sora for video creation directly within the AIGNE Framework. This document provides a comprehensive guide to installing, configuring, and using these models.

For a broader overview of available model providers, please see the [Models](/en/docs/aigne-framework/models-9dc03e/) section.

## Features

The OpenAI integration is designed to be robust and developer-friendly, offering a range of features:

- <strong>Comprehensive Model Support</strong>: Full integration with OpenAI's Chat, Image, and Video generation APIs.
- <strong>Official SDK</strong>: Built on top of the official OpenAI SDK for maximum reliability and compatibility.
- <strong>Advanced Capabilities</strong>: Includes support for function calling, streaming responses, and structured JSON outputs.
- <strong>Type-Safe</strong>: Provides complete TypeScript typings for all model configurations and API responses, ensuring code quality and autocompletion.
- <strong>Consistent Interface</strong>: Adheres to the AIGNE Framework's model interface for uniform implementation across different providers.
- <strong>Extensive Configuration</strong>: Offers detailed options for fine-tuning model behavior to meet specific application needs.

## Installation

To integrate OpenAI models into your project, install the `@aigne/openai` package alongside the `@aigne/core` framework. Use the command appropriate for your package manager:

**npm**

```bash
npm install @aigne/openai @aigne/core
```

**yarn**

```bash
yarn add @aigne/openai @aigne/core
```

**pnpm**

```bash
pnpm add @aigne/openai @aigne/core
```

## Chat Model (OpenAIChatModel)

The `OpenAIChatModel` class serves as the primary interface for interacting with OpenAI's text-based language models, such as GPT-4o and GPT-4o-mini.

### Configuration

When creating an instance of `OpenAIChatModel`, you must provide your OpenAI API key. This can be passed directly in the constructor or set as an environment variable named `OPENAI_API_KEY`.

- **apiKey** `string` — Your OpenAI API key. If omitted, the system will look for the OPENAI_API_KEY environment variable.
- **baseURL** `string` — An optional base URL for the OpenAI API, useful for connecting through a proxy or an alternative endpoint.
- **model** `string` (default: `gpt-4o-mini`) — The identifier of the model to be used for chat completions (e.g., "gpt-4o").
- **modelOptions** `object` — A set of parameters to control the generation process.
  - **temperature** `number` — Controls the randomness of the output. Lower values produce more deterministic results.
  - **topP** `number` — An alternative to temperature sampling, known as nucleus sampling.
  - **frequencyPenalty** `number` — Reduces the likelihood of repeating tokens.
  - **presencePenalty** `number` — Reduces the likelihood of repeating topics.
  - **parallelToolCalls** `boolean` (default: `true`) — Enables the model to execute multiple function calls concurrently.
  - **reasoningEffort** `string | number` — For reasoning models (o1/o3), sets the reasoning effort ('minimal', 'low', 'medium', 'high', or a token count).
- **clientOptions** `object` — Additional options passed directly to the underlying OpenAI SDK client for advanced customization.

### Basic Usage

The following example shows how to instantiate `OpenAIChatModel` and use the `invoke` method to get a response.

**Basic Chat Completion**

```typescript
import { OpenAIChatModel } from "@aigne/openai";

const model = new OpenAIChatModel({
  // Using an environment variable for the API key is recommended.
  apiKey: "your-api-key",
  model: "gpt-4o",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Hello, who are you?" }],
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "text": "Hello! How can I assist you today?",
  "model": "gpt-4o",
  "usage": {
    "inputTokens": 10,
    "outputTokens": 9
  }
}
```

### Streaming Responses

For real-time applications, you can enable streaming by passing `{ streaming: true }` to the `invoke` method. This returns an async iterator that yields response chunks as they are generated.

**Streaming Chat Response**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/openai";

const model = new OpenAIChatModel({
  apiKey: "your-api-key",
  model: "gpt-4o",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Hello, who are you?" }],
  },
  { streaming: true },
);

let fullText = "";
for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text);
    }
  }
}

console.log("\n--- Response Complete ---");
```

## Image Model (OpenAIImageModel)

The `OpenAIImageModel` class provides an interface for OpenAI's image generation and editing models, such as DALL-E 2, DALL-E 3, and gpt-image-1.

### Configuration

The image model is configured similarly to the chat model, requiring an API key and allowing for model-specific options.

- **apiKey** `string` — Your OpenAI API key. Defaults to the OPENAI_API_KEY environment variable if not provided.
- **baseURL** `string` — An optional base URL for the OpenAI API.
- **model** `string` (default: `dall-e-2`) — The image model to use (e.g., "dall-e-3", "gpt-image-1").
- **modelOptions** `object` — Parameters to control the image generation process. Available options vary by model.
  - **size** `string` — The dimensions of the generated image (e.g., '1024x1024').
  - **quality** `string` — Image quality, either 'standard' or 'hd' (DALL-E 3 only).
  - **style** `string` — The artistic style, either 'vivid' or 'natural' (DALL-E 3 only).
  - **n** `number` — The number of images to generate.
- **clientOptions** `object` — Advanced options passed directly to the underlying OpenAI SDK client.

### Image Generation

To generate an image, create an instance of `OpenAIImageModel` and invoke it with a text prompt.

**Image Generation**

```typescript
import { OpenAIImageModel } from "@aigne/openai";

const imageModel = new OpenAIImageModel({
  apiKey: "your-api-key",
  model: "dall-e-3",
  modelOptions: {
    size: "1024x1024",
    quality: "standard",
    style: "vivid",
  },
});

const result = await imageModel.invoke({
  prompt: "A futuristic city at sunset with flying cars",
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "images": [
    {
      "type": "url",
      "url": "https://...",
      "mimeType": "image/png"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0
  },
  "model": "dall-e-3"
}
```

### Image Editing

Image editing is supported by specific models like `gpt-image-1`. To edit an image, provide both a prompt and a reference image.

**Image Editing**

```typescript
import { OpenAIImageModel } from "@aigne/openai";

const imageModel = new OpenAIImageModel({
  apiKey: "your-api-key",
  model: "gpt-image-1",
});

const result = await imageModel.invoke({
  prompt: "Add a rainbow to the sky",
  image: [
    {
      type: "url",
      url: "https://example.com/original-image.png",
    },
  ],
});

console.log(result.images); // Array of edited images
```

## Video Model (OpenAIVideoModel)

The `OpenAIVideoModel` class enables video generation using OpenAI's Sora models.

### Configuration

The video model requires an API key and allows for specifying the model, resolution, and duration.

- **apiKey** `string` — Your OpenAI API key. Defaults to the OPENAI_API_KEY environment variable if not provided.
- **model** `string` (default: `sora-2`) — The video model to use, either "sora-2" (standard) or "sora-2-pro" (higher quality).
- **modelOptions** `object` — Parameters to control the video generation process.
  - **size** `string` (default: `1280x720`) — Video resolution (e.g., '1280x720' for horizontal, '720x1280' for vertical).
  - **seconds** `string` (default: `4`) — Video duration in seconds. Accepted values are '4', '8', or '12'.

### Video Generation

The following example demonstrates how to generate a short video from a text prompt.

**Video Generation**

```typescript
import { OpenAIVideoModel } from "@aigne/openai";

const videoModel = new OpenAIVideoModel({
  apiKey: "your-api-key",
  model: "sora-2",
  modelOptions: {
    size: "1280x720",
    seconds: "4",
  },
});

const result = await videoModel.invoke({
  prompt: "A serene lake with mountains in the background, gentle waves rippling",
});

console.log(result);
```

<strong>Example Response</strong>

```json
{
  "videos": [
    {
      "type": "file",
      "data": "base64-encoded-video-data...",
      "mimeType": "video/mp4",
      "filename": "video-id.mp4"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0
  },
  "model": "sora-2",
  "seconds": 4
}
```

### Image-to-Video Generation

You can also generate a video by animating a still image.

**Image-to-Video**

```typescript
import { OpenAIVideoModel } from "@aigne/openai";

const videoModel = new OpenAIVideoModel({
  apiKey: "your-api-key",
  model: "sora-2",
});

const result = await videoModel.invoke({
  prompt: "Animate this image with gentle movement",
  image: {
    type: "url",
    url: "https://example.com/input-image.png",
  },
  size: "1280x720",
  seconds: "8",
});

console.log(result.videos);
```

## Summary

This guide has covered the essentials for integrating OpenAI's chat, image, and video models into your AIGNE applications. By using the `@aigne/openai` package, you can easily harness the power of these advanced AI capabilities.

For further details, refer to the official [OpenAI API documentation](https://platform.openai.com/docs/api-reference). To explore other supported model providers, please visit the [Models Overview](/en/docs/aigne-framework/models-overview-9dc03e/).

---

## Overview

URL: https://www.arcblock.io/en/docs/aigne-framework/models-overview-9dc03e/

The AIGNE Framework is designed to be model-agnostic, allowing developers to integrate a wide variety of large language models (LLMs) and image generation models from different providers. This is achieved through a standardized adapter system that abstracts the unique APIs of each provider behind a consistent interface.

At the core of this system are the `ChatModel` and `ImageModel` agents. These specialized agents act as a bridge between your application's logic and the external AI services. By using these standardized agents, you can switch between model providers with minimal code changes, often only requiring a change in configuration. Each supported provider has a dedicated package (e.g., `@aigne/openai`, `@aigne/anthropic`) that contains the specific implementation for communicating with its API.

This section provides a summary of all officially supported model providers. For detailed instructions on how to install, configure, and use a specific provider, please refer to its dedicated documentation page.

The following diagram illustrates the architecture of the AIGNE Framework's model abstraction layer:

![Overview](https://media.arcblock.io/lib/25/25e13feac1772cc5.w1600.webp)

## Supported Chat Models

The following table lists the chat model providers that are officially supported by the AIGNE Framework. Select a provider to view its detailed integration guide.

| Provider  | Package  |
|---|---|
| [AIGNE Hub](/en/docs/aigne-framework/models-aigne-hub-9dc03e/)  | `@aigne/aigne-hub`  |
| [Anthropic](/en/docs/aigne-framework/models-anthropic-9dc03e/)  | `@aigne/anthropic`  |
| [AWS Bedrock](/en/docs/aigne-framework/models-bedrock-9dc03e/)  | `@aigne/bedrock`  |
| [DeepSeek](/en/docs/aigne-framework/models-deepseek-9dc03e/)  | `@aigne/deepseek`  |
| [Doubao](/en/docs/aigne-framework/models-doubao-9dc03e/)  | `@aigne/doubao`  |
| [Google Gemini](/en/docs/aigne-framework/models-gemini-9dc03e/)  | `@aigne/gemini`  |
| [LMStudio](/en/docs/aigne-framework/models-lmstudio-9dc03e/)  | `@aigne/lmstudio`  |
| [Ollama](/en/docs/aigne-framework/models-ollama-9dc03e/)  | `@aigne/ollama`  |
| [OpenAI](/en/docs/aigne-framework/models-openai-9dc03e/)  | `@aigne/openai`  |
| [OpenRouter](/en/docs/aigne-framework/models-open-router-9dc03e/)  | `@aigne/open-router`  |
| [Poe](/en/docs/aigne-framework/models-poe-9dc03e/)  | `@aigne/poe`  |
| [xAI](/en/docs/aigne-framework/models-xai-9dc03e/)  | `@aigne/xai`  |

## Supported Image Models

The following table lists the image generation model providers that are officially supported. Select a provider to view its detailed integration guide.

| Provider  | Package  |
|---|---|
| [AIGNE Hub](/en/docs/aigne-framework/models-aigne-hub-9dc03e/)  | `@aigne/aigne-hub`  |
| [Doubao](/en/docs/aigne-framework/models-doubao-9dc03e/)  | `@aigne/doubao`  |
| [Google Gemini](/en/docs/aigne-framework/models-gemini-9dc03e/)  | `@aigne/gemini`  |
| [Ideogram](/en/docs/aigne-framework/models-ideogram-9dc03e/)  | `@aigne/ideogram`  |
| [OpenAI](/en/docs/aigne-framework/models-openai-9dc03e/)  | `@aigne/openai`  |

---

## Poe

URL: https://www.arcblock.io/en/docs/aigne-framework/models-poe-9dc03e/

The `@aigne/poe` package provides a standardized interface for integrating with [Poe](https://poe.com/), a service that offers access to a wide range of third-party language models, including those from OpenAI, Anthropic, and Google. By leveraging an OpenAI-compatible API endpoint, this package allows you to seamlessly use various models within the AIGNE Framework.

This guide provides a step-by-step process for installing, configuring, and utilizing the `PoeChatModel`. For more general information on model integration, refer to the [Models Overview](/en/docs/aigne-framework/models-overview-9dc03e/) documentation.

The following diagram illustrates the data flow from a developer's application through the AIGNE Framework to the Poe service and the underlying language models.

![Poe](https://media.arcblock.io/lib/85/85c0c0191cee3a20.w1600.webp)

## Installation

To begin, install the necessary packages using your preferred package manager. You will need both `@aigne/core` and the Poe-specific package.

```bash
npm install @aigne/poe @aigne/core
```

```bash
yarn add @aigne/poe @aigne/core
```

```bash
pnpm add @aigne/poe @aigne/core
```

## Configuration

The `PoeChatModel` class is the primary interface for interacting with the Poe API. To instantiate it, you must provide your Poe API key and specify the desired model.

Your API key can be set in two ways:

1. Directly in the constructor via the `apiKey` property.
2. As an environment variable named `POE_API_KEY`.

- **apiKey** `string` — Your Poe API key. While this is optional in the constructor, the key must be available either here or in the POE_API_KEY environment variable for authentication to succeed.
- **model** `string` (default: `gpt-5-mini`) — The identifier for the model you wish to use. Poe provides access to models like claude-3-opus, gpt-4o, etc. If not specified, it defaults to gpt-5-mini.
- **modelOptions** `object` — Additional options to pass to the model API, such as temperature, topP, or maxTokens. These parameters are sent directly to the underlying model provider.
- **baseURL** `string` (default: `https://api.poe.com/v1`) — The base URL for the Poe API. This should not be changed unless you are using a custom proxy.

## Usage

The following examples demonstrate how to create a `PoeChatModel` instance and use it for both standard and streaming chat completions.

### Standard Invocation

For simple request-response interactions, use the `invoke` method. This method sends the request and waits for the complete response from the model.

**Basic Usage**

```typescript
import { PoeChatModel } from "@aigne/poe";

const model = new PoeChatModel({
  // Provide API key directly or set the POE_API_KEY environment variable
  apiKey: "your-poe-api-key",
  // Specify the desired model available through Poe
  model: "claude-3-opus",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Which model are you using?" }],
});

console.log(result);
```

The `invoke` method returns a structured response containing the model's output and usage metadata.

**Expected Output**

```json
{
  "text": "I'm powered by Poe, using the Claude 3 Opus model from Anthropic.",
  "model": "claude-3-opus",
  "usage": {
    "inputTokens": 5,
    "outputTokens": 14
  }
}
```

### Streaming Responses

For real-time applications, you can stream the response as it's generated. Set the `streaming: true` option in the `invoke` call to receive an asynchronous stream of response chunks.

**Streaming Example**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { PoeChatModel } from "@aigne/poe";

const model = new PoeChatModel({
  apiKey: "your-poe-api-key",
  model: "claude-3-opus",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Which model are you using?" }],
  },
  { streaming: true },
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text);
    }
    if (chunk.delta.json) {
      Object.assign(json, chunk.delta.json);
    }
  }
}

console.log("\n--- Final Assembled Data ---");
console.log("Full Text:", fullText);
console.log("Metadata:", json);
```

When iterating through the stream, each chunk provides a delta of the response. The complete text and metadata must be assembled from these individual chunks.

**Expected Output**

```text
I'm powered by Poe, using the Claude 3 Opus model from Anthropic.
--- Final Assembled Data ---
Full Text: I'm powered by Poe, using the Claude 3 Opus model from Anthropic.
Metadata: { model: "anthropic/claude-3-opus", usage: { inputTokens: 5, outputTokens: 14 } }
```

## Further Reading

- For a complete list of available models and their capabilities, please consult the official [Poe documentation](https://developer.poe.com/docs/server-bots-and-apis).
- To understand how models fit into the broader AIGNE architecture, see the [Core Concepts: Models](/en/docs/aigne-framework/developer-guide-core-concepts-models-9dc03e/) page.

---

## xAI

URL: https://www.arcblock.io/en/docs/aigne-framework/models-xai-9dc03e/

This guide provides instructions for configuring and using xAI's language models, specifically Grok, within the AIGNE Framework. It covers the installation of the necessary package, API key configuration, model instantiation, and examples of both standard and streaming invocations.

The `@aigne/xai` package serves as a direct interface to the xAI API, allowing developers to integrate Grok's capabilities into their applications through the standardized `ChatModel` interface provided by the AIGNE Framework.

The following diagram illustrates the interaction between the developer, the `@aigne/xai` package, and the xAI Platform.

![xAI](https://media.arcblock.io/lib/c9/c9fa8a1f15d4066e.w1600.webp)

## Installation

To begin, install the `@aigne/xai` package along with the AIGNE core library using your preferred package manager.

::::card-group
::link-card{title="npm" description="```bash     npm install @aigne/xai @aigne/core     ```" icon="package"}
::link-card{title="yarn" description="```bash     yarn add @aigne/xai @aigne/core     ```" icon="package"}
::link-card{title="pnpm" description="```bash     pnpm add @aigne/xai @aigne/core     ```" icon="package"}
::::

## Configuration

The `XAIChatModel` class is the primary interface for interacting with the xAI API. To use it, you must configure it with your xAI API key.

You can provide the API key in two ways:

::::steps
:::step{title="Directly in the constructor"}
Pass the key via the `apiKey` property.
:::

:::step{title="Environment variable"}
Set the `XAI_API_KEY` environment variable. The model will automatically detect and use it.
:::
::::

### Constructor Options

When creating an instance of `XAIChatModel`, you can provide the following options:

- **apiKey** `string` — Your xAI API key. If not provided, the system will fall back to the XAI_API_KEY environment variable.
- **model** `string` (default: `grok-2-latest`) — The specific xAI model to use for chat completions. Defaults to grok-2-latest.
- **baseURL** `string` (default: `https://api.x.ai/v1`) — The base URL for the xAI API. This is pre-configured and typically does not need to be changed.
- **modelOptions** `object` — Additional options to pass to the xAI API, such as temperature, topP, etc.

## Basic Usage

The following example demonstrates how to instantiate the `XAIChatModel` and invoke it to get a response.

**Basic Invocation**

```typescript
import { XAIChatModel } from "@aigne/xai";

const model = new XAIChatModel({
  // Provide API key directly or use environment variable XAI_API_KEY
  apiKey: "your-api-key", // Optional if set in env variables
  // Specify model (defaults to 'grok-2-latest')
  model: "grok-2-latest",
  modelOptions: {
    temperature: 0.8,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Tell me about yourself" }],
});

console.log(result);
```

### Example Response

The `invoke` method returns an object containing the model's response and usage metadata.

**Response Object**

```json
{
  "text": "I'm Grok, an AI assistant from X.AI. I'm here to assist with a touch of humor and wit!",
  "model": "grok-2-latest",
  "usage": {
    "inputTokens": 6,
    "outputTokens": 17
  }
}
```

## Streaming Responses

For real-time applications, you can stream the response from the model. Set the `streaming: true` option in the `invoke` method to receive data in chunks as it becomes available.

**Streaming Example**

```typescript
import { isAgentResponseDelta } from "@aigne/core";
import { XAIChatModel } from "@aigne/xai";

const model = new XAIChatModel({
  apiKey: "your-api-key",
  model: "grok-2-latest",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Tell me about yourself" }],
  },
  { streaming: true },
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) fullText += text;
    if (chunk.delta.json) Object.assign(json, chunk.delta.json);
  }
}

console.log(fullText);
console.log(json);
```

### Streaming Output

When iterating through the stream, you can accumulate the text delta to form the complete message and merge the JSON parts to get the final metadata.

**Text Output**

```text
I'm Grok, an AI assistant from X.AI. I'm here to assist with a touch of humor and wit!
```

**JSON Output**

```json
{
  "model": "grok-2-latest",
  "usage": {
    "inputTokens": 6,
    "outputTokens": 17
  }
}
```

This concludes the guide on using the `@aigne/xai` package. For more information on other available models, please see the [Models Overview](/en/docs/aigne-framework/models-overview-9dc03e/).

---

## Overview

URL: https://www.arcblock.io/en/docs/aigne-framework/overview-9dc03e/

The AIGNE Framework is a functional AI application development framework designed to simplify and accelerate the process of building scalable, agentic AI applications. It combines functional programming concepts, robust artificial intelligence capabilities, and a modular design to provide a structured environment for developers.

This document provides a high-level overview of the AIGNE Framework's architecture, core components, and key features. It also serves as a navigational guide, directing you to the appropriate documentation path based on your technical background and objectives.

## Core Architecture

The framework is architecturally designed around a central orchestrator, known as the `AIGNE`, which manages the lifecycle and interactions of various specialized components called `Agents`. Agents are the fundamental units of work, designed to perform specific tasks. They can be composed into teams to handle complex workflows.

The following diagram illustrates the relationship between these core components:

![Overview](https://media.arcblock.io/lib/25/25e13feac1772cc5.w1600.webp)

- <strong>AIGNE</strong>: The central execution engine responsible for managing the lifecycle of agents, orchestrating their interactions, and handling the overall execution flow. It is instantiated with a configuration that can include models, agents, and skills.
- <strong>Agents</strong>: The fundamental building blocks of the framework. An agent is an autonomous unit that performs a specific task. The framework provides several specialized agent types, including `AIAgent` for interacting with language models, `TeamAgent` for coordinating multiple agents, and `FunctionAgent` for executing custom code.
- <strong>Models</strong>: Abstractions that interface with external AI model providers like OpenAI, Anthropic, and Google. These are used by agents to leverage the power of large language models (LLMs) and image generation models.
- <strong>Skills</strong>: Reusable capabilities, often represented as functions or other agents, that can be attached to an agent to extend its functionality.

## Key Features

The AIGNE Framework is equipped with a comprehensive set of features to support the development of sophisticated AI applications.

::::card-group
::link-card{title="Modular Design" description="A clear modular structure allows developers to organize code effectively, improving development efficiency and simplifying maintenance." icon="box"}
::link-card{title="Multiple AI Model Support" description="Built-in support for a wide range of mainstream AI models, including those from OpenAI, Google, and Anthropic, with an extensible design to support additional models." icon="bot"}
::link-card{title="Flexible Workflow Patterns" description="Natively supports various workflow patterns such as sequential, concurrent, and routing to meet complex application requirements." icon="git-merge"}
::link-card{title="TypeScript Support" description="Provides comprehensive TypeScript type definitions, ensuring type safety and enhancing the overall developer experience." icon="file-text"}
::link-card{title="Code Execution" description="Supports the execution of dynamically generated code within a secure sandbox, enabling powerful automation capabilities." icon="terminal"}
::link-card{title="MCP Protocol Integration" description="Seamlessly integrates with external systems and services through the Model Context Protocol (MCP)." icon="zap"}
::::

## How to Use These Docs

To accommodate different needs, this documentation is divided into two primary paths. Please select the path that best aligns with your role and goals.

::::card-group
:::action-card{title="Developer Guide" description="For engineers and developers. This guide provides technical deep-dives, code-first examples, API references, and everything you need to build, test, and deploy agentic applications with the AIGNE Framework." icon="code"}
::action{label="Start Building" href="/en/docs/aigne-framework/developer-guide-getting-started-9dc03e/" variant="primary"}
:::
:::action-card{title="User Guide" description="For non-technical users, product managers, and business stakeholders. This guide explains the core concepts of AI agents and workflows in plain language, focusing on potential applications and business outcomes without technical jargon." icon="user"}
::action{label="Learn Concepts" href="/en/docs/aigne-framework/user-guide-9dc03e/" variant="primary"}
:::
::::

## Summary

This overview has introduced the AIGNE Framework, its core architecture, and its primary features. The framework is a comprehensive toolset for building modern, agent-based AI applications.

For your next step, we recommend the following:

- <strong>Developers</strong>: Proceed to the [Getting Started](/en/docs/aigne-framework/developer-guide-getting-started-9dc03e/) guide for a hands-on tutorial.
- <strong>Non-technical Users</strong>: Begin with [What is AIGNE?](/en/docs/aigne-framework/user-guide-what-is-aigne-9dc03e/) for a conceptual introduction.

---

## User Guide

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-9dc03e/

Welcome to the AIGNE User Guide. This guide is designed for a non-technical audience, including business leaders, managers, and anyone curious about how AI can be harnessed to automate complex tasks and streamline business processes. You don't need any programming knowledge to follow along.

Our goal is to explain the core concepts of AI agents and workflows in simple, easy-to-understand terms. You will learn what AI agents are, how they can work individually or as a team, and how they can be orchestrated to solve real-world problems, ultimately driving business outcomes.

This guide is structured to build your understanding from the ground up:

::::card-group
::link-card{title="What is AIGNE?" description="Start with the fundamentals. This section provides a plain-language introduction to the AIGNE Framework, explaining what AI agents are, the problems they solve, and how they can be used to automate complex tasks." icon="brain" href="/en/docs/aigne-framework/user-guide-what-is-aigne-9dc03e/"}
::link-card{title="Understanding Agents" description="Discover the different roles agents can play. We use simple analogies to explain their functions, from a single digital assistant to a highly coordinated team of specialists, without any technical jargon." icon="users" href="/en/docs/aigne-framework/user-guide-understanding-agents-9dc03e/"}
::link-card{title="Common Workflows" description="See how agents collaborate to achieve a goal. This section illustrates common patterns of agent teamwork using high-level diagrams, showing how information and tasks flow through the system." icon="flag" href="/en/docs/aigne-framework/user-guide-common-workflows-9dc03e/"}
::::

By the end of this guide, you will have a solid conceptual grasp of how AIGNE can be applied to create powerful automated solutions for your business.

To get started, we recommend beginning with [What is AIGNE?](/en/docs/aigne-framework/user-guide-what-is-aigne-9dc03e/).

---

## Common Workflows

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-common-workflows-9dc03e/

In the AIGNE Framework, a single agent can perform a specific task. However, the true power of the system is realized when multiple agents collaborate to solve more complex problems. Just like members of a team, agents can be organized to work together in structured ways. These patterns of collaboration are called "workflows."

Workflows define how tasks and information flow between different agents to achieve a larger goal. By arranging agents in different patterns, we can create sophisticated automated processes for various business needs.

The diagram below illustrates three fundamental workflow patterns.

![Common Workflows](https://media.arcblock.io/lib/a0/a040fd84b475bf19.w1600.webp)

This guide introduces the most common workflows you'll encounter. Understanding these patterns will help you visualize how agents can automate complex, multi-step processes for you.

Explore the detailed explanations for each workflow to learn more about their specific use cases and benefits.

::::card-group
::link-card{title="Sequential Tasks" description="Like an assembly line, agents complete tasks one after another, passing their work to the next agent in line. This is ideal for processes that must happen in a specific order." icon="list" href="/en/docs/aigne-framework/user-guide-common-workflows-sequential-tasks-9dc03e/"}
::link-card{title="Parallel Tasks" description="To get things done faster, multiple agents can work on different parts of a job at the same time. Their individual results are then combined to form a complete solution." icon="git-branch" href="/en/docs/aigne-framework/user-guide-common-workflows-parallel-tasks-9dc03e/"}
::link-card{title="Decision-Making" description="Just like a manager, one agent can analyze an incoming request and intelligently route it to the most suitable specialist agent to handle the job." icon="git-merge" href="/en/docs/aigne-framework/user-guide-common-workflows-decision-making-9dc03e/"}
::::

By combining these fundamental patterns, you can build powerful and autonomous systems tailored to your specific needs. Click on any card to dive deeper into how each workflow operates.

---

## Decision-Making

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-common-workflows-decision-making-9dc03e/

Illustrates a scenario where a 'manager' agent analyzes a request and decides which specialized agent is best suited to handle the task.

## Overview

In many real-world scenarios, a single AI agent isn't enough. Complex problems often require a team of specialized agents, each an expert in a specific domain. The Decision-Making workflow, also known as a Router or Triage pattern, addresses this by introducing a "manager" agent.

The manager agent's sole responsibility is to analyze an incoming request, understand its intent, and route it to the most appropriate specialist agent in the team. This is similar to a customer service dispatcher who listens to a customer's problem and connects them with the right department—be it technical support, billing, or sales.

This pattern creates a more efficient and intelligent system. Instead of a single, generalist agent trying to do everything, you have a coordinated team where each member excels at its designated task.

## How It Works

The workflow begins when a user submits a request. The manager agent, acting as the central router, receives this request. Based on its instructions and the available "tools" (the specialist agents), it decides which specialist is best equipped to handle the query. The request is then handed off to the chosen specialist, which processes it and produces the final output.

For example, if a user asks, "What's the status of my order?", the manager agent would route the query to the "Order Status" agent. If the user asks, "How do I reset my password?", it would be routed to the "Account Support" agent.

![Decision-Making](https://media.arcblock.io/lib/57/571920bc1cdd7e22.w1600.webp)

## Use Cases

This workflow is highly effective for:

- <strong>Intelligent Customer Support:</strong> Automatically routing customer queries to the correct department (e.g., Technical Support, Billing, Sales).
- <strong>Multi-functional Assistants:</strong> Creating a single assistant that can delegate tasks like scheduling, data analysis, or content creation to different specialized agents.
- <strong>Content Moderation:</strong> Classifying incoming content and sending it to different moderation queues based on its nature (e.g., spam, hate speech, inappropriate content).
- <strong>Complex Query Processing:</strong> Breaking down a complex query into sub-tasks and routing each to a specific agent for processing.

## Summary

The Decision-Making workflow is a powerful pattern for orchestrating a team of specialized AI agents. By using a manager agent to triage and route tasks, you can build more sophisticated, scalable, and efficient AI applications that leverage the strengths of individual, focused agents.

To learn more about the technical implementation, see the [Team Agent](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/) and [AI Agent](/en/docs/aigne-framework/developer-guide-agents-ai-agent-9dc03e/) documentation.

---

## Parallel Tasks

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-common-workflows-parallel-tasks-9dc03e/

In some situations, you need to perform several independent tasks at the same time to be more efficient. The parallel tasks workflow is designed for this purpose. It allows multiple AI agents to work simultaneously on the same initial information, with their individual results collected and combined at the end.

This approach is like hiring a team of specialists to analyze a business proposal. One specialist might focus on financial viability, another on market trends, and a third on legal risks. They all start with the same proposal and work at the same time, and their final reports are gathered to give a complete picture. This is much faster than if they had to wait for each other to finish.

This workflow is managed by an [Agent Team](/en/docs/aigne-framework/user-guide-understanding-agents-agent-teams-9dc03e/) configured to operate in parallel mode. For a different approach where tasks are done one after another, see the [Sequential Tasks](/en/docs/aigne-framework/user-guide-common-workflows-sequential-tasks-9dc03e/) workflow.

## How It Works

The parallel workflow follows a clear, efficient process for handling tasks that don't depend on each other. The flow is designed to maximize speed by running all agents at once.

The following diagram illustrates this process:

![Parallel Tasks](https://media.arcblock.io/lib/6d/6de04053f30946b1.w1600.webp)

::::steps
:::step{title="Single Input"}
The process begins with a single piece of information, like a document, a user query, or a set of data.
:::

:::step{title="Simultaneous Distribution"}
The Agent Team takes this input and distributes the <em>exact same information</em> to every agent in the team.
:::

:::step{title="Independent Processing"}
All agents start working at the same time. Each agent performs its specialized task based on its unique instructions, without waiting for or interacting with the other agents.
:::

:::step{title="Result Aggregation"}
As each agent finishes its work, its output is collected. The Agent Team then aggregates these individual outputs into a single, combined result. If multiple agents produce an output for the same field, the system typically accepts the result from whichever agent finishes first.
:::
::::

This structure ensures that the total time required to complete all tasks is determined by the longest-running agent, rather than the sum of all their times.

## Common Use Cases

The parallel workflow is best suited for scenarios where multiple, independent analyses or tasks are needed on the same piece of information, and speed is a priority.

::::card-group
::link-card{title="Multi-Perspective Content Analysis" description="When analyzing a document, one agent could extract key features, another could analyze the emotional tone (sentiment), and a third could identify the target audience. All three tasks can happen at once." icon="search"}
::link-card{title="Parallel Data Queries" description="If you need to search for information across different sources (e.g., a customer database, a product catalog, and a knowledge base), you can dispatch an agent for each source to search simultaneously." icon="database"}
::link-card{title="Competitive Analysis" description="To analyze a competitor's product, one agent could gather recent customer reviews, another could find pricing information, and a third could look up technical specifications, all in parallel." icon="bar-chart"}
::link-card{title="Code Review" description="For a piece of code, one agent can check for security vulnerabilities while another checks for adherence to style guidelines. The feedback is then combined for the developer." icon="code-2"}
::::

## Summary

The parallel tasks workflow is a powerful pattern for improving efficiency. By allowing multiple agents to work independently and simultaneously, it significantly reduces the time needed to complete complex jobs that involve several unrelated sub-tasks. This makes it a fundamental workflow for building responsive and powerful AI applications.

To see how agents can work together in a different way, read about the [Sequential Tasks](/en/docs/aigne-framework/user-guide-common-workflows-sequential-tasks-9dc03e/) workflow next.

---

## Sequential Tasks

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-common-workflows-sequential-tasks-9dc03e/

A sequential task workflow processes a series of tasks in a specific, predetermined order. It operates like a digital assembly line, where the output of one step becomes the input for the next. This pattern is ideal for multi-stage processes where each step builds upon the work of the previous one.

In the AIGNE Framework, this is managed by a `TeamAgent` configured to run in `sequential` mode. Each agent in the team completes its task before passing the result along, ensuring a logical and orderly progression from start to finish.

The following diagram illustrates this sequential workflow:

![Sequential Tasks](https://media.arcblock.io/lib/8f/8f8e851e70ebba56.w1600.webp)

## How It Works

Imagine a request entering the workflow.

1. The first agent in the sequence receives the initial input and processes it.
2. Once complete, its output is combined with the original input.
3. This combined result is then passed to the second agent in the sequence.
4. This handoff process continues down the line until the final agent completes its task.
5. The output from the last agent is the final result of the entire workflow.

This ensures that each agent has the full context of the work done by all preceding agents, allowing for the creation of complex and sophisticated pipelines.

## Common Use Cases

Sequential workflows are highly effective for tasks that require a structured, step-by-step approach.

- <strong>Content Generation Pipeline</strong>: An initial agent brainstorms a topic, a second agent writes a draft, a third agent proofreads it, and a final agent formats it for publication.
- <strong>Data Processing (ETL)</strong>: One agent extracts data from a source, another transforms it into a standardized format, and a third loads it into a database.
- <strong>Customer Inquiry Escalation</strong>: A frontline agent answers a basic customer question. If the issue is complex, it passes the conversation history to a specialized technical support agent for resolution.
- <strong>Report Generation</strong>: An agent gathers raw data, a second agent analyzes it and generates key insights, and a third agent compiles the findings into a formatted report.

## Summary

The sequential tasks workflow provides a reliable and structured way to automate complex, multi-step processes. By chaining agents together, you can build powerful and consistent automation pipelines where the order of operations is critical to achieving the desired outcome.

For tasks that can be performed simultaneously, consider the [Parallel Tasks](/en/docs/aigne-framework/user-guide-common-workflows-parallel-tasks-9dc03e/) workflow to improve efficiency.

---

## Understanding Agents

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-understanding-agents-9dc03e/

In the AIGNE framework, an "agent" is the fundamental building block for getting work done. Think of an agent as a specialized digital worker, hired to perform a specific task. Each agent has a clear role and a set of skills. Just like in a real-world team, you can assign a single task to one agent or assemble a team of agents to tackle a more complex project.

The core principle is to break down a large problem into smaller, manageable tasks and assign each task to an agent best suited for the job. This approach allows for clarity, efficiency, and the ability to build sophisticated automated workflows.

This section provides a conceptual overview of the different roles agents can play. The following diagram illustrates a common workflow where a manager agent coordinates several specialist agents to fulfill a user's request.

![Understanding Agents](https://media.arcblock.io/lib/b4/b43e96b12ad1c80a.w1600.webp)

For more detailed explanations, please refer to the following pages:

- [<strong>Basic Agents</strong>](/en/docs/aigne-framework/user-guide-understanding-agents-basic-agents-9dc03e/)<strong>:</strong> Learn about individual agents as standalone workers.
- [<strong>Agent Teams</strong>](/en/docs/aigne-framework/user-guide-understanding-agents-agent-teams-9dc03e/)<strong>:</strong> Discover how multiple agents can collaborate to solve complex problems.

### Roles Agents Can Play

To better understand their function, we can use analogies to describe the common types of agents and the roles they fulfill within the system.

::::card-group
::link-card{title="The Specialist" description="This is the most common type of agent, often powered by an AI model. It's like an expert you hire for a specific cognitive task, such as a writer, translator, or analyst. You give it instructions and a piece of information, and it produces a result based on its expertise. For example, you could ask it to summarize a long article or draft a professional email." icon="user"}
::link-card{title="The Project Manager" description="This agent doesn't perform the tasks itself but excels at coordinating other agents. Like a real project manager, it takes a complex goal, breaks it down into smaller steps, and delegates those steps to the appropriate specialist agents. It ensures the work flows in the correct order and that the final result is assembled correctly." icon="users"}
::link-card{title="The Tool User" description="Some agents are designed to operate specific tools. This could be a calculator for performing mathematical operations, a tool that searches a database, or one that connects to an external service like a weather API. These agents are reliable and predictable, executing a precise function every time they are called." icon="wrench"}
::link-card{title="The Data Clerk" description="This agent specializes in formatting and reorganizing information. It can take data in one structure and transform it into another. For instance, it could extract specific details from a customer email and format them into a structured record that can be saved in a database, much like a clerk transferring information from a paper form to a spreadsheet." icon="file"}
::::

### Summary

By understanding agents as digital workers with specialized roles, you can begin to see how they can be combined to automate complex processes. A single agent can be a powerful tool for a specific task, but the true potential of the AIGNE framework is realized when you assemble a team of agents, each contributing its unique skills to achieve a common goal.

To learn more about how these concepts are put into practice, continue to the next sections.

- [<strong>Basic Agents</strong>](/en/docs/aigne-framework/user-guide-understanding-agents-basic-agents-9dc03e/)<strong>:</strong> Explore how individual agents function.
- [<strong>Agent Teams</strong>](/en/docs/aigne-framework/user-guide-understanding-agents-agent-teams-9dc03e/)<strong>:</strong> See how to orchestrate multiple agents for complex workflows.

---

## Agent Teams

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-understanding-agents-agent-teams-9dc03e/

While a single, specialized agent is useful for a specific task, some problems are too large or complex for one agent to handle alone. Just as in a human organization, when a task requires multiple steps or diverse skills, you assemble a team. In AIGNE, an Agent Team is a group of agents organized to collaborate on solving a larger goal.

Think of it this way: if a [Basic Agent](/en/docs/aigne-framework/user-guide-understanding-agents-basic-agents-9dc03e/) is a specialist like a graphic designer, an Agent Team is the entire marketing department, including a copywriter, a strategist, and the designer, all working together on a campaign.

## How Agent Teams Collaborate

Agent Teams can be configured to work together in different ways, depending on the nature of the task. The two primary modes of collaboration are sequential and parallel.

### Sequential Workflow: The Assembly Line

In a sequential workflow, agents execute tasks one after another in a specific order. The output of the first agent becomes the input for the second agent, and so on, much like an assembly line. This approach is ideal for processes where each step depends on the completion of the previous one.

For example, to write a blog post, a team might work as follows:

::::steps
:::step{title="Researcher Agent:"}
Gathers information and key facts about a topic.
:::

:::step{title="Writer Agent:"}
Takes the research and drafts the blog post.
:::

:::step{title="Editor Agent:"}
Reviews the draft for grammar and style, and provides the final version.
:::
::::

### Parallel Workflow: The Brainstorming Session

In a parallel workflow, all agents in the team work on the same initial input simultaneously. Each agent performs its specialized task independently, and their individual outputs are then combined to form a final result. This is similar to a brainstorming session where different experts contribute their unique perspectives on a problem at the same time.

For example, to analyze market sentiment, a team could work in parallel:

- <strong>Input:</strong> A company's name.
- <strong>Social Media Agent:</strong> Scans Twitter for mentions.
- <strong>News Agent:</strong> Searches for recent news articles.
- <strong>Financial Agent:</strong> Looks up recent stock performance.
- <strong>Output:</strong> All three reports are combined into a single, comprehensive market analysis.

### Reflection: The Quality Assurance Loop

A more advanced pattern is "reflection," which introduces a quality control step. In this model, the team completes its task, and then a special <strong>Reviewer Agent</strong> examines the output.

- If the work meets the required standard, the Reviewer approves it, and the process is complete.
- If the work is not satisfactory, the Reviewer provides feedback and sends it back to the team for another attempt.

This loop continues until the output is approved or a maximum number of attempts is reached. It ensures a higher quality result by building a review-and-refine cycle directly into the workflow.

The diagram below illustrates these three primary collaboration patterns.

![Agent Teams](https://media.arcblock.io/lib/09/09c46e20ffc6024e.w1600.webp)

## Summary

By organizing agents into teams, you can automate more complex, multi-step workflows. This collaborative approach allows for building sophisticated solutions that mirror real-world business processes, from content creation pipelines to data analysis and quality assurance checks.

To see these concepts in action, explore our guides on [Common Workflows](/en/docs/aigne-framework/user-guide-common-workflows-9dc03e/), which provide practical examples of agent teams solving real problems. For technical details on implementation, developers can refer to the [Team Agent documentation](/en/docs/aigne-framework/developer-guide-agents-team-agent-9dc03e/).

---

## Basic Agents

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-understanding-agents-basic-agents-9dc03e/

Think of a basic agent as a specialized digital assistant, like a helpful chatbot or a focused data entry clerk. Each agent is designed to perform one specific type of task and do it well. It operates based on a clear set of instructions, receives a specific input to work on, and produces a result.

These single-purpose agents are the fundamental building blocks of AIGNE. While simple on their own, they can be combined to handle much more complex workflows, which we will explore in the [Agent Teams](/en/docs/aigne-framework/user-guide-understanding-agents-agent-teams-9dc03e/) section.

## The Anatomy of an Agent

Every basic agent, regardless of its function, is defined by a few core components. Understanding these parts helps clarify how an agent knows what to do.

::::card-group
::link-card{title="Instructions" description="This is the agent's permanent rulebook or job description. It's a detailed guide that tells the agent who it is, what its purpose is, and how it should behave. For example, the instructions for a customer service agent might be: \"You are a friendly and helpful assistant. Your goal is to answer customer questions accurately.\"" icon="book-open"}
::link-card{title="Input" description="This is the specific piece of information or the task you give the agent at a particular moment. If the agent is a chatbot, the input would be the user's question, like \"What are your business hours?\"." icon="arrow-right"}
::link-card{title="Output" description="This is the result the agent produces after processing the input according to its instructions. For the chatbot example, the output would be the answer: \"Our business hours are from 9 AM to 5 PM, Monday to Friday.\"" icon="arrow-left"}
::link-card{title="Skills" description="These are special tools or abilities an agent can use to perform its task. For instance, a \"Weather Agent\" might have a skill that allows it to access real-time weather data from an external service." icon="sparkles"}
::::

## How an Agent Works

The process is straightforward. A user provides an input to an agent. The agent then consults its core instructions to understand the context and rules, uses any skills it might have if necessary, and generates an output.

![Basic Agents](https://media.arcblock.io/lib/df/dff4279eef7546f8.w1600.webp)

## Example: A Simple Chat Agent

Let's look at a practical example of a "Chat Agent." This agent is designed to be a helpful assistant that answers questions. Its configuration would look something like this:

| Property  | Value  | Description  |
|---|---|---|
| <strong>Name</strong>  | `chat`  | A simple identifier for the agent.  |
| <strong>Description</strong>  | `Chat agent`  | A brief explanation of its purpose.  |
| <strong>Instructions</strong>  | `You are a helpful assistant...`  | This tells the agent to be friendly and informative.  |
| <strong>Input Key</strong>  | `message`  | The agent expects the user's question to be labeled as "message".  |
| <strong>Output Key</strong>  | `message`  | The agent will label its answer as "message".  |

When you send this agent an input like `message: "How does an agent work?"`, it follows its instructions to be helpful and provides a clear, informative answer based on its programming.

## Summary

A basic agent is a single-task digital worker defined by its instructions, the input it receives, and the output it produces. They are the essential, foundational components of AIGNE. While powerful for specific tasks, their true potential is unlocked when they are assembled into [Agent Teams](/en/docs/aigne-framework/user-guide-understanding-agents-agent-teams-9dc03e/) to tackle more complex challenges.

---

## What is AIGNE?

URL: https://www.arcblock.io/en/docs/aigne-framework/user-guide-what-is-aigne-9dc03e/

AIGNE (pronounced `[ˈei dʒən]`, like "agent" without the "t") is a functional framework for developing AI applications. It is designed to simplify and accelerate the process of building scalable, modern applications by combining functional programming, modular design, and powerful artificial intelligence capabilities.

The core concept of AIGNE is the use of <strong>agents</strong>—specialized AI assistants—that can be organized into teams to automate complex, multi-step tasks. Instead of relying on a single, monolithic AI, AIGNE provides the structure to create a digital workforce where different agents collaborate, each handling a specific part of a larger problem.

This document provides a plain-language introduction to the AIGNE Framework, explaining what AI agents are, the problems they solve, and how they work together to automate sophisticated workflows.

## What is an AI Agent?

An AI Agent is a specialized digital assistant designed to perform a specific function. Each agent operates based on a given set of instructions and can be equipped with specific tools to execute its tasks. Unlike a general-purpose chatbot, an AIGNE agent is an expert in a narrow domain.

Consider agents as individual members of a highly efficient project team:

- <strong>The Researcher:</strong> An agent that can access external information sources to gather data.
- <strong>The Writer:</strong> An agent that processes raw information and drafts a structured document.
- <strong>The Coder:</strong> An agent capable of writing and executing code to perform a technical function.
- <strong>The Analyst:</strong> An agent that can interpret data, identify patterns, and provide insights.

While a single agent is effective for simple, defined tasks, the primary strength of the AIGNE Framework is its ability to orchestrate multiple agents into a cohesive team to achieve a complex objective.

## The Problem AIGNE Solves

A single Large Language Model (LLM) is a powerful tool for tasks like answering questions or generating text. However, its capabilities are limited when faced with processes that require multiple distinct steps, different skill sets, or information from various sources.

For instance, a request such as, "Analyze our latest sales report, compare it to public competitor performance data, and draft a presentation for the marketing team," would be challenging for a standard chatbot. This process involves several discrete stages:

::::steps
:::step{title="Data Analysis:"}
Reading and interpreting the internal sales report.
:::

:::step{title="External Research:"}
Locating and extracting competitor performance data.
:::

:::step{title="Synthesis:"}
Comparing the two datasets to identify key insights.
:::

:::step{title="Content Creation:"}
Structuring the findings into a coherent presentation.
:::
::::

AIGNE addresses this by providing a framework to deconstruct such a complex request into manageable sub-tasks. Each sub-task is then assigned to a specialized agent, and the framework manages the flow of information between them, ensuring a complete and accurate final output.

## How Agents Work Together to Automate Tasks

AIGNE orchestrates agents into <strong>workflows</strong>, which are structured processes for executing tasks. By connecting agents, you can automate processes that would otherwise require significant manual coordination. The framework supports several patterns of collaboration, allowing for flexible and powerful automation.

The following diagram illustrates how the AIGNE Framework breaks down a complex task and manages a team of agents to produce a final result.

![What is AIGNE?](https://media.arcblock.io/lib/20/20f440d04e947520.w1600.webp)

Common workflow patterns include:

- <strong>Sequential Workflow (Assembly Line):</strong> One agent completes its task and passes the result directly to the next agent. This is suitable for processes with a required order of operations, such as gathering data, summarizing it, and then drafting a report.
- <strong>Parallel Workflow (Teamwork):</strong> Multiple agents work on different parts of a task simultaneously to improve efficiency. For example, to analyze customer feedback, one agent could process positive reviews while another processes negative reviews at the same time, with the results aggregated at the end.
- <strong>Routing Workflow (Manager):</strong> A "manager" agent analyzes an incoming request and determines which specialist agent is best equipped to handle it. This pattern is effective for creating intelligent assistants or helpdesks that can address a wide variety of queries.

By combining these workflow patterns, developers can construct sophisticated systems to automate a vast range of digital processes.

## Summary

AIGNE is a framework for building and managing a digital workforce of specialized AI agents. It provides the tools to:

- <strong>Decompose</strong> complex problems into smaller, well-defined tasks.
- <strong>Assign</strong> each task to an appropriate AI agent with the right skills.
- <strong>Orchestrate</strong> the collaboration between agents to achieve a final, coherent goal.

This agent-based approach overcomes the limitations of single AI models, enabling the automation of complex, real-world business processes with greater reliability and precision.

To learn more about the different roles agents can play within the system, proceed to the next section.

- <strong>Next:</strong> [Understanding Agents](/en/docs/aigne-framework/user-guide-understanding-agents-9dc03e/)

---

## AIGNE Hub

URL: https://www.arcblock.io/en/docs/aigne-hub/

---

## API Reference

URL: https://www.arcblock.io/en/docs/aigne-hub/api-reference-32e774/

This document provides technical specifications for the AIGNE Hub RESTful API. By following this guide, you will understand how to authenticate and interact with the core endpoints for chat completions, image generation, and embeddings, enabling robust backend integrations with your applications.

The AIGNE Hub API provides a unified interface to various underlying AI models, abstracting the complexity of individual provider APIs. All requests are authenticated using API keys.

The following diagram illustrates the interaction between an application, the AIGNE Hub API, and the underlying AI models.

![API Reference](https://media.arcblock.io/lib/c6/c65f3bf14cf3e416.w1600.webp)

For detailed specifications on each endpoint, including request and response schemas, please refer to the specific sub-sections:

::::card-group
::link-card{title="Chat Completions" description="Detailed specification for the chat completions endpoint, including request/response schemas and streaming support." icon="message-square" href="/en/docs/aigne-hub/api-reference-chat-completions-32e774/"}
::link-card{title="Image Generation" description="Reference for the image generation endpoint, covering supported models and parameters for size and quality." icon="image" href="/en/docs/aigne-hub/api-reference-image-generation-32e774/"}
::link-card{title="Embeddings" description="Documentation for creating vector representations of text for use in semantic search and other ML tasks." icon="code" href="/en/docs/aigne-hub/api-reference-embeddings-32e774/"}
::::

::::card-group
::link-card{title="API Authentication" description="Explains how to securely authenticate requests to the AIGNE Hub API using OAuth and API keys." icon="key" href="/en/docs/aigne-hub/api-reference-authentication-32e774/"}
::::

## Endpoints

The following table provides a summary of the available API endpoints.

| Method  | Endpoint  | Description  |
|---|---|---|
| `POST`  | `/chat/completions`  | Generates a response for a given chat conversation.  |
| `POST`  | `/embeddings`  | Generates vector embeddings for a given input text.  |
| `POST`  | `/image/generations`  | Creates an image based on a text prompt.  |
| `POST`  | `/audio/transcriptions`  | Transcribes audio into the input language.  |
| `POST`  | `/audio/speech`  | Generates audio from the input text.  |
| `GET`  | `/status`  | Checks the availability of the service and models.  |

## Summary

This section provided an overview of the AIGNE Hub API, covering authentication and a summary of available endpoints. For practical integration, proceed to the detailed documentation for each endpoint.

- <strong>For building conversational AI:</strong> See the [Chat Completions API](/en/docs/aigne-hub/api-reference-chat-completions-32e774/).
- <strong>For generating images:</strong> Explore the [Image Generation API](/en/docs/aigne-hub/api-reference-image-generation-32e774/).
- <strong>For text analysis and search:</strong> Use the [Embeddings API](/en/docs/aigne-hub/api-reference-embeddings-32e774/).

---

## API Authentication

URL: https://www.arcblock.io/en/docs/aigne-hub/api-reference-authentication-32e774/

Securely authenticating requests to the AIGNE Hub API is a critical step for programmatic access and integration. This guide provides a clear, step-by-step process for using API keys to authorize your applications, ensuring that all interactions are secure and properly identified.

## Authentication Methods

AIGNE Hub primarily uses bearer authentication with API keys for its RESTful API. All API requests must include an `Authorization` header containing a valid API key. This method is straightforward, secure, and aligns with industry best practices for service-to-service communication.

## Generating an API Key

Before you can authenticate, you must generate an API key from the AIGNE Hub admin interface.

1. Navigate to the <strong>Settings</strong> section in your AIGNE Hub instance.
2. Select the <strong>API Keys</strong> tab.
3. Click the <strong>"Generate New Key"</strong> button.
4. Provide a descriptive name for your key to help you identify its purpose later (e.g., `dev-server-integration`, `analytics-script-key`).
5. The system will generate a new key. <strong>Copy this key immediately and store it in a secure location.</strong> For security reasons, the full key will not be shown again after you leave this page.

## Using the API Key

To authenticate an API request, include the API key in the `Authorization` header of your HTTP request. The value must be prefixed with the `Bearer `scheme.

### HTTP Header Format

```
Authorization: Bearer <YOUR_API_KEY>
```

Replace `<YOUR_API_KEY>` with the actual key you generated.

### Example Request with cURL

Here is an example of how to make an authenticated request to the Chat Completions endpoint using `cURL`.

**Authenticated API Request**

```bash
curl -X POST https://your-aigne-hub-url/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "aignehub/gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### Example in a Node.js Application

When integrating with an application, you will set the `Authorization` header in your HTTP client library. The following example uses the AIGNE Hub SDK, which simplifies this process.

**AIGNEHubChatModel.js**

```javascript
import { AIGNEHubChatModel } from "@aigne/aigne-hub";

const model = new AIGNEHubChatModel({
  baseURL: "https://your-aigne-hub-url",
  apiKey: "YOUR_API_KEY", // The SDK handles adding the "Bearer " prefix
  model: "aignehub/gpt-3.5-turbo",
});

async function getGreeting() {
  try {
    const result = await model.invoke({
      messages: [{ role: "user", content: "Hello, AIGNE Hub!" }],
    });
    console.log(result);
  } catch (error) {
    console.error("API request failed:", error.message);
  }
}

getGreeting();
```

In this example, the `apiKey` provided to the `AIGNEHubChatModel` constructor is automatically placed into the correct `Authorization` header for all subsequent API calls made by the model instance.

## Security Best Practices

- <strong>Treat API keys like passwords.</strong> Store them securely in a secret manager or as environment variables. Never expose them in client-side code or commit them to version control.
- <strong>Use different keys for different applications.</strong> This practice, known as the principle of least privilege, limits the impact if a single key is compromised.
- <strong>Rotate keys regularly.</strong> Periodically revoke old keys and generate new ones to reduce the risk of unauthorized access from a compromised key.
- <strong>Monitor API usage.</strong> Keep an eye on the analytics dashboard to detect any unusual activity that might indicate a compromised key.

## Summary

Authentication to the AIGNE Hub API is handled via API keys included in the `Authorization` header as bearer tokens. By following the generation process and security best practices outlined above, you can ensure secure and reliable programmatic access to all API endpoints.

For more information on specific endpoints, please refer to the following sections:

- [Chat Completions](/en/docs/aigne-hub/api-reference-chat-completions-32e774/)
- [Image Generation](/en/docs/aigne-hub/api-reference-image-generation-32e774/)
- [Embeddings](/en/docs/aigne-hub/api-reference-embeddings-32e774/)

---

## Chat Completions

URL: https://www.arcblock.io/en/docs/aigne-hub/api-reference-chat-completions-32e774/

This document provides a detailed specification for the Chat Completions API endpoint. By following this guide, you will learn how to generate conversational AI responses, manage streaming, and utilize model-specific parameters for building robust applications. This endpoint is central to creating interactive, text-based experiences.

The Chat Completions API enables you to build applications that leverage large language models for a variety of conversational tasks. You provide a series of messages as input, and the model returns a text-based response.

![Chat Completions](https://media.arcblock.io/lib/57/572eeb077b3eebfe.w1600.webp)

For related functionalities, refer to the [Image Generation](/en/docs/aigne-hub/api-reference-image-generation-32e774/) and [Embeddings](/en/docs/aigne-hub/api-reference-embeddings-32e774/) API documentation.

## Create Chat Completion

Creates a model response for the given chat conversation.

`POST /api/chat/completions`

### Request Body

- **model** `string` *(required)* (default: `gpt-3.5-turbo`) — ID of the model to use. See the model endpoint compatibility table for details on which models work with the Chat API.
- **messages** `array` *(required)* — A list of messages comprising the conversation so far. See below for the message object structure.
  - **message** `object` — Each message object must have a role and content.
    - **role** `string` *(required)* — The role of the message's author. Can be system, user, assistant, or tool.
    - **content** `string or array` *(required)* — The content of the message. This can be a string or an array of content parts for multimodal models (e.g., text and image URLs).
    - **name** `string` — An optional name for the participant. Provides the model with context about the author of the message.
    - **tool_calls** `array` — The tool calls generated by the model, such as function calls.
    - **tool_call_id** `string` — Required if the role is tool. The ID of the tool call that this message is responding to.
- **temperature** `number` (default: `1`) — Controls randomness. Lowering results in less random completions. As the temperature approaches zero, the model will become deterministic and repetitive. Range: 0 to 2.
- **top_p** `number` (default: `1`) — Controls diversity via nucleus sampling. 0.5 means half of all likelihood-weighted options are considered. Range: 0.1 to 1.
- **stream** `boolean` (default: `false`) — If set to true, partial message deltas will be sent as server-sent events. The stream terminates with a data: [DONE] message.
- **max_tokens** `integer` — The maximum number of tokens to generate. The total length of input tokens and generated tokens is limited by the model's context length.
- **presence_penalty** `number` (default: `0`) — Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
- **frequency_penalty** `number` (default: `0`) — Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
- **tools** `array` — A list of tools the model may call. Currently, only functions are supported as a tool.
- **tool_choice** `string or object` — Controls which (if any) tool is called by the model. Can be 'none', 'auto', 'required', or an object specifying a function to call.
- **response_format** `object` — An object specifying the format that the model must output. Setting to { "type": "json_object" } enables JSON mode.

### Examples

#### Basic Request

This example demonstrates a simple conversation with the model.

**cURL Request**

```bash
curl --location 'https://your-aigne-hub-instance.com/api/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "model": "gpt-3.5-turbo",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello! Can you explain what AIGNE Hub is in simple terms?"
        }
    ]
}'
```

#### Streaming Request

To receive the response as a stream of events, set the `stream` parameter to `true`.

**cURL Stream Request**

```bash
curl --location 'https://your-aigne-hub-instance.com/api/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
    "model": "gpt-3.5-turbo",
    "messages": [
        {
            "role": "user",
            "content": "Write a short story about a robot who discovers music."
        }
    ],
    "stream": true
}'
```

### Response Body

#### Standard Response

A standard JSON object is returned when `stream` is `false` or not set.

- **role** `string` — The role of the author of this message, always 'assistant'.
- **content** `string` — The content of the message generated by the model.
- **tool_calls** `array` — The tool calls generated by the model, if any.

<strong>Example Standard Response</strong>

**Response Body**

```json
{
  "role": "assistant",
  "content": "AIGNE Hub is a centralized gateway that manages interactions with various AI models from different providers. It simplifies API access, handles billing and credits, and provides analytics on usage and costs, acting as a single point of control for an organization's AI services."
}
```

#### Streaming Response

When `stream` is `true`, the API returns a stream of `text/event-stream` chunks. Each chunk is a JSON object.

- **delta** `object` — A chunk of the message delta.
  - **role** `string` — The role of the author, typically 'assistant'.
  - **content** `string` — A partial content of the message.
  - **tool_calls** `array` — Partial tool call information.
- **usage** `object` — Present in the final chunk, contains token usage statistics.
  - **prompt_tokens** `integer` — Number of tokens in the prompt.
  - **completion_tokens** `integer` — Number of tokens in the generated completion.
  - **total_tokens** `integer` — Total number of tokens used in the request.

<strong>Example Stream Chunks</strong>

**Event Stream**

```text
data: {"delta":{"role":"assistant","content":"Unit "}}

data: {"delta":{"content":"734,"}}

data: {"delta":{"content":" a sanitation "}}

data: {"delta":{"content":"and maintenance "}}

data: {"delta":{"content":"robot, hummed..."}}

data: {"usage":{"promptTokens":15,"completionTokens":100,"totalTokens":115}}

data: [DONE]
```

## Summary

The Chat Completions endpoint is a powerful tool for integrating conversational AI into your applications. It offers flexibility through various parameters, including streaming and tool use, to support a wide range of use cases.

For more information on other available API endpoints, please refer to the following documents:

::::card-group
::link-card{title="Image Generation" description="Learn how to generate and manipulate images using AI models." icon="image" href="/en/docs/aigne-hub/api-reference-image-generation-32e774/"}
::link-card{title="Embeddings" description="Understand how to create vector representations of text for machine learning tasks." icon="bot" href="/en/docs/aigne-hub/api-reference-embeddings-32e774/"}
::::

---

## Embeddings

URL: https://www.arcblock.io/en/docs/aigne-hub/api-reference-embeddings-32e774/

This document provides a detailed specification for the AIGNE Hub Embeddings API endpoint. By following this guide, you will learn how to convert text into numerical vector representations, a foundational step for tasks like semantic search, text clustering, and similarity analysis.

## Create embedding

Generates a vector representation for a given text input. This is useful for machine learning applications that require a numerical representation of text.

<strong>POST</strong> `/api/embeddings`

### Request Body

- **model** `string` *(required)* — The ID of the model to use for generating the embeddings. The model must be compatible with embedding tasks.
- **input** `string or array` *(required)* — The input text or tokens to embed. This can be a single string, an array of strings, an array of integers (tokens), or an array of integer arrays (batched tokens).

### Example Request

Here is an example of how to call the embeddings endpoint using cURL.

**Create an embedding request**

```bash
curl https://your-aigne-hub-instance.com/api/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "AIGNE Hub is a unified AI gateway."
  }'
```

### Response Body

The API returns an object containing the list of embedding data.

- **data** `array` *(required)* — An array of embedding objects, where each object corresponds to an input item.
  - **embedding** `array` *(required)* — The vector representation of the input text, returned as an array of floating-point numbers.
  - **index** `number` *(required)* — The index of the embedding in the list, corresponding to the order of the input items.
  - **object** `string` *(required)* — The type of object, which is always embedding.
- **model** `string` *(required)* — The model that was used to generate the embeddings.
- **object** `string` *(required)* — The type of the top-level object, which is always list.
- **usage** `object` *(required)* — An object detailing the token usage for the request.
  - **prompt_tokens** `number` *(required)* — The number of tokens in the input prompt.
  - **total_tokens** `number` *(required)* — The total number of tokens consumed by the request.

### Example Response

**Example Response**

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        -0.006929283495992422,
        -0.005336422007530928,
        ...
        -4.547132266452536e-05
      ],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

## Summary

The Embeddings API provides a straightforward method for converting text into high-dimensional vectors, enabling a wide range of natural language processing applications. For building more complex conversational or generative AI, you may also want to explore the [Chat Completions API](/en/docs/aigne-hub/api-reference-chat-completions-32e774/).

---

## Image Generation

URL: https://www.arcblock.io/en/docs/aigne-hub/api-reference-image-generation-32e774/

This document provides the technical specifications for the image generation endpoint. By following this guide, you will be able to integrate AI-powered image creation into your applications by structuring requests, specifying models and parameters, and handling the resulting image data.

The AIGNE Hub API allows you to generate new images from a text prompt or edit existing images. For details on other AI functionalities, see the [Chat Completions](/en/docs/aigne-hub/api-reference-chat-completions-32e774/) and [Embeddings](/en/docs/aigne-hub/api-reference-embeddings-32e774/) documentation.

## Create Image

Generates an image based on a textual description (prompt). You can also provide an existing image to be edited.

<strong>Endpoint</strong>

```sh
POST /api/images/generations
```

This endpoint creates a new image or edits an existing one, returning the image data in the specified format.

### Request Body

- **prompt** `string` *(required)* — A detailed text description of the desired image. The maximum length depends on the model, but shorter, precise prompts often yield better results.
- **model** `string` (default: `dall-e-2`) — The model ID to use for image generation. If not specified, the system defaults to dall-e-2. Other models like dall-e-3 or Google's gemini models may be available depending on provider configurations.
- **image** `string or array` — The source image or images for editing. This can be a URL or a Base64 encoded string. Currently, this parameter is utilized by the gpt-image-1 model for image editing tasks.
- **n** `integer` (default: `1`) — The number of images to generate. Must be an integer between 1 and 10.
- **size** `string` (default: `1024x1024`) — The desired dimensions of the generated image. Supported sizes depend on the selected model. Common values include 256x256, 512x512, and 1024x1024 for DALL·E 2, and 1024x1024, 1792x1024, or 1024x1792 for DALL·E 3.
- **response_format** `string` (default: `url`) — The format in which the generated images are returned. Must be one of url or b64_json. A url will be accessible for one hour, while b64_json provides the image data encoded in Base64.
- **quality** `string` (default: `standard`) — The quality of the generated image. Only supported by dall-e-3. Can be standard for faster generation or hd for enhanced detail and higher quality, which may have increased cost.
- **style** `string` (default: `vivid`) — The artistic style of the generated image. Only supported by dall-e-3. Can be vivid for hyper-realistic and dramatic results or natural for a more photorealistic and less processed look.

### Response Body

The API returns an object containing the creation timestamp and an array of generated image data.

- **created** `integer` — A UNIX timestamp indicating when the image generation was initiated.
- **data** `array` — An array of objects, where each object contains one generated image. The structure of the objects inside the array depends on the response_format parameter.
  - **object** `object` — Contains either a url or b64_json field with the image data.
    - **url** `string` — The URL where the generated image can be accessed. This URL is temporary and will expire.
    - **b64_json** `string` — The Base64-encoded JSON string of the generated image.

### Examples

#### Basic Image Generation

This example demonstrates a standard request to generate a single image using the default `dall-e-2` model.

**Request**

```bash
curl --location 'https://your-aigne-hub-instance.com/api/images/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "prompt": "A photorealistic image of a cat programming on a laptop",
    "n": 1,
    "size": "1024x1024"
}'
```

The server returns the URL for the generated image.

**Response**

```json
{
  "created": 1678886400,
  "data": [
    {
      "url": "https://example.com/generated-images/image-xyz.png"
    }
  ]
}
```

#### Generating with DALL·E 3 and Base64 Response

This example uses the `dall-e-3` model to create a high-quality, vivid image and returns the result as a Base64 encoded string.

**Request**

```bash
curl --location 'https://your-aigne-hub-instance.com/api/images/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "model": "dall-e-3",
    "prompt": "An oil painting of a futuristic city skyline at sunset, with flying cars",
    "n": 1,
    "size": "1792x1024",
    "quality": "hd",
    "style": "vivid",
    "response_format": "b64_json"
}'
```

The response contains the Base64 data, which can be directly decoded and saved as an image file.

**Response**

```json
{
  "created": 1678886400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAB...rest_of_base64_string"
    }
  ]
}
```

## Summary

You now have the necessary information to use the image generation endpoint. This includes understanding the request parameters for creating and editing images, as well as handling the different response formats.

For further reading on related API functionalities, please refer to the following documents:
::link-card{title="Chat Completions API" icon="message-square" href="/en/docs/aigne-hub/api-reference-chat-completions-32e774/"}
Learn how to build conversational experiences with our chat models.
::link-card{title="Embeddings API" icon="tool" href="/en/docs/aigne-hub/api-reference-embeddings-32e774/"}
Discover how to create numerical representations of text for machine learning tasks.

---

## Deployment Scenarios

URL: https://www.arcblock.io/en/docs/aigne-hub/deployment-scenarios-32e774/

Choosing the right deployment model is crucial for aligning AIGNE Hub with your specific operational and business objectives. This document outlines the two primary deployment scenarios available, providing a clear comparison to guide your architectural decisions. Each mode is designed to address distinct use cases, from internal corporate use to public-facing commercial services.

AIGNE Hub offers the flexibility to be deployed in one of two primary modes: as a self-hosted gateway for internal enterprise use or as a multi-tenant service provider platform with a built-in credit and billing system. The selected mode dictates the configuration for billing, user management, and security.

![Deployment Scenarios](https://media.arcblock.io/lib/a6/a620f1e3b9fe6c92.w1600.webp)

The following sections provide an overview of each deployment scenario. For detailed configuration instructions, please refer to the specific sub-documents.

## Deployment Models

AIGNE Hub supports two distinct operational modes, each tailored to different organizational needs. Below is a summary of each model and its intended use case.

::::card-group
::link-card{title="Enterprise Self-Hosting" description="Deploy AIGNE Hub within your own infrastructure as a centralized gateway for internal teams. This model provides maximum control over data and security, with billing handled directly between your organization and the upstream AI providers." icon="briefcase" href="/en/docs/aigne-hub/deployment-scenarios-enterprise-self-hosting-32e774/"}
::link-card{title="Service Provider Mode" description="Configure AIGNE Hub to function as a public-facing, monetized AI service. This mode enables a credit-based billing system, allowing you to set custom pricing, manage user subscriptions, and generate revenue from AI services." icon="shopping-bag" href="/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/"}
::::

## Summary

This document has introduced the two primary deployment scenarios for AIGNE Hub. The Enterprise Self-Hosting model is ideal for internal use, prioritizing security and direct billing. In contrast, the Service Provider mode is designed for public-facing services that require multi-tenancy and monetization.

For detailed implementation guides, please proceed to the relevant sections:

- [<strong>Enterprise Self-Hosting</strong>](/en/docs/aigne-hub/deployment-scenarios-enterprise-self-hosting-32e774/)
- [<strong>Service Provider Mode</strong>](/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/)

---

## Enterprise Self-Hosting

URL: https://www.arcblock.io/en/docs/aigne-hub/deployment-scenarios-enterprise-self-hosting-32e774/

Deploying AIGNE Hub within your own infrastructure grants your organization complete control over AI model access, data privacy, and operational costs. This guide provides a structured approach to configuring and managing a self-hosted AIGNE Hub instance for secure, internal enterprise use.

## Overview

The enterprise self-hosting model is designed for organizations that prioritize data security and direct management of their AI resources. By deploying AIGNE Hub within your own network perimeter, you create a centralized, secure gateway for all internal teams and applications to access a variety of AI models.

This approach offers several distinct advantages:

- <strong>Enhanced Security</strong>: All data, including prompts, responses, and API credentials, remains within your corporate network, ensuring compliance with strict data privacy policies.
- <strong>Direct Billing</strong>: You maintain a direct billing relationship with each AI provider (e.g., OpenAI, Anthropic, Google). AIGNE Hub tracks usage, but all costs are paid directly to the vendors, simplifying budget allocation and eliminating third-party billing complexities.
- <strong>Full Control</strong>: Your team has complete administrative control over the instance, including which models are available, who can access them, and how they are configured.
- <strong>Internal Integration</strong>: Seamlessly connect AIGNE Hub with your existing internal authentication systems, such as your corporate OAuth provider, for unified and secure access management.

This deployment scenario is ideal for development teams, corporate AI initiatives, and any application requiring robust, private access to generative AI capabilities.

## Architectural Considerations

When deploying AIGNE Hub for internal enterprise use, it functions as a centralized gateway within your security perimeter. All internal applications and services route their AI requests through the Hub, which then securely communicates with the external AI providers.

![Enterprise Self-Hosting](https://media.arcblock.io/lib/0a/0a431417ad2ea78b.w1600.webp)

### Key Components

- <strong>AIGNE Hub Instance</strong>: A dedicated Blocklet running on your internal infrastructure (e.g., a private cloud, on-premises server, or VPC).
- <strong>Internal Applications</strong>: Your services, developer environments, and internal tools that need to consume AI services.
- <strong>Authentication System</strong>: Your corporate identity provider (e.g., an internal OAuth 2.0 server) that manages user access.
- <strong>External AI Providers</strong>: The upstream LLM and AIGC services that AIGNE Hub connects to.

In this configuration, the Hub acts as the sole intermediary. Internal applications do not need direct access to provider API keys, which significantly strengthens your security posture.

## Configuration Steps

Configuring AIGNE Hub for enterprise use is a straightforward process focused on connecting providers and securing access.

### 1. Initial Deployment

First, ensure you have a running instance of AIGNE Hub. If you have not yet installed it, follow the deployment instructions in our [Getting Started](/en/docs/aigne-hub/getting-started-32e774/) guide. The primary method is to launch it from the Blocklet Store onto your Blocklet Server.

### 2. Provider Configuration

The core of the self-hosted setup is configuring AIGNE Hub to use your organization's own API keys for each AI provider. This ensures that all usage is billed directly to your corporate accounts.

1. Navigate to the admin dashboard of your AIGNE Hub instance.
2. In the left-hand sidebar, go to <strong>Config > AI Providers</strong>.
3. Here, you will see a list of supported AI providers. Click <strong>+ Add Provider</strong> or select an existing one to configure.
4. Enter your organization's API credentials for the selected provider. The system stores these credentials securely using encryption.
5. Enable the providers you wish to make available to your internal users.

![Provider Configuration](https://raw.githubusercontent.com/AIGNE-io/aigne-hub/main/blocklets/core/screenshots/6fff77ec3c1fbefb780b2b79c61a36f7.png)

### 3. User Access and Security

For internal use, you can manage access through your existing identity infrastructure.

#### Internal OAuth Integration

AIGNE Hub supports standard OAuth 2.0 for secure, single sign-on (SSO) access. By integrating it with your internal identity provider, employees can use their corporate credentials to access the Hub and generate API tokens for their applications. This centralizes user management and access control.

To configure this, you will need to provide the client ID, client secret, and relevant endpoints from your OAuth provider in the AIGNE Hub security settings.

#### Direct API Access

For services or automated workflows, administrators can generate long-lived API keys directly within AIGNE Hub. These keys can be assigned specific permissions and revoked at any time, providing a secure method for non-interactive access.

## Usage and Management

With the self-hosted instance configured, internal teams can begin using the unified API endpoint for all their AI needs.

### Unified API Endpoint

All requests to any configured AI model are sent to your AIGNE Hub instance's API endpoints. The Hub automatically routes the request to the appropriate upstream provider, using the securely stored credentials.

For example, an application can switch from using OpenAI's `gpt-4` to Anthropic's `claude-3-opus` simply by changing the model name in the API call, without needing to manage different API keys or endpoints.

### Usage Analytics

Even though billing is handled directly with providers, AIGNE Hub provides detailed analytics on usage and costs.

- Navigate to the <strong>Usage Analytics</strong> section in the admin dashboard.
- Monitor token consumption, image generation counts, and estimated costs per user, team, or application.
- Use this data for internal chargebacks, budget tracking, and identifying high-consumption services.

This allows you to maintain visibility over AI spending across the organization without the complexity of parsing individual provider invoices.

## Summary

The enterprise self-hosting model provides a secure, controlled, and efficient way to deploy AIGNE Hub for internal use. By centralizing AI access, keeping data within your security perimeter, and maintaining direct billing relationships, you can build a robust AI infrastructure that meets strict corporate requirements.

For more advanced configurations, such as setting up a monetized service for external customers, please refer to the [Service Provider Mode](/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/) documentation. You can also find detailed information on securing your instance in the [Security & Access](/en/docs/aigne-hub/features-security-32e774/) guide.

---

## Service Provider Mode

URL: https://www.arcblock.io/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/

Ready to offer your own multi-tenant AI service? This guide details how to activate Service Provider Mode in AIGNE Hub. You will learn to enable the credit-based billing system, integrate the Payment Kit, and define custom pricing to create a monetized AI gateway for your users.

Service Provider Mode transforms AIGNE Hub from an internal tool into a full-featured, customer-facing platform. It builds upon the core features by adding a comprehensive billing and monetization layer, allowing you to resell access to a wide range of AI models. This is ideal for SaaS platforms, agencies, and developers looking to offer AI capabilities as a service.

For information on deploying AIGNE Hub for internal use, see the [Enterprise Self-Hosting](/en/docs/aigne-hub/deployment-scenarios-enterprise-self-hosting-32e774/) documentation.

## How It Works

When Service Provider Mode is enabled, AIGNE Hub operates on a prepaid, credit-based system. The following diagram illustrates the workflow:

![Service Provider Mode](https://media.arcblock.io/lib/3e/3e4eeb130709f751.w1600.webp)

The workflow is as follows:

::::steps
:::step{title="User Onboarding"}
New users are automatically registered within the system. You can configure starter credits to allow them to test the service immediately.
:::

:::step{title="Credit Purchase"}
Users purchase credits through a payment link. This process is managed by the <strong>Payment Kit</strong>, a companion Blocklet that handles checkout sessions and payment processing.
:::

:::step{title="AI Model Usage"}
Users make API calls to AIGNE Hub to interact with various AI models.
:::

:::step{title="Credit Deduction"}
For each API call, AIGNE Hub calculates the cost based on your custom-defined model rates and deducts the corresponding amount from the user's credit balance.
:::

:::step{title="Usage Tracking"}
All transactions are recorded, providing both the administrator and the user with detailed analytics on consumption and spending.
:::
::::

This model provides a flexible and scalable way to manage a multi-tenant AI service, ensuring that usage is billed accurately and automatically.

![AIGNE Hub dashboard with a modal for adding a new model rate, showing fields for configuration.](https://media.arcblock.io/lib/46/467a43898fb97a96.w1600.webp)

## Configuration Steps

Enabling the credit-based billing system involves installing the Payment Kit and configuring your pricing models.

### 1. Install the Payment Kit

The Payment Kit is a separate Blocklet that integrates with AIGNE Hub to handle all payment-related functionalities, including customer management, credit purchasing, and checkout processes.

To install it:

1. Navigate to the <strong>Blocklet Store</strong> in your Blocklet Server admin interface.
2. Search for <strong>"Payment Kit"</strong>.
3. Click <strong>"Launch"</strong> and follow the installation wizard to deploy it.

Once the Payment Kit is running, AIGNE Hub will automatically detect it and enable the necessary billing features.

### 2. Define Custom Pricing Models

After enabling the billing system, you must define the rates at which user consumption will be charged. This allows you to set your own pricing, which can include a margin on top of the costs from the upstream AI providers.

1. In the AIGNE Hub admin dashboard, navigate to <strong>Config</strong> > <strong>Model Rates</strong>.
2. Click <strong>"Add Model Rate"</strong> to open the configuration modal.
3. Define the pricing for a specific model by filling in the required fields:
4.
  - <strong>Model Name</strong>: The identifier for the model (e.g., `gpt-4o`).
  - <strong>Rate Type</strong>: The type of content the model handles (e.g., Text, Image).
  - <strong>Providers</strong>: The upstream AI provider for this model.
  - <strong>Model Cost</strong>: The actual cost you pay to the provider.
  - <strong>AIGNE Hub Credit Rate</strong>: The price in credits you will charge your users.
  - <strong>Description</strong>: An optional description for the model rate.

![The Model Rates configuration page in AIGNE Hub, displaying a table of AI models and their associated pricing.](https://media.arcblock.io/lib/3c/3c965b1fec89be97.w1600.webp)

By setting a higher credit rate than your actual cost, you can generate a profit margin on each transaction. You can create multiple pricing tiers for the same model or different rates for various customer groups if needed.

### 3. Configure the Credit Purchase Link

To allow users to buy credits, you need to set up a payment link. The Payment Kit can automatically generate a default link, or you can create a custom one.

1. A default payment link is created automatically when the Payment Kit is installed. You can find and manage it within the Payment Kit's interface.
2. In the AIGNE Hub admin dashboard, go to <strong>Billing & Credits</strong> > <strong>Settings</strong>.
3. Enter the URL for your credit purchase page in the <strong>Credit Payment Link</strong> field. This link will be provided to users when their balance is low.

This setup ensures a seamless experience for users to recharge their credit balance and continue using the service without interruption.

## Managing User Credits

As an administrator, you have full control over user credit balances and can view detailed transaction histories.

### Viewing User Balances

To see a user's current credit balance, pending deductions, and total credits purchased:

1. Navigate to the <strong>Users</strong> section in the AIGNE Hub admin dashboard.
2. Select a user from the list to view their details.
3. The user's credit information will be displayed, providing a complete overview of their account status.

### Reviewing Transactions

AIGNE Hub logs every transaction that consumes credits. This includes API calls for chat completions, image generation, and other AI tasks.

- <strong>Credit Grants</strong>: Records of all credits added to a user's account, either through purchase or manual grants.
- <strong>Credit Transactions</strong>: A detailed log of all deductions, showing which AI model was used, the amount consumed, and the timestamp of the event.

You can access these logs through the <strong>Billing & Credits</strong> section, allowing for transparent auditing and easy resolution of any billing inquiries.

## Summary

By enabling Service Provider Mode, you can leverage AIGNE Hub's powerful multi-provider gateway to build and scale your own monetized AI service. The integration with the Payment Kit provides a robust, automated system for managing credit-based billing, custom pricing, and user consumption.

For a deeper dive into monitoring consumption, refer to the [Usage & Cost Analytics](/en/docs/aigne-hub/features-analytics-32e774/) guide. To understand how to manage upstream providers, see [Provider Management](/en/docs/aigne-hub/features-provider-management-32e774/).

---

## Core Features

URL: https://www.arcblock.io/en/docs/aigne-hub/features-32e774/

This section provides a technical deep-dive into the key functionalities of AIGNE Hub. By the end, you will understand the platform's primary capabilities, from unified AI model interactions and provider management to robust security and detailed analytics, forming a solid foundation for leveraging the system.

AIGNE Hub is engineered to serve as a central gateway, streamlining all interactions with a diverse range of Large Language Models (LLMs) and AI services. It unifies API access, centralizes security, and provides comprehensive visibility into usage and costs. The platform's features are designed to support both internal enterprise deployments and multi-tenant service provider models.

The following diagram provides a high-level overview of AIGNE Hub's architecture and its core components.

![Core Features](https://media.arcblock.io/lib/55/550ea91d14c6145c.w1600.webp)

For more detailed information on specific features, please refer to the following sections:

::::card-group
::link-card{title="Provider Management" description="Learn how to connect, configure, and manage upstream AI providers." icon="cloud" href="/en/docs/aigne-hub/features-provider-management-32e774/"}
::link-card{title="Usage & Cost Analytics" description="Understand how to monitor system-wide and per-user consumption and costs." icon="bar-chart" href="/en/docs/aigne-hub/features-analytics-32e774/"}
::link-card{title="Security & Access" description="Review the security architecture, including access control and data protection." icon="shield-check" href="/en/docs/aigne-hub/features-security-32e774/"}
::::

## AI Service Unification

AIGNE Hub abstracts the complexity of integrating with multiple AI providers by offering a single, consistent set of API endpoints. This allows developers to build applications without being locked into a specific vendor and to switch between models seamlessly.

### Core AI Capabilities

The platform provides standardized access to the most common generative AI modalities:

- <strong>💬 Chat Completions</strong>: Engage with conversational AI and advanced text generation models for a wide range of applications. The system supports standard and streaming responses through an OpenAI-compatible API.
- <strong>🖼️ Image Generation</strong>: Access generative image models like DALL·E for AI-powered image creation and editing tasks.
- <strong>🧠 Embeddings</strong>: Generate vector representations of text for use cases such as semantic search, clustering, and retrieval-augmented generation (RAG).

### Built-in Model Playground

AIGNE Hub includes an interactive playground for testing and experimenting with any connected AI model in real time. This tool is invaluable for prompt engineering, model comparison, and rapid prototyping without writing any code.

![AIGNE Hub's interactive playground for testing AI models.](https://media.arcblock.io/lib/84/84151b07ec025b9f.w1600.webp)

## Centralized Management and Analytics

Effective management and operational visibility are central to the AIGNE Hub design. The platform provides a unified dashboard to control, monitor, and analyze all AI-related activities.

### Provider and Billing Configuration

From a single administrative interface, you can manage all aspects of the service.

- <strong>Provider Management</strong>: Connect to a growing list of AI providers, including OpenAI, Anthropic, Google Gemini, and Amazon Bedrock. Credentials are encrypted and stored securely.
- <strong>Flexible Billing System</strong>: Operate in two primary modes. For internal use, you can connect your own provider keys and pay them directly. For public-facing services, you can enable the credit-based billing system, set custom pricing rates, and monetize your AI gateway.

![The AI provider configuration screen in AIGNE Hub.](https://media.arcblock.io/lib/75/759f20b4abfeccdf.w1600.webp)

### Usage and Cost Analytics

The analytics dashboard offers deep insights into consumption and spending across all providers, models, and users.

- <strong>Usage Tracking</strong>: Monitor key metrics such as token consumption, API requests, and latency in real time.
- <strong>Cost Analysis</strong>: Track spending against your provider accounts or, in service provider mode, monitor revenue and credit consumption. This data is essential for budgeting, forecasting, and optimizing AI expenditures.

## Security and Access Control

AIGNE Hub is built with enterprise-grade security to protect sensitive data and ensure controlled access to powerful AI models.

- <strong>Encrypted Credential Storage</strong>: All upstream provider API keys and credentials are encrypted using AES-256 to prevent unauthorized access.
- <strong>OAuth Integration</strong>: Secure access for applications and users through industry-standard OAuth 2.0 protocols.
- <strong>API Key Management</strong>: Generate and manage API keys within AIGNE Hub, allowing for fine-grained control over application access.
- <strong>Audit Logging</strong>: A comprehensive audit trail logs all significant events, including API requests, configuration changes, and user activity, ensuring accountability and compliance.

## Summary

AIGNE Hub provides a comprehensive suite of features designed to unify, manage, and secure your organization's access to generative AI. By centralizing provider integrations, offering detailed analytics, and enforcing robust security measures, it serves as a critical infrastructure component for any team building with AI.

To continue, explore the detailed documentation for each core feature area:

- [<strong>Provider Management</strong>](/en/docs/aigne-hub/features-provider-management-32e774/): Dive into the specifics of connecting and configuring AI services.
- [<strong>Usage & Cost Analytics</strong>](/en/docs/aigne-hub/features-analytics-32e774/): Learn how to leverage the analytics dashboard for operational insights.
- [<strong>Security & Access</strong>](/en/docs/aigne-hub/features-security-32e774/): Understand the platform's security mechanisms in detail.

---

## Usage & Cost Analytics

URL: https://www.arcblock.io/en/docs/aigne-hub/features-analytics-32e774/

Understanding AI model consumption is crucial for managing costs, monitoring performance, and ensuring fair resource allocation. This document provides a detailed guide on how to query usage statistics, track costs, and interpret the data models AIGNE Hub uses for analytics and reporting.

## Overview

AIGNE Hub records every API interaction as a `ModelCall` entry. These records form the basis for all usage analytics. The system provides several API endpoints to query and aggregate this data, allowing you to monitor consumption for the entire system or on a per-user basis. This enables detailed tracking of token usage, credit consumption, and overall API call volume.

## Data Models

Understanding the underlying data structures is essential for effectively querying and interpreting analytics data. The following diagram illustrates how a `ModelCall` record is generated and used by the analytics endpoints.

![Usage & Cost Analytics](https://media.arcblock.io/lib/28/28c803b95e528073.w1600.webp)

### The ModelCall Object

Every request made to an AI provider through the hub is logged as a `ModelCall`. This object contains detailed information about the request, its execution, and the associated costs.

- **id** `string` *(required)* — A unique identifier for the model call record.
- **providerId** `string` *(required)* — The identifier of the AI provider used for the call.
- **model** `string` *(required)* — The specific model that was called (e.g., 'gpt-4o-mini').
- **credentialId** `string` *(required)* — The ID of the credential used for authentication with the provider.
- **type** `string` *(required)* — The type of the API call. Possible values include 'chatCompletion', 'embedding', 'imageGeneration', 'audioGeneration', 'video', or 'custom'.
- **totalUsage** `number` *(required)* — A normalized usage metric. For text models, this is typically the total number of tokens (input + output).
- **usageMetrics** `object` — A detailed breakdown of usage, such as input and output tokens.
  - **inputTokens** `number` — The number of tokens in the input prompt.
  - **outputTokens** `number` — The number of tokens in the generated response.
- **credits** `number` *(required)* — The number of credits consumed by the call, based on the configured model rates.
- **status** `string` *(required)* — The final status of the call. Can be 'success' or 'failed'.
- **duration** `number` — The duration of the API call in seconds.
- **errorReason** `string` — If the call failed, this field contains the reason for the failure.
- **appDid** `string` — The DID of the application that initiated the call.
- **userDid** `string` *(required)* — The DID of the user who made the call.
- **requestId** `string` — An optional client-side request identifier for tracing.
- **callTime** `number` *(required)* — The Unix timestamp when the call was made.
- **createdAt** `string` *(required)* — The timestamp when the record was created in the database.

## Querying Usage Data

You can retrieve analytics data through several REST API endpoints. These endpoints require authentication.

### Fetching Usage Statistics

To get a summarized and aggregated view of usage over a specific period, use the `GET /api/user/usage-stats` endpoint. For system-wide analytics, administrators can use `GET /api/user/admin/user-stats`.

<strong>Request Parameters</strong>

- **startTime** `string` *(required)* — The start of the time range as a Unix timestamp.
- **endTime** `string` *(required)* — The end of the time range as a Unix timestamp.
- **allUsers** `boolean` — When using /api/user/model-calls, set to true to fetch data for all users. This is restricted to admin users.

<strong>Example Request</strong>

**Requesting user stats**

```bash
curl -X GET 'https://your-aigne-hub-url/api/user/usage-stats?startTime=1672531200&endTime=1675228799' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
```

<strong>Response Body</strong>

The endpoint returns a comprehensive object containing a summary, daily breakdowns, model statistics, and trend comparisons.

- **summary** `object` — An object containing aggregated totals for the specified period.
  - **totalCredits** `number` — Total credits consumed.
  - **totalCalls** `number` — Total number of API calls.
  - **modelCount** `number` — Total number of unique models used.
  - **byType** `object` — An object with usage statistics broken down by call type (e.g., 'chatCompletion').
    - **[callType]** `object`
      - **totalUsage** `number` — Total usage (e.g., tokens) for this type.
      - **totalCredits** `number` — Total credits consumed by this type.
      - **totalCalls** `number` — Total calls of this type.
      - **successCalls** `number` — Number of successful calls of this type.
- **dailyStats** `array` — An array of objects, each representing a day's usage statistics.
  - **date** `string` — The date in 'YYYY-MM-DD' format.
  - **credits** `number` — Total credits consumed on this day.
  - **tokens** `number` — Total tokens processed on this day.
  - **requests** `number` — Total API calls made on this day.
- **modelStats** `array` — An array listing the most frequently used models.
  - **providerId** `string` — The ID of the provider for the model.
  - **model** `string` — The name of the model.
  - **totalCalls** `number` — Total number of calls made to this model.
- **trendComparison** `object` — Comparison of usage between the current and previous period.
  - **current** `object` — Statistics for the current period.
  - **previous** `object` — Statistics for the equivalent previous period.
  - **growth** `object` — Growth rates between the two periods.

### Listing Model Calls

For a detailed, chronological log of individual API requests, use the `GET /api/user/model-calls` endpoint. This provides access to the raw `ModelCall` records with pagination and filtering.

<strong>Request Parameters</strong>

- **page** `number` (default: `1`) — The page number for pagination.
- **pageSize** `number` (default: `50`) — The number of items to return per page. Maximum is 100.
- **startTime** `string` — The start of the time range as a Unix timestamp.
- **endTime** `string` — The end of the time range as a Unix timestamp.
- **search** `string` — A search term to filter results by model name, application DID, or user DID.
- **status** `string` — Filter by call status. Can be 'success', 'failed', or 'all'.
- **model** `string` — Filter by a specific model name.
- **providerId** `string` — Filter by a specific provider ID.
- **appDid** `string` — Filter by a specific application DID.
- **allUsers** `boolean` — If true, returns model calls for all users (admin only).

<strong>Example Request</strong>

**Listing model calls**

```bash
curl -X GET 'https://your-aigne-hub-url/api/user/model-calls?page=1&pageSize=10&status=failed' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
```

<strong>Response Body</strong>

The response is a paginated list of `ModelCall` objects.

**response.json**

```json
{
  "count": 1,
  "list": [
    {
      "id": "z8VwXGf6k3qN...",
      "providerId": "openai",
      "model": "gpt-4o-mini",
      "credentialId": "z3tXy..._default",
      "type": "chatCompletion",
      "totalUsage": 150,
      "usageMetrics": {
        "inputTokens": 100,
        "outputTokens": 50
      },
      "credits": 0.0002,
      "status": "failed",
      "duration": 2,
      "errorReason": "API key is invalid.",
      "appDid": "z2qa9sD2tFAP...",
      "userDid": "z1...",
      "requestId": null,
      "callTime": 1675228799,
      "createdAt": "2023-01-31T23:59:59.000Z",
      "updatedAt": "2023-01-31T23:59:59.000Z",
      "traceId": null,
      "provider": {
        "id": "openai",
        "name": "openai",
        "displayName": "OpenAI",
        "baseUrl": "https://api.openai.com/v1",
        "region": null,
        "enabled": true
      },
      "appInfo": {
        "appName": "My AI App",
        "appDid": "z2qa9sD2tFAP...",
        "appLogo": "...",
        "appUrl": "..."
      },
      "userInfo": {
        "did": "z1...",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "avatar": "..."
      }
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

### Exporting Model Calls

You can export the model call history to a CSV file for offline analysis or reporting using the `GET /api/user/model-calls/export` endpoint. This endpoint accepts the same filtering parameters as the listing endpoint.

<strong>Example Request</strong>

**Exporting model calls**

```bash
curl -X GET 'https://your-aigne-hub-url/api/user/model-calls/export?startTime=1672531200&endTime=1675228799' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-o model-calls-export.csv
```

The server will respond with a `text/csv` file containing the requested data.

## Summary

The analytics features in AIGNE Hub provide powerful tools for monitoring and understanding AI model usage. By leveraging the `ModelCall` data model and the associated API endpoints, you can build dashboards, generate reports, and gain critical insights into your operational costs and performance.

For details on how credits are configured and billed, refer to the [Service Provider Mode](/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/) documentation.

---

## Provider Management

URL: https://www.arcblock.io/en/docs/aigne-hub/features-provider-management-32e774/

Effective management of upstream AI providers is crucial for maintaining a reliable and cost-efficient AI gateway. AIGNE Hub centralizes this process, offering a unified interface to connect, configure, and manage credentials for various AI services. This section details the procedures for handling provider settings, credentials, and model rates.

The following diagram illustrates how Providers, Credentials, and Model Rates are interconnected within AIGNE Hub:

![Provider Management](https://media.arcblock.io/lib/9b/9bcb86d95ae0edb9.w1600.webp)

## Provider Configuration

Providers are the foundational elements that connect AIGNE Hub to upstream AI services like OpenAI, Google, and AWS Bedrock. Proper configuration ensures that the hub can route requests to the appropriate service.

![Provider Configuration UI showing a list of configured AI providers like OpenAI, Google, and AWS Bedrock.](https://media.arcblock.io/lib/75/759f20b4abfeccdf.w1600.webp)

### Add a Provider

To integrate a new AI service, you must add it as a provider. Each provider requires a unique name, a display name for the UI, and service-specific details like a `baseUrl` or `region`.

#### Request Body

- **name** `string` *(required)* — The official name of the provider. Must be one of the supported provider values (e.g., openai, google, bedrock).
- **displayName** `string` *(required)* — A user-friendly name for the provider that will be displayed in the UI.
- **baseUrl** `string` — The base URL for the provider's API endpoint. This is required for most providers but is optional for AWS Bedrock.
- **region** `string` — The AWS region for the Bedrock service. This is required only for the bedrock provider.
- **enabled** `boolean` (default: `true`) — Enables or disables the provider. A disabled provider will not be used for routing requests.

### Update a Provider

You can modify an existing provider's configuration, such as its `baseUrl`, `region`, or `enabled` status.

#### Request Body

- **baseUrl** `string` — The updated base URL for the provider's API endpoint.
- **region** `string` — The updated AWS region for the Bedrock service.
- **enabled** `boolean` — The new status for the provider.

### List and Delete Providers

You can retrieve a list of all configured providers or delete a specific provider by its ID. Deleting a provider will also remove all associated credentials and model rates.

## Credential Management

Credentials are used to authenticate with the upstream AI providers. AIGNE Hub encrypts and securely stores these credentials, associating them with a specific provider. Each provider can have multiple credentials, which allows for key rotation and load balancing.

### Add a Credential

When adding a credential, you must specify its type and value. AIGNE Hub automatically validates the credential against the provider's service to ensure it is active.

#### Request Body

- **name** `string` *(required)* — A descriptive name for the credential (e.g., "Team A API Key").
- **credentialType** `string` (default: `api_key`) — The type of credential. Supported values are api_key and access_key_pair.
- **value** `string or object` *(required)* — The credential value. For api_key, this is a string. For access_key_pair, this is an object containing access_key_id and secret_access_key.

### Credential Validation

AIGNE Hub includes an endpoint to check the validity of a stored credential. This action triggers a test connection to the provider using the specified credential to confirm it is active and has the necessary permissions.

### Update and Delete Credentials

Existing credentials can be updated with new values or deleted. When a credential is deleted, it is permanently removed from the system and can no longer be used for requests.

## Model Rate Management

Model rates define the cost of using specific AI models in AIGNE Hub credits. These rates are essential for systems operating in [Service Provider Mode](/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/) where usage is billed based on credits.

![Model Rate Configuration UI showing a list of AI models with their associated costs.](https://media.arcblock.io/lib/3c/3c965b1fec89be97.w1600.webp)

### Add a Model Rate

You can define rates for any model supported by a configured provider. This includes setting separate credit costs for input and output tokens (for text models) or per image/video (for generation models).

#### Request Body

- **model** `string` *(required)* — The identifier for the model (e.g., gpt-4o-mini).
- **type** `string` *(required)* — The type of service. Supported values are chatCompletion, imageGeneration, embedding, and video.
- **providers** `array` *(required)* — An array of provider IDs to which this model rate applies. This allows a single model to be offered by multiple providers.
- **inputRate** `number` *(required)* — The cost in credits for input (e.g., per 1,000 tokens).
- **outputRate** `number` *(required)* — The cost in credits for output (e.g., per 1,000 tokens).
- **unitCosts** `object` — The actual cost from the provider in USD per million units (tokens/images). Used for automatic rate calculation based on profit margins.
  - **input** `number` *(required)* — The input cost per million units.
  - **output** `number` *(required)* — The output cost per million units.
- **modelMetadata** `object` — Additional metadata about the model's capabilities.
  - **maxTokens** `number` — The maximum context window size.
  - **features** `array` — An array of supported features, such as `tools` or `vision`.

### Bulk Update Model Rates

To simplify pricing adjustments, AIGNE Hub supports bulk updates of model rates based on a defined profit margin and credit price. The system automatically recalculates the `inputRate` and `outputRate` for all models that have `unitCosts` defined.

The calculation is as follows: `New Rate = (Unit Cost * (1 + Profit Margin / 100)) / Credit Price`

#### Request Body

- **profitMargin** `number` *(required)* — The desired profit margin as a percentage (e.g., 20 for 20%).
- **creditPrice** `number` *(required)* — The price of a single credit in USD.

### Update and Delete Model Rates

Individual model rates can be modified or removed. If a model rate is deleted, the corresponding model will no longer be available for users if credit-based billing is enabled.

## Summary

This section covered the core functionalities for managing AI providers, credentials, and model rates within AIGNE Hub. Proper configuration of these resources is essential for the security, reliability, and financial management of your AI services.

For more information on related topics, refer to the following sections:
::link-card{title="Service Provider Mode" icon="briefcase" href="/en/docs/aigne-hub/deployment-scenarios-service-provider-32e774/"}
Learn how to configure credit-based billing and custom pricing models.
::link-card{title="Security and Access Control" icon="shield" href="/en/docs/aigne-hub/features-security-32e774/"}
Understand the security architecture, including encrypted storage and access controls.

---

## Security & Access

URL: https://www.arcblock.io/en/docs/aigne-hub/features-security-32e774/

A secure and well-managed system is critical for any enterprise-grade deployment. This section details the robust security architecture of AIGNE Hub, covering authentication, credential management, access control, and logging to ensure the integrity and confidentiality of your AI operations.

The following diagram provides a high-level overview of the security layers and components within AIGNE Hub:

![Security & Access](https://media.arcblock.io/lib/6e/6eb62829c76d1117.w1600.webp)

## Authentication

AIGNE Hub integrates with Blocklet Server's standard authentication mechanisms, providing a secure and unified login experience. The primary method of authentication is through DID Connect, which leverages decentralized identity for passwordless and secure access.

### DID Connect Integration

All user authentication is handled by the underlying Blocklet Server environment. When a user logs into AIGNE Hub, they are authenticated via the DID Connect wallet authenticator, ensuring that access is tied to a verified decentralized identity. This approach eliminates the need for traditional username/password combinations, reducing the risk of credential theft.

The system uses an authentication storage database (`auth.db`) to manage session tokens securely.

For details on how to authenticate programmatic API requests to AIGNE Hub, please see the [API Authentication](/en/docs/aigne-hub/api-reference-authentication-32e774/) documentation.

## Encrypted Credential Storage

Storing API keys and other sensitive credentials from upstream AI providers is a critical security concern. AIGNE Hub addresses this by implementing strong, field-level encryption for all sensitive credential data.

### Encryption Mechanism

When you add a provider's credentials (like an API key or a secret access key), the sensitive parts of the credential are encrypted before being stored in the database.

- <strong>Encryption Target</strong>: Only sensitive fields are encrypted. For example, in an `access_key_pair`, the `secret_access_key` is encrypted, while the `access_key_id` remains in plaintext for identification purposes. Standalone `api_key` values are always encrypted.
- <strong>Technology</strong>: Encryption and decryption operations are handled by the `@blocklet/sdk/lib/security` module, which provides robust cryptographic functions.

The following code snippet from the `AiCredential` model illustrates the process:

**ai-credential.ts**

```typescript
// Encrypt credential value (only encrypts sensitive fields)
static encryptCredentialValue(credential: CredentialValue): CredentialValue {
  const encrypted: CredentialValue = { ...credential };

  // Encrypt sensitive fields
  if (credential.secret_access_key) {
    encrypted.secret_access_key = security.encrypt(credential.secret_access_key);
  }
  if (credential.api_key) {
    encrypted.api_key = security.encrypt(credential.api_key);
  }

  // access_key_id remains plaintext
  return encrypted;
}

// Decrypt credential value
static decryptCredentialValue(encryptedCredential: CredentialValue): CredentialValue {
  const decrypted: CredentialValue = { ...encryptedCredential };

  // Decrypt sensitive fields
  if (encryptedCredential.secret_access_key) {
    decrypted.secret_access_key = security.decrypt(encryptedCredential.secret_access_key);
  }
  if (encryptedCredential.api_key) {
    decrypted.api_key = security.decrypt(encryptedCredential.api_key);
  }

  return decrypted;
}
```

### Credential Masking

To prevent accidental exposure of sensitive keys in the user interface, AIGNE Hub automatically masks credential values. Only the first four and last four characters of a key are displayed, with the rest replaced by asterisks.

## Role-Based Access Control (RBAC)

AIGNE Hub employs a simple yet effective Role-Based Access Control (RBAC) model to restrict access to administrative functions. The roles are inherited from the Blocklet Server environment.

### Available Roles

| Role  | Permissions  |
|---|---|
| `owner`  | Full administrative access to the AIGNE Hub instance. Can manage providers, configure billing, view analytics, and manage all settings.  |
| `admin`  | Same permissions as the `owner`. This role is also considered a privileged user with full access to administrative functions.  |
| `guest`  | Standard user role. Can use the AI services provided by the Hub (e.g., Playground, API access) but cannot access the admin configuration.  |

Access to critical administrative API endpoints is protected by a middleware that verifies the user's role, ensuring that only users with `owner` or `admin` roles can perform management tasks.

**security.ts**

```typescript
import { auth } from '@blocklet/sdk/lib/middlewares';

// Middleware to ensure the user has 'owner' or 'admin' role
export const ensureAdmin = auth({ roles: ['owner', 'admin'] });
```

## Audit Logging

Comprehensive audit logging is essential for security analysis, troubleshooting, and compliance. AIGNE Hub maintains detailed logs of all significant activities within the system.

### Logged Activities

- <strong>API Requests</strong>: All incoming requests to the AI endpoints are logged, including the user, model requested, and usage metrics.
- <strong>Administrative Actions</strong>: Actions performed in the admin panel, such as adding or updating a provider, changing model rates, or modifying configurations, are recorded.
- <strong>Credential Management</strong>: Events related to the creation, modification, or deletion of provider credentials.

These logs provide a complete history of usage and administrative changes, which is invaluable for security audits and operational monitoring.

## Summary

AIGNE Hub is designed with a multi-layered security model to protect your AI gateway. By combining DID-based authentication, strong encryption for credentials, role-based access control, and detailed audit logs, it provides a secure foundation for both internal enterprise use and public-facing services.

For more information on related features, please refer to the following sections:

::::card-group
::link-card{title="Provider Management" description="Learn how to connect and configure upstream AI providers." icon="server" href="/en/docs/aigne-hub/features-provider-management-32e774/"}
::link-card{title="Usage & Cost Analytics" description="Explore how to monitor system-wide and per-user consumption." icon="pie-chart" href="/en/docs/aigne-hub/features-analytics-32e774/"}
::::

---

## Getting Started

URL: https://www.arcblock.io/en/docs/aigne-hub/getting-started-32e774/

This guide provides a direct, task-oriented path to deploying and operating AIGNE Hub. By following these steps, a functional instance can be configured in under 30 minutes, enabling immediate integration with upstream AI providers and downstream applications.

The following diagram illustrates the core workflow for getting started:

![Getting Started](https://media.arcblock.io/lib/d3/d3e59dfe0b305a8f.w1600.webp)

## Prerequisites

Before proceeding, ensure the following requirements are met:

- <strong>Blocklet Server:</strong> A running instance of Blocklet Server is required to host AIGNE Hub.
- <strong>AI Provider Accounts:</strong> You must have active accounts and corresponding API keys for the AI services you intend to connect (e.g., OpenAI, Anthropic, Google Gemini).

## Step 1: Install AIGNE Hub

AIGNE Hub is distributed as a Blocklet, ensuring a standardized and straightforward installation process.

1. Navigate to the <strong>Blocklet Store</strong> within your Blocklet Server instance.
2. Use the search bar to find "AIGNE Hub".
3. Click the <strong>"Launch"</strong> button on the AIGNE Hub blocklet page.
4. Follow the on-screen installation wizard to complete the deployment. The system will handle the necessary setup and configuration automatically.

After the installation is complete, AIGNE Hub will be running and accessible from your Blocklet Server dashboard.

![AIGNE Hub Dashboard](https://media.arcblock.io/lib/a9/a9cd09be56bd2502.w1600.webp)

## Step 2: Connect AI Providers

Once installed, the next step is to connect AIGNE Hub to your chosen AI providers. All credentials are AES-encrypted at rest to ensure security.

1. Access the AIGNE Hub admin dashboard.
2. Navigate to the configuration section via the sidebar: <strong>Config → AI Providers</strong>.
3. Click the <strong>"+ Add Provider"</strong> button to open the configuration modal.
4. Select the desired provider from the list (e.g., OpenAI, Google Gemini).
5. Enter your API key and any other required credentials or parameters.
6. Save the configuration. The provider will now appear in the list with a "Connected" status if the credentials are valid.

Repeat this process for all the AI providers you wish to manage through AIGNE Hub.

![Configure AI Providers](https://media.arcblock.io/lib/75/759f20b4abfeccdf.w1600.webp)

## Step 3: Choose an Operational Mode

AIGNE Hub can be configured for two primary deployment scenarios. Your choice determines the next steps for usage and integration.

### For Internal Enterprise Use

This is the default and simplest mode, designed for teams that need a centralized AI gateway for internal applications.

- <strong>Direct Billing:</strong> Your organization is billed directly by the AI providers (OpenAI, Anthropic, etc.). AIGNE Hub tracks usage for analytics but does not handle payments.
- <strong>Secure Access:</strong> Integrate with your existing OAuth provider for secure, single-sign-on access for internal developers and applications.

With providers configured, your AIGNE Hub instance is ready for immediate use. Proceed to the [Basic Usage](#basic-usage) section.

### For Use as a Service Provider

This mode turns AIGNE Hub into a multi-tenant, monetized service by enabling the credit-based billing system.

- <strong>Monetization:</strong> Charge end-users for AI usage on a credit basis. You set the pricing per model, creating a margin over the costs from the upstream provider.
- <strong>Payment Kit Integration:</strong> This mode requires installing the <strong>Payment Kit</strong> blocklet, which handles credit purchases, invoicing, and payment processing.
- <strong>User Onboarding:</strong> Automatically grant new users a starting balance of credits to encourage adoption.

To enable this mode, navigate to <strong>Preferences</strong>, enable credit-based billing, and configure your model pricing rates.

![Configure Model Rates](https://media.arcblock.io/lib/3c/3c965b1fec89be97.w1600.webp)

## Step 4: Basic Usage

After configuration, you can begin making API requests through AIGNE Hub's unified endpoint or test models directly in the built-in Playground.

### Using the Playground

The Playground provides a no-code interface for interacting with any connected AI model. It is an excellent tool for testing, prompt engineering, and demonstrations.

1. Navigate to the <strong>Playground</strong> section in the AIGNE Hub dashboard.
2. Select a connected model from the dropdown menu.
3. Enter your prompt and submit to receive a response.

![AIGNE Hub Playground](https://media.arcblock.io/lib/84/84151b07ec025b9f.w1600.webp)

### Programmatic Usage

Integrate AIGNE Hub into your applications by making API calls to its OpenAI-compatible endpoints. The following example shows how to use the `@aigne/aigne-hub` client library.

**AIGNEHubChatModel.ts**

```typescript
// Using AIGNE Framework with AIGNE Hub
import { AIGNEHubChatModel } from "@aigne/aigne-hub";

const model = new AIGNEHubChatModel({
  baseURL: "https://your-aigne-hub-url",
  apiKey: "your-oauth-access-key", // Use an access key generated via OAuth
  model: "aignehub/gpt-3.5-turbo", // Prefix model with 'aignehub/'
});

const result = await model.invoke({
  messages: "Hello, AIGNE Hub!",
});

console.log(result);
```

This code snippet initializes a chat model client pointing to your self-hosted AIGNE Hub instance. It authenticates using an OAuth access key and makes a request to the `gpt-3.5-turbo` model through the gateway.

## Summary

You have now successfully deployed, configured, and tested your AIGNE Hub instance. The gateway is operational and ready to serve AI capabilities to your teams and applications.

For more advanced configurations and a deeper dive into the platform's features, refer to the following documentation:

::::card-group
::link-card{title="Deployment Scenarios" description="Explore detailed architectures for enterprise self-hosting and public service provider modes." icon="server" href="/en/docs/aigne-hub/deployment-scenarios-32e774/"}
::link-card{title="API Reference" description="Review the technical specifications for the Chat Completions, Image Generation, and Embeddings endpoints." icon="code" href="/en/docs/aigne-hub/api-reference-32e774/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/aigne-hub/overview-32e774/

Struggling to manage a growing collection of API keys, billing systems, and integrations for different AI providers? This document provides a comprehensive introduction to AIGNE Hub, a unified AI gateway that simplifies this complexity. You will learn about its core capabilities, key benefits, and system architecture, establishing a clear understanding of its value for infrastructure management.

AIGNE Hub serves as a centralized gateway, enabling you to connect your applications to leading Large Language Models (LLMs) and AIGC services through a single, consistent API. It streamlines the management of API keys, usage tracking, and security, whether you're deploying it as an internal tool or as a monetized, multi-tenant service.

## Why AIGNE Hub?

Integrating multiple AI services into an organization's infrastructure introduces significant operational overhead. Teams often face a fragmented landscape of provider-specific APIs, disparate billing cycles, and inconsistent security models. This complexity slows down development, complicates cost management, and increases the security surface area.

The diagram below illustrates how AIGNE Hub sits between your applications and various AI providers to solve these challenges:

![Overview](https://media.arcblock.io/lib/cd/cda398893dea7b57.w1600.webp)

AIGNE Hub is designed to solve these specific challenges by providing:

- <strong>A Single Point of Integration:</strong> It offers a unified, OpenAI-compatible API endpoint for all connected providers. This eliminates the need for developers to learn and maintain multiple SDKs and integration patterns.
- <strong>Centralized Credential Management:</strong> All upstream API keys are stored securely in one place with AES encryption, reducing the risk of key exposure across various applications and environments.
- <strong>Unified Usage and Cost Analytics:</strong> Gain full visibility into consumption and spending across all models, users, and providers from a single dashboard. This simplifies budget tracking and resource allocation.
- <strong>Flexible Deployment Models:</strong> AIGNE Hub can be deployed for purely internal use, where you bring your own keys, or as a public-facing service with a built-in, credit-based billing system.

## Core Capabilities

AIGNE Hub provides a robust set of features designed to streamline the entire lifecycle of AI service consumption and management.

::::card-group
::link-card{title="Multi-Provider Management" description="Connect to over 8 leading AI providers like OpenAI, Anthropic, and Google Gemini through a single interface." icon="cloud"}
::link-card{title="Unified API Endpoints" description="Interact with all models using OpenAI-compatible RESTful APIs for chat completions, image generation, and embeddings." icon="zap"}
::link-card{title="Usage & Cost Analytics" description="Monitor token usage, cost, and latency metrics across all users and providers with a comprehensive analytics dashboard." icon="chart"}
::link-card{title="Centralized Security" description="Benefit from encrypted API key storage, OAuth integration, role-based access control (RBAC), and detailed audit logs." icon="shield-check"}
::link-card{title="Flexible Billing System" description="Optionally enable a credit-based billing system powered by Payment Kit to monetize your service for external users." icon="credit-card"}
::link-card{title="Built-in Playground" description="Test and experiment with any connected AI model in real-time directly from the AIGNE Hub user interface." icon="activity"}
::::

## Supported AI Providers

AIGNE Hub supports a growing list of major AI providers. The system is designed to be extensible, with new providers being added continuously.

| Provider  | Supported Services  |
|---|---|
| <strong>OpenAI</strong>  | GPT models, DALL-E, Embeddings  |
| <strong>Anthropic</strong>  | Claude models  |
| <strong>Google Gemini</strong>  | Gemini Pro, Vision models  |
| <strong>Amazon Bedrock</strong>  | AWS-hosted foundation models  |
| <strong>DeepSeek</strong>  | Advanced reasoning models  |
| <strong>xAI</strong>  | Grok models  |
| <strong>OpenRouter</strong>  | Aggregator for multiple providers  |
| <strong>Ollama</strong>  | Local model deployment  |
| <strong>Doubao</strong>  | Doubao AI models  |
| <strong>Poe</strong>  | Poe AI platform  |

## System Architecture

AIGNE Hub is engineered for reliability and performance, built as a [Blocklet](https://blocklet.io) on the AIGNE framework. This architecture ensures seamless integration within the AIGNE ecosystem and provides a robust foundation for cloud-native deployment and scaling.

The primary components of the stack include:

- <strong>Backend:</strong> Built with Node.js and TypeScript, providing a strongly-typed and efficient server-side environment.
- <strong>Frontend:</strong> A modern user interface constructed with React 19.
- <strong>Database:</strong> Utilizes SQLite with the Sequelize ORM for local data storage, ensuring simple setup and reliable data management.
- <strong>Framework:</strong> Leverages the latest version of the AIGNE Framework for core functionality and integration capabilities.

![AIGNE Hub Dashboard](https://raw.githubusercontent.com/AIGNE-io/aigne-hub/main/blocklets/core/screenshots/fc46e9461382f0be7541af17ef13f632.png)

## Summary

This overview has introduced AIGNE Hub as a unified AI gateway designed to simplify infrastructure management for multi-provider AI services. We have outlined the problems it solves, its core features, and its technical architecture.

For the next steps, you can proceed to the following sections for more detailed information:

::::card-group
::link-card{title="Getting Started" description="Follow a step-by-step guide to deploy and configure your AIGNE Hub instance in under 30 minutes." icon="rocket" href="/en/docs/aigne-hub/getting-started-32e774/"}
::link-card{title="Deployment Scenarios" description="Explore the architectural guidance for deploying AIGNE Hub for internal enterprise use or as a monetized service." icon="flag" href="/en/docs/aigne-hub/deployment-scenarios-32e774/"}
::::

---

## Release Notes

URL: https://www.arcblock.io/en/docs/aigne-hub/release-notes-32e774/

This document provides a detailed record of all notable changes, new features, and bug fixes for AIGNE Hub. DevOps and SRE teams can use this information to track the platform's evolution, understand the impact of each update, and schedule upgrades accordingly.

## October 2025

### New Features

- <strong>Video Generation Support</strong>: The platform's core capabilities have been extended to support video generation models. A new `video` type has been added to the `ModelCalls` table to track these requests.
- <strong>Media Duration Analytics</strong>: To enhance usage tracking for multimedia content, a `mediaDuration` field has been added to the `Usages` table. This allows for more precise cost and consumption analysis of audio and video generation.
- <strong>Request Tracing</strong>: A `traceId` field has been added to all model calls. This identifier improves observability by allowing requests to be tracked consistently across different system components, simplifying debugging and performance analysis.

## September 2025

### New Features

- <strong>Credential Weighting for Load Balancing</strong>: A `weight` attribute has been added to AI provider credentials. This feature enables weighted load balancing, allowing administrators to distribute API traffic across multiple keys based on predefined priorities, such as routing more requests to higher-limit or lower-cost credentials.
- <strong>Credential Error Tracking</strong>: An `error` field has been added to the `AiCredentials` table. This allows the system to store the last known error associated with a specific credential, improving diagnostics and making it easier to identify and resolve issues with provider API keys.

## August 2025

### New Features

- <strong>Model Health Monitoring</strong>: A new system for tracking the operational status of individual AI models has been introduced. The `AiModelStatuses` table now records the health and availability of each model, providing better insight into provider-side issues and improving overall system reliability.

This summary provides an overview of recent updates. For more detailed information on integrating and managing these features, please refer to the relevant sections of the documentation.

---

## AIGNE Studio

URL: https://www.arcblock.io/en/docs/aigne-studio/

---

## Introduce

URL: https://www.arcblock.io/en/docs/aigne-studio/ai-studio/

## Overview

AI Studio is an AI application development platform based on the Blocklet ecosystem, which can help you:

- No code/low code rapid development AI applications
- Prompt Version Control
- Automated testing prompt
- Fast Release: Easily publish AI applications based on the Blocklet ecosystem
- Collaborative Editing: Team members can collaborate on editing the development prompt

You can also learn more about AI Studio through the following link:

---

## Guide

URL: https://www.arcblock.io/en/docs/aigne-studio/getting-started-z1f81/

## Overview

In this guide, you can learn how to start AI Studio and begin using it.

- [Start AI Studio](/en/docs/aigne-studio/launch/)

---

## Start AI Studio

URL: https://www.arcblock.io/en/docs/aigne-studio/launch/

Before you start, you need to install the DID wallet, you can refer to [https://support.didwallet.io/howToDownload](https://support.didwallet.io/howToDownload) to complete the wallet download and installation.

## Launch AI Studio.

First time using the Blocklet platform? You can directly click the "Launch" button from the [AI Studio](https://store.blocklet.dev/blocklets/z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB) in the Blocklet Store, and run an AI Studio instance in our Serverless.

If you have already run your own Blocklet application, you can also install the AI Studio component by adding components.

[AI Studio](https://store.blocklet.dev/blocklets/z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB)

Want to run Blocklet Server by yourself? You can refer to:

[Welcome](/en/docs/blocklet-developer/welcome/)

---

## AIGNE WebSmith

URL: https://www.arcblock.io/en/docs/aigne-web-smith/

---

## Advanced Features

URL: https://www.arcblock.io/en/docs/aigne-web-smith/advanced-features-c47353/

Once you have mastered the basics of generating and updating your website, you can explore the advanced features of AIGNE WebSmith to gain more granular control and add unique, powerful visual elements. This section covers how to manage your component library and leverage specialized components for more dynamic and engaging pages.

This section provides an overview of advanced capabilities. For detailed instructions, please refer to the specific sub-documents:

::::card-group
::link-card{title="Use Custom Component Libraries" description="Learn how to pull and update the component library that WebSmith uses to construct your website's visual elements." icon="book-open" href="/en/docs/aigne-web-smith/advanced-features-use-custom-component-libraries-c47353/"}
::link-card{title="Use Special Components" description="Discover how to implement powerful, pre-built components like the Terminal Player to create visually rich web pages." icon="box" href="/en/docs/aigne-web-smith/advanced-features-use-special-components-c47353/"}
::::

## Summary

This section serves as a gateway to the more powerful and customizable aspects of AIGNE WebSmith. By learning to manage component libraries and utilize special components, you can significantly enhance the visual appeal and functionality of your generated website.

For a complete list of all available commands and their parameters, consult the [Command Reference](/en/docs/aigne-web-smith/reference-command-c47353/).

---

## Use Custom Component Libraries

URL: https://www.arcblock.io/en/docs/aigne-web-smith/advanced-features-use-custom-component-libraries-c47353/

Websites generated by AIGNE WebSmith are constructed from a library of pre-designed visual elements called components. While WebSmith includes a standard set of components, you can define and manage a <strong>custom component library</strong> using a Pages Kit project. This allows for tailored designs and functionalities specific to your needs.

This section explains how to use the `component pull` command to synchronize your local component library with the one defined in your Pages Kit project.

## Overview of the Component Library

A custom component library is a collection of standardized, reusable page elements tailored for your project. When you generate a website, WebSmith will use your custom components to build the pages, ensuring brand consistency and unique layouts.

Keeping your local library synchronized is important for two main reasons:

::::steps
:::step{title="Access to New Designs"}
As new visual components are designed and added to your Pages Kit project, pulling them into your local library makes them available for the AI to use.
:::

:::step{title="Bug Fixes and Improvements"}
Updates may contain improvements or fixes to existing components, enhancing the quality and appearance of your website.
:::
::::

## Syncing Your Custom Library

The `aigne web component pull` command fetches the latest version of the component library from a specific URL provided by your Pages Kit project.

### Command Syntax

To pull the latest components, use the following command structure:

**Component Pull**

```bash
aigne web component pull --url <your_component_pull_url>
```

You can also use the alias `comp`:

**Component Pull (Alias)**

```bash
aigne web comp pull --url <your_component_pull_url>
```

### Parameters

- **--url** `string` *(required)* — The unique URL for pulling components from your Pages Kit project. This URL contains the necessary project ID and security credentials. You can typically find this URL within your project's settings page in Pages Kit.

### The Update Process

Updating your component library is a straightforward but important process. Follow these steps carefully.

#### Step 1: Run the Pull Command

Execute the command with the specific URL provided by your Pages Kit project.

**Component Pull**

```bash
aigne web component pull --url "https://your-pages-kit/api/projects/your-project-id/components/pull?secret=your-secret&hash=your-hash"
```

The tool will connect to the URL and download the latest component library definition.

#### Step 2: Review the Changes

After a successful download, WebSmith will display a summary of the changes. It will show a comparison between your existing library and the new one, detailing the number of "atomic" (basic) and "composite" (complex) components.

An example of the output might look like this:

```
✅ Pull Components successfully (not saved yet)!
📊 New Components Statistics:
  🔹 Atomic components: 10 (9 → 10)
    • LogoV1 - A component to display a heading and a list of logos...
    • RichText - A RichText component primarily displays the title...
    • NewFeatureCard - A brand new card for features...
  🧩 Composite components: 22 (22 → 22)
    • Logo Wall - Structure - Optional section title...
    • User Review - Structure (top → bottom) - Review Content/Quote...
```

This summary allows you to verify the incoming changes before they are applied.

#### Step 3: Confirm the Update

WebSmith will then prompt you for confirmation before making any permanent changes to your local files.

```
Do you want to update (save) the built-in components file? (y/N)
```

- Press `y` and `Enter` to proceed with the update.
- Press `n` or `Enter` to cancel the operation. No changes will be made.

#### Step 4: Re-generate Your Website

If you confirm the update, WebSmith will perform two critical actions:

::::steps
:::step{title="Save the New Library"}
It overwrites your local `builtin-component-library.yaml` file with the new version.
:::

:::step{title="Clear Generated Content"}
To ensure your website is rebuilt correctly with the new components, it will <strong>delete all previously generated page files</strong> from your workspace and output directories.
:::
::::

Once the process is complete, you will see a confirmation message and a reminder for the next step.

```
💾 New components saved.
🧹 Cleaned previous generated content.
🚀 Next: please run below command to re-generate pages:

  `aigne web generate`
```

You must now run the `generate` command to create your website pages using the updated component library.

## Summary

The `component pull` command is the standard procedure for keeping your local environment's visual building blocks in sync with your custom Pages Kit repository. The process involves pulling the latest library, reviewing the changes, confirming the update, and finally, re-generating your website to apply the new components.

For more information on creating pages, proceed to the [Create Website](/en/docs/aigne-web-smith/guides-create-website-c47353/) section.

---

## Use Special Components

URL: https://www.arcblock.io/en/docs/aigne-web-smith/advanced-features-use-special-components-c47353/

AIGNE WebSmith includes a library of special components designed to add powerful visual and interactive elements to your website with minimal configuration. These pre-built components handle complex functionalities, allowing you to create engaging user experiences efficiently.

This section provides an overview of the available special components and directs you to detailed guides for implementing them. By leveraging these tools, you can significantly enhance the presentation and interactivity of your web pages.

## Available Components

WebSmith offers several advanced components out of the box. The primary components are detailed below. For specific implementation instructions, please refer to the linked sub-pages.

::::card-group
::link-card{title="Terminal Player" description="A component for embedding animated terminal session recordings directly into your web pages. It is ideal for tutorials, command-line tool demonstrations, and technical documentation." icon="terminal" href="/en/docs/aigne-web-smith/advanced-features-use-special-components-terminal-player-c47353/"}
::link-card{title="Latest Updates" description="A component to showcase recent changes, news, or blog posts on your website." icon="file-text" href="/en/docs/aigne-web-smith/advanced-features-use-special-components-latest-updates-c47353/"}
::::

## Summary

Using special components can dramatically improve the visual appeal and functional capabilities of your website.

For detailed instructions on how to use these components, refer to their respective documentation sections.

- [Terminal Player](/en/docs/aigne-web-smith/advanced-features-use-special-components-terminal-player-c47353/)
- [Latest Updates](/en/docs/aigne-web-smith/advanced-features-use-special-components-latest-updates-c47353/)

---

## Latest Updates

URL: https://www.arcblock.io/en/docs/aigne-web-smith/advanced-features-use-special-components-latest-updates-c47353/

The 'Latest Updates' component provides a dynamic way to showcase recent news, blog posts, or announcements on your website. It integrates with Discuss Kit, a blog system, to automatically fetch and display content, keeping your site fresh and demonstrating ongoing activity.

This component is particularly useful for:

- Showcasing new features, updates, or technical articles.
- Providing "Proof & Momentum"—visible, ongoing progress.
- Reinforcing brand transparency and engagement.

## How to Use

To implement the 'Latest Updates' section, you must prepare a data source file and then reference it in your website's generation rules. The process is straightforward and ensures that the AI can correctly locate and render the content.

### Step 1: Prepare the Data File

First, create a YAML file that acts as a data descriptor, telling WebSmith where to fetch the blog content from.

A recommended location for this file is `src/blog-list-data.yaml`.

#### Example Data File

**src/blog-list-data.yaml**

```yaml
blogTitle: "Latest Updates"
blogDescription: "Get the latest updates right here."
blogUrl: "https://www.arcblock.io" # Or your Discuss Kit Blocklet URL
blogLabel: "did-domain"
blogMoreButtonText: "See More"
```

#### Field Descriptions

| Field  | Description  | Required  |
|---|---|---|
| `blogTitle`  | The main title displayed for the section. It is recommended to keep this under 60 characters for clarity.  | Yes  |
| `blogDescription`  | A brief summary that appears under the title, explaining the content of the section.  | Yes  |
| `blogUrl`  | The source URL, usually your Discuss Kit Blocklet. WebSmith automatically extracts titles, summaries, cover images, and dates. The Discuss Kit API must be publicly accessible.  | Yes  |
| `blogLabel`  | An optional filter tag to display content from a specific category. The value should be obtained from your Discuss Kit site (e.g., the `labels` query parameter in the URL).  | No  |
| `blogMoreButtonText`  | The text for an optional "See More" button that can link to your main blog or news page.  | No  |

### Step 2: Register the Data Source

After creating the data file, you must register it so WebSmith can find and use it.

Add the file path to the `sourcesPath` field in your `config.yaml`:

**config.yaml**

```yaml
sourcesPath:
  - src/blog-list-data.yaml
```

If you are updating an existing site, you must also add the file path to `.aigne/web-smith/pages/workspace/website-structure.yaml` under the `sourceIds` section. This ensures WebSmith can locate the new data source during `update` operations.

**.aigne/web-smith/pages/workspace/website-structure.yaml**

```yaml
sourceIds:
  - src/blog-list-data.yaml
```

### Step 3: Define the Section in Generation Rules

Next, instruct the AI on how to use the data source by adding a rule to your WebSmith `config.yaml` file. The rule should specify the section's position, component type, and data source.

#### Example Rule

**config.yaml**

```yaml
rule: Section 2 must render the `Latest Updates` section using `src/blog-list-data.yaml` as immediate proof and momentum.
```

This example rule accomplishes the following:

- <strong>Positioning</strong>: Places the 'Latest Updates' component as the second section on the page.
- <strong>Component Type</strong>: Identifies the section as a "Latest Updates" or "Blog List" type.
- <strong>Data Source</strong>: Points to `src/blog-list-data.yaml` as the source of configuration.

Alternatively, when using the `update` command, you can provide a direct prompt instead of editing the `config.yaml` file:

```
Change section 2 to “Latest Updates” and generate its content using src/blog-list-data.yaml.
```

### Step 4: Generate or Update Your Website

With the data file and generation rule in place, run the appropriate command to have AIGNE WebSmith build or refresh your site. If generating for the first time, use `aigne web generate`. To add a section to an existing site, use `aigne web update` and select the document to add the section.

WebSmith will now automatically load your YAML data, retrieve the latest posts from the specified Discuss Kit URL, and render the 'Latest Updates' section on your website.

## Summary

The 'Latest Updates' component is a powerful tool for keeping your website content current and engaging. By following the simple steps of creating a data file and defining a generation rule, you can automate the process of displaying news and blog posts directly on your site.

For more information on other special components, please refer to the documentation on [Using Special Components](/en/docs/aigne-web-smith/advanced-features-use-special-components-c47353/).

---

## Terminal Player

URL: https://www.arcblock.io/en/docs/aigne-web-smith/advanced-features-use-special-components-terminal-player-c47353/

The Terminal Player is a specialized component used to display interactive, pre-recorded terminal sessions on your website. This component is an effective tool for demonstrating command-line instructions, showcasing software installations, or guiding users through technical processes in a clear and replayable format.

This component utilizes recordings created in the `asciinema` format, which ensures a lightweight, text-based capture of the terminal output.

## Overview of the Process

The workflow for using the Terminal Player can be broken down into a sequence of clear, manageable steps. The process begins with the developer recording a terminal session and concludes with the end-user viewing the interactive playback on the website.

The following diagram illustrates this process:

![Terminal Player](https://media.arcblock.io/lib/be/be2df1d1543db676.w1600.webp)

## Creating a Terminal Recording

To use the Terminal Player, you must first create a recording file. The recommended tool for this is `asciinema`, an open-source command-line utility for recording and sharing terminal sessions.

### Step 1: Install the asciinema CLI

First, install the `asciinema` tool on your local machine. The installation method varies depending on your operating system.

**Installation**

```bash
# On macOS using Homebrew
brew install asciinema

# On Ubuntu/Debian using APT
sudo apt install asciinema

# Using pipx (cross-platform)
pipx install asciinema
```

For additional installation options, please refer to the official [asciinema documentation](https://docs.asciinema.org/).

### Step 2: Record Your Session

Once `asciinema` is installed, you can begin recording a terminal session by executing the `rec` command.

**Recording Command**

```bash
# Start a new recording, which will be saved to 'my-demo.cast'
asciinema rec my-demo.cast
```

After initiating the command, perform all the actions you wish to capture within your terminal. To stop the recording, press `Ctrl+D` or type the `exit` command. A file named `my-demo.cast` will be saved in your current directory. You can verify the playback locally by running `asciinema play my-demo.cast`.

<strong>Important Considerations:</strong>

- <strong>Plan your steps:</strong> The recording captures all actions, including pauses and errors. It is advisable to prepare a script beforehand.
- <strong>Terminal Dimensions:</strong> The player will replicate the column and row dimensions of the terminal used for recording. Ensure your terminal window is sized appropriately to prevent content wrapping or truncation during playback.

### Step 3: Convert the .cast File to JSON

The Terminal Player component requires the recording data to be in a specific JSON format. An online converter is available to simplify this conversion process.

::::steps
:::step{title="Navigate to the Converter:"}
Open the [ArcBlock Terminal Player Converter](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--recording-guide) in your web browser.
:::

:::step{title="Upload Your File:"}
Drag and drop your `.cast` file onto the page.
:::

:::step{title="Preview and Download:"}
The tool will generate a live preview of your recording. After confirming it is correct, download the converted `.json` file.
:::

:::step{title="Add to Project:"}
Place the downloaded JSON file into your website's media or assets directory.
:::
::::

## Using the Recording

Once the JSON recording file is placed in your project's media or assets directory, it becomes available to the AI. There is no need to manually configure the component in a YAML file.

Simply describe the need for a terminal demonstration in your content source files. When you run `aigne web generate` or `aigne web update`, the AI will automatically find the relevant `.json` recording and use the Terminal Player component to display it on your website.

**AIGNE CLI Commands**

```bash
# To generate the website from scratch
aigne web generate

# To update the website with your changes
aigne web update
```

For additional information on recording, you may consult the official [asciinema website](https://asciinema.org/).

## Additional Resources

- [ArcBlock Terminal Player Converter](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--recording-guide)
- [asciinema Documentation](https://docs.asciinema.org/)

---

## Getting Started

URL: https://www.arcblock.io/en/docs/aigne-web-smith/getting-started-c47353/

Use this guide as the fastest path to a working site: install the AIGNE CLI, gather source materials, run `aigne web generate`, approve the plan, and review the generated pages—all in one place.

## See the end-to-end flow

![Getting Started](https://media.arcblock.io/lib/76/76cf186f467012cd.w1600.webp)

## Prerequisites

- <strong>Node.js 20 or newer</strong> (npm is included). Check with `node -v`.
- <strong>AIGNE account</strong> (optional). You can use the hosted models that ship with the AIGNE CLI without adding API keys.
- <strong>Source material</strong> that describes your product or service. For a deeper checklist, read the [Prepare Materials](/en/docs/aigne-web-smith/reference-prepare-materials-c47353/) guide.

## Step 1. Install and verify the AIGNE CLI

Install the AIGNE CLI globally so the `aigne` command is available from any folder:

**Install AIGNE CLI**

```bash
npm install -g @aigne/cli
```

Verify that installation succeeded:

**--help**

```bash
aigne web --help
```

Need the beta channel? Install with `npm install -g @aigne/cli@beta` and run `aigne web upgrade --beta` to pick up the latest agents.

## Step 2. Create a project workspace

Set up a clean directory for your first site and switch into it:

**Create workspace**

```bash
mkdir my-first-websmith-site
cd my-first-websmith-site
```

Copy or create the documents, briefs, and media you want the AI to read inside this folder (or a nearby `sources` directory). Well-defined materials dramatically improve output quality, so spend a few minutes following the [preparation checklist](/en/docs/aigne-web-smith/reference-prepare-materials-c47353/).

## Step 3. Run aigne web generate

From the project directory, start the generator:

**Generate website**

```bash
aigne web generate
```

Because this is a new workspace, WebSmith launches an interactive wizard that captures:

::::steps
:::step{title="Website purpose"}
- e.g., SaaS marketing site, documentation hub, investor update.
:::

:::step{title="Target audiences"}
- developers, customers, investors, etc., so tone and proof match the reader.
:::

:::step{title="Website scale"}
- choose minimal, standard, comprehensive, or let the AI decide.
:::

:::step{title="Languages"}
- pick the primary locale and any translations to produce.
:::

:::step{title="Pages directory"}
- where generated files are stored (defaults to `aigne/web-smith/pages`).
:::

:::step{title="Source paths"}
- directories or files that contain your product knowledge.
:::

:::step{title="Custom rules"}
- constraints such as tone, terminology, or compliance reminders.
:::
::::

Your answers are written to `.aigne/doc-smith/config.yaml` so future runs can reuse them.

## Step 4. Review the configuration

Open the generated config and sanity-check the values, especially `sourcesPath`. Below is a trimmed example:

**config.yaml**

```yaml
projectName: My Awesome Project
projectDesc: This is a project that does amazing things.
pagePurpose:
  - saas
targetAudienceTypes:
  - developers
websiteScale: standard
locale: en
pagesDir: aigne/web-smith/pages
sourcesPath:
  - ./docs
  - ./briefs/product-overview.md
  - ./evidence
rules: >
  Use confident, concrete copy. Highlight 99.99% uptime and SOC 2 compliance.
```

> <strong>Important:</strong> `sourcesPath` controls everything the AI can reference. Point it to the exact directories that contain your briefs, specs, pricing sheets, and proof so the generated copy is accurate.
>

## Step 5. Approve the plan and inspect pages

After reading your config, WebSmith proposes a site map (pages, sections, and key talking points). Approve it to let the AI draft content and assemble the Astro/React templates. When the run finishes you will see:

- Generated files inside the `pagesDir` you selected.
- Logs for each page that show which source files were used.
- Suggestions for next actions (publish, translate, or iterate).

Open the generated pages locally or continue straight to the [Publish Website](/en/docs/aigne-web-smith/guides-publish-website-c47353/) guide to push them live.

## What's next?

::::card-group
::link-card{title="Prepare Materials" description="Build a repeatable content kit so every generation starts with high-quality inputs." icon="folder" href="/en/docs/aigne-web-smith/reference-prepare-materials-c47353/"}
::link-card{title="Create Website" description="Dive deeper into advanced options for the `generate` workflow." icon="wrench" href="/en/docs/aigne-web-smith/guides-create-website-c47353/"}
::link-card{title="Publish Website" description="Turn the generated pages into a live site on WebSmith Cloud or your own infra." icon="rocket" href="/en/docs/aigne-web-smith/guides-publish-website-c47353/"}
::::

---

## Guides

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-c47353/

Need to manage your website day-to-day? This section provides step-by-step guides for common operations like creating your site, publishing updates, managing translations, and customizing the look and feel. Follow these tutorials to keep your website running smoothly.

::::card-group
::link-card{title="Create Website" description="Breaks down the create workflow, including configuration fields, prompts, and ways to validate the output before publishing." icon="plus" href="/en/docs/aigne-web-smith/guides-create-website-c47353/"}
::link-card{title="Update Website" description="Learn how to use the 'update' command to make changes or provide feedback to refine the content on your existing pages." icon="edit" href="/en/docs/aigne-web-smith/guides-update-website-c47353/"}
::link-card{title="Publish Website" description="Explains every publish target, from WebSmith Cloud to fully custom infrastructure, with prerequisites and validation tips." icon="upload" href="/en/docs/aigne-web-smith/guides-publish-website-c47353/"}
::link-card{title="Localize Website" description="Explains how to use the 'translate' command to automatically create different language versions of your website pages." icon="globe" href="/en/docs/aigne-web-smith/guides-localize-website-c47353/"}
::link-card{title="Customize Theme" description="Covers how to use the 'theme' command to generate and apply different visual styles and color schemes to your website." icon="palette" href="/en/docs/aigne-web-smith/guides-customize-theme-c47353/"}
::link-card{title="Manage Preferences" description="Explains how to use the 'prefs' command to view, manage, and clear saved user preferences to customize WebSmith's behavior." icon="settings" href="/en/docs/aigne-web-smith/guides-manage-preferences-c47353/"}
::link-card{title="Cleanup Workspace" description="Shows you how to use the 'clear' command to safely remove generated files, workspace data, or the entire configuration." icon="trash" href="/en/docs/aigne-web-smith/guides-cleanup-workspace-c47353/"}
::link-card{title="Interactive Mode (Beta)" description="Use the interactive mode as a conversational co-pilot to iteratively plan, edit, and polish your site." icon="bot" href="/en/docs/aigne-web-smith/guides-interactive-mode-c47353/"}
::::

## Summary

These guides cover the essential commands for managing your website's lifecycle. For more advanced topics and a complete command listing, please refer to the [Advanced Features](/en/docs/aigne-web-smith/advanced-features-c47353/) and [Reference](/en/docs/aigne-web-smith/reference-c47353/) sections.

---

## Cleanup Workspace

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-cleanup-workspace-c47353/

Use this guide to run `aigne web clear` safely, whether you want to wipe generated pages, reset cached data, or remove authorization tokens before handing off a project.

The `clear` command is a utility for managing your project's workspace (typically the `./.websmith/tmp` directory). It allows you to selectively remove generated files, cached data, and configuration settings. This is particularly useful when you want to start a fresh build, reset your configuration, or remove sensitive authorization data.

Executing the command can be a destructive action. Please ensure you have backed up any important data before proceeding.

## Interactive Clearing

The simplest way to use the command is to run it without any arguments. This will launch an interactive prompt where you can select the specific items you wish to clear.

**Cleanup Workspace**

```bash
aigne web clear
```

This will present a list of available items to remove. You can navigate with the arrow keys, select items with the spacebar, and confirm your selection by pressing Enter.

## Clearable Targets

The following table details the specific items that can be cleared, what they contain, and the command to clear them directly.

| Target Name  | Command Flag  | Description  |
|---|---|---|
| Website Structure  | `websiteStructure`  | Removes the website structure file (`website-structure.yaml`) from the workspace. Your original source content is not affected.  |
| Generated Pages  | `generatedPages`  | Deletes all generated page content from the workspace. This leaves the website structure file intact.  |
| Website Configuration  | `websiteConfig`  | Deletes the main `config.yaml` file. <strong>Caution:</strong> This action is irreversible. You will need to run `aigne web init` to generate a new configuration file.  |
| Authorizations  | `authTokens`  | Deletes the `.env.websmith` file, which stores authentication tokens. After clearing, you will need to re-authorize for operations like publishing.  |
| Deployment Config  | `deploymentConfig`  | Removes only the `appUrl` key from your `config.yaml` file. This is useful for resetting your deployment target without deleting the entire website configuration.  |
| Media File Descriptions  | `mediaDescription`  | Deletes the cached, AI-generated descriptions for your media assets. These will be automatically regenerated on the next run of the `generate` command.  |
| Translation Caches  | `translationCaches`  | Deletes the AI-generated translation caches. These will be regenerated automatically on the next publish.  |

## Non-Interactive Clearing

To bypass the interactive prompt, you can use the `--targets` flag followed by one or more target names. This is useful for scripting or automating cleanup tasks.

### Clearing a Single Target

To clear a single item, specify its name with the `--targets` flag.

**Clear Website Structure**

```bash
aigne web clear --targets websiteStructure
```

### Clearing Multiple Targets

You can provide a space-separated list of targets to clear multiple items at once. The following example clears both the website structure and the generated pages.

**Clear --targets Websitestructure Generatedpages**

```bash
aigne web clear --targets websiteStructure generatedPages
```

## Summary

The `clear` command provides a safe and controlled way to manage your project's generated assets and configuration. Use the interactive mode for guided cleanup or the `--targets` flag for direct, automated control. Always exercise caution, especially when clearing the `websiteConfig`, to avoid unintended data loss.

After clearing your workspace or generated pages, you may want to create the website again. For more details, see [Create Website](/en/docs/aigne-web-smith/guides-create-website-c47353/).

---

## Create Website

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-create-website-c47353/

Use this guide to turn your source material into a live-ready site with a single command. You will inspect the available `aigne web generate` flags, approve the AI-generated sitemap, and understand where the finished pages land on disk.

If you need a quick reference to every flag and alias, run `aigne web -h`; the sample output below is what you should see.

![Output of aigne web -h, showing available flags and aliases](https://media.arcblock.io/lib/5c/5c43d2c28254dc14.w1600.webp)

## Creation Workflow

The `aigne web generate` command initiates the entire website creation process. It reads your configuration, analyzes your source materials, plans the website's structure, generates content for each page, and assembles the final files.

### Usage

To run the generation process, execute the following command in your terminal:

**Create Website**

```bash
aigne web generate
```

You can also use the aliases `gen` or `g`:

**Create Website**

```bash
aigne web gen
```

### What Happens During Generate

When you run the `generate` command, WebSmith performs the following sequence of operations:

::::steps
:::step{title="Load Configuration"}
It first looks for and loads the `config.yaml` file to understand your high-level requirements. If this file doesn't exist, it will automatically initiate a guided setup to create one.
:::

:::step{title="Analyze Sources"}
The AI scans the documents, markdown files, and other materials specified in the `sourcesPath` of your configuration to understand the subject matter.
:::

:::step{title="Plan Website Structure"}
Based on the purpose, audience, and source content, the AI proposes a logical sitemap for your website, outlining all the pages and their hierarchy. You will be prompted to review and approve this structure before content generation begins.
:::
::::

![Reviewing the proposed site structure before approving generation](https://media.arcblock.io/lib/2d/2df83fe441708a5a.w1600.webp)

::::steps
:::step{title="Generate Page Content"}
For each page in the approved structure, the AI generates detailed content, including titles, descriptions, and sections composed of professional components like hero banners, feature lists, and FAQs.
:::

:::step{title="Save Website Files"}
The final, structured content for each page is saved as YAML files in the directory specified by `pagesDir` in your configuration. These files are now ready for publishing.
:::
::::

![Generation run summary showing successful output and next steps](https://media.arcblock.io/lib/a0/a0f6b275e9ffe714.w1600.webp)

### Parameters

The `generate` command accepts several optional parameters to customize its behavior.

- **glossary** `string` — Specifies the path to a glossary file (e.g., @glossary.md). This ensures that project-specific terms are used consistently throughout the generated content.
- **forceRegenerate** `boolean` — If set to true, the command will regenerate all pages from scratch, overwriting any previously generated files. This is useful after making significant changes to the config.yaml file or your source documents.

<strong>Example with parameters:</strong>

**Regenerate Website**

```bash
# Regenerate the entire website using a glossary file
aigne web generate --forceRegenerate --glossary "@glossary.md"
```

## The Configuration File (config.yaml)

The `config.yaml` file is the blueprint for your website. It provides the AI with the necessary context and constraints to build a site that meets your specific needs. This file defines the project, the site's purpose and audience, language settings, and file locations.

Below is a detailed breakdown of the key properties within the `config.yaml` file.

### Configuration Options

- **projectName** `string` *(required)* — The name of your project or website. This is used for metadata and publishing.
- **projectDesc** `string` — A brief description of your project.
- **projectLogo** `string` — A URL or local path to your project's logo.
- **pagePurpose** `array` *(required)* — An array of strings defining the website's primary goals. Examples: landingPage, ecommerce, portfolio, corporate, blog, saas, nonprofit, education, mixedPurpose.
- **targetAudienceTypes** `array` *(required)* — An array of strings identifying the primary audience. Examples: customers, businessOwners, marketers, designers, developers, investors, jobSeekers, students, generalPublic.
- **websiteScale** `string` *(required)* — Defines the desired size and complexity of the website. Options include singlePage, minimal, standard, comprehensive, and aiDecide.
- **rules** `string` — A field for any custom rules or specific instructions for the AI to follow during generation, such as tone of voice, content to exclude, or specific points to emphasize.
- **locale** `string` *(required)* (default: `en`) — The primary language for the website content, specified by a language code (e.g., en, zh, es).
- **translateLanguages** `array` — A list of language codes to translate the website into. For example, ['zh', 'fr'].
- **pagesDir** `string` *(required)* — The local directory path where the generated website page files will be saved.
- **sourcesPath** `array` *(required)* — An array of file paths or glob patterns that point to your source content. The AI will analyze these files to generate the website.

### Example config.yaml

Here is an example of a complete `config.yaml` file with comments explaining each section.

**config.yaml**

```yaml
# Project information for page publishing
projectName: AIGNE WebSmith
projectDesc: AI-driven website generation tool
projectLogo: https://www.aigne.io/image-bin/uploads/bc5afab4e6d282cc7f4aa444e9b9f7f4.svg
projectId: aigne-websmith-docs
projectSlug: aigne-websmith

# =============================================================================
# Website Configuration
# =============================================================================

# Purpose: What's the main outcome you want readers to achieve?
# Available options (uncomment and modify as needed):
#   landingPage     - Landing page / Homepage: Convert visitors into users or customers
#   ecommerce       - E-commerce / Online store: Sell products or services online
#   portfolio       - Portfolio / Showcase: Display creative work, projects, or achievements
#   corporate       - Corporate / Business: Professional business website with company information
#   blog            - Blog / Content site: Share articles, news, and regular content updates
#   saas            - SaaS / Software product: Promote and onboard users to software services
#   nonprofit       - Non-profit / Community: Promote causes, accept donations, engage volunteers
#   education       - Educational / Learning: Provide courses, tutorials, or educational content
#   mixedPurpose    - Multi-purpose website: Comprehensive website covering multiple needs
pagePurpose:
  - saas

# Target Audience: Who will be reading this most often?
# Available options (uncomment and modify as needed):
#   customers        - Customers / End users: People who buy or use your products/services
#   businessOwners   - Business owners / Entrepreneurs: People running businesses looking for solutions
#   marketers        - Marketing teams: People promoting products or managing campaigns
#   designers        - Designers / Creative professionals: People focused on visual design and user experience
#   developers       - Developers / Technical users: People building or integrating technical solutions
#   investors        - Investors / Stakeholders: People evaluating business potential and growth
#   jobSeekers       - Job seekers / Potential employees: People looking for career opportunities
#   students         - Students / Learners: People seeking educational content or resources
#   generalPublic    - General public / Mixed audience: Broad audience with varied interests and backgrounds
targetAudienceTypes:
  - developers

# Website Scale: How many pages should your website have?
# Available options (uncomment and modify as needed):
#   singlePage      - Single Page (only 1 page): All content consolidated into 1 page
#   minimal         - Minimal (2-6 pages): Core pages only - quick to launch
#   standard        - Standard (7-12 pages): Complete website with main sections [RECOMMENDED]
#   comprehensive   - Comprehensive (12+ pages): Full-featured website with detailed sections
#   aiDecide        - Let AI decide: Analyze project complexity and suggest appropriate scale
websiteScale: standard

# Custom Rules: Define specific page generation rules and requirements
rules: 'Maintain a formal and technical tone. Avoid marketing jargon. Focus on practical, step-by-step instructions.'

# Glossary: Define project-specific terms and definitions
# glossary: "@glossary.md"  # Path to markdown file containing glossary definitions

locale: en
# translateLanguages:  # List of languages to translate the pages to
#   - zh  # Example: Chinese translation
#   - en  # Example: English translation

pagesDir: ./aigne-web-smith/pages  # Directory to save generated pages
sourcesPath:  # Source code paths to analyze
  - ./docs/**/*.md
  - ./README.md
defaultDatasources:  # Default datasources included in every page
  - ./media.md
# minImageWidth: Only images wider than this value (in pixels) will be used in page generation
media:
  minImageWidth: 800
```

## Summary

By combining the `generate` command with a well-defined `config.yaml` file, you can efficiently produce a complete website tailored to your exact specifications. This process automates the heavy lifting of site structure and content creation, allowing you to focus on providing high-quality source material.

After generating your website, the next step is to make it available online.

Further reading:

- [Publish Website](/en/docs/aigne-web-smith/guides-publish-website-c47353/)

---

## Customize Theme

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-customize-theme-c47353/

Consistent colors, typography, and spacing make your site feel professional. This guide walks through the exact commands to generate a new WebSmith theme with AI assistance and then apply it to your live site.

AIGNE WebSmith streamlines theme management with two sub-commands:

- <strong>`theme generate`</strong> – capture your design direction and save it as a YAML theme file.
- <strong>`theme apply`</strong> – upload any saved theme to your live site.

Follow the steps below to create and apply a theme end to end.

## Generating a New Theme

1. <strong>Start the generator</strong> **Run command**  ```bash aigne web theme generate ```  <em>Alias:</em> <em>`aigne web theme gen`</em>
2. <strong>Describe the look and feel</strong> The terminal asks for a name, palette, typography, and mood. Provide concrete cues (“dark background, neon accents, rounded headings”) so the AI can shape the design.
3. <strong>Review the preview list</strong> After generation, the theme appears in the local `themes` directory with metadata (primary color, fonts) as shown below. Edit the YAML if you want to fine‑tune tokens.

![Theme generation prompt showing the list of saved themes with metadata](https://media.arcblock.io/lib/81/8141d94b0cb8a9e1.w1600.webp)

## Applying a Theme

After generating one or more themes, the `theme apply` command allows you to select a saved theme and apply it to your website. This command reads your local theme files, presents them as a list, and, upon your confirmation, uploads the selected theme to your site, making the changes live.

### Process

::::steps
:::step{title="Run the Command"}
Execute `aigne web theme apply` in your terminal.
:::

:::step{title="Select a Theme"}
The tool scans the `themes` directory and displays a list of all available themes you have generated. The list includes details like the theme name, primary color, and fonts to help you choose.
:::

:::step{title="Review and Confirm"}
The system will display the target website URL, the currently active theme, and the new theme you have selected. You will be asked for a final confirmation before any changes are made.
:::

:::step{title="Apply to Website"}
Once confirmed, the theme is uploaded and applied to your website. A success message will indicate that the process is complete.
:::
::::

### Usage

To apply an existing theme, use the command below.

```sh
aigne web theme apply
```

You can also specify the website URL directly as a parameter. If omitted, the `appUrl` from your `config.yaml` file will be used.

```sh
aigne web theme apply --appUrl https://your-website.com
```

### Parameters

The `apply` command accepts the following parameters:

- **appUrl** `string` — The full URL of your website. If you do not provide this, the command will use the appUrl defined in your config.yaml configuration file.
- **config** `string` — The location of your configuration file. Defaults to the standard config.yaml path.

### Handling a Locked Theme

To protect a website's live theme from accidental changes, Blocklet applications include a "theme lock" feature. If a theme is locked, any attempt to apply a new one from the terminal will be blocked.

When you try to apply a theme to a locked site, you will encounter a `403 Forbidden` error:

```
Failed to apply theme: Failed to upload theme data: 403 Forbidden
{"code":"internal_server_error","error":"Theme is locked and cannot be modified"}
```

To resolve this, you must unlock the theme through the website's administrative interface:

1. <strong>Log in</strong> to your website's administrative dashboard.
2. Navigate to <strong>WebSite > Theming</strong> in the admin menu.
3. Click the <strong>unlock button</strong> to remove the theme lock.
4. Run `aigne web theme apply` again.

![Unlock Theme Button Interface](https://media.arcblock.io/lib/a7/a7ca31b2bbce4b99.w1600.webp)

By following these steps, you can effectively manage your website's visual identity. For the next step after updating your theme, you may want to review how to [publish your website](/en/docs/aigne-web-smith/guides-publish-website-c47353/).

---

## Interactive Mode（Beta）

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-interactive-mode-c47353/

> <strong>Note:</strong> Interactive mode is currently in beta. While fully functional, you may encounter unexpected behavior. We appreciate your feedback as we continue to improve this experience.
>

Use this guide to launch `aigne web chat`, speak to WebSmith in natural language, and let the assistant trigger generate/update/publish actions on your behalf.

The `chat` command provides an interactive, conversational interface for building and managing your website. Instead of running individual commands like `generate` or `update`, you can describe your needs in plain language, and the AI assistant will guide you through the process. This is an ideal starting point for users who prefer a more guided experience.

## How It Works

Interactive mode is powered by a dedicated AI agent that understands your requests and can use other WebSmith tools to perform tasks. It maintains a memory of your conversation, allowing you to make sequential changes and build on previous actions.

The general workflow follows a simple, conversational loop, as illustrated in the diagram below:

![Interactive Mode（Beta）](https://media.arcblock.io/lib/d3/d3f8fc5f2fa1c2f0.w1600.webp)

## Starting an Interactive Session

To begin, run the `chat` command from your terminal:

**Command**

```bash
aigne web
```

This will launch the assistant, which will greet you and wait for your instructions.

## What You Can Do

The chat assistant can perform most of the core tasks available in the AIGNE WebSmith CLI. You can simply ask it to:

- <strong>Generate a new website</strong>: Describe your website requirements, target audience, and desired style.
- <strong>Update existing content</strong>: Specify which page or section you want to change and provide the new details.
- <strong>Translate pages</strong>: Request translation of specific pages into another language.
- <strong>Publish your site</strong>: Tell the assistant you're ready to publish your website to Pages Kit.
- <strong>Manage files</strong>: Ask to see the current file structure or content of a specific page.

## Example Conversation

Here is an example of how you might use interactive mode to create, modify, and publish a simple website.

**Command Line**

```bash
aigne web

> Welcome to the AIGNE WebSmith interactive assistant!
> How can I help you build your website today?

You:
I need to create a website for a new SaaS product that helps teams manage their projects.

> Of course. Could you please provide a few more details?
> - What are the core features of the product?
> - Who is the target audience?
> - What style should the website have (e.g., business, modern, playful)?

You:
The main features are task tracking, team collaboration, and reporting. The target audience is small to medium-sized business owners. Let's go with a modern business style.

> Thank you. I have enough information to plan the website structure.
> I will now generate the following pages:
> - Home
> - Features
> - Pricing
> - About Us
> - Contact
> ...
> [Generation process starts]
> ...
> Website generation is complete. The files have been saved to the 'output' directory.
> What would you like to do next?

You:
On the homepage, add a section for customer testimonials.

> Understood. I will add a customer testimonials section to the homepage.
> [Update process starts]
> ...
> The homepage has been updated. Is there anything else?

You:
No, that's all for now. Please publish the website.

> I will now publish the website to your configured Pages Kit project.
> [Publishing process starts]
> ...
> Your website has been successfully published.
> You can now exit the chat by typing 'exit'.

You:
exit

> Goodbye!
```

## Exit Interactive Mode

To end your session at any time, type `exit` or `quit` and press Enter.

Interactive mode is a powerful way to manage your entire website lifecycle without needing to memorize specific commands and parameters. For more direct control, you can always use the standard commands detailed in the following sections.

### Further Reading

- [Create Website](/en/docs/aigne-web-smith/guides-create-website-c47353/)
- [Update Website](/en/docs/aigne-web-smith/guides-update-website-c47353/)
- [Publish Website](/en/docs/aigne-web-smith/guides-publish-website-c47353/)

---

## Localize Website

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-localize-website-c47353/

Use this guide to run `aigne web translate`, select the pages and languages you want, and save localized versions that are ready to publish alongside your primary site.

AIGNE WebSmith provides a powerful and straightforward way to automatically translate your website content into multiple languages, enabling you to reach a global audience with minimal effort. The `translate` command uses AI to generate high-quality translations for your existing pages.

This document will guide you through the process of translating your content, from basic interactive usage to more advanced options using command-line parameters.

## How Translation Works

The translation process is designed to be simple and efficient. When you run the `translate` command, WebSmith performs the following steps:

::::steps
:::step{title="Identifies Source Content"}
It loads your existing website structure and content, determining the primary language from your configuration.
:::

:::step{title="Selects Pages"}
You can specify which pages to translate. If you don't, it will present an interactive list of all available pages for you to choose from.
:::

:::step{title="Chooses Target Languages"}
You can provide a list of target languages. If you don't, it will display a list of supported languages for you to select.
:::

:::step{title="Generates Translations"}
The AI processes the content of each selected page and generates a translated version for every chosen language. It can use an optional glossary to ensure consistent terminology.
:::

:::step{title="Saves Translated Files"}
The newly translated pages are saved into language-specific directories, ready for you to review and publish.
:::
::::

## Basic Usage

For the most straightforward approach, you can run the command without any parameters. WebSmith will guide you through the process with interactive prompts.

Run the following command in your terminal:

**Localize Website**

```bash
aigne web translate
```

![Interactive prompt showing multiple languages selected for translation](https://media.arcblock.io/lib/0a/0a11eced20ec5faa.w1600.webp)

You will be prompted to:

1. Select the pages you wish to translate (use the spacebar to select and enter to confirm).
2. Select the target languages from a list of supported options.

Once you've made your selections, the AI will begin the translation process.

## Command Parameters

For more control and for use in automated scripts, you can use the following command-line parameters.

- **--pages** `array` — An array of page paths to translate. If omitted, you will be prompted to select pages interactively. For example: --pages /about /contact
- **--langs** `array` — An array of language codes to translate to. If omitted, you will be prompted to select languages interactively. See the table below for a full list of supported languages.
- **--glossary** `string` — A glossary of specific terms to ensure consistent terminology during translation. You can provide a string of key-value pairs or reference a file path using the @ prefix (e.g., @./glossary.txt).
- **--feedback** `string` — Provide feedback to the AI to refine and improve existing translations. This is useful for making corrections or adjusting the tone.

## Examples

### Translate Specific Pages into Multiple Languages

This command translates the `/about-us` and `/services/main` pages into Japanese and French without interactive prompts.

**Translate Specific Pages**

```bash
aigne web translate --pages /about-us /services/main --langs ja fr
```

### Using a Glossary for Consistent Terminology

To ensure that your brand name "WebSmith" and the term "SaaS" are translated consistently into Spanish, you can use the `--glossary` parameter.

**Translate With Glossary**

```bash
aigne web translate --langs es --glossary "WebSmith:WebSmith AI,SaaS:Software como Servicio"
```

For a larger glossary, it is more practical to use a file. Create a file named `glossary.txt` with your terms, and then reference it.

**Translate With Glossary File**

```bash
aigne web translate --langs de --glossary @./glossary.txt
```

## Supported Languages

The following table lists all languages currently available for translation.

| Language  | Code  |
|---|---|
| English  | `en`  |
| Chinese (Simplified)  | `zh`  |
| Chinese (Traditional)  | `zh-TW`  |
| Japanese  | `ja`  |
| French  | `fr`  |
| German  | `de`  |
| Spanish  | `es`  |
| Italian  | `it`  |
| Russian  | `ru`  |
| Korean  | `ko`  |
| Portuguese  | `pt`  |
| Arabic  | `ar`  |

After translating your content, the next logical step is to make it available to your users. Learn how to deploy your multilingual site in the [Publish Website](/en/docs/aigne-web-smith/guides-publish-website-c47353/) section.

---

## Manage Preferences

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-manage-preferences-c47353/

Use this guide to configure `aigne web prefs`, including how to list saved rules, toggle them on or off, and remove entries you no longer need.

AIGNE WebSmith learns from your feedback to refine how it generates and updates your website. These learned instructions are stored as user preferences. The `prefs` command provides a way to view, manage, and clear these saved preferences, giving you full control over the AI's behavior.

Managing your preferences ensures that the AI consistently adheres to your specific style guides, content requirements, and structural conventions over time.

## Listing Preferences

To view all your currently saved preferences, use the `list` command. This command displays a table of all preference rules, including their ID, active status, scope, and the rule itself.

**List Preferences**

```bash
aigne web prefs list
```

You can also use the alias `ls`:

**List Preferences**

```bash
aigne web prefs ls
```

### Example Output

The output will be a formatted table, making it easy to review your saved rules.

| ID  | Active  | Scope  | Rule  |
|---|---|---|---|
| pref_a1b2c3d4  | true  | page  | Write in a formal, professional tone.  |
| pref_e5f6g7h8  | true  | structure  | Do not generate pages or sections for outdated 'Legacy API Reference'.  |
| pref_i9j0k1l2  | false  | theme  | Healthcare websites must use warm color tones.  |

## Toggling a Preference

If you want to temporarily disable a preference without permanently deleting it, you can use the `toggle` command. This command switches the `active` status of a rule. To toggle a specific rule, you must provide its unique ID using the `--id` parameter.

**Toggle Preference**

```bash
aigne web prefs toggle --id <PREFERENCE_ID>
```

You can also use the alias `t`:

**Toggle Preference**

```bash
aigne web prefs t --id <PREFERENCE_ID>
```

### Example

To deactivate the theme preference from the example above:

**Prefs Toggle --id Pref_i9j0k1l2**

```bash
aigne web prefs toggle --id pref_i9j0k1l2
```

Running `aigne web prefs list` again would show `pref_i9j0k1l2` as `false`. Running the toggle command on the same ID again would reactivate it.

## Removing a Preference

To permanently delete a preference that is no longer needed, use the `remove` command. This action is irreversible. You must specify the rule to delete by providing its ID via the `--id` parameter.

**Remove Preference**

```bash
aigne web prefs remove --id <PREFERENCE_ID>
```

You can also use the alias `rm`:

**Remove Preference**

```bash
aigne web prefs rm --id <PREFERENCE_ID>
```

### Example

To permanently remove the page preference from the example above:

**Prefs Remove --id Pref_a1b2c3d4**

```bash
aigne web prefs remove --id pref_a1b2c3d4
```

The specified preference will be removed from your `preferences.yml` file.

## Understanding Preference Scopes

Preferences are applied based on their assigned `scope`, which determines the context in which a rule is triggered.

| Scope  | Description  |
|---|---|
| <strong>global</strong>  | Applies to all stages of generation and content refinement. Use for universal style or content rules.  |
| <strong>structure</strong>  | Applies only when planning or updating the website's structure (e.g., adding, removing pages).  |
| <strong>page</strong>  | Applies when generating or refining the content of individual pages.  |
| <strong>translation</strong>  | Applies only during the content translation process.  |
| <strong>theme</strong>  | Applies when generating or modifying the website's visual theme, such as colors and fonts.  |

## Summary

The `prefs` command is an essential tool for customizing and controlling the long-term behavior of AIGNE WebSmith. By listing, toggling, and removing preferences, you can maintain a clean and effective set of rules that ensures the AI consistently produces results aligned with your project's specific needs.

---

## Publish Website

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-publish-website-c47353/

Once your website is generated, the final step is to make it accessible online. This guide covers the various methods to publish your site using AIGNE WebSmith, ensuring you can choose the option that best fits your technical and budget requirements.

The `aigne web publish` command is the primary tool for deploying your generated website files. Depending on your needs, you can deploy to the free WebSmith Cloud, integrate with your own existing infrastructure, or set up a new dedicated website.

### Publishing Destinations

WebSmith provides three distinct publishing targets. For detailed step-by-step instructions, please refer to the specific guides for each option.

::::card-group
::link-card{title="To WebSmith Cloud" description="Publish to our free, managed hosting platform. Ideal for open-source projects, personal sites, or community sharing." icon="cloud" href="/en/docs/aigne-web-smith/guides-publish-website-to-websmith-cloud-c47353/"}
::link-card{title="To Existing Website" description="Integrate and deploy the generated pages directly onto your current, self-managed website infrastructure." icon="server" href="/en/docs/aigne-web-smith/guides-publish-website-to-existing-website-c47353/"}
::link-card{title="To New Dedicated Website" description="Create and publish to a new, fully-managed website with a custom domain and professional hosting. This is a paid service." icon="globe" href="/en/docs/aigne-web-smith/guides-publish-website-to-new-dedicated-website-c47353/"}
::::

### General Process

Regardless of the destination, the publishing process is initiated with a single command. The tool will then guide you through any necessary authentication or configuration steps.

1. <strong>Generate Your Website</strong>: Before publishing, ensure your website has been created using the `aigne web generate` command.
2. <strong>Run the Publish Command</strong>: Execute the following command in your terminal: **aigne web publish**  ```sh aigne web publish ```
3. <strong>Follow Interactive Prompts</strong>: The CLI will present you with the available publishing options. If you haven't specified a target, you will be asked to select one. For first-time connections to a service, a browser window will open for authentication. ![WebSmith Publish Options](https://media.arcblock.io/lib/93/935785420285cb10.w1600.webp)
4. <strong>Validate Deployment</strong>: After the command completes, it will output a confirmation message and the live URLs for your published pages. It is recommended to visit these links to verify that the deployment was successful and the website appears as expected. ![Successful Publish Output](https://media.arcblock.io/lib/ee/ee30758408f794f2.w1600.webp)

### Summary

Publishing your website is a straightforward process handled by the `aigne web publish` command. By offering multiple deployment targets, WebSmith ensures flexibility for various use cases.

For specific instructions on each publishing method, refer to the detailed guides:

- [To WebSmith Cloud](/en/docs/aigne-web-smith/guides-publish-website-to-websmith-cloud-c47353/)
- [To Existing Website](/en/docs/aigne-web-smith/guides-publish-website-to-existing-website-c47353/)
- [To New Dedicated Website](/en/docs/aigne-web-smith/guides-publish-website-to-new-dedicated-website-c47353/)

---

## To Existing Website

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-publish-website-to-existing-website-c47353/

This guide shows you how to publish to an ArcBlock-powered website you already operate. Publishing to your own infrastructure gives you complete control over hosting, integration, and deployment. Before proceeding, ensure your website is compatible and properly configured.

## Prerequisites

To successfully publish to your own website, the following conditions must be met:

::::steps
:::step{title="A Generated Website:"}
You must have already generated your website pages using the `aigne web generate` command. The generated content should be present in your project's output directory.
:::

:::step{title="A Blocklet Server-Powered Website:"}
Your target website must be a running Blocklet application. AIGNE WebSmith integrates directly with the Blocklet Server environment.
:::

:::step{title="Required Component:"}
The <strong>Pages Kit</strong> component must be installed and running on your target website. This component provides the necessary APIs for AIGNE WebSmith to upload and manage your content.
:::
::::

If your website is not yet set up, you can acquire the necessary components from the Blocklet Store:

- [Install Pages Kit on your website](https://store.blocklet.dev/blocklets/z8iZiDFg3vkkrPwsiba1TLXy3H9XHzFERsP8o)

## Publishing Process

The publishing process involves running a command, selecting the appropriate option, providing your website's URL, and authorizing the AIGNE WebSmith CLI to connect to your site.

### Step 1: Initiate the Publish Command

Begin the process by running the `publish` command in your terminal from your project directory.

**Publish Website**

```bash
aigne web publish
```

### Step 2: Select Publishing Option

When prompted for a destination, choose <strong>Your existing website</strong>.

![Prompt showing the “Your existing website” option selected](https://media.arcblock.io/lib/37/37bb741556b9f11c.w1600.webp)

### Step 3: Provide Your Website URL

Provide the full URL of the site that already runs Pages Kit when the terminal prompt asks for it.

![Prompt requesting the target website URL](https://media.arcblock.io/lib/b2/b29df027c128a1b5.w1600.webp)

### Step 4: Authorize the Publish Command

For the first connection to a new website, the terminal command requires your authorization to publish content. This is a one-time setup process for each website.

::::steps
:::step{title="Browser Authentication:"}
Your default web browser automatically opens a page so you can grant the publish command access.
:::

:::step{title="Log In:"}
You will be prompted to log in to your website using your DID Wallet.
:::

:::step{title="Approve Connection:"}
After logging in, you must approve the request from "AIGNE WebSmith" to access your site. The request will ask for permissions to manage pages.
:::
::::

Once approved, a secure access token is generated and stored locally in your home directory (`~/.aigne/web-smith-connected.yaml`). This token will be used for all subsequent publish operations to this specific URL, so you will not need to repeat the authorization step.

![Service authorization screen confirming WebSmith access](https://media.arcblock.io/lib/63/635df8119def0e1a.w1600.webp)

### Step 5: Await Confirmation

After authorization, the terminal command proceeds to:

1. Bundle your generated page files and assets.
2. Upload all referenced media files.
3. Publish the page content to your website.

Upon successful completion, a confirmation message will be displayed in the terminal, including the live URLs for your newly published pages.

![Terminal output confirming page and asset upload success](https://media.arcblock.io/lib/ee/ee30758408f794f2.w1600.webp)

## Troubleshooting

If you encounter an error during the publishing process, refer to the common issues below.

- <strong>Error: "The provided URL is not a valid website on ArcBlock platform"</strong>
-
  - <strong>Cause:</strong> The URL you entered does not point to a valid Blocklet application.
  - <strong>Solution:</strong> Verify that the URL is correct and that the website is running. Ensure you have included the correct protocol (e.g., `https://`).
- <strong>Error: "This website does not have required components for publishing"</strong>
-
  - <strong>Cause:</strong> The target website is a valid Blocklet but is missing the required "Pages Kit" component.
  - <strong>Solution:</strong> Install the Pages Kit component on your website. You can install [here](https://store.blocklet.dev/blocklets/z8iZiDFg3vkkrPwsiba1TLXy3H9XHzFERsP8o).
- <strong>Error: "Unable to connect" or "Failed to obtain access token"</strong>
-
  - <strong>Cause:</strong> This typically indicates a network issue, or the target server is unavailable. It can also occur if you reject the authorization request in your browser.
  - <strong>Solution:</strong> Check your internet connection, ensure the website URL is correct and accessible, and re-run the `aigne web publish` command, making sure to approve the authorization request.

After successfully publishing, you can manage your content further. To make changes to existing pages, see [Update Website](/en/docs/aigne-web-smith/guides-update-website-c47353/).

---

## To New Dedicated Website

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-publish-website-to-new-dedicated-website-c47353/

This guide walks you through creating and publishing to a brand-new dedicated website. This paid service provisions a fully managed hosting environment with custom domain support and dedicated resources—perfect for professional projects. The entire process is automated: run the command, complete the one-time setup and payment, and your website goes live.

## Process Overview

Publishing to a new dedicated website involves a sequence of automated steps handled by the `publish` command. The command interfaces with a deployment service to provision and configure all necessary resources.

The workflow is as follows:

::::steps
:::step{title="Initiation"}
The user runs the `aigne web publish` command.
:::

:::step{title="Option Selection"}
The user chooses the "New dedicated website" option from the interactive prompt.
:::

:::step{title="Confirm Assets"}
The user is prompted to confirm whether to include branding, navigations, and locale settings in the deployment.
:::

:::step{title="Payment & Provisioning"}
The user is directed to a secure web page to complete payment. The system then automatically sets up the website hosting and environment.
:::

:::step{title="Content Deployment"}
AIGNE WebSmith uploads and publishes the generated pages to a default project on the newly created website.
:::

:::step{title="Confirmation"}
The user receives the live URL for the new website.
:::
::::

## Step-by-Step Instructions

To publish your website, follow these steps precisely.

### 1. Initiate the Publish Command

First, ensure your website pages have been generated using the `aigne web generate` command. Once your content is ready in the output directory, execute the following command in your terminal:

**Publish Website**

```bash
aigne web publish
```

### 2. Select the Publishing Option

When the terminal lists publishing targets, choose <strong>New dedicated website</strong> and confirm.![Prompt showing the “New dedicated website” option highlighted](https://media.arcblock.io/lib/8a/8aafb31d05a6eb7e.w1600.webp)

### 3. Confirm Additional Assets

After selecting the dedicated option, the terminal asks whether to include locales, navigation, and branding. Accept the default “Yes” so your new site launches fully configured.

![Prompt asking whether to include locales, navigation, and branding](https://media.arcblock.io/lib/b0/b0bfe4d2a2714ae1.w1600.webp)

### 4. Complete the Setup and Payment

After selecting the option, the automated setup process will begin:

::::steps
:::step{title="Payment"}
A message will appear in your terminal indicating that the payment process is starting. A secure payment link will be opened in your default web browser.
:::
::::

![Checkout screen confirming payment for the dedicated website](https://media.arcblock.io/lib/e5/e5d22e10373c2d04.w1600.webp)

::::steps
:::step{title="Provisioning"}
After payment completes, WebSmith resumes automatically. The terminal waits for the service to be provisioned, started, and verified—no further action is required on your part.
:::
::::

![Payment confirmation and success message](https://media.arcblock.io/lib/70/70af154c6a1840bc.w1600.webp)

::::steps
:::step{title="Completion"}
When the setup is complete, the terminal displays the live URL plus a subscription-management link.
:::
::::

![Terminal output showing provisioning progress and the live URL](https://media.arcblock.io/lib/71/713f433202bad291.w1600.webp)

### 5. Authorize the Hosting Service

Before WebSmith can upload content, approve the publish permission request. The terminal launches a browser, you grant access, and the resulting token is saved for future runs.

![Service authorization screen confirming WebSmith access](https://media.arcblock.io/lib/63/635df8119def0e1a.w1600.webp)

### 6. Automatic Content Publishing

Once the site is provisioned and authorization succeeds, AIGNE WebSmith uploads your generated pages and media assets automatically.

![Terminal output confirming page and asset upload success](https://media.arcblock.io/lib/ee/ee30758408f794f2.w1600.webp)

## Resuming an Incomplete Setup

If a previous attempt to create a dedicated website was initiated but not completed (e.g., the payment process was abandoned), the system will save the session details. The next time you run `aigne web publish`, you will see an additional option to resume the process.

![Prompt showing option to resume previous website setup](https://media.arcblock.io/lib/93/935785420285cb10.w1600.webp)

Selecting this "Resume" option allows you to continue from where you left off without needing to start over or pay again if the payment was already processed. The system will use the saved `checkoutId` to restore the previous session and complete the website setup.

## Summary

You have successfully published your project to a new, dedicated website. Your content is now live and accessible at the provided URL. To make changes, you can either update the content with `aigne web update` or regenerate the entire site structure with `aigne web generate`, followed by another `aigne web publish` command. The system will use the saved configuration to publish updates to the same website.

---

## To WebSmith Cloud

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-publish-website-to-websmith-cloud-c47353/

This guide walks you through publishing to WebSmith Cloud—a free hosting service that makes your website publicly accessible without managing any infrastructure. It's the recommended starting point for new users and perfect for open-source projects, portfolios, or community-focused sites.

## Prerequisites

Before proceeding with the publication process, ensure that you have already generated your website's pages. If you have not completed this step, please do so by running the following command:

**Generate Website**

```bash
aigne web generate
```

## Publishing Procedure

The publishing process is initiated through a single command. The system will then guide you through the necessary selections and authorizations.

### Step 1: Execute the Publish Command

Open your terminal, navigate to your project's root directory, and execute the `publish` command.

**Publish Website**

```bash
aigne web publish
```

You can also use the aliases `pub` or `p`.

### Step 2: Select the Publishing Platform

After executing the command, you will be presented with a list of publishing options. Select <strong>WebSmith Cloud</strong> to use the free hosting option.

![Prompt showing WebSmith Cloud selected as the publish destination](https://media.arcblock.io/lib/de/deba2c42f80e591d.w1600.webp)

### Step 3: Authorize AIGNE WebSmith (First-Time Setup Required)

If this is your first time publishing to WebSmith Cloud, the command-line tool needs to be authorized to publish on your behalf. This is a one-time security procedure.

1. A secure authentication URL will automatically open in your default web browser.
2. You will be prompted to log in to your account and approve the connection request from "AIGNE WebSmith".
3. Once you approve, you can close the browser tab and return to the terminal.

The tool will securely store your authorization credentials, so you will not need to repeat this step for subsequent publications.

![Browser window requesting authorization for the WebSmith Cloud deployment](https://media.arcblock.io/lib/8d/8ddf5f5d4dafa4ec.w1600.webp)

### Step 4: Await Publication

The terminal now handles the entire publication process automatically. This includes:

- Bundling your page and content files.
- Uploading all associated media assets.
- Deploying the files to the WebSmith Cloud servers.

This process may take a few minutes, depending on the size of your website.

## Reviewing Your Live Website

Upon successful completion, the terminal displays a confirmation message. This message includes the total number of pages and assets published, along with the direct URLs to access your live website.

![Terminal output confirming page and asset upload success](https://media.arcblock.io/lib/ee/ee30758408f794f2.w1600.webp)

You can now visit these URLs in your web browser to view your published website.

You have successfully published your website to WebSmith Cloud. If you need to make changes, you can modify your content and run the `publish` command again, or use the `update` command for more specific modifications. For more details, see [Update Website](/en/docs/aigne-web-smith/guides-update-website-c47353/).

For alternative deployment targets, refer to the following guides:

- [To Existing Website](/en/docs/aigne-web-smith/guides-publish-website-to-existing-website-c47353/)
- [To New Dedicated Website](/en/docs/aigne-web-smith/guides-publish-website-to-new-dedicated-website-c47353/)

---

## Add Page

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-update-website-add-page-c47353/

Expanding your website is straightforward with AIGNE WebSmith. This guide explains how to use the `aigne web add-page` command to seamlessly integrate new pages into your site's structure, automatically updating content and internal links.

The `aigne web add-page` command provides an interactive way to expand your website. It allows you to describe new pages in natural language, and WebSmith handles the process of creating the page, generating its content, and intelligently updating existing pages with relevant links to the new content.

## Command Usage

To start adding pages, navigate to your project's root directory and run the following command:

**aigne web add-page**

```sh
aigne web add-page
```

Alternatively, you can use the shorter alias `add`:

**aigne web add**

```sh
aigne web add
```

## Process

When you run the `add-page` command, WebSmith initiates a comprehensive, automated workflow. The process is broken down into the following steps:

### 1. Add New Pages

The command first prints the current sitemap, giving you a clear overview of your existing pages. You are then prompted to describe the page you wish to add, specifying its title and location (e.g., "add a pricing page under the main services page"). You can add multiple pages in a single session. After each addition, the tool displays the updated structure and prompts for the next one. To finish adding pages, simply press Enter at an empty prompt. WebSmith then generates the content for each new page based on your project's source materials. The following is a use case for adding a page:

**Add 'Team' and 'Careers' pages**

```text
- My SaaS Platform [/home]
  - Features [/features]
  - About Us [/about]

You can add a new page.
  • e.g. 'add an FAQ page under the About Us page'

Press Enter to finish: add a 'Team' page under '/about'
- My SaaS Platform [/home]
  - Features [/features]
  - About Us [/about]
    - Team [/about/team]

You can continue adding pages, or press Enter to finish: add a 'Careers' page under '/about'
```

### 2. Review Pages for Link Insertion

After the new pages are created, WebSmith analyzes your existing content to identify relevant places to insert links to your new content. This ensures seamless navigation and helps users discover the new pages. The system will present you with a list of pages where links can be added, allowing you to review and confirm the changes before they are applied. Here is a use case for reviewing pages for link insertion:

**Reviewing Link Suggestions**

```text
? Select pages that need new links added (all selected by default, press Enter to confirm, or unselect all to skip):
  ◉ About Us (/about)
  ◯ My SaaS Platform (/home)

Do you want to proceed with these changes? (Y/n)
```

### 3. Output Summary

Once the structure is finalized and links are inserted, a summary report is displayed. This report lists the new pages created and any existing pages that were updated with new links. If your site uses multiple languages, the new pages and updated links are automatically included in the translation workflow. The following is a use case for the output summary:

**Final Summary**

```text
---
📊 Summary

✨ Newly Generated Pages:
   Total: 2 page(s)

   1. /about/team
      Title: Our Team
      Description: Meet the dedicated team behind our project, driving innovation...

🔗 Pages Updated with New Links:
   Total: 1 page(s)

   1. /about
      Added links to: /about/team
```

## Next Steps

::::card-group
::link-card{title="Update Page" description="Learn how to refine the text and details on individual pages using natural language commands." icon="file-text" href="/en/docs/aigne-web-smith/guides-update-website-update-page-c47353/"}
::link-card{title="Remove Page" description="Learn how to remove an existing page from your website structure." icon="file-minus" href="/en/docs/aigne-web-smith/guides-update-website-remove-page-c47353/"}
::::

---

## Update Website

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-update-website-c47353/

Use this guide to select the right update workflow and then dive into the detailed sub-guides for structure or page-level changes.

Once your website is generated, you will inevitably need to make changes. AIGNE WebSmith provides a clear and structured approach to keeping your site current. Updates typically fall into two categories: modifying the overall structure of your site or refining the content within individual pages.

This section provides a high-level overview of both processes. For detailed, step-by-step instructions, please refer to the specific sub-documents linked below.

::::card-group
::link-card{title="Update Page" description="Learn how to refine the text and details on individual pages using natural language commands." icon="file-text" href="/en/docs/aigne-web-smith/guides-update-website-update-page-c47353/"}
::link-card{title="Add Page" description="Learn how to add a new page to your website structure." icon="file-plus" href="/en/docs/aigne-web-smith/guides-update-website-add-page-c47353/"}
::link-card{title="Remove Page" description="Learn how to remove an existing page from your website structure." icon="file-minus" href="/en/docs/aigne-web-smith/guides-update-website-remove-page-c47353/"}
::link-card{title="Manage Update History" description="Review everything the `history` command captured so you can explain what changed and when." icon="clock" href="/en/docs/aigne-web-smith/guides-update-website-manage-update-history-c47353/"}
::::

## Summary

By separating structural adjustments, page-level refinements, and the audit trail, WebSmith offers a logical and efficient workflow for managing your website.

After making your desired changes, the next step is often to make them live. For guidance on this, see the [Publish Website](/en/docs/aigne-web-smith/guides-publish-website-c47353/) article.

---

## Manage Update History

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-update-website-manage-update-history-c47353/

Use this guide to audit everything WebSmith has changed. The `aigne web history` command records every generate or update action, so you always know what changed, when it happened, and why feedback was applied.

This guide lives inside the broader <strong>Update Website</strong> workflow. Run it whenever you need a paper trail before publishing, reviewing with teammates, or rolling back edits.

## View the history log

Show the entire update log (most recent first) with:

**View History Log**

```bash
aigne web history view
```

Aliases `log` and `list` produce the same output:

**View History Log (Alias)**

```bash
aigne web history log
```

If no updates exist yet, WebSmith prints `No update history found`.

## Understand each entry

Every line describes one change event and follows the same structure.

| Field  | Description  |
|---|---|
| <strong>Short hash</strong>  | Deterministic identifier derived from the timestamp. Use it when discussing a specific update with your team.  |
| <strong>Date</strong>  | Relative timestamp (for example, `5 minutes ago` or `2 days ago`). Entries older than a week show the calendar date.  |
| <strong>Operation</strong>  | `structure_update` for sitemap changes or `page_update` for individual page edits.  |
| <strong>Page path</strong>  | Only shown for `page_update` entries and appears in parentheses (such as `(about-us)`).  |
| <strong>Feedback</strong>  | The summary you provided when running `aigne web update`, captured so future readers understand the intent.  |

### Sample output

```text
📜 Update History

e5c7a91 5 minutes ago   page_update (about-us): Refined the company mission statement
a3b4f8e 2 hours ago     page_update (services): Added new section for consulting services
1d9c0b2 1 day ago       structure_update: Added a new "Careers" page to the main menu
f4e5a67 3 days ago      page_update (contact): Updated the main office phone number
```

Use the history log before publishing to confirm which edits are about to go live, or after publishing to answer stakeholder questions about when something changed.

## Related workflows

- [Update Structure](/en/docs/aigne-web-smith/guides-update-website-update-structure-c47353/) – regenerate navigation and site maps.
- [Update Page](/en/docs/aigne-web-smith/guides-update-website-update-page-c47353/) – refine copy on individual pages.

---

## Remove Page

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-update-website-remove-page-c47353/

Need to clean up your website's structure? This guide explains how to use the `aigne web remove-page` command to safely delete pages, automatically find any broken links this creates, and regenerate the affected content to maintain site integrity.

## Overview

The `remove-page` command provides an interactive way to remove one or more pages from your website. A key feature of this command is its ability to detect and repair broken internal links that result from page deletion. After you remove pages, WebSmith automatically scans the remaining content for any links that pointed to the deleted pages. It then prompts you to regenerate the affected pages, ensuring your site's navigation remains consistent and error-free.

This process helps maintain a clean and professional website by preventing users from encountering dead links.

## The Process

To start the process, run the following command in your terminal:

**aigne web remove-page**

```sh
aigne web remove-page
```

You can also use the aliases `remove` or `rm`:

**aigne web rm**

```sh
aigne web rm
```

### Step 1: Select Pages to Remove

The command will display a list of all pages in your current website structure. You can navigate this list using the arrow keys and select the pages you wish to remove by pressing the spacebar.

**Select pages to remove**

```text
? Select pages to remove (Press Enter with no selection to finish):
❯ ◯ Smart Video Streaming Credit Service [/home]
  ◉ About the Project [/about]
  ◯ Frequently Asked Questions [/about/faq]
```

Once you have selected all the pages you want to delete, press `Enter` to confirm. If you decide not to remove any pages, you can press `Enter` without making a selection to exit the process. The tool will then ask for confirmation before proceeding with the deletion.

### Step 2: Automatic Link Correction (Optional)

After removing the selected pages, WebSmith scans your remaining pages for any internal links that now point to non-existent content.

If broken links are found, you will be presented with a list of the affected pages. By default, all of these pages are selected to be fixed. You can review the list and press `Enter` to allow WebSmith to regenerate these pages, automatically removing the invalid links. If you prefer to handle the broken links manually, you can unselect all pages to skip this step.

**Select pages to fix**

```text
? Select Pages with Invalid Links to Fix (all selected by default, press Enter to confirm, or unselect all to skip):
❯ ◉ Home (home.md)
    Invalid Links(1): /about
```

### Step 3: Review the Summary

Once the process is complete, a summary will be displayed in the terminal. This summary provides:

- A list of all pages that were successfully removed.
- A list of all pages that were regenerated to fix broken links.

**Summary of remove page operation**

```text
---
📊 Summary

🗑️  Removed Pages:
   Total: 1 page(s)

   1. /about

✅ Pages fixed (Removed invalid links):
   Total: 1 page(s)

   1. /home
      Title: Home
      Invalid links fixed: /about
```

This ensures you have a clear record of all changes made to your website structure and content.

## Summary

The `aigne web remove-page` command is a reliable tool for maintaining your website's structure. It not only simplifies the process of deleting pages but also includes an intelligent link-checking feature to preserve the integrity of your site's navigation.

For related tasks, see the following guides:

::::card-group
::link-card{title="Add Page" description="Learn how to add new pages to your website structure." icon="file-plus" href="/en/docs/aigne-web-smith/guides-update-website-add-page-c47353/"}
::link-card{title="Update Page" description="Refine the content and details within an individual webpage." icon="edit" href="/en/docs/aigne-web-smith/guides-update-website-update-page-c47353/"}
::::

---

## Update Page

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-update-website-update-page-c47353/

Use this guide when you need to run `aigne web update` against a single page—rewriting sections, inserting new modules, reordering blocks, or trimming obsolete content—without changing the rest of the site.

This process is distinct from modifying the overall site map. For instructions on adding, removing, or reorganizing pages, refer to the [Update Structure](/en/docs/aigne-web-smith/guides-update-website-update-structure-c47353/) guide.

## The Update Process

Content updates are initiated using the `aigne web update` command. The process is interactive, allowing you to provide feedback in natural language, which WebSmith then converts into structured changes on the selected page.

**Update Page**

```bash
aigne web update
```

The command can also be invoked with its alias, `up`.

The standard workflow is as follows:

::::steps
:::step{title="Execute the Command"}
Run `aigne web update`.
:::

:::step{title="Select Page"}
WebSmith presents a list of existing pages. Select the single page you wish to modify.
:::

:::step{title="Provide Feedback"}
Enter natural language instructions describing the changes you want to make. For example, “Change the hero headline to ‘Instant AI Websites’” or “Add a three-column feature section after Benefits.”
:::

:::step{title="Processing"}
WebSmith analyzes your request and uses its update tools to apply the changes to the page’s content structure.
:::

:::step{title="Review and Save"}
The updated page content is saved. You can regenerate or publish to see the new copy reflected in rendered pages.
:::
::::

![Interactive prompt showing page selection and feedback entry for updates](https://media.arcblock.io/lib/c9/c94310712109a8b2.w1600.webp)

## Command Parameters

For non-interactive or scripted use, you can provide feedback and other parameters directly as command-line arguments.

- **--pages** `array` — Specify one or more page paths to update. If not provided, WebSmith prompts you to select a page interactively.
- **--feedback** `string` — Provide content feedback directly. Useful for scripted updates.
- **--glossary** `string` — A glossary of terms to ensure consistent terminology during content generation. You can provide a path to a file using the @ syntax.

## Content Modification Capabilities

The update workflow uses tool-based operations. Align your feedback to these capabilities for predictable results.

| Action  | Description  | Example Feedback  |
|---|---|---|
| <strong>Add Section</strong>  | Adds a new content block. Specify the content and its position.  | “Add a ‘Customers’ section after Features with three testimonials.”  |
| <strong>Delete Section</strong>  | Removes an existing block by name.  | “Remove the ‘Legacy Support’ section.”  |
| <strong>Update Section</strong>  | Modifies content within a block.  | “In the ‘Pricing’ section, change the headline to ‘Predictable pricing for teams.’”  |
| <strong>Move Section</strong>  | Reorders sections.  | “Move ‘FAQ’ so it appears before the final CTA.”  |
| <strong>Update Metadata</strong>  | Updates page metadata such as title or description.  | “Set the page title to ‘Platform Overview’.”  |

## Example Feedback Prompts

**Example Feedback**

```text
"Add a four-step walkthrough section after the hero for onboarding instructions."

"Remove the case-study section that references Legacy API clients."

"Change the CTA in the hero to 'See it in action' and adjust the subheading to mention 5-minute setup."
```

## Summary

Updating page content is an iterative process driven by clear instructions. By aligning your feedback to WebSmith’s page-update capabilities, you can quickly refine copy, re-order sections, and keep your site accurate without affecting the rest of the website.

For structural changes, see the [Update Structure](/en/docs/aigne-web-smith/guides-update-website-update-structure-c47353/) guide. For publishing updates, visit [Publish Website](/en/docs/aigne-web-smith/guides-publish-website-c47353/).

---

## Update Structure

URL: https://www.arcblock.io/en/docs/aigne-web-smith/guides-update-website-update-structure-c47353/

Follow this guide when you want to reshape the sitemap with `aigne web generate`, such as adding or removing pages before approving the plan.

Modifying the structure of your website—such as adding new pages, removing obsolete ones, or reorganizing the navigation—is a critical task for keeping your content relevant and user-friendly. AIGNE WebSmith facilitates this process through an AI-driven workflow that interprets natural language feedback to perform precise structural changes.

This document explains how to modify your site's structure using the `aigne web generate` command. During this process, an AI agent interprets your feedback in natural language to add, remove, update, or move pages. Understanding the available operations helps you provide clear instructions to achieve your desired site layout.

The primary command for applying structural changes is `aigne web generate`. For more details on the creation process itself, see [Create Website](/en/docs/aigne-web-smith/guides-create-website-c47353/).

## The Structure Update Process

When you run the `aigne web generate` command, the system first analyzes your content sources and proposes a website structure. You are then given an opportunity to review and modify this structure interactively.

## Interactive Update Workflow

The process for updating your website's structure is interactive. Here is a summary of the workflow:

1. <strong>Initiate Generation</strong>: Run the generate command in your terminal. **Run command**  ```bash aigne web generate ```
2. <strong>Review Proposed Structure</strong>: After analyzing your sources, the terminal displays the proposed structure and asks for your input.
3. <strong>Provide Natural Language Feedback</strong>: At the prompt, type your desired changes in natural language. For example: > "Add a 'Contact Us' page at the top level with the path `/contact`. Also, remove the page at `/about/old-team`." >
4. <strong>Review and Approve</strong>: The AI processes your feedback, applies the necessary changes, and displays the revised structure. You can then approve the changes to finalize the process or provide more feedback to refine it further.

## Core Structural Operations

The AI agent understands four fundamental operations for modifying the website structure. Providing clear feedback that aligns with these operations will yield the most accurate results.

| Operation  | Description  | Key Parameters  |
|---|---|---|
| <strong>Add</strong>  | Creates a new page in the website structure.  | `title`, `description`, `path`, `parentId`, `sourceIds`  |
| <strong>Delete</strong>  | Removes an existing page from the structure.  | `path`  |
| <strong>Update</strong>  | Modifies the metadata of an existing page.  | `path`, `title` (optional), `description` (optional), `sourceIds` (optional)  |
| <strong>Move</strong>  | Relocates a page to a different parent, changing its path.  | `path`, `newParentId`, `newPath`  |

### Examples of Feedback

Here are some examples of how you can phrase your feedback to perform specific structural changes:

- <strong>Adding a page:</strong> > "Add a new page titled 'Our Team' under the '/about' section. The path should be `/about/team`." >
- <strong>Deleting a page:</strong> > "Please remove the 'Legacy Products' page located at `/products/legacy`." >
- <strong>Updating a page:</strong> > "Update the title for the page at `/services` to 'Our Professional Services'." >
- <strong>Moving a page:</strong> > "Move the 'Careers' page, currently at `/careers`, so it becomes a child of the '/about' page. Its new path should be `/about/careers`." >

## Summary

This interactive process ensures your website's structure is always organized, up-to-date, and aligned with your goals. The system handles the technical details, allowing you to focus on the logical arrangement of your content.

For more hands-on guidance, please refer to the following sections:

- [Create Website](/en/docs/aigne-web-smith/guides-create-website-c47353/)
- [Interactive Mode](/en/docs/aigne-web-smith/guides-interactive-mode-c47353/)

---

## Overview

URL: https://www.arcblock.io/en/docs/aigne-web-smith/overview-c47353/

This document provides a high-level introduction to AIGNE WebSmith. By the end, you will understand its core purpose, key features, and the fundamental workflow it uses to automate the creation of professional websites, from initial planning to final publication.

AIGNE WebSmith is an AI-driven tool that automates the creation of professional, SEO-optimized websites. It generates complete content and templates based on your provided source materials and can publish the final site directly. The system is designed to streamline the entire web development process, minimizing manual effort and technical requirements.

## Key Features

WebSmith offers a comprehensive set of features for automated website creation and management. The system is organized around four main capabilities: AI-driven generation, a professional template system, quality assurance, and direct publishing.

| Feature Area  | Description  |
|---|---|
| <strong>AI-Powered Generation</strong>  | Utilizes AI to analyze requirements, plan an optimal site structure, generate detailed content for all pages in a single operation, and apply SEO best practices. It supports both English and Chinese content generation.  |
| <strong>Professional Templates</strong>  | Creates templates compatible with Pages Kit, using a component-based design with elements like Hero, CTA, and FAQ. The templates are responsive, adapting to both mobile and desktop displays.  |
| <strong>Quality Assurance</strong>  | Includes an automated evaluation system to assess website architecture, user experience, and content consistency. It is supported by a suite of over 32 test cases covering core functions.  |
| <strong>One-Click Publishing</strong>  | Enables direct, batch publishing of multi-page websites to Pages Kit. It provides status monitoring and delivers public access links immediately after a successful deployment.  |

## How It Works

WebSmith employs a series of specialized AI agents that work sequentially to build and deploy a website. Each agent is responsible for a specific stage of the process, ensuring a structured and reliable workflow from conception to publication.

The following diagram illustrates this sequential process:

![Overview](https://media.arcblock.io/lib/a8/a8e8c09c4c9e7c6e.w1600.webp)

The process is as follows:

::::steps
:::step{title="Structure Planning"}
An agent analyzes your project requirements to design an intelligent and logical website architecture.
:::

:::step{title="Content Generation"}
Based on the planned structure, another agent generates high-quality, relevant content for each page.
:::

:::step{title="Template Generation"}
A third agent takes the generated content and assembles it into professional, component-based templates.
:::

:::step{title="Evaluation & Publishing"}
Finally, evaluation agents assess the quality of the output before the publishing agent uploads the completed website.
:::
::::

This modular, agent-based architecture ensures that each step is handled by a specialized process, resulting in a consistent and high-quality final product.

## Core Components

The functionality of WebSmith is delivered through a set of distinct command-line interface (CLI) commands. Each command corresponds to a core component or workflow within the system.

::::card-group
::link-card{title="Generate" description="Generates a complete website, including structure and content, from user-defined requirements." icon="bot" href="/en/docs/aigne-web-smith/guides-create-website-c47353/"}
::link-card{title="Publish" description="Publishes the generated website to various targets, including WebSmith Cloud or your own infrastructure." icon="rocket" href="/en/docs/aigne-web-smith/guides-publish-website-c47353/"}
::link-card{title="Update" description="Modifies the content or structure of an existing website based on new feedback or requirements." icon="edit" href="/en/docs/aigne-web-smith/guides-update-website-c47353/"}
::link-card{title="Translate" description="Translates existing website content into multiple languages, such as Chinese, Japanese, French, and German." icon="globe" href="/en/docs/aigne-web-smith/guides-localize-website-c47353/"}
::link-card{title="Theme" description="Manages visual themes by generating and applying different styles and color schemes to the website." icon="palette" href="/en/docs/aigne-web-smith/guides-customize-theme-c47353/"}
::link-card{title="Component" description="Manages the component library used to build the visual elements of your website." icon="book-open" href="/en/docs/aigne-web-smith/advanced-features-use-custom-component-libraries-c47353/"}
::::

## Summary

This overview has introduced the primary functions and architecture of AIGNE WebSmith. You should now have a foundational understanding of what WebSmith is, its main features, and the commands used to interact with it.

For your next steps, we recommend proceeding to the [Getting Started](/en/docs/aigne-web-smith/getting-started-c47353/) guide, which provides a step-by-step tutorial to install, configure, and generate your first website.

---

## Reference

URL: https://www.arcblock.io/en/docs/aigne-web-smith/reference-c47353/

This section provides detailed technical material for AIGNE WebSmith. It is designed for users seeking specific, in-depth information about commands, configuration options, material preparation, and licensing. For practical, step-by-step guides, please consult the [Getting Started](/en/docs/aigne-web-smith/getting-started-c47353/) or [Guides](/en/docs/aigne-web-smith/guides-c47353/) sections.

The reference materials are organized into the following detailed pages:

::::card-group
::link-card{title="Command Reference" description="A comprehensive guide to all available commands, their aliases, parameters, and usage examples." icon="terminal" href="/en/docs/aigne-web-smith/reference-command-c47353/"}
::link-card{title="Config Reference" description="Configuration options and settings for customizing WebSmith behavior, including project structure, generation preferences, and deployment settings." icon="wrench" href="/en/docs/aigne-web-smith/reference-config-c47353/"}
::link-card{title="Prepare Materials" description="A repeatable process for gathering briefs, source docs, and evidence so WebSmith can generate accurate, high-quality pages." icon="folder" href="/en/docs/aigne-web-smith/reference-prepare-materials-c47353/"}
::link-card{title="Trouble Shooting" description="Solutions to common problems with configuration, generation, publishing, and translation. Includes error messages, causes, and step-by-step fixes." icon="wrench" href="/en/docs/aigne-web-smith/reference-trouble-shooting-c47353/"}
::::

## Licensing

AIGNE WebSmith is licensed under the <strong>Elastic License 2.0</strong>. This license grants you a non-exclusive, royalty-free, worldwide license to use, copy, distribute, and prepare derivative works of the software, subject to specific conditions.

Key limitations include:

- <strong>Hosted Services Restriction</strong>: You may not provide the software to third parties as a hosted or managed service where the service provides access to any substantial set of the software's features or functionality.
- <strong>License Key Integrity</strong>: You may not move, change, disable, or circumvent the license key functionality in the software.
- <strong>Notice Preservation</strong>: You are not permitted to alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software.

For a complete understanding of your rights and obligations, please review the full license terms available at the official Elastic License 2.0 URL.

---

## Command Reference

URL: https://www.arcblock.io/en/docs/aigne-web-smith/reference-command-c47353/

This reference lists all commands available in the AIGNE WebSmith CLI, including their aliases, parameters, and usage examples.

The standard syntax for CLI operations is as follows:

**Run Command**

```bash
aigne web <command> [subcommand] [parameters]
```

Executing `aigne web` without a command initiates interactive mode.

## Main Commands

The following table summarizes the primary commands. Each command is detailed further in the sections below.

| Command  | Aliases  | Description  |
|---|---|---|
| [generate](#generate)  | `gen`, `g`  | Generates a complete website based on a configuration file.  |
| [publish](#publish)  | `pub`, `p`  | Publishes the generated website to a Pages Kit instance.  |
| [update](#update)  | `up`  | Modifies existing website content based on user feedback.  |
| [translate](#translate)  |  | Translates website pages into different languages.  |
| [theme](#theme)  |  | Manages website visual themes, including generation and application.  |
| [component](#component)  | `comp`  | Manages the component library used to build the website.  |
| [chat](#chat)  |  | Starts interactive mode for website management (default).  |
| [prefs](#prefs)  |  | Manages saved user preferences learned from feedback.  |
| [history](#history)  |  | Displays a log of previous updates made to the website.  |
| [clear](#clear)  |  | Removes generated files, workspace data, or configuration settings.  |

### generate

The `generate` command orchestrates the creation of a complete website, from planning the site structure to generating page content and templates based on a specified configuration file.

<strong>Aliases:</strong> `gen`, `g`

<strong>Usage:</strong>

**Generate**

```bash
aigne web generate
```

<strong>Parameters:</strong>

- **config** `string` — Specifies the file path for the website configuration. This is typically provided automatically.
- **glossary** `string` — Path to a glossary file to ensure consistent terminology. Use the format @<file>.
- **forceRegenerate** `boolean` — Forces the regeneration of all pages, overwriting any existing generated content.

### publish

The `publish` command uploads the generated website files to a Pages Kit instance. It manages the batch upload process and provides status monitoring.

<strong>Aliases:</strong> `pub`, `p`

<strong>Usage:</strong>

**Publish**

```bash
aigne web publish --appUrl "https://example.com"
```

<strong>Parameters:</strong>

- **appUrl** `string` — The target base URL of the Pages Kit website where the pages will be published.
- **with-navigations** `string` (default: `menu`) — Publishes navigation data. Accepted values are 'flat' or 'menu'.
- **with-locales** `boolean` — Publishes website locale and language settings when set to true.

### update

The `update` command modifies the content of an existing website based on user-provided feedback. It can be used to refine text, add or remove sections, or alter page structures.

<strong>Alias:</strong> `up`

<strong>Usage:</strong>

**Update**

```bash
aigne web update --pages "/about" --feedback "Add a mission statement."
```

<strong>Parameters:</strong>

- **pages** `array` — An array of page paths to be updated (e.g., [\
- **feedback** `string` — A description of the required changes or improvements for the specified pages.
- **glossary** `string` — Path to a glossary file for consistent terminology. Use the format @<file>.

### translate

The `translate` command translates the content of existing website pages into one or more specified languages.

<strong>Usage:</strong>

**Translate**

```bash
aigne web translate --pages "/home" --langs "fr,de,es"
```

<strong>Parameters:</strong>

- **pages** `array` — An array of page paths to be translated.
- **langs** `array` — An array of language codes. Available languages: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar.
- **feedback** `string` — Specific instructions to guide and improve the quality of the translation.
- **glossary** `string` — Path to a glossary file for consistent translation. Use the format @<file>.

### theme

The `theme` command manages website visual themes, including their generation and application.

#### Subcommands

<strong>`generate`</strong> Generates a new theme based on the website's design and user suggestions.

<strong>Alias:</strong> `gen`

<strong>Usage:</strong>

**Theme Generate**

```bash
aigne web theme generate --name "CustomTheme"
```

- **name** `string` — A name for the new theme.
- **config** `string` — The file path of the website configuration to use as a basis for the theme.

<strong>`apply`</strong> Applies a previously generated theme to the website.

<strong>Alias:</strong> `a`

<strong>Usage:</strong>

**Apply Theme**

```bash
aigne web theme apply
```

This subcommand does not have any specific parameters. It applies the currently configured theme.

### component

The `component` command manages the component library for the website.

<strong>Alias:</strong> `comp`

#### Subcommands

<strong>`pull`</strong> Pulls components from a specified URL to update the local component library.

<strong>Usage:</strong>

**Component Pull**

```bash
aigne web component pull --url "https://your-pages-kit/api/..."
```

- **url** `string` *(required)* — The full URL from which to pull the component library.

<strong>`list`</strong> Lists the components available in the current library.

<strong>Aliases:</strong> `ls`, `l`

<strong>Usage:</strong>

**Component List**

```bash
aigne web component list
```

This subcommand does not take any parameters.

### chat

The `chat` command starts an interactive session for generating, updating, and managing the website conversationally. This is the default command executed when `aigne web` is run without specifying another command.

<strong>Usage:</strong>

**Command**

```bash
aigne web
```

This command does not take any parameters.

### prefs

The `prefs` command manages user preferences that WebSmith learns from feedback to customize AI behavior.

#### Subcommands

<strong>`list`</strong> Lists all saved user preferences.

<strong>Alias:</strong> `ls`

<strong>Usage:</strong>

**List Preferences**

```bash
aigne web prefs list
```

This subcommand does not take any parameters.

<strong>`remove`</strong> Removes one or more specified preferences.

<strong>Alias:</strong> `rm`

<strong>Usage:</strong>

**Prefs Remove**

```bash
aigne web prefs remove --id "pref_abc123"
```

- **id** `array` *(required)* — An array of preference IDs to be removed.

<strong>`toggle`</strong> Toggles the active status of one or more preferences.

<strong>Alias:</strong> `t`

<strong>Usage:</strong>

**Prefs Toggle**

```bash
aigne web prefs toggle --id "pref_abc123"
```

- **id** `array` *(required)* — An array of preference IDs whose status will be toggled.

### history

The `history` command is used to view the update history of the website content and structure.

#### Subcommands

<strong>`view`</strong> Displays the update history in a compact, log-style format. Each entry includes a hash, date, operation, and the associated feedback.

<strong>Aliases:</strong> `log`, `list`

<strong>Usage:</strong>

**History View**

```bash
aigne web history view
```

This subcommand does not take any parameters.

### clear

The `clear` command removes generated files, workspace data, or configuration settings from the project directory.

<strong>Usage:</strong>

**Clear**

```bash
aigne web clear --targets "generatedPages" "websiteConfig"
```

<strong>Parameters:</strong>

- **targets** `array` — An array of items to clear without prompting. Valid items are: websiteStructure, generatedPages, websiteConfig, deploymentConfig, authTokens, mediaDescription, translationCaches.
- **pagesDir** `string` — Overrides the default directory path for source pages.
- **tmpDir** `string` — Overrides the default directory path for the temporary workspace.
- **outputDir** `string` — Overrides the default directory path for generated pages.
- **configPath** `string` — Overrides the default path for the configuration file.

## Summary

This reference guide has detailed the primary commands and parameters for the AIGNE WebSmith CLI. For task-oriented instructions, refer to the guides in the [Guides](/en/docs/aigne-web-smith/guides-c47353/) section of the documentation.

---

## Config Reference

URL: https://www.arcblock.io/en/docs/aigne-web-smith/reference-config-c47353/

The `config.yaml` file is the central control panel for your website generation. Understanding its settings allows you to customize every aspect of the AI's output, from page structure to content tone. This guide provides a complete, field-by-field reference to help you modify your site with precision.

## Overview

The `config.yaml` file is the primary configuration source for AIGNE WebSmith. It uses the YAML format to store all the parameters the AI agent needs to generate your website. Every time you run a command like `generate` or `update`, WebSmith reads this file to understand your requirements.

- <strong>File Name:</strong> `config.yaml`
- <strong>Location:</strong> `.aigne/web-smith/config.yaml` (relative to your project's root directory)
- <strong>Format:</strong> YAML (UTF-8)

This file controls the website's purpose, target audience, content generation rules, page structure, multilingual support, and deployment settings.

### Creating and Updating the Configuration

The `config.yaml` file is created automatically when you first use WebSmith.

<strong>Creation:</strong>

You can create the file in two ways:

::::steps
:::step{title="During the first generation:"}
Running `aigne web generate` in a new project will launch an interactive wizard to create the `config.yaml` file before starting the generation process.
:::

:::step{title="Separately:"}
Running `aigne web init` launches the same wizard to create the configuration file without immediately generating the site.
:::
::::

**aigne web init**

```sh
aigne web init
```

![AIGNE WebSmith configuration wizard](https://media.arcblock.io/lib/11/114809cb26a0ee87.w1600.webp)

<strong>Updating:</strong>

You can update your configuration using one of two methods:

::::steps
:::step{title="Directly edit the file:"}
Open `.aigne/web-smith/config.yaml` in a text editor and modify the fields.
:::

:::step{title="Use the interactive wizard:"}
Run `aigne web init` again. The wizard will load your existing settings and guide you through updating them.
:::
::::

## Configuration Parameters

The fields in `config.yaml` are organized into functional groups. The following sections provide a detailed explanation of each parameter.

### Project Basics

This group defines your project's identity, which is used for branding, SEO, and social media sharing.

- **projectName** `string` *(required)*

### Site Strategy

These fields define the high-level strategy for the AI, influencing the site's purpose, content tone, and overall structure.

- **pagePurpose** `array` *(required)* — Defines the primary goal of the website, which influences the page structure and components used. Possible values include landingPage, ecommerce, saas, portfolio, corporate, blog, nonprofit, and education.
- **targetAudienceTypes** `array` *(required)* — Specifies the target audience, which affects the AI's tone, complexity, and examples. Possible values include customers, businessOwners, marketers, designers, developers, investors, jobSeekers, students, and generalPublic.
- **websiteScale** `string` (default: `standard`) — Controls the number of pages and navigation complexity. Options are: singlePage (one scrollable page), minimal (2-6 pages), standard (7-12 pages, recommended), comprehensive (12+ pages), or aiDecide (lets the AI choose).
- **rules** `string` — Provides detailed, multi-line instructions for the AI on content structure, tone, and style. This is a critical field for guiding the generation process to match your specific requirements. Supports Markdown format.

### Languages

Configure the primary language and any additional languages for translation.

- **locale** `string` (default: `en`) — The primary language for the website's base content, specified using an IETF language code (e.g., en, zh, ja).
- **translateLanguages** `array` — A list of additional language codes to translate the site into. Each language code will generate a full, translated version of the site structure.

### Data Sources

These fields specify the content and data that the AI agent will use as reference material.

- **sourcesPath** `array` *(required)* — An array of local directory and file paths for the AI to analyze. This is the most important field for content quality, as the AI uses only these sources as references. Include documentation, READMEs, and other key project files.
- **defaultDatasources** `array` — An array of file paths that are injected into the context of every page. This is useful for shared data like a media.md file that lists image locations and descriptions.

### Output & Deployment

Configure output directories and deployment URLs.

- **pagesDir** `string` (default: `./aigne/web-smith/pages`) — The output directory where generated site files (e.g., page.yaml) are stored.
- **appUrl** `string` — The final deployment URL of your website. This is used by the publish command to determine the deployment target.

### Media & Display

These settings control how media assets like images are handled.

- **media.minImageWidth** `integer` (default: `800`) — The minimum width in pixels for an image to be considered for use on the website. This helps filter out low-quality or small images.

### System-Managed Fields

These fields are typically managed by WebSmith and do not require manual editing.

- **lastGitHead** `string` — The Git commit hash of the last generation, used for incremental updates.
- **checkoutId** `string` — A temporary variable used during development.
- **shouldSyncAll** `string` — A temporary variable used during development.
- **navigationType** `string` — A temporary variable used during development.

## Applying Changes

Changes to the `config.yaml` file are not applied automatically. You must run the appropriate command to see your modifications take effect. The command needed depends on which field you changed.

| Field(s)  | Command to Apply Changes  | Notes  |
|---|---|---|
| `pagePurpose`, `targetAudienceTypes`, `websiteScale`, `locale`  | `aigne web clear && aigne web generate`  | These require a full regeneration to restructure the site correctly.  |
| `rules`, `media.minImageWidth`, `defaultDatasources`  | `aigne web update`  | Updates existing content without a full regeneration.  |
| `sourcesPath`  | `aigne web clear && aigne web generate` or `aigne web update`  | New sources are analyzed to improve content during updates.  |
| `translateLanguages`  | `aigne web translate`  | Adds new language versions based on the updated list.  |
| `projectName`, `projectDesc`, `projectLogo`, `projectCover`, `appUrl`  | `aigne web publish`  | These fields are primarily used during the publishing process.  |

## Full Configuration Example

The following is a complete `config.yaml` file from the AIGNE WebSmith project itself, demonstrating a real-world configuration.

**config.yaml**

```yaml
projectName: AIGNE WebSmith
projectDesc: "AI-powered website generation tool built on the AIGNE Framework"
projectLogo: https://www.arcblock.io/content/uploads/2e5edbac4a7d5310c117d09601811c.png
projectId: pg4d0000-0000-4000-a000-000000000000
projectSlug: /
pagePurpose:
  - landingPage
targetAudienceTypes:
  - customers
websiteScale: singlePage
rules: |
  ### I. Core Messaging & Strategy: Foundational elements that define *what* you communicate to the user.
  1. Answer Critical Questions "Above the Fold": The very first screen a user sees must clearly and immediately answer:
    * What it is: A concise description of the product.
    * Who it's for: The specific target audience (e.g., solo founders, small teams).
    * Why it's different: Your unique value proposition (e.g., "open, composable, exportable code, agent workflow").
    * Primary Action: A single, clear Call to Action (CTA) that aligns with the user's main goal.
  2. Establish Credibility with Proof: Don't expect users to trust your claims. Show them proof early in the narrative.
    * Show, Don't Just Tell: The most powerful proof is a demo. Include a short (30-45s) silent video loop or a link to a real site built with the tool.
    * Use Social Proof: Before explaining "How it Works," insert tangible evidence like a customer logo, a compelling data point (e.g., "Used by 50+ teams"), or a strong user quote.
  3. Define a Clear Call to Action (CTA):
    * Align CTA with the Audience: The primary CTA should be the main action you want your target user to take (e.g., "Generate My Site").
    * Prioritize CTAs: Relegate secondary actions (like "See it on GitHub") to less prominent positions (tertiary buttons or footer links), especially for non-developer audiences.
    * Maintain a Persistent Mobile CTA: On mobile, a single primary CTA should always be visible.
locale: en
translateLanguages:
  - zh
  - zh-TW
  - ja
pagesDir: .aigne/web-smith/pages
sourcesPath:
  - ./assets/documents
  - ./README.md
  - ./aigne.yaml
  - ./assets/images
  - ./assets/recordings/README.md
  - ./CHANGELOG.md
  - ./agents
defaultDatasources:
  - ./media.md
media:
  minImageWidth: 600
lastGitHead: c4a4d3db4bf230e2c6873419e26b6654c39613a5
checkoutId: ""
projectCover: .aigne/web-smith/cover.png
shouldSyncAll: ""
navigationType: ""
appUrl: https://mhevtaeg.user.aigne.io
```

## Summary

Mastering the `config.yaml` file gives you full control over the website generation process. By carefully defining your project basics, site strategy, and data sources, you can guide the AI to produce a high-quality, relevant, and customized website.

For more hands-on guidance, see the following guides:

::::card-group
::link-card{title="Create Website" description="Learn the complete workflow for generating your first site from scratch." icon="rocket" href="/en/docs/aigne-web-smith/guides-create-website-c47353/"}
::link-card{title="Prepare Materials" description="Understand how to prepare your source documents for the best results." icon="folder" href="/en/docs/aigne-web-smith/reference-prepare-materials-c47353/"}
::link-card{title="Troubleshooting" description="Find solutions to common configuration and generation issues." icon="wrench" href="/en/docs/aigne-web-smith/reference-trouble-shooting-c47353/"}
::::

---

## Prepare Materials

URL: https://www.arcblock.io/en/docs/aigne-web-smith/reference-prepare-materials-c47353/

Great websites start before you run `aigne web generate`. This guide gives you a concrete checklist for collecting briefs, source docs, and proof so WebSmith can build pages that reflect your requirements, cite the right evidence, and require fewer revision cycles.

## The preparation workflow

Here's how the process flows from gathering materials to getting your first website:

![Prepare Materials](https://media.arcblock.io/lib/84/8475404d894661cb.w1600.webp)

Each step builds on the previous one. Better inputs mean better output—it's that simple. A well-organized content kit helps WebSmith create authoritative, on-brand pages from the start.

## Step 1. Start with the essentials

Create a short brief that answers these four questions. A simple Markdown or Word doc works perfectly:

| Question  | Why it matters  | Example  |
|---|---|---|
| <strong>Audience</strong>  | Tone, vocabulary, and proof should match who will read the page.  | "Growth-stage fintech founders and their engineering leads."  |
| <strong>Problem</strong>  | Forces clarity on the pain you solve.  | "Manual onboarding creates 10+ hours of repetitive compliance reviews."  |
| <strong>Differentiator</strong>  | Keeps the copy from sounding like every competitor.  | "Only platform with KYC + KYB automation built on regional data lakes."  |
| <strong>Primary CTA</strong>  | Aligns every section toward a single conversion action.  | "Book a 20-minute integration review."  |

Save this file inside the project so you can add it to `sourcesPath`.

## Step 2. Gather your content and assets

WebSmith works with what you give it. The more relevant material you provide, the better your website will be. Organize these items into a `sources` directory:

### Recommended content types

| Content Type  | Description  | Example  |
|---|---|---|
| <strong>Product Documents</strong>  | Feature breakdowns, architecture notes, API references, pricing explanations.  | `docs/product-overview.md`, `api/quickstart.md`  |
| <strong>Marketing Plans</strong>  | Positioning, messaging house, campaign briefs, competitor summaries.  | `marketing/positioning.pdf`, `brand/voice.md`  |
| <strong>Business Plans</strong>  | Mission, vision, roadmap, funding milestones, leadership bios.  | `company/mission.txt`, `investor/roadmap.pptx`  |
| <strong>Existing Content</strong>  | Blog posts, FAQs, changelogs - anything that shows tone or repeatable stories.  | `blog/*.md`, `faq.md`, `release-notes/2024-02.md`  |
| <strong>Media Files</strong>  | Logos, product screenshots, team photos, charts.  | `assets/logo.svg`, `screenshots/dashboard.png`  |

### Supported formats

| Category  | Formats  |
|---|---|
| <strong>Text</strong>  | `.md`, `.txt`, `.html`, `.json`, `.yaml`, `.xml`  |
| <strong>Documents</strong>  | `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`  |
| <strong>Images</strong>  | `.jpg`, `.jpeg`, `.png`, `.gif`, `.svg`, `.webp`  |
| <strong>Code</strong>  | `.js`, `.ts`, `.py`, `.go`, `.rs`, `.java`, plus most other mainstream languages for snippet extraction  |

## Step 3. Organize for clarity

Group your files logically. This makes it easy for both you and WebSmith to find what's needed.

**project-sources/**

```sh
project-sources/
├── 01_briefs/
│   ├── product-overview.md
│   └── audience-matrix.md
├── 02_proof/
│   ├── testimonials.md
│   └── security-metrics.xlsx
├── 03_assets/
│   ├── logo.svg
│   └── dashboard.png
└── 04_content/
    ├── blog/
    └── faq.md
```

Use descriptive folder names and prefixes. It should be obvious at a glance what each directory contains.

## Step 4. Connect your sources in config.yaml

Point the `sourcesPath` array at the directories (or specific files) you just organized. This is the single most important configuration parameter.

**config.yaml**

```yaml
sourcesPath:
  - ./project-sources/01_briefs
  - ./project-sources/02_proof
  - ./project-sources/03_assets
pagePurpose:
  - saas
targetAudienceTypes:
  - businessOwners
  - developers
rules: >
  Highlight 40% cost savings backed by customer quotes. Mention SOC 2 + ISO 27001.
```

When you run `aigne web generate`, WebSmith recursively reads those folders, chunks the files, and cites them while writing copy and assembling layouts.

## Choose your approach

How much time do you have? Pick the approach that fits your situation.

### Quick start: Just need a demo?

Perfect for when you need something up fast and can refine it later.

- Start with a well-written README (~500+ words) and a few screenshots
- Add them to `sourcesPath`
- Run `aigne web generate`, review the result, and iterate once
- Great for prototypes, internal demos, or testing the waters

### Recommended: Building something real

This is the sweet spot for most teams launching a real product or service.

1. Document your <strong>audience</strong>, <strong>problem</strong>, <strong>differentiation</strong>, and <strong>CTA</strong>
2. Build a value matrix for each persona with functional + emotional proof
3. Outline each page section by intent before letting WebSmith write
4. Package testimonials, metrics, and screenshots as separate files
5. After generation, verify each section hits its goal, then refine and re-run

### Advanced: Team knowledge base

For teams shipping multiple sites or maintaining long-term content systems.

- Split your expertise into focused Markdown files organized by topic
- Example structure:

```sh
knowledge-base/
├── foundation/
│   ├── mission.md
│   └── brand-voice.md
├── products/
│   ├── payments-overview.md
│   └── payments-technical-specs.md
├── proof-points/
│   ├── case-study-fintech-x.md
│   └── g2-reviews.md
└── audiences/
    ├── developer-persona.md
    └── operator-persona.md
```

This approach scales beautifully:

- Mix and match directories for different projects
- Every site pulls from a single source of truth
- Update one file (`case-study-fintech-x.md`) and it automatically improves every website that references it

## Quality checklist

Before you run generate, make sure:

- Every claim is backed by a data point, quote, or metric in your source files
- Personas and CTAs are documented separately from marketing copy
- Assets have descriptive names (`dashboard-dark.png`, not `image1.png`)
- Sensitive or internal-only files are excluded (WebSmith reads everything you point to)
- Source docs contain knowledge; style guidance goes in the `rules` field

## Tips for best results

WebSmith is designed to generate great websites in one shot—but the quality depends on what you feed it.

- <strong>Provide concrete details.</strong> The more specific your source materials (data points, quotes, metrics), the more authoritative your website will be.
- <strong>Break content into focused files.</strong> Instead of one massive document, organize topics into smaller files. This helps WebSmith cite sources precisely and generate more structured content.
- <strong>Separate content from instructions.</strong> Put your knowledge in source files, but keep layout and tone directives in the `rules` field where they belong.

## Next steps

::::card-group
::link-card{title="Getting Started" description="Install the AIGNE CLI, run `aigne web generate`, and review your first site." icon="rocket" href="/en/docs/aigne-web-smith/getting-started-c47353/"}
::link-card{title="Create Website" description="Learn every option available during the generate workflow." icon="wrench" href="/en/docs/aigne-web-smith/guides-create-website-c47353/"}
::link-card{title="Publish Website" description="Deploy to WebSmith Cloud or your own infrastructure once content looks great." icon="globe" href="/en/docs/aigne-web-smith/guides-publish-website-c47353/"}
::::

---

## Troubleshooting

URL: https://www.arcblock.io/en/docs/aigne-web-smith/reference-trouble-shooting-c47353/

This guide helps you diagnose and fix common issues when working with AIGNE WebSmith. If you encounter problems during generation, publishing, or configuration, check the scenarios below for solutions.

## Configuration Issues

### Issue 1: Configuration file format error

<strong>Error message:</strong>

```
Error: Failed to parse config file: Implicit map keys need to be followed by map values at line 112, column 1:

lastGitHead: c4a4d3db4bf230e2c6873419e26b6654c39613a5
appUrl: https://staging.websmith.aigne.io
```

```
Error: Failed to parse config file: Map keys must be unique at line 116, column 1:

projectCover: .aigne/web-smith/cover.png
appUrl: https://staging.websmith.aigne.io
^
```

<strong>Possible causes:</strong> There's a YAML syntax error in your configuration file. Common issues include:

- Using tabs instead of spaces for indentation
- Using full-width colons (：) instead of ASCII colons (:)
- Missing required quotes
- Duplicate configuration items

<strong>How to fix:</strong>

1. Check the line number mentioned in the error message to locate the issue
2. Verify the indentation on that line (use spaces, not tabs)
3. Make sure the colon is an ASCII colon (:), not a full-width colon (：)
4. Use an online YAML validator to check the syntax
5. Re-run `aigne web publish` after fixing

> <strong>Tip:</strong> Except for configuration file format errors that need to be fixed, if some parameters are not configured correctly, the system will automatically use default values, which won't affect basic functionality.
>

## Generation Issues

### Issue 2: Generated content doesn't match expectations

<strong>You might encounter:</strong>

- The tone of generated content doesn't match your requirements
- The page structure doesn't match what you expected
- Some important information is missing

<strong>Possible causes:</strong>

1. The `rules` description in your config is insufficient or unclear
2. The `targetAudienceTypes` setting doesn't match your actual target audience
3. There are too few or irrelevant reference documents in `sourcesPath`

<strong>How to fix:</strong>

1. <strong>Enrich</strong> <strong>`rules`</strong><strong>:</strong> Add detailed guidance in your `config.yaml`: ```yaml rules: |   ### Page Structure Requirements   1. Above the fold must include:      * Clear product headline      * Concise description      * Primary call-to-action      ### Content Tone   - Use positive, confident language   - Include concrete data and examples   - Avoid marketing jargon ```
2. <strong>Adjust audience:</strong> Ensure `targetAudienceTypes` matches your actual audience: ```yaml targetAudienceTypes:   - customers      # For end users   - developers     # For technical audience ```
3. <strong>Add more sources:</strong> Include relevant documentation in `sourcesPath`: ```yaml sourcesPath:   - ./README.md   - ./docs   - ./CHANGELOG.md ```

### Issue 3: Images are low quality or missing

<strong>You might encounter:</strong>

- Low-resolution images in generated pages
- Expected images not appearing

<strong>Cause:</strong> The `media.minImageWidth` setting is too high, filtering out some images.

<strong>How to fix:</strong>

1. Open the `config.yaml` file and find the `media` configuration: ```yaml media:   minImageWidth: 800  # Current threshold ```
2. Adjust this value based on your needs:
3.
  - <strong>400-600</strong>: Will include more images, but some may be lower quality
  - <strong>600-800</strong>: Balanced quality and quantity (recommended setting)
  - <strong>800-1000</strong>: Only high-quality images are kept, quantity will be reduced
4. Run the update command after saving the file: ```bash aigne web update ```

## Publishing Issues

### Issue 4: URL invalid error when publishing

<strong>Error message:</strong>

```
Error: ⚠️  The provided URL is not a valid website on ArcBlock platform

💡 Solution: Start here to set up your own website to host pages:
```

<strong>Cause:</strong> The `appUrl` in your configuration is empty or points to an invalid website address.

<strong>How to fix:</strong> Set the correct deployment address in `config.yaml`:

```yaml
# Enter your website address
appUrl: https://your-site.user.aigne.io

# If you don't have a website yet, you can clear this configuration
# appUrl: ""
```

### Issue 5: Authorization expired error when publishing

<strong>Error message:</strong>

```
❌ Failed to publish pages: bundle: not authorized
```

<strong>Cause:</strong> Your login credentials have expired and need to be re-authorized.

<strong>How to fix:</strong> Run the following commands in order:

```bash
# First, clear old authorization information
aigne web clear

# Then republish, the system will prompt you to log in again
aigne web publish
```

## How to Recover

### Method 1: Restore using Git

If you're using Git to manage your code, you can quickly restore to a previously working configuration:

```bash
# Stash current changes
git stash
```

Then regenerate the website:

```bash
aigne web generate
```

> <strong>Tip:</strong> If you want to restore the stashed changes later, you can run `git stash pop`
>

### Method 2: Clean and regenerate

If you encounter issues that are hard to locate, you can clear all generated files and regenerate from scratch:

```bash
# Clear all generated files, then regenerate
aigne web clear && aigne web generate
```

> <strong>Note:</strong> This will delete all generated content, but won't affect your configuration files. After execution, the system will regenerate the website based on the current configuration.
>

## Usage Tips

Here are some practical tips to help you avoid common issues:

::::steps
:::step{title="Save your change history:"}
If you're using Git, remember to commit after each configuration file change, so you can easily go back to a previous version if something goes wrong
:::

:::step{title="Back up before making changes:"}
Before modifying important configurations, copy your configuration file as a backup, just in case
:::

:::step{title="Test immediately after changes:"}
After each configuration change, run `aigne web generate` right away to test, so you can catch any issues early
:::

:::step{title="Check if the format is correct:"}
After modifying YAML files, you can use online tools to check if there are any format errors
:::

:::step{title="Start simple:"}
Begin with the simplest configuration, and after confirming everything works, gradually add more complex features
:::

:::step{title="Keep notes of your changes:"}
Simply note down what you changed and why, so it's easier to find the cause when problems occur later
:::
::::

## Getting More Help

If the methods above don't solve your problem, you can try:

::::steps
:::step{title="Check configuration documentation:"}
Review [Config Reference](/en/docs/aigne-web-smith/reference-config-c47353/) for detailed descriptions of each configuration item
:::

:::step{title="Check command documentation:"}
Refer to [Command Reference](/en/docs/aigne-web-smith/reference-command-c47353/) for detailed command usage
:::

:::step{title="Check error logs:"}
Carefully read the error messages displayed in the terminal, which usually contain specific hints
:::

:::step{title="Use AIGNE Observability:"}
Use the AIGNE Observability tool described below to get detailed execution records
:::

:::step{title="Seek community help:"}
Visit the [AIGNE Community](https://community.arcblock.io/discussions/boards/aigne) to ask questions, other users or developers may be able to help
:::
::::

## Using AIGNE Observability to Troubleshoot

When you need to investigate complex issues in depth or report problems to the community, you can use <strong>AIGNE Observability</strong>. It records detailed execution processes for each step to help you or technical support staff quickly find issues.

### Start the Observability Server

Run the following command to start the local observability server:

**Start Observability Server**

```bash
aigne observe
```

You'll see output showing:

- Database path: where trace data is saved
- Server address: open this address in your browser to view the observability dashboard

![Observability server running](https://media.arcblock.io/lib/e1/e10d985846bc2643.w1600.webp)

### View Execution Records

1. <strong>Open the dashboard:</strong> Click the server address shown in the output or open it in your browser
2. <strong>View operation records:</strong> The dashboard displays all WebSmith operations, including:
3.
  - Input and output data
  - Time taken for each step
  - Operation steps executed and their results
  - Detailed error information

![Observability dashboard showing execution records](https://media.arcblock.io/lib/5a/5a700be9522f2b53.w1600.webp)

### Report Issues with Observability

When reporting problems to the community:

1. <strong>Capture the trace:</strong> Keep the observability server running during the problematic operation
2. <strong>Export the trace data:</strong> Export the relevant execution records from the dashboard
3. <strong>Report the issue:</strong> Visit the [AIGNE Community](https://community.arcblock.io/discussions/boards/aigne) and attach:
4.
  - Description of the problem
  - Steps to reproduce
  - Exported trace file
  - Your configuration (if relevant)

> <strong>Tip:</strong> Trace records contain complete information about WebSmith's execution, including operations and results for each step. Providing this information to technical support or the community can greatly improve problem-solving efficiency.
>

---

## Release Notes

URL: https://www.arcblock.io/en/docs/aigne-web-smith/release-notes-c47353/

This document records all version updates for AIGNE WebSmith, including new features, bug fixes, and other changes, organized by version in reverse chronological order.

## [1.8.0-beta](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.7.0...v1.8.0-beta) (2025-11-13)

### Features

- support for add-page and remove-page ([#231](https://github.com/AIGNE-io/aigne-web-smith/issues/231)) ([d02fe21](https://github.com/AIGNE-io/aigne-web-smith/commit/d02fe21b0425b870ad7ba98d4bc28c4a0f95c8e2))

## [1.7.0](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.7.0-beta.3...v1.7.0) (2025-11-11)

## [1.7.0-beta.3](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.7.0-beta.2...v1.7.0-beta.3) (2025-11-11)

### Features

- add automated section error fixing system with AI fallback ([#239](https://github.com/AIGNE-io/aigne-web-smith/issues/239)) ([7fe6421](https://github.com/AIGNE-io/aigne-web-smith/commit/7fe64215114d5cfa99afc658ec7f967855c1ed69))
- <strong>validate:</strong> enforce maximum length for project name and description ([#238](https://github.com/AIGNE-io/aigne-web-smith/issues/238)) ([3aef2d5](https://github.com/AIGNE-io/aigne-web-smith/commit/3aef2d556f2fdb40ef6ab4538bd7146e580fc5af))

### Bug Fixes

- improve error handling and parameter extraction in detail check utilities ([#240](https://github.com/AIGNE-io/aigne-web-smith/issues/240)) ([16f1397](https://github.com/AIGNE-io/aigne-web-smith/commit/16f1397809c47bbb73997cc08f026f3cebed476b))
- update chat model from aignehub/gemini-2.5-pro to google/gemini-2.5-pro ([0c01596](https://github.com/AIGNE-io/aigne-web-smith/commit/0c01596da4c6659ce6da080327d7ddf2bef5a650))

## [1.7.0-beta.2](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.7.0-beta.1...v1.7.0-beta.2) (2025-11-10)

### Bug Fixes

- tune naming for publish access token environment ([#234](https://github.com/AIGNE-io/aigne-web-smith/issues/234)) ([2887bd9](https://github.com/AIGNE-io/aigne-web-smith/commit/2887bd95487626ace7e4ecb200eb0c4222ab1ef8))

## [1.7.0-beta.1](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.7.0-beta...v1.7.0-beta.1) (2025-11-10)

### Bug Fixes

- add validation check for existing translation files ([#232](https://github.com/AIGNE-io/aigne-web-smith/issues/232)) ([f9760fb](https://github.com/AIGNE-io/aigne-web-smith/commit/f9760fbf295b51cf35a728e8a351f099401359bb))

## [1.7.0-beta](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0...v1.7.0-beta) (2025-11-08)

### Features

- upgrade to use the built-in components of version v2 ([#229](https://github.com/AIGNE-io/aigne-web-smith/issues/229)) ([93e3915](https://github.com/AIGNE-io/aigne-web-smith/commit/93e3915c6140c5b7061762cdc635a4632e92b3cf))

## [1.6.0](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.15...v1.6.0) (2025-11-07)

## [1.6.0-beta.15](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.14...v1.6.0-beta.15) (2025-11-07)

### Bug Fixes

- reload media after generated media ([#226](https://github.com/AIGNE-io/aigne-web-smith/issues/226)) ([1b0a62b](https://github.com/AIGNE-io/aigne-web-smith/commit/1b0a62b63eab6abf93950888346e9edc1a7d7952))

## [1.6.0-beta.14](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.13...v1.6.0-beta.14) (2025-11-07)

### Features

- add reasoning effort configuration for customizable AI model settings ([#223](https://github.com/AIGNE-io/aigne-web-smith/issues/223)) ([47813ce](https://github.com/AIGNE-io/aigne-web-smith/commit/47813ce77277ece9ec74a38870ae11d1540d7a6d))
- <strong>doc:</strong> update config doc and history entries for clarity and consistency ([#222](https://github.com/AIGNE-io/aigne-web-smith/issues/222)) ([1941dee](https://github.com/AIGNE-io/aigne-web-smith/commit/1941deed2f52edfbd84318ea546b92b771204e9d))
- <strong>guest:</strong> allow guests to publish web pages on the official site ([#220](https://github.com/AIGNE-io/aigne-web-smith/issues/220)) ([3367ce9](https://github.com/AIGNE-io/aigne-web-smith/commit/3367ce9e5dbff39afc879f5dc312cab6e9f93ce4))

### Bug Fixes

- centralize reasoning effort constants and refactor initialization logic ([#225](https://github.com/AIGNE-io/aigne-web-smith/issues/225)) ([fe3c0cb](https://github.com/AIGNE-io/aigne-web-smith/commit/fe3c0cbcabe80c75da3f309e954efc524bb8fb81))
- more accurate timing fields for pages ([#224](https://github.com/AIGNE-io/aigne-web-smith/issues/224)) ([bf074d9](https://github.com/AIGNE-io/aigne-web-smith/commit/bf074d9801d9c4fd15442c0f727416020c5d1d38))

## [1.6.0-beta.13](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.12...v1.6.0-beta.13) (2025-11-05)

### Features

- enhance page validation with media files and streamlined navigation ([#217](https://github.com/AIGNE-io/aigne-web-smith/issues/217)) ([7777805](https://github.com/AIGNE-io/aigne-web-smith/commit/77778050e4473222a859001c306265d22bc531ba))
- improve component loading with better error handling and filtering ([a375567](https://github.com/AIGNE-io/aigne-web-smith/commit/a375567cedf031f834712e133b66742c3d04df77))

### Bug Fixes

- improve error logging in choosePages ([#215](https://github.com/AIGNE-io/aigne-web-smith/issues/215)) ([645a591](https://github.com/AIGNE-io/aigne-web-smith/commit/645a591bea6434f0e1ad172c40e2aee82a07b503))
- make paid deployment more smooth stable ([#214](https://github.com/AIGNE-io/aigne-web-smith/issues/214)) ([d6bccfb](https://github.com/AIGNE-io/aigne-web-smith/commit/d6bccfb7a6a3d45c3498b4b84128a5ee62ac610e))
- tune theme/prefs/component/publish commands and validation ([#219](https://github.com/AIGNE-io/aigne-web-smith/issues/219)) ([d2e8465](https://github.com/AIGNE-io/aigne-web-smith/commit/d2e8465471cb2ff2bad4fc3deb8ad7e5245616d3))

## [1.6.0-beta.12](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.11...v1.6.0-beta.12) (2025-11-05)

### Features

- tune token consumption for update ops with intent analysis ([#212](https://github.com/AIGNE-io/aigne-web-smith/issues/212)) ([534aa3e](https://github.com/AIGNE-io/aigne-web-smith/commit/534aa3e3bce96feb7334e8d3701c7c29909a2059))

## [1.6.0-beta.11](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.10...v1.6.0-beta.11) (2025-11-04)

### Features

- add reasoning_effort parameter to agent configurations ([#184](https://github.com/AIGNE-io/aigne-web-smith/issues/184)) ([a31899f](https://github.com/AIGNE-io/aigne-web-smith/commit/a31899f805a9bd0fd5a75f90f02199d5298fb6ab))
- warn on invalid sources and tuning translate messages ([#183](https://github.com/AIGNE-io/aigne-web-smith/issues/183)) ([b99e0b5](https://github.com/AIGNE-io/aigne-web-smith/commit/b99e0b554a936da9466bd7eeab4e46e429cee977))

## [1.6.0-beta.10](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.9...v1.6.0-beta.10) (2025-11-03)

### Features

- <strong>doc:</strong> add config.yml guide and update latest update doc ([#175](https://github.com/AIGNE-io/aigne-web-smith/issues/175)) ([46b1ef0](https://github.com/AIGNE-io/aigne-web-smith/commit/46b1ef05282f9d345f5cd15b008eb6f8782f206c))

## [1.6.0-beta.9](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.8...v1.6.0-beta.9) (2025-11-01)

### Bug Fixes

- adjust component background colors ([#178](https://github.com/AIGNE-io/aigne-web-smith/issues/178)) ([6ce85f6](https://github.com/AIGNE-io/aigne-web-smith/commit/6ce85f63ae5833f0e027d5586d213d51264d84a4))

## [1.6.0-beta.8](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.7...v1.6.0-beta.8) (2025-11-01)

### Features

- support cleaning specific pages ([#179](https://github.com/AIGNE-io/aigne-web-smith/issues/179)) ([ec49d3f](https://github.com/AIGNE-io/aigne-web-smith/commit/ec49d3f157bd9dfea6268dd412442e8f21544468))

## [1.6.0-beta.7](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.6...v1.6.0-beta.7) (2025-11-01)

### Bug Fixes

- double slash in website structure display ([b905586](https://github.com/AIGNE-io/aigne-web-smith/commit/b905586d8b4c0c19964556b9fcbb1ba7ad2d8990))

## [1.6.0-beta.6](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.5...v1.6.0-beta.6) (2025-11-01)

### Features

- include page link when display site structure ([49569c8](https://github.com/AIGNE-io/aigne-web-smith/commit/49569c8fdd7fe0755df7ad63c20a73c4abf2f167))

## [1.6.0-beta.5](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.4...v1.6.0-beta.5) (2025-10-31)

### Features

- add carousel component ([#173](https://github.com/AIGNE-io/aigne-web-smith/issues/173)) ([d6c7a4b](https://github.com/AIGNE-io/aigne-web-smith/commit/d6c7a4b8308a406f44c0a43e05acbd458046fd31))

## [1.6.0-beta.4](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.3...v1.6.0-beta.4) (2025-10-28)

### Bug Fixes

- enhance multi-page content planning ([#168](https://github.com/AIGNE-io/aigne-web-smith/issues/168)) ([3106397](https://github.com/AIGNE-io/aigne-web-smith/commit/31063972134c1188fc17545fa7872de2ca3c1ce9))

## [1.6.0-beta.3](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.6.0-beta.2...v1.6.0-beta.3) (2025-10-27)

### Bug Fixes

- optimize built-in component styles ([#166](https://github.com/AIGNE-io/aigne-web-smith/issues/166)) ([e61bf64](https://github.com/AIGNE-io/aigne-web-smith/commit/e61bf643be8e0c48bc93d1520398f370fc36a825))

## [1.6.0-beta.2](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.1-beta.2...v1.6.0-beta.2) (2025-10-26)

### Features

- publish doc to official site ([#162](https://github.com/AIGNE-io/aigne-web-smith/issues/162)) ([11a7641](https://github.com/AIGNE-io/aigne-web-smith/commit/11a76414cd94383d2dc4a09466a98f3bd9159c9e))

### Bug Fixes

- remove source file change detection logic ([#165](https://github.com/AIGNE-io/aigne-web-smith/issues/165)) ([0408df8](https://github.com/AIGNE-io/aigne-web-smith/commit/0408df87d57ed771d2d2b592c9c52b9414ebd410))

## [1.5.1-beta.2](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.1-beta.1...v1.5.1-beta.2) (2025-10-24)

### Bug Fixes

- enhance content card components with screenshot display support ([#161](https://github.com/AIGNE-io/aigne-web-smith/issues/161)) ([1e4b67a](https://github.com/AIGNE-io/aigne-web-smith/commit/1e4b67a3593acda6b4682ddcaf0dfaa757348958))

## [1.5.1-beta.1](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.1-beta...v1.5.1-beta.1) (2025-10-22)

### Bug Fixes

- <strong>layout:</strong> adjust grid settings for mobile responsiveness ([#156](https://github.com/AIGNE-io/aigne-web-smith/issues/156)) ([b873dbc](https://github.com/AIGNE-io/aigne-web-smith/commit/b873dbc7db7bc41a875d9b9c691fe6d9e2d2f955))

## [1.5.1-beta](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0...v1.5.1-beta) (2025-10-21)

### Bug Fixes

- home page action link to auto ([0959250](https://github.com/AIGNE-io/aigne-web-smith/commit/0959250bd26ca368ccbedfcad98892ed6061bc4c))
- prevent duplicate tool calls in updatePageDetail ([#154](https://github.com/AIGNE-io/aigne-web-smith/issues/154)) ([ca5eba1](https://github.com/AIGNE-io/aigne-web-smith/commit/ca5eba14e72131db29c5ab0bf9c8deb27e4bd113))

## [1.5.0](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.16...v1.5.0) (2025-10-19)

## [1.5.0-beta.16](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.15...v1.5.0-beta.16) (2025-10-17)

### Bug Fixes

- doc review and update ([#147](https://github.com/AIGNE-io/aigne-web-smith/issues/147)) ([436344c](https://github.com/AIGNE-io/aigne-web-smith/commit/436344c1bd1f1ac4fa98200927e184d705061c7d))
- prevent component type changes in updateSection tool ([#151](https://github.com/AIGNE-io/aigne-web-smith/issues/151)) ([cdbdc91](https://github.com/AIGNE-io/aigne-web-smith/commit/cdbdc9126e64071e7ef40a78bcdfc6da436b71d1))
- tune resume capability and support navigation layout ([#150](https://github.com/AIGNE-io/aigne-web-smith/issues/150)) ([4c62fbd](https://github.com/AIGNE-io/aigne-web-smith/commit/4c62fbdbcb9bf441644d6a260a086d5481f1e46d))

## [1.5.0-beta.15](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.14...v1.5.0-beta.15) (2025-10-16)

### Bug Fixes

- reload translation model keys after refresh ([#146](https://github.com/AIGNE-io/aigne-web-smith/issues/146)) ([c0183ff](https://github.com/AIGNE-io/aigne-web-smith/commit/c0183ff3d1417a7a3c0970bb71e9a61f8b63dfa6))

## [1.5.0-beta.14](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.13...v1.5.0-beta.14) (2025-10-16)

### Bug Fixes

- tune translate doc improvement and translate output ([#144](https://github.com/AIGNE-io/aigne-web-smith/issues/144)) ([681b076](https://github.com/AIGNE-io/aigne-web-smith/commit/681b0769ea00db461439af0dd5b939ae42309952))

## [1.5.0-beta.13](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.12...v1.5.0-beta.13) (2025-10-15)

### Bug Fixes

- add terminal recording support ([#143](https://github.com/AIGNE-io/aigne-web-smith/issues/143)) ([f23fbab](https://github.com/AIGNE-io/aigne-web-smith/commit/f23fbab98129fba91200b798d317090dcb4175d2))

## [1.5.0-beta.12](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.11...v1.5.0-beta.12) (2025-10-15)

### Bug Fixes

- use better prompt structure for plan -> detail ([#141](https://github.com/AIGNE-io/aigne-web-smith/issues/141)) ([aa01994](https://github.com/AIGNE-io/aigne-web-smith/commit/aa019946cfac635c4a2f5acfffc4b1468b969adb))

## [1.5.0-beta.11](https://github.com/AIGNE-io/aigne-web-smith/compare/v1.5.0-beta.10...v1.5.0-beta.11) (2025-10-16)

### Bug Fixes

- Added project validation and dynamic slug handling for publishing ([#137](https://github.com/AIGNE-io/aigne-web-smith/issues/137)).
- Enhanced error handling and structure validation ([#133](https://github.com/AIGNE-io/aigne-web-smith/issues/133)).
- <strong>ux:</strong> Optimized visible copy for improved user interaction ([#136](https://github.com/AIGNE-io/aigne-web-smith/issues/136)).

... <em>(older releases omitted for brevity)</em> ...

---

## ARC CLI

URL: https://www.arcblock.io/en/docs/arc-cli/

---

## arc afs

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-afs/

`arc afs` is the command group for AFS file system operations. Every subcommand operates on an AFS path, a mounted location like `/src` or `/data`, not a raw filesystem path on your machine.

Captured against `arc` `2.0.0-beta.50` (commit `a99fb2c37`, main, 2026-09-11). Run `arc --version` before you copy dumps; the commit is what pins the command surface.

```bash
arc afs <subcommand> [options]
```

Run `arc afs --help` to see the full subcommand list. Every subcommand also accepts the global `--json`, `--view <default|llm|human|json>`, `--instance` / `-i`, and `--home <dir>` flags described in [Overview](../overview/). `--yaml` was removed (never implemented); use `--json` or `--view json`.

An unrecognized flag is now rejected (`Unknown argument: <name>`, exit `5`), not silently ignored — for example `arc afs ls --bogus-flag foo` fails instead of running with `--bogus-flag` dropped.

## Which instance does this talk to

`arc afs` needs a live instance to run against. With no flag it attaches to the **default** background instance (started with a bare `arc service start`); if none is running, every `arc afs` subcommand exits non-zero instead of silently falling back to a throwaway ad-hoc AFS:

```bash
$ arc afs ls /
ERROR: No AFS daemon is running for instance "default".
Start it with:  arc service start
Or use --standalone for ad-hoc mode (no runtime state)
```

- **`--instance <name>`** / **`-i`**: global. Attach to a named instance instead of the default one (see `arc service list`). Omit for `default`
- **`--home <dir>`**: global. Instance root. Used by `arc service start` (create), `--standalone` (ad-hoc), and `arc did init`. To pick which instance, use `--instance`. If you pass both and they name different instances, the command fails
- **`--standalone`**: force ad-hoc mode — load AFS straight from the local `.afs-config/config.toml` in the current directory instead of connecting to any running daemon. No runtime state (mounts you add elsewhere, live subscriptions, etc. are invisible); prints a `[standalone] not attached to any instance` line to stderr as a reminder

```bash
arc service start --instance docs-demo --home ~/docs-demo   # start a named instance once
arc afs ls / --instance docs-demo                 # every later afs call names it explicitly
```

## Reading and listing

### arc afs ls

List directory contents.

**Usage**

```bash
arc afs ls [path] [options]
```

- `[path]` (optional, default `/`): the AFS path to list
- **`--depth <n>`**: maximum depth to list (default `1`)
- **`-l`**: long listing format, shows kind and size
- **`-R`**: list recursively
- **`--limit <n>`**: maximum number of entries to return
- **`--max-children <n>`**: maximum children per directory
- **`--pattern <glob>`**: filter entries by glob pattern

Aliased as `arc afs list`.

`-R` and an explicit `--depth` are mutually exclusive — `-R` always lists at depth 10, so combining it with `--depth` is ambiguous about which one wins:

```bash
$ arc afs ls /demo -R --depth 2
ERROR: ls: --depth conflicts with -R (recursive always lists at depth 10) — choose one: drop --depth to use -R's depth of 10, or drop -R and pass --depth explicitly
```

A path that does not exist exits `1` (not `0` with an empty list, and not `5`):

```bash
$ arc afs ls /demo/does-not-exist
ERROR: No data found for path: /demo/does-not-exist
```

**Example: recursive, long listing**

```bash
arc afs ls /demo -l -R
```

```
└── 📁 demo
    ├── 📄 notes.txt (fs:file)  15B
    └── 📁 reports (fs:directory)
        └── 📄 q1.txt (fs:file)  15B
```

### arc afs read

Read file content.

**Usage**

```bash
arc afs read [path] [options]
```

- `[path]` (positional, or **`--path <path>`**, one of the two is required): path to read
- **`--start-line <n>`**: start line, 1-indexed, inclusive
- **`--end-line <n>`**: end line, 1-indexed, inclusive; `-1` for end of file

Aliased as `arc afs cat`.

**Example**

```bash
$ arc afs read /demo/notes.txt
Hello from AFS
```

A path that does not exist exits `1`:

```bash
$ arc afs read /demo/does-not-exist.txt
ERROR: No data found for path: /demo/does-not-exist.txt
```

### arc afs stat

Get file or directory info.

**Usage**

```bash
arc afs stat [path]
```

- `[path]` (positional, or **`--path <path>`**, one of the two is required): path to inspect

**Example**

```bash
$ arc afs stat /demo/notes.txt
PATH=/demo/notes.txt
KIND=fs:file
SIZE=15
MODIFIED=2026-08-01T04:00:51.508Z
```

A path that does not exist exits `1`, same message and exit code as `arc afs read`:

```bash
$ arc afs stat /demo/does-not-exist.txt
ERROR: No data found for path: /demo/does-not-exist.txt
```

### arc afs search

Search for content within an AFS path.

**Usage**

```bash
arc afs search [path] [query]
```

- `[path]` (positional, or **`--path <path>`**, one of the two is required): path to search in
- `[query]` (positional, or **`--query <text>`**, one of the two is required): search query

Aliased as `arc afs grep`. **Not** aliased as `find` — `find` was removed (it searches content, not names; to filter entries by name instead, use `arc afs ls --pattern`).

**Example**

```bash
$ arc afs search /demo revenue
/demo/reports/q1.txt
```

### arc afs explain

Explain AFS concepts or paths. With no argument it prints a general overview (mount / path / uri concepts); with a topic or an actual AFS path it explains that specifically.

**Usage**

```bash
arc afs explain [topic]
```

- `[topic]`: a concept name (`mount`, `path`, `uri`) or an AFS path, e.g. `/src`. Can also be passed as **`--topic <value>`** instead of positionally

**Example**

```bash
$ arc afs explain
AFS Overview
============

AFS (Agentic File System) is a virtual filesystem that unifies different data sources into a single namespace.

Core Concepts:
- mount: Mount a data source to a virtual path
- path: Virtual path, e.g., /src, /data
- uri: Data source address, e.g., fs://, git://, sqlite://

Data Flow:
  User Path -> AFS -> /{mount} -> Provider -> Actual Data

Examples:
  $ arc afs mount add /src fs:///path/to/source
  $ arc afs ls /src
  $ arc afs read /src/file.txt
```

### arc afs subscribe

Subscribe to AFS events under a path; prints one JSON event per line until you press Ctrl-C. Useful for watching a mount for changes made by another process (a build tool, another `arc afs write`, a running blocklet).

**Usage**

```bash
arc afs subscribe [path] [options]
```

- `[path]` (optional, default `/`): path prefix to watch, e.g. `/demo` or `/dev/code-agents`. Can also be passed as **`--path <value>`**
- **`--type <pattern>`**: event type filter, e.g. `afs:write`, `afs:*` (default `afs:write`, wildcards allowed)

**Example** (run in one terminal, then `arc afs write /demo/hello.txt ...` in another)

```bash
$ arc afs subscribe /demo
Subscribed to /demo (type=afs:write) — Ctrl-C to stop
{"type":"afs:write","path":"/demo/hello.txt","source":"fs","timestamp":1787870798884}
```

## Writing and deleting

### arc afs write

Write content to a file.

**Usage**

```bash
arc afs write [path] [content] [options]
```

- `[path]` (positional, or **`--path <path>`**, one of the two is required): path to write
- **`--content <text>`**: content to write
- **`--mode <mode>`**: one of `replace` (default), `append`, `prepend`, `patch`, `create`, `update`
- **`--patch <json>`**: JSON array of patch operations, used with `--mode patch`
- **`--meta <key=value>`**: set a metadata field, repeatable
- **`--if-match <version>`**: optimistic-concurrency token from a prior `stat`/`read`/`write`. Rejects the write with `AFS_CONFLICT` if the current version differs; providers that don't support it ignore the flag (last-write-wins)

**Example: write, then append**

```bash
$ arc afs write /demo/draft.txt --content 'first draft'
OK /demo/draft.txt

$ arc afs write /demo/draft.txt --content ' plus more' --mode append
OK /demo/draft.txt

$ arc afs read /demo/draft.txt
first draft plus more
```

### arc afs delete

Delete a file or directory.

**Usage**

```bash
arc afs delete [path] [options]
```

- `[path]` (positional, or **`--path <path>`**, one of the two is required): path to delete
- **`-r, --recursive`**: delete a directory recursively (default `false`)
- **`--dry-run`**: print what would be deleted without deleting it
- **`--yes`**: skip the TTY confirmation prompt (the prompt only appears when stdin is a real TTY; a non-interactive `arc afs delete` — a script, CI, this doc's own examples — never blocks on it either way)

Aliased as `arc afs rm`.

**Example: preview, then delete**

```bash
$ arc afs delete /demo/draft.txt --dry-run
Would delete /demo/draft.txt (dry-run)

$ arc afs stat /demo/draft.txt
PATH=/demo/draft.txt
KIND=fs:file
SIZE=21

$ arc afs delete /demo/draft.txt --yes
OK /demo/draft.txt
```

## Executing actions

### arc afs exec

Execute an action exposed by a provider at a given path, for example a provider-defined operation that isn't just a plain file read/write.

**Usage**

```bash
arc afs exec <executable_path> [options]
```

- **`executable_path`** (required): the action path to execute
- **`--args <json>`**: JSON arguments, e.g. `--args '{"key": "value"}'`

Not every mount exposes actions. Against a plain `fs://` mount attached to a running instance, calling an action path currently surfaces as a generic server error, not a specific one — the daemon's HTTP layer doesn't propagate the underlying AFS error text for this case:

```bash
$ arc afs exec /demo/.actions/foo
ERROR: Internal server error
```

In `--standalone` mode (no daemon in the loop) the same call gets the specific message instead:

```bash
$ arc afs exec /demo/.actions/foo --standalone
ERROR: No actions available for path: /.actions/foo
```

## Mount management

`arc afs mount` is its own subcommand group for managing what's mounted where.

```bash
arc afs mount <subcommand> [options]
```

**`arc afs mount add` writes to the `.afs-config/config.toml` found by walking up from your current directory — not to any `--instance`/`--home` instance.** `--home` is rejected outright (exit `5`) because that flag would imply the change reaches an instance's daemon, and it never does. `--instance` / `-i` is the global instance selector: if that instance isn't running, the command fails before `mount add` runs. Drop `--home` and run from the right directory instead. To change what a running instance has mounted: `cd` into that instance's home directory (the one you passed to `arc service start --home`) before running `arc afs mount add`, then it takes effect for that instance immediately, no restart needed. (This is the mechanism behind the "`mount add` is not automatically an acceptance path" caveat on the [AFS runtime boundaries](../../afs/runtime-boundaries/) page — running `mount add` from the wrong directory is what makes the mount show up in `mount list` but not in `ls`.)

```bash
$ arc afs mount add /demo fs:///path/to/a/local/directory --instance docs-demo
ERROR: no instance named "docs-demo". `arc service list` shows 0

$ arc afs mount add /demo fs:///path/to/a/local/directory --home /Users/you
ERROR: --home is not supported by `arc afs mount add`. `arc afs mount` only reads and writes the `.afs-config/config.toml` found by walking up from the current directory; it never reaches an instance's daemon, so the selected instance would silently not see the change. Drop the flag to edit the cwd config, or mount into a running instance at runtime with `arc attach --to <daemon-url> --namespace <ns> --source <dir>`.
```

```bash
cd ~/docs-demo                                    # the instance's --home directory
arc afs mount add /demo fs:///path/to/a/local/directory
arc afs ls /demo --instance docs-demo               # visible right away
```

### arc afs mount add

Add a mount.

**Usage**

```bash
arc afs mount add <path> <uri> [options]
```

- **`path`** (required): mount path, e.g. `/src`
- **`uri`** (required): provider URI, e.g. `fs://./src`
- **`--namespace <name>`**: mount namespace
- **`--description <text>`**: mount description
- **`--sensitive-args <names>`**: field names to treat as sensitive credentials
- **`-s, --set <key=value>`**: set a credential directly, repeatable, bypasses the interactive prompt
- **`--terminal`**: collect credentials via terminal readline instead of a browser
- **`-f, --force`**: force re-collecting credentials, ignoring cached values

**Example**

```bash
$ arc afs mount add /demo fs:///path/to/a/local/directory
Mounted fs:///path/to/a/local/directory at /demo
```

### arc afs mount list

List all mounts.

**Usage**

```bash
arc afs mount list [options]
```

Aliased as `arc afs mount ls`. There is no `--namespace` filter — the cwd `.afs-config/config.toml` is one table with no per-namespace slice to filter by, so passing `--namespace` is rejected:

```bash
$ arc afs mount list --namespace anything
ERROR: --namespace is not supported by `arc afs mount list`. `arc afs mount` reads and writes the cwd `.afs-config/config.toml` as one table; there is no per-namespace slice. Drop --namespace.
```

**Example** (one entry shown; your actual list will contain every mount you've added)

```bash
$ arc afs mount list
/demo -> fs:///path/to/a/local/directory
```

### arc afs mount remove

Unmount a path.

**Usage**

```bash
arc afs mount remove <path> [options]
```

- **`path`** (required, **positional only**): mount path to remove. `--help` also lists a `--path` option marked `[required]`, but passing it as a flag instead of positionally does not satisfy the requirement — it still fails with `Not enough non-option arguments: got 0, need at least 1`. Always pass the path positionally
- **`--namespace <name>`**: not supported — `arc afs mount` treats the cwd `.afs-config/config.toml` as one table with no per-namespace slice, so `remove --namespace foo` is rejected (`ERROR: --namespace is not supported by 'arc afs mount remove'`), same as on `mount list`

Aliased as `arc afs mount rm`.

**Example**

```bash
$ arc afs mount remove /demo
Unmounted /demo
```

Passing the path as `--path` instead of positionally does not work, even though `--help` lists it as a required option:

```bash
$ arc afs mount remove --path /demo
ERROR: Not enough non-option arguments: got 0, need at least 1
```

### arc afs mount validate

Validate the current mount configuration.

**Usage**

```bash
arc afs mount validate
```

**Example**

```bash
$ arc afs mount validate
Configuration is valid
```

## Notes on output

When an `afs` command talks to a running instance — the default — it writes nothing to stderr at all: the result on stdout is the whole output. Boot logging belongs to the daemon, not to your shell.

`--standalone` is the exception, because there the command boots AFS inside your own process and that boot log goes to your terminal. Three lines are invariant — the one naming the ad-hoc mode, one echoing which `.afs-config/config.toml` file(s) it read, and, whenever `AFS_DID_SPACE_SCOPE_SECRET` is unset, a `warn` record from `node:boot` reporting that DID Space scope de-identification is off and directory names are stored in plaintext:

```text
[standalone] not attached to any instance — ad-hoc mode (no runtime state)
[standalone] config: /path/to/.afs-config/config.toml
{"ts":"…","level":"warn","service":"arc-node","ns":"node:boot","message":"[afs-loader] AFS_DID_SPACE_SCOPE_SECRET unset — DID Space scope de-identification is OFF (plaintext directories). Set the secret to enable; set AFS_DID_SPACE_REQUIRE_DEID=true to enforce."}
```

Set the secret and the third line is gone; set `AFS_DID_SPACE_REQUIRE_DEID=true` to make its absence an error instead. Anything further on stderr is `node:boot` reporting on your own machine — a mount it could not establish, or a `[code-agents] recover ok: ...` line from the scheduler's own boot, say — so the total line count differs between hosts. Recognise the three above rather than counting them. None of it is part of the command's result, and all of it is omitted from the examples above.

---

## arc attach

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-attach/

`arc attach` reverse-mounts a local directory into a *remote* arc daemon, exposing it as a provider under `/modules/{namespace}` on that remote daemon. This is the opposite direction from `arc afs mount`: instead of mounting something remote into your local AFS, you're making something local visible to a remote AFS.

**Usage**

```bash
arc attach --to <url> [options]
```

`--to` is the only strictly required flag; what else you need depends on which of the three things you're attaching:

- **directory attach** (the default): `--namespace <name>` + `--source <dir>` — exposes a local directory as a provider mounted at `/modules/{namespace}` on the remote
- **host attach**: `--as-host` — exports this host's HostFace at `/peers/{peer.json.id}` on the remote (no `--namespace`/`--source` needed)
- **engine attach**: `--as-engine <name>` alone — attaches a bare code-agents engine under that id; combined with `--as-host` it's just display metadata alongside the HostFace

**Options**

- **`--to <url>`** (required): target daemon URL, e.g. `ws://host:4900` or `ws://host:4900/ws/attach`
- **`--namespace <name>`**: namespace to expose on the target, mounted at `/modules/{namespace}` (directory attach)
- **`--source <dir>`**: local directory to expose as the provider (directory attach)
- **`--as-engine <name>`**: engine id alone; with `--as-host` it's display metadata only (remote id is `peer.json`'s `id`)
- **`--as-host`**: export this host's HostFace at `/peers/{peer.json.id}` on the target
- **`--readonly`**: expose the source as read-only (directory attach)
- **`--replace`**: replace an existing session at this namespace
- **`--token <token>`**: owner access token for a remote daemon (skipped for loopback targets)
- **`--browser`**: open a browser for the auth flow (default `true`); pass **`--no-browser`** with `--token` for unattended runs
- **`--json`**: print machine-readable events on stdout instead of the default human text
- **`--view`**: output view format (`json` is equivalent to `--json`)
- **`--instance <name>`** / **`-i`**: which local ARC instance this command operates against; omit for `default`
- **`--home <dir>`**: instance root (where this host's `peer.json` and credentials live; usually not needed). To pick which instance, use `--instance`

On SIGINT (Ctrl+C) `arc attach` detaches gracefully so the remote side unmounts cleanly.

**Example**

```bash
arc attach --to ws://host:4900 --namespace my-local-src --source ./src --readonly
arc attach --to ws://host:4900 --as-host
```

### `--json`

With `--json`, every progress line (`Attaching...`, `to:`, `namespace:`, `source:`, `Press Ctrl+C to detach.`, `Detaching...`) moves to stderr, and stdout carries only newline-delimited JSON events — a script piping `arc attach ... --json` can read stdout as pure JSON without filtering out human prose:

```bash
$ arc attach --to ws://127.0.0.1:PORT/ws/attach --source /tmp --namespace test --json
```
stdout (only this one line, on a successful attach):
```json
{"event":"attached","sessionId":"sess_test_...","namespace":"test","targetPath":"/modules/test"}
```
stderr (all progress, banner omitted):
```
Attaching...
  to:        ws://127.0.0.1:PORT/ws/attach
  namespace: test
  source:    /tmp
Press Ctrl+C to detach.
```

On a failure, `--json` does not add a matching JSON object to stdout — stdout stays empty and the error is still the human `ERROR: ...` line on stderr, for both a validation failure (missing required combination) and a connection failure, exit `5` either way:

```bash
$ arc attach --to ws://127.0.0.1:1/ws/attach --source /tmp --json
```
stdout: (empty)

stderr:
```
ERROR: attach requires --namespace and --source, or --as-engine, or --as-host
```

```bash
$ arc attach --to ws://127.0.0.1:9/ws/attach --namespace test --source /tmp --json
```
stdout: (empty)

stderr:
```
Attaching...
  to:        ws://127.0.0.1:9/ws/attach
  namespace: test
  source:    /tmp
ERROR: attach failed [cockpit-unreachable]: connect ECONNREFUSED 127.0.0.1:9
```

---

## arc blocklet

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-blocklet/

`arc blocklet` covers a blocklet's whole lifecycle: scaffolding a new package, building it, validating it, and deploying it, either on its own or as part of a fleet.

Captured against `arc` `2.0.0-beta.50` (commit `a99fb2c37`, main, 2026-09-11). Run `arc --version` before you copy dumps; the commit is what pins the command surface.

```bash
arc blocklet <subcommand> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

## Scaffold

### arc blocklet create

Scaffold a new blocklet package. Aliased as `arc blocklet init` (kept for backwards compatibility).

**Usage**

```bash
arc blocklet create [dir] [options]
```

- `[dir]` (optional, default cwd): blocklet directory
- **`--name <name>`**: blocklet name (default: directory name)
- **`--recipe <name>`** (alias `--template`): scaffold recipe, one of `basic`, `blank`, `blog`, `agent`, `minimal-app`, `agent-workspace`, `support-community` (default `basic`)

`--name` must derive a legal blocklet identifier — checked, and rejected, *before* anything is written to disk:

```bash
$ arc blocklet create bad-dir --name "Not A Valid Name!"
ERROR: Error: Cannot derive a blocklet DID from --name "Not A Valid Name!": a blocklet identifier allows alphanumeric, hyphen, underscore only. Pass a valid identifier instead, e.g. --name Not-A-Valid-Name.
```

No `bad-dir` directory gets created. A valid name scaffolds normally, and prints a `Next:` hint for the next step in the pipeline:

```bash
$ arc blocklet create my-app --recipe basic
Created blocklet.yaml with did: "did:blocklet:my-app"
Next: arc blocklet build /path/to/my-app
```

The `Next:` chain follows the recipe's own capabilities: a DSL-bearing recipe (`minimal-app`, `agent-workspace`, `support-community`, `agent`, `blog`) inserts `arc dsl validate` before the build step, a manifest-only recipe (`basic`, `blank`) does not:

```bash
$ arc blocklet create my-agent --recipe minimal-app
Created minimal app blocklet "my-agent" with 18 file(s).
Next: arc dsl validate /path/to/my-agent

$ arc dsl validate /path/to/my-agent
Passed DSL validation
  path: /path/to/my-agent
  files: 16
Next: arc blocklet build /path/to/my-agent

$ arc blocklet build /path/to/my-agent
Published 20 file(s) → /path/to/my-agent/dist
  .afs/manifest.json  (http-mount protocol)
  blocklet.dist.json  (flat manifest)
  instance: requires /instance DID Space

Next: arc blocklet run /path/to/my-agent

Deploy to CF Pages:
  arc blocklet deploy /path/to/my-agent --project <project-name>
```

The `Next:` hint after a DSL-bearing scaffold is `arc dsl validate`, and that command does exit 0 on a fresh `minimal-app`. The rest of the DSL check chain is not uniformly green. With zero edits after `arc blocklet create . --recipe minimal-app`:

```bash
$ arc dsl lint .
Passed DSL lint
  path: /path/to/my-agent
  files: 16

$ arc dsl format --check .
Would format 0 file(s) (dry-run) — nothing to change
  path: /path/to/my-agent
  files: 5

$ arc dsl generate --check .
ERROR: Failed DSL generate (dry-run) — would change 4 file(s)
  path: /path/to/my-agent
  files: 11
  changed: .aup/app.json, .aup/pages/agent.json, .aup/pages/home.json, .aup/wrapper.json

  WARNING missing_man_coverage .aup/man/home.yaml: page "home" declares node-bound action(s) but has no .aup/man/home.yaml coverage
  ERROR generated_changed .aup/app.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/agent.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/home.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/wrapper.json: Generated artifact is stale. Run arc dsl generate --write.

$ arc dsl doctor .
ERROR: Failed DSL doctor
  path: /path/to/my-agent
  decompile step: failed (0 files, 0 changed)
```

`lint` and `format --check` exit 0; `generate --check` and `doctor` currently exit 5. This is the CLI's current behavior on a zero-edit scaffold, not a documentation workaround — do not treat those two gates as green just because `validate` passed.

### arc blocklet recipe

Discover the available scaffold recipes.

```bash
arc blocklet recipe <subcommand>
```

- **`arc blocklet recipe list`**: list scaffold recipes
- **`arc blocklet recipe explain <name>`**: explain one recipe

**Example**

```bash
$ arc blocklet recipe list
Blocklet scaffold recipes:
  basic
    Create only a blocklet manifest.
    capabilities: manifest
    generated files: 1
  ...
  minimal-app
    Create a tiny complete app with one web page, one AUP app, one agent, and generated settings.
    capabilities: web, aup, agent, settings
    generated files: 18
    source files: 14
  ...

$ arc blocklet recipe explain basic
Recipe: basic
  Create only a blocklet manifest.
  capabilities: manifest
  generated files:
    blocklet.yaml
  AFS data:
    blocklet.yaml
  checks:
    arc blocklet check <dir>
```

## Build and validate

This repo's own build-and-check pattern (`bun .claude/verify/config.ts`) is `arc blocklet check` then `arc blocklet build`, run against `blocklets/arcblock`.

### arc blocklet build

Build a Pages-ready `dist/`, copies files and writes `.afs/manifest.json` plus a flat manifest.

**Usage**

```bash
arc blocklet build [dir] [options]
```

- `[dir]` (optional, default cwd): blocklet directory
- **`--output <dir>`**: output directory (default `<dir>/dist`)
- **`--dry-run`**: compute the manifest without copying files or writing to disk
- **`--clean`**: clean the output directory before writing (default `true`)

On success it also prints a `Next: arc blocklet run <dir>` hint plus a `Deploy to CF Pages:` hint — see the full chain under [arc blocklet create](#arc-blocklet-create) above.

### arc blocklet check

Validate a blocklet against a recipe/profile contract. Aliased as `arc blocklet validate`.

**Usage**

```bash
arc blocklet check [dir] [options]
```

- `[dir]` (optional, default cwd): blocklet directory
- **`--profile <name>`**: validation profile, one of `basic`, `minimal-app`, `agent-workspace`, `support-community` (default `basic`)

Unlike `create` and `build`, `check` does not print a `Next:` hint on success.

### arc blocklet dev

Scan blocklet directory conventions and report the results, a lint pass over the directory shape rather than the DSL content (that's `arc dsl lint`).

```bash
arc blocklet dev [dir]
```

## Inspect

### arc blocklet list

List local blocklet packages: discovers `blocklet.yaml`, reports publish status.

```bash
arc blocklet list [dir]
```

### arc blocklet inspect

Show the manifest and file list for a local blocklet package.

```bash
arc blocklet inspect <ref>
```

- **`ref`** (required): path to a blocklet directory

## Run and deploy

### arc blocklet run

Serve a single blocklet on the daemon and print its access URLs.

**Usage**

```bash
arc blocklet run <path> [options]
```

- **`path`** (required): path to the blocklet directory to serve

To keep a source across daemon restarts, record it on a named instance: `arc service start --instance <name> --blocklet <path>`. See [arc service](../command-reference-service/).

### arc blocklet deploy

Publish a blocklet locally, then deploy it to Cloudflare Pages, in one step.

**Usage**

```bash
arc blocklet deploy [dir] [options]
```

- `[dir]` (optional, default cwd): blocklet directory
- **`--project <name>`**: Pages project name (default: blocklet id); multiple blocklets deployed to the same project share a single aggregated http-mount tree
- **`--domain <domain>`**: domain to bind the instance to
- **`--cloud <cf|none>`**: `cf` pushes to Cloudflare Pages, `none` is staging only (default `cf`)
- **`--branch <name>`**: git branch label for the deploy (default `main`)
- **`--staging-root <dir>`**: staging dir root (default `~/.afs/blocklets-staging`)
- **`--cf-account-id <id>`** / **`--cf-api-token <token>`**: forwarded to wrangler
- **`--verify`**: after `--cloud=cf` with `--domain`, verify the package, diagnostics, and live routes (default `true`)
- **`--routes <list>`**: space/comma-separated live routes to verify (default `/`)
- **`--compare-local`**: also fetch matching local routes and compare status/health
- **`--local-port <n>`**: local Arc port used with `--compare-local` (omit to use the instance registry)
- **`--timeout-ms <n>`**: per-request verification timeout in milliseconds (default `10000`)

### arc blocklet instance

Manage blocklet instances, i.e. deployments.

```bash
arc blocklet instance <subcommand> [options]
```

- **`arc blocklet instance deploy <ref>`**: deploy a published `dist/` to local Pages and bind a domain. `--cloud <fs|cf|none>` picks the target (default `fs`); `--pages-root <dir>` sets the local Pages store root for `--cloud=fs` (default `~/.arc/pages`)
- **`arc blocklet instance list`**: list deployed instances, i.e. Pages projects
- **`arc blocklet instance inspect <id>`**: show details for a deployed instance
- **`arc blocklet instance destroy <id>`**: tear down a deployed instance, removes all deployments and domains; requires `--force` to confirm
- **`arc blocklet instance logs <id>`**: show deploy history for a Pages instance (no runtime logs available — Pages has no runtime log stream). `--follow` was removed (it used to be accepted and immediately error "not supported"; now it's rejected outright as an unknown argument, exit `5`)

## Fleet

`arc blocklet fleet` deploys a group of blocklets as one aggregate Pages project, this is how a multi-domain site fleet (like this one) gets deployed together.

```bash
arc blocklet fleet <subcommand> [dir] [options]
```

Shared options across the fleet subcommands: `--blocklets <list>` (overrides `--fleet`), `--fleet <yaml>` (defaults to `<dir>/site-fleet.yaml` or `<dir>/fleet.yaml`), `--deployment <id>` (resolves the fleet manifest path from `instances.json`, mutually exclusive with `--fleet`), `--project <name>` (default `afsd-blocklets`), `--domain-root <domain>` (default `afsd.io`).

`--deployment`/`--fleet` is a declared, enforced conflict on all four subcommands (not just prose):

```bash
$ arc blocklet fleet deploy --deployment foo --fleet bar.yaml
ERROR: Arguments deployment and fleet are mutually exclusive
...
```

Passing only one of the two flags clears this specific check — it then fails later for a different, expected reason (no such fleet manifest here), which is how you tell the guard discriminates rather than rejecting everything:

```bash
$ arc blocklet fleet deploy --fleet bar.yaml
ERROR: Error: Fleet manifest not found: /path/to/bar.yaml
```

- **`arc blocklet fleet deploy [dir]`**: publish and deploy multiple blocklets with aliases, Web Provider assets, and smoke checks. `--publish` runs `arc blocklet build` for every blocklet before staging (default `true`); `--web-library` stages Web Provider themes/widgets into `/web/.library` (default `true`); `--web-library-dir <dir>` picks the Web Provider package dir to stage from (default `providers/runtime/web-device`)
- **`arc blocklet fleet verify [dir]`**: verify a deployed fleet without publishing or pushing changes
- **`arc blocklet fleet doctor [dir]`**: check local prerequisites for a fleet deploy (wrangler availability when `--cloud cf`, staging root, etc.)
- **`arc blocklet fleet rollback <deploymentId> [dir]`**: roll a Cloudflare Pages fleet project back to a previous deployment

---

## arc collections

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-collections/

`arc collections` is a small authoring-tool group for the `collections:` declarations in a blocklet's `blocklet.yaml` — the block that tells the runtime which `content/` subtrees are indexable collections, and what faces (web, sitemap, llms) they expose. Right now it has one subcommand.

```bash
arc collections <subcommand> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

### arc collections scan

Scan a site's `content/` directory and emit a `collections:` YAML fragment you can paste into `blocklet.yaml`, instead of hand-writing the declaration.

**Usage**

```bash
arc collections scan [dir] [options]
```

- `[dir]` (optional, default `.`): site root — the directory that contains `content/`

**Example** (run from a site root with a `content/` tree; two of the emitted collections shown, the rest follow the same shape)

```bash
$ arc collections scan .
# Paste into blocklet.yaml. mcp is intentionally omitted — opt-in only (epic #3657 W2).
collections:
  articles:
    type: local:articles
    indexable:
      - "content/articles/**/content.md"
    faces:
      web: true
      sitemap: true
      llms: [index, full]
  docs:
    type: local:docs
    indexable:
      - "content/docs/**/content.md"
    faces:
      web: true
      sitemap: true
      llms: [index, full]
  ...
```

Paste the emitted fragment into the target `blocklet.yaml`'s `collections:` key; `arc collections scan` only prints it, it does not write the file for you.

---

## arc completion

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-completion/

`arc completion` generates a tab-completion script for your shell and prints it to stdout. It never writes anywhere on disk — turning the output into a file, or appending it to your shell's startup file, is a step you do yourself.

Captured against `arc` `2.0.0-beta.48` (commit `5a5316bde`, main, 2026-09-10). Run `arc --version` before copying anything below; the generated script can change between builds.

## Usage

```bash
arc completion [shell]
```

- **`shell`**: `bash`, `zsh`, or `fish`. Omit it and `arc` detects your shell from `$SHELL`; if `$SHELL` is unset, or set to something that isn't one of those three, it falls back to `bash`:

```bash
$ env -i PATH="$PATH" SHELL=/bin/zsh arc completion | head -1
#compdef arc
$ env -i PATH="$PATH" SHELL=/usr/bin/tcsh arc completion | head -1
###-begin-arc-completions-###
```

## Generating a script

The three scripts are different lengths — bash has to do the matching and escaping itself, zsh hands most of that to `_describe`, and fish is a single `complete` call:

```bash
$ arc completion bash | wc -l
86
$ arc completion zsh | wc -l
67
$ arc completion fish | wc -l
14
```

A shell name outside the three choices is rejected the same way any other invalid choice value is — a yargs validation error, exit `5`:

```bash
$ arc completion nosuchshell
ERROR: Invalid values:
  Argument: shell, Given: "nosuchshell", Choices: "bash", "zsh", "fish"
```

(trimmed here — the rest of the block is the same text `arc completion --help` prints)

## Installing it

Each script's own header states how it expects to be installed. `arc completion <shell>` only prints; it never writes to any of the paths below for you.

### bash

```bash
arc completion bash >> ~/.bashrc
```

Use `~/.bash_profile` instead on macOS, per the comment inside the script. Open a new shell, or `source` the file, to pick it up.

### zsh

```bash
arc completion zsh >> ~/.zshrc
```

If your `~/.zshrc` has never run `compinit`, the script bootstraps it the first time it loads, so you don't add that step separately. It also re-registers itself on every prompt, so a later `compinit` elsewhere in your setup that rebuilds the completion table doesn't silently drop `arc`'s entry.

### fish

```bash
mkdir -p ~/.config/fish/completions
arc completion fish > ~/.config/fish/completions/arc.fish
```

The `mkdir -p` matters — `>` does not create the parent directory, and fish only picks up completion files that are already inside `~/.config/fish/completions/`.

## What it completes

Press Tab after any of these and the installed script asks the running `arc` binary what fits, so the answer always matches the binary you actually have, not a snapshot baked in when the script was generated:

- **Command names** — `arc d<TAB>` offers `did`, `deploy`, `drain`, `dsl`
- **Subcommand names** — `arc did <TAB>` offers `init`, `check`, `issue`, `verify`, `info`, `list`, `issuer`
- **`--instance` / `-i` values** — the same names `arc service list` would show, so `arc service status -i <TAB>` only ever offers an instance you actually have
- **`--recipe` / `--template` values** — `arc blocklet create --recipe <TAB>` offers the same choices `arc blocklet create --help` lists: `basic`, `blank`, `blog`, `agent`, `minimal-app`, `agent-workspace`, `support-community`

Anything else — an AFS path in `arc afs ls <TAB>`, for example — is not one of the slots above, so the script falls through to your shell's ordinary filename completion instead.

## How values reach your command line

Instance names and recipe names are not fixed at generation time. Each keystroke queries the arc binary you have installed right now, so a script you generated last week still offers an instance you created five minutes ago.

Insertion is also safe regardless of what characters a value contains. bash quotes every candidate with `printf %q` before inserting it, so an instance literally named `my prod box` completes to the three-word-safe `my\ prod\ box` instead of splitting into separate words, and a name containing shell metacharacters is never handed to the shell unescaped. zsh's `_describe` carries the same property built in.

## Exit codes

| What you ran | Exit code |
| --- | --- |
| `arc completion bash` / `zsh` / `fish` | `0` |
| `arc completion` (no argument, shell detected) | `0` |
| `arc completion <anything else>` | `5` |

---

## arc deploy

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-deploy/

`arc deploy` deploys and manages blocklets, both local daemon registration (for development) and DID Space publishing (for real distribution). This is a different thing from `arc blocklet deploy`, which pushes to Cloudflare Pages, `arc deploy` is about the local daemon and DID Space.

```bash
arc deploy <path> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

- **`path`**: local blocklet directory path, a `git+https://…` URL, or an `https://…/archive.tar.gz` URL — the latter two (remote sources) additionally require `--publish`, or the command fails fast with `Remote sources (git+url / http-url) require --publish.`

**Options**

- **`--publish`**: publish blocklet code to the local developer DID Space instead of registering with the local daemon (zero network/auth); only local publishes are visible to `arc deploy show`/`list --published`
- **`--server <url>`**: publish to a *remote* DID Space server instead of the local one, implies `--publish`; always requires auth (browser flow, cached credential, or `--token`), even against a loopback URL
- **`--token <token>`**: bearer token for `--server`, otherwise an interactive browser auth flow is used. Declared and enforced: passing `--token` without `--server` fails fast rather than silently ignoring the token —
  ```bash
  $ arc deploy /path/to/my-blocklet --token abc123
  ERROR: Missing dependent arguments:
   token -> server
  ```
  Passing both together clears that check and moves on to the real work — it fails here only because the path doesn't exist, proving the check discriminates rather than rejecting everything:
  ```bash
  $ arc deploy /path/to/my-blocklet --server http://127.0.0.1:9 --token abc123 --no-browser
  ERROR: Error: No blocklet found at /path/to/my-blocklet. Expected a directory with blocklet.yaml, .aup/, index.html, or a terminal index file.
  ```
- **`--browser`**: open a browser for the auth flow when publishing to `--server` (default `true`); pass **`--no-browser`** with `--token` for unattended runs
- **`--prerender`**: pre-render web pages into `.web-cache/` before publishing, same as `arc blocklet build`'s `ARC_PRERENDER`; on by default, pass `--no-prerender` or `ARC_PRERENDER=0` to opt out
- **`--dry-run`**: print the deploy plan without registering, publishing, or fetching

`arc deploy <path>` on its own registers and serves the blocklet for the current daemon session only — it does not survive a restart. There is no `--persist` flag on `arc deploy` itself; to make a blocklet source come back after `arc service restart`, record it on the instance instead:

```bash
arc service start --blocklet /path/to/my-blocklet   # or: arc service restart --blocklet /path/to/my-blocklet
```

**Examples** (from `arc deploy --help`)

```bash
arc deploy /path/to/my-blocklet                          # register and serve a local blocklet (hot-adds if the instance is running)
arc deploy /path/to/my-blocklet --dry-run                # preview a deploy without writing
arc service start --blocklet /path/to/my-blocklet        # record the source on the instance so it survives restart
arc deploy /path/to/my-blocklet --publish                # publish blocklet code to developer DID Space
arc deploy list                                          # list the default instance's registered blocklet sources
arc deploy list -i alice                                 # list only instance alice's registered sources
arc deploy list --home /path/to/instance                 # list sources of the instance registered at that home
arc deploy list --published                              # list blocklets published to DID Space
arc deploy show did:blocklet:z2x                         # read back files published to DID Space
arc deploy remove /path/to/my-blocklet                   # drop a source from the instance record; restart to apply
```

### arc deploy list

List all extra-registered blocklet sources, or published DID Space blocklets.

**Usage**

```bash
arc deploy list [options]
```

- **`--published`**: list blocklets published to DID Space (`blocklet-sources.json`), instead of registered sources

**Example**

```bash
$ arc deploy list
Registered blocklet sources (via instance default):
No extra blocklet sources registered.
Tip: arc service start --blocklet <path>
```

### arc deploy remove

Drop one registered extra blocklet source from the instance record (arc#6061; not a hot-unplug — restart to apply).

**Usage**

```bash
arc deploy remove <target> [options]
```

- **`target`** (required): blocklet dir, or its parent extra-source dir, to drop

**Example** (accept path: `target` is actually registered)

```bash
$ arc deploy remove /path/to/my-blocklet
Unregistered /path/to/my-blocklet from instance default.
Restart with `arc service restart` to apply.
```

Nothing registered to drop is a reject path, exit `1`:

```bash
$ arc deploy remove /path/to/my-blocklet
ERROR: Error: "/path/to/my-blocklet" is not a registered extra source on instance default.
Registered: (none)
```

### arc deploy show

Read back the files published to the developer DID Space for a blocklet.

**Usage**

```bash
arc deploy show <did> [subpath] [options]
```

- **`did`** (required): blocklet DID, or bare id, to inspect
- **`subpath`**: optional path inside the published tree

---

## arc did

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-did/

`arc did` manages identity and trust: generating a DID identity for yourself, a provider, or a blocklet; issuing and verifying verifiable credentials; and managing the list of issuers you trust.

Captured against `arc` `2.0.0-beta.50` (commit `a99fb2c37`, main, 2026-09-11). Run `arc --version` before you copy dumps; the commit is what pins the command surface.

```bash
arc did <subcommand> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`). `arc did init --home` is one of the places `--home` creates identity at a chosen root.

## Identity

### arc did init

Generate a DID identity.

**Usage**

```bash
arc did init [options]
```

- **`--developer`**: generate a developer root key (`ROLE_ACCOUNT`)
- **`--provider`**: derive a provider DID from the developer key (`ROLE_PROVIDER`)
- **`--blocklet`**: derive a blocklet DID from the developer key (`ROLE_BLOCKLET`)
- **`--force`**: overwrite an existing identity

Without any of `--developer`/`--provider`/`--blocklet`, it auto-detects which kind to generate based on where you run it.

### arc did info

Show identity and credential info.

```bash
arc did info
```

**Example** (run outside a recognized project)

```bash
$ arc did info
ERROR: No entity manifest found in current directory (looked for blocklet.yaml, .aup/, index.html, index.{txt,md,ans}, package.json)
```

**Example** (run inside a project that has an identity and an issued credential)

```bash
$ arc did info
acme-widget DID=z2qaHJMfMAjP3t1eooziSUa6n7v25AbyfH4G1 CREDENTIAL=true ISSUER=z2qaHJMfMAjP3t1eooziSUa6n7v25AbyfH4G1
```

### arc did check

Run conformance tests for the current provider.

```bash
arc did check
```

### arc did list

List identities stored in this instance home — reads whatever identity files are on disk; no running daemon is required. Captured against `arc` `2.0.0-beta.48` (commit `5a5316bde`, main, 2026-09-10).

```bash
arc did list [options]
```

**Example** (fresh home, nothing generated yet)

```bash
$ arc did list --home /tmp/arc-did-doc-home
No identities
```

**Example** (after `arc did init --developer`)

```bash
$ arc did init --developer --home /tmp/arc-did-doc-home
CREATED developer:developer DID=z1kExiHjGkUcBe6YTpyspLLNy1wb2vfCsV2
Next: arc did list --home /tmp/arc-did-doc-home
$ arc did list --home /tmp/arc-did-doc-home
developer DID=z1kExiHjGkUcBe6YTpyspLLNy1wb2vfCsV2 TYPE=developer
```

`--home` points straight at a folder on disk. `--instance` / `-i` instead resolves through the instance registry (`arc service list`); `did list` itself never needs a running daemon, but the name still has to be one you actually created:

```bash
$ arc did list -i doc519-nonexistent
ERROR: no instance named "doc519-nonexistent". `arc service list` shows 5
```

Exit `1`. (The number after `shows` is how many instances this machine had at capture time — it says nothing about the name you typed.) A real instance works whether its daemon is running or stopped — `arc service start` already generated it a `developer` identity, which is why the first `did list` against a fresh instance is not empty the way a bare `--home` folder is:

```bash
$ arc service start -i doc519didlist --home /tmp/arc-doc519-instance-home --port 0
...
  Status:   up
$ arc did list -i doc519didlist
developer DID=z1jhrDL9b5Et2jgSZJwPkL324R4aVaXBHbf TYPE=developer
$ arc service stop -i doc519didlist
Service stopped: doc519didlist
$ arc did list -i doc519didlist
developer DID=z1jhrDL9b5Et2jgSZJwPkL324R4aVaXBHbf TYPE=developer
```

(splash banner lines omitted from the `service start`/`service stop` output above.) `--json` returns the same rows as structured data:

```bash
$ arc did list -i doc519didlist --json
{
  "identities": [
    {
      "name": "developer",
      "did": "z1jhrDL9b5Et2jgSZJwPkL324R4aVaXBHbf",
      "entityType": "developer"
    }
  ],
  "total": 1,
  "hintSelector": "-i doc519didlist"
}
```

## Credentials

### arc did issue

Issue a verifiable credential.

**Usage**

```bash
arc did issue [options]
```

- **`--skip-check`**: skip the conformance check
- **`--counter-sign`**: counter-sign an existing VC with a trusted issuer key
- **`--issuer-key <path>`**: path to the issuer key file, used with `--counter-sign`
- **`--expiration <date>`**: expiration date, ISO format
- **`--all`**: issue VCs for all entities (providers + blocklets)
- **`--trust`**: auto-register the issuer as trusted after counter-signing

### arc did verify

Verify a credential.

```bash
arc did verify
```

## Trusted issuers

`arc did issuer` manages the list of issuers your setup trusts.

```bash
arc did issuer <subcommand> [options]
```

### arc did issuer list

List all trusted issuers.

**Example**

```bash
$ arc did issuer list
No trusted issuers
```

### arc did issuer add

Add a trusted issuer.

**Usage**

```bash
arc did issuer add <name> [options]
```

- **`--name <name>`** (required): issuer identifier, used as filename prefix
- **`--from-key <path>`**: path to a key file containing DID and public key
- **`--from-file <path-or-url>`**: path or HTTPS URL to a `.did.json` file
- **`--from-vc <path>`**: path to a VC file, extracts the counter-sign proof signer
- **`--proof-index <n>`**: select a specific proof by index, for `--from-vc` with multiple proofs
- **`--did <did>`**: DID address, base58 `z...` format
- **`--pk <key>`**: public key, hex format

### arc did issuer remove

Remove a trusted issuer.

```bash
arc did issuer remove <name>
```

### arc did issuer inspect

Show detailed information about a trusted issuer.

```bash
arc did issuer inspect <name>
```

### arc did issuer reset

Reset the trust store: remove manually-added issuers. This build has no shipped seed set to restore — on a clean home the command is a no-op.

**Usage**

```bash
arc did issuer reset [options]
```

- **`--yes`**: skip the confirmation prompt (required when stdin is not a TTY)

**Example** (clean home)

```bash
$ arc did issuer reset --yes
RESET no-op

$ arc did issuer list
No trusted issuers
```

`--help` still says "restore shipped seeds"; that one-liner does not match this build. `--json` reports `{"removed":[],"restored":[]}`. After you add an issuer, the same `--yes` command prints `REMOVED <name>` and `arc did issuer list` again reports `No trusted issuers`.

---

## arc drain

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-drain/

`arc drain` is a real CLI process, not a chat turn — killing whatever session started it does not stop draining unless this process itself is killed. It subscribes to `/dev/code-agents` (or the path you pass with `--subscribe-path`), and on each wake it claims ready work from the work ledger and execs `/dev/code-agents/.actions/run` with the claimed work. An empty ready set exits `0`; `arc drain` never creates ledger rows itself, it only consumes them.

**Usage**

```bash
arc drain --cwd <dir> [options]
```

- **`--cwd <dir>`** (required, no default): working directory passed to `/dev/code-agents/.actions/run`. Must **not** be the daemon's own project checkout
- **`--work-root <path>`**: work collection root, i.e. which AFS path holds the work records (default `/work`)
- **`--subscribe-path <path>`**: AFS path prefix to subscribe for wakes, e.g. `/dev/code-agents` or `/settled` (default `/dev/code-agents`)
- **`--engine <id>`**: restrict dispatch to this engine id (default: first idle dispatch target)
- **`--peer <id>`**: restrict dispatch to this peer id (default: first idle online peer)

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`). `--standalone` is also global (ad-hoc mode: load AFS from the current directory's local config instead of a running daemon). Drain is normally left against the default instance unless you pass `--instance`.

`arc drain` expects the target instance's daemon to already be up (e.g. via `arc service start`). Letting `drain` auto-start it instead boots a leaner AFS that skips the default `/work` mount, so it fails with `No module found for path: /work in namespace 'default'` before ever reaching the ledger.

**Example** (empty ready set, daemon already running)

```bash
$ arc drain --cwd /path/to/a/work/tree
ready set empty
```

Press Ctrl-C (SIGINT) or send SIGTERM to stop draining; either aborts the current wait cleanly.

**Example** (missing the required flag)

```bash
$ arc drain
ERROR: --cwd is required (no default — must not be the daemon's own project checkout)
```

---

## arc dsl

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-dsl/

`arc dsl` works with AUP DSL, the declarative language `.aup` files (like a page's `layout.aup`) are written in. Every subcommand except `lsp` takes a path (an `.aup` file or a blocklet directory) and defaults to the current directory.

Captured against `arc` `2.0.0-beta.50` (commit `a99fb2c37`, main, 2026-09-11). Run `arc --version` before you copy dumps; the commit is what pins the command surface.

```bash
arc dsl <subcommand> [path] [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

### arc dsl lint

Check DSL formatting and semantic validity. This is one of the four checks this repo's own merge gate runs.

**Usage**

```bash
arc dsl lint [path] [options]
```

- **`--fix`**: apply all safe lint fixes before linting
- **`--fix-format`**: rewrite DSL sources with canonical formatting
- **`--fix-ids`**: remove unreferenced explicit ids from page DSL sources
- **`--fix-locales`**: prune locale JSON keys not referenced by DSL sources

### arc dsl validate

Validate an `.aup` file or blocklet directory. The second of the four merge-gate checks.

```bash
arc dsl validate [path]
```

**Example**

```bash
$ arc dsl validate
Passed DSL validation
  path: /path/to/your/blocklet
  files: 368
Next: arc blocklet build /path/to/your/blocklet
```

On success it prints a `Next:` hint pointing at the next command to run (`arc blocklet build`); on failure it reports each problem as `ERROR <rule> path:line:col: message`. This is the only `dsl` subcommand that prints a `Next:` hint — `lint`, `format`, `generate`, `decompile`, `doctor`, and `migrate-i18n` do not.

### arc dsl schema

Print the AUP DSL language schema and primitive metadata.

```bash
arc dsl schema [path]
```

**Example**

```bash
$ arc dsl schema
Passed DSL schema
  path: /path/to/your/blocklet
  root: /path/to/your/blocklet
  primitives: 63
  aliases: 12
  snippets: 4
  files: 0
```

These counts are per-project: a blocklet that defines its own primitives (via `.scaffold/*.dsl`) reports a higher `primitives` number than a plain blocklet, and the built-in tally itself changes as the DSL language gains primitives across releases — run the command to see the current numbers rather than treating any fixed number here as canonical.

### arc dsl format

Format page `.aup` files.

**Usage**

```bash
arc dsl format [path] [options]
```

- **`--check`**: fail if formatting would change files
- **`--write`**: rewrite files in place

### arc dsl generate

Generate `app.json` and page JSON artifacts from `app.aup`.

**Usage**

```bash
arc dsl generate [path] [options]
```

- **`--check`**: fail if generated artifacts would change
- **`--write`**: rewrite generated artifacts in place

On a fresh `minimal-app` scaffold with zero edits, `--check` currently exits 5 (`generated_changed` on `.aup/app.json`, `.aup/pages/agent.json`, `.aup/pages/home.json`, `.aup/wrapper.json`). See the check chain under [arc blocklet create](../command-reference-blocklet/#arc-blocklet-create).

### arc dsl decompile

Decompile generated AUP JSON artifacts back into AUP DSL sources, the reverse of `generate`.

**Usage**

```bash
arc dsl decompile [path] [options]
```

- **`--check`**: fail if decompiled DSL would change files
- **`--write`**: rewrite decompiled DSL files in place
- **`--partial`**: write sources that can be decompiled, downgrade missing page artifacts to warnings instead of failing

### arc dsl doctor

Run decompile, format, regenerate-check, and validate together, a one-command health check for DSL artifacts.

**Usage**

```bash
arc dsl doctor [path] [options]
```

- **`--check`**: fail if doctor would change files
- **`--write`**: rewrite decompiled DSL files in place before verifying

On that same zero-edit `minimal-app` scaffold, `arc dsl doctor` currently exits 5 (`decompile step: failed (0 files, 0 changed)`). Same transcript as the check chain under [arc blocklet create](../command-reference-blocklet/#arc-blocklet-create).

### arc dsl migrate-i18n

Move exact `$t(page.key)` strings into page-local inline i18n blocks.

**Usage**

```bash
arc dsl migrate-i18n [path] [options]
```

- **`--check`**: fail if migration would change files
- **`--write`**: rewrite page DSL and locale JSON files in place

### arc dsl language

Inspect DSL diagnostics, completions, and hover metadata, the machinery behind editor integrations.

**Usage**

```bash
arc dsl language [path] [options]
```

- **`--line <n>`**: one-based line for completion/hover lookup
- **`--column <n>`**: one-based column for completion/hover lookup

### arc dsl lsp

Start a JSON-RPC language server for AUP DSL editor integrations.

```bash
arc dsl lsp
```

---

## arc mcp

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-mcp/

`arc mcp` bridges stdio to the running AFS daemon's MCP endpoint. It auto-starts the daemon if it isn't already running.

**Usage**

```bash
arc mcp [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

- **`--port <port>`**: daemon port, 1-65535 (omit, or pass `0`, to use the instance registry / seed `default` on `4900`)

**Example** (auto-starts the daemon; blocks on stdio afterward)

```bash
$ arc mcp
Starting AFS service...
```

A port already held by another instance is a reject path, exit `1`:

```bash
$ arc mcp --port 4900
Starting AFS service...
ERROR: Failed to start service: Port 4900 is already in use
```

**Claude Desktop config**

```json
{ "mcpServers": { "AFS": { "command": "arc", "args": ["mcp"] } } }
```

`arc mcp` is a bridge, not a standalone MCP server. If you want a standalone one, use `arc serve --transport mcp-stdio` (loads AFS directly) or `arc serve --transport mcp-http`.

---

## arc network

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-network/

`arc network` answers one question: can this machine reach the outside world the way `arc` needs to? It has a single subcommand, `doctor`, which runs four checks — proxy discovery, DNS, an HTTPS request, and a WebSocket handshake — and reports each on its own line. They are reported separately on purpose: "DNS resolves but the proxy refuses CONNECT" and "nothing resolves at all" are different faults with different fixes, and a single pass/fail would hide which one you have.

Captured against `arc` `2.0.0-beta.48` (commit `5a5316bde`, 2026-09-10). The version number alone does not pin this — `2.0.0-beta.48` has named more than one binary this cycle — so run `arc --version` and compare its third field, the commit, against the one above before trusting anything below byte-for-byte; checks and flags can move between releases regardless.

**Usage**

```bash
arc network doctor [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`). `doctor` does not talk to a daemon, so it works whether or not one is running.

- **`--target <url>`**: HTTPS URL to probe (default `https://main.abtnetwork.io/`)
- **`--ws-target <url>`**: WSS URL to probe (default `wss://main.abtnetwork.io/api/websocket?vsn=2.0.0`)

`arc network` on its own is not a command: it prints `Please specify a subcommand` along with the subcommand list, and exits `5`.

**Example** (everything reachable, no proxy)

```bash
$ arc network doctor
Outbound network doctor

Proxy:
  (none)

Checks:
  ✓ proxy-discovery         no proxy environment variables
  ✓ direct-dns              main.abtnetwork.io → 198.18.0.38
  ✓ https-through-proxy     HTTP 200 direct
  ✓ wss-through-proxy       WSS handshake direct

OK
```

All four passing exits `0`. The two network checks keep `through-proxy` in their names even when no proxy is involved; the detail column is what tells you which route was actually taken — `direct` here.

**The address on the `direct-dns` line is whatever your own resolver returns**, so expect a different one, and on a network with a captive or filtering resolver expect an address the name does not really have. This is worth more than a footnote, because the layer a failure gets attributed to follows the resolver: a name that does not exist is reported as a DNS failure where the resolver says so, and as a connection or TLS failure where the resolver answers anyway. When a `doctor` result surprises you, confirm the name independently before believing which check went red.

**Example** (a proxy is configured but not answering)

```bash
$ HTTPS_PROXY=http://127.0.0.1:9 HTTP_PROXY=http://127.0.0.1:9 arc network doctor
ERROR: Outbound network doctor

Proxy:
  HTTP_PROXY   http://127.0.0.1:9/
  HTTPS_PROXY  http://127.0.0.1:9/

Checks:
  ✓ proxy-discovery         proxy environment variables present (credentials redacted)
  ✓ direct-dns              main.abtnetwork.io → 198.18.0.38
  ✗ https-through-proxy    PROXY_CONNECT_FAILED  connect ECONNREFUSED 127.0.0.1:9
  ✗ wss-through-proxy      PROXY_CONNECT_FAILED  connect ECONNREFUSED 127.0.0.1:9

FAILED
```

Any failing check exits `5`. The `ERROR: ` prefix on the first line is the CLI's one sole marker for "this run failed" (arc#6301) — every failure the CLI reports, from any command, starts a message this same way, so a caller can find the front of an error without knowing which command produced it. Notice what stayed green: proxy discovery passed because it only reports which variables are set, not whether the proxy works, and DNS passed because resolution never went through the proxy at all. The two that failed name the reason — `PROXY_CONNECT_FAILED` — instead of a generic timeout, which is what tells you to look at the proxy rather than at DNS or at the target host. Proxy URLs are printed with any credentials redacted.

**Machine-readable output**

`--json` prints the same run as structured data. Below is the failing run above, because failure is where the interesting fields appear: each failed check gains a `code`, and `required` / `affectsOverallHealth` say which results the verdict is computed from. `direct-dns` flips to `required: false` here — once a proxy is in play, resolving directly is no longer something the verdict depends on.

```bash
$ HTTPS_PROXY=http://127.0.0.1:9 HTTP_PROXY=http://127.0.0.1:9 arc network doctor --json
ERROR: {
  "proxy": {
    "httpProxy": "http://127.0.0.1:9/",
    "httpsProxy": "http://127.0.0.1:9/"
  },
  "checks": [
    {
      "name": "proxy-discovery",
      "ok": true,
      "status": "pass",
      "required": true,
      "affectsOverallHealth": true,
      "detail": "proxy environment variables present (credentials redacted)"
    },
    {
      "name": "direct-dns",
      "ok": true,
      "status": "pass",
      "required": false,
      "affectsOverallHealth": false,
      "detail": "main.abtnetwork.io → 198.18.0.38"
    },
    {
      "name": "https-through-proxy",
      "ok": false,
      "status": "fail",
      "required": true,
      "affectsOverallHealth": true,
      "code": "PROXY_CONNECT_FAILED",
      "detail": "connect ECONNREFUSED 127.0.0.1:9"
    },
    {
      "name": "wss-through-proxy",
      "ok": false,
      "status": "fail",
      "required": true,
      "affectsOverallHealth": true,
      "code": "PROXY_CONNECT_FAILED",
      "detail": "connect ECONNREFUSED 127.0.0.1:9"
    }
  ],
  "ok": false
}
```

The leading `ERROR: ` above is real and not a copy-paste mistake: on a failing run the same one-sink prefix from the human example lands in front of the JSON too, on the same line as the opening `{`, because a failed command's whole message — human text or JSON, this CLI does not distinguish at that point — gets the marker prepended once. Strip that one token before parsing on a non-zero exit, or route on the exit code instead of trying to parse stderr as JSON at all. A clean run is the same shape with the `code` fields absent, every `status` set to `pass`, `proxy` an empty object, and the top-level `ok` true — and no `ERROR: ` prefix, because it only appears on failure. One more thing worth knowing before you pipe this: on a failing run **stdout is 0 bytes** — the whole message, prefix and all, goes to stderr — so `arc network doctor --json | jq` sees nothing at all rather than an error object; check the exit code first, or you will end up debugging your `jq` filter instead of the actual failure.

The two targets move independently. `--target` retargets the HTTPS probe and the DNS check with it — probing `https://arc.arcblock.io/` puts `arc.arcblock.io → …` on the `direct-dns` line instead of the default host — while `--ws-target` moves only the WebSocket probe, leaving DNS on whatever `--target` names. Aiming `--ws-target` at a closed port therefore fails exactly one check:

```bash
$ arc network doctor --ws-target wss://127.0.0.1:9/
ERROR: Outbound network doctor

Proxy:
  (none)

Checks:
  ✓ proxy-discovery         no proxy environment variables
  ✓ direct-dns              main.abtnetwork.io → 198.18.0.38
  ✓ https-through-proxy     HTTP 200 direct
  ✗ wss-through-proxy      UPSTREAM_REJECTED

FAILED
```

A literal address and a closed port were chosen here so the probe fails the same way on every machine — no name to resolve means no resolver to disagree. What names the failed layer is the `code`, `UPSTREAM_REJECTED`, distinct from `PROXY_CONNECT_FAILED` / `DIRECT_DNS_FAILED` / `TLS_FAILED`; the free-text detail after it is not guaranteed and came back empty in this capture — an immediately-refused loopback connection did not leave the underlying socket layer anything to say. Do not match on the detail text; match on the `code`, in `--json` if you need it structured. Use these two flags when the defaults are reachable but the host you actually care about is not.

---

## arc provider

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-provider/

`arc provider` handles operations on provider packages themselves (the npm packages that implement AFS providers), as opposed to `arc afs`, which operates on what a provider exposes once mounted.

```bash
arc provider <subcommand> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

### arc provider publish-resources

Publish a provider package's `aup/` tree to CF Pages, under `/_providers/<name>@<version>/`. This is how a provider's companion resources (like UI snippets referenced from AUP) become fetchable by URL.

**Usage**

```bash
arc provider publish-resources <package> [options]
```

- **`package`** (required): npm package name, e.g. `@aigne/afs-ocap`, or a path to the package directory
- **`--cloud <fs|cf|none>`**: deploy target: `fs` writes a local Pages dir, `cf` pushes to Cloudflare Pages, `none` stages into `~/.afs/blocklets-staging` without pushing, for batch deploys where only the last command should push (default `fs`)
- **`--pages-root <path>`**: local Pages store root, only for `--cloud fs` (default `~/.arc/pages`)
- **`--cf-account-id <id>`**: Cloudflare account ID, used for `--cloud cf` read operations
- **`--cf-api-token <token>`**: Cloudflare API token, used for `--cloud cf` read operations
- **`--deployment <id>`**: Cloudflare deployment id (staging/prod/...), resolves `pagesProject` from `runtimes/cloudflare/instances.json`; mutually exclusive with `--project`
- **`--project <name>`**: Pages project name, an escape hatch for projects not in `instances.json`; mutually exclusive with `--deployment`; defaults to `afsd-blocklets` when neither is set

The `--deployment`/`--project` exclusion is declared and enforced, not just documented:

```bash
$ arc provider publish-resources @aigne/afs-ocap --deployment foo --project bar
ERROR: Arguments deployment and project are mutually exclusive
```

A real package publishes to `--cloud fs` without either flag (the cumulative-staging count keeps growing with every publish to that store, so yours will differ):

```bash
$ arc provider publish-resources ./providers/runtime/ocap --cloud fs --pages-root /tmp/pages
Published 23 file(s) to /_providers/ocap@2.0.0-beta.48/
  package:  ./providers/runtime/ocap
  provider: ocap@2.0.0-beta.48
  bytes:    170952
  target:   local Pages store (cumulative staging: 1983 file(s))
  deploy:   deploy-1789005081569-e83ray
```

---

## arc serve

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-serve/

`arc serve` starts an AFS server, over HTTP or MCP, so something other than the CLI itself (a browser, an agent, an MCP client) can talk to your AFS instance over the network.

**Usage**

```bash
arc serve [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

- **`--host <host>`**: host to bind (default `localhost`)
- **`--port <port>`**: port to listen on (default `3000`)
- **`--path <path>`**: base path for the API (default `/afs`)
- **`--readonly`**: read-only mode
- **`--cors`**: enable CORS; pass no value for off, `*` for any origin, or a comma-separated allowlist
- **`--transport <http|mcp-stdio|mcp-http>`**: transport mode (default `http`). `mcp-http` is local-dev-only by design, it has no Bearer token support
- **`--token <token>`**: require a Bearer token on every request; overrides `serve.token` from config
- **`--insecure-no-auth`**: explicitly serve without an auth token when binding to a non-loopback host. Dangerous, anyone who can reach the bound address gets full AFS access

This is different from `arc service`, which manages named long-running background instances. `arc serve` is a foreground process for a single session. See [arc service](../command-reference-service/).

**Example**

```bash
$ arc serve --port 4000 --cors '*'
AFS HTTP Server starting...
Mounted providers:
  ...

Listening on: http://localhost:4000/afs
Press Ctrl+C to stop
```

---

## arc service

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-service/

`arc service` manages named AFS background instances. `arc afs`, MCP bridging, and blocklet serving all depend on a running instance.

Captured against `arc` `2.0.0-beta.48`, commit `5a5316bde` (main, 2026-09-10) — not the published binary of the same version string; two different builds have carried `2.0.0-beta.48` at once, so this page is pinned to the commit, not the semver. `arc service` is **nine real subcommands** (`arc service <verb> [options]`), each with its own `--help` and `Examples:` block — not one command with a positional `action` choice list. `--json` reject path remeasured after ArcBlock/arc#5205 (error object on stdout — corrected again below, see [`--json` contract](#json-contract)); `delete` became the primary action name after ArcBlock/arc#5279 (`rm`/`remove` are now aliases); the subcommand split and the `ERROR: ` prefix on every failure line are both ArcBlock/arc#6301. Positional instance names were removed in ArcBlock/arc#5713: the only way to pick an instance is `--instance` / `-i`. Run `arc --version` before you copy dumps; verbs and flags can still move. `--help` text below is English (`LC_ALL=C`) — since ArcBlock/arc#5244, help/error text is always English regardless of your system locale.

Instance names, home paths and ports below are shortened to a readable `docs514a` / `/tmp/arc-svc-docs-514/...` form; the message text, field names, exit codes and JSON shapes are copied verbatim from a real run.

```bash
arc service <verb> [options]
```

`verb` is one of `list` (`ls`, `ps`), `start`, `stop`, `restart`, `status`, `delete` (`rm`, `remove`), `gc` (`prune`), `url`, `logs` (`log`). Pick the instance with `--instance <name>` / `-i`. Omit `--instance` to operate on the seed instance `default` (home `~`, port `4900`). Any other name gets a kernel-assigned port unless you pass `--port`.

Do not `stop` or `delete` a seed instance you did not start. The dumps on this page used a throwaway registry and never touched the machine's `default` on `:4900`.

## Isolation

Named instances plus `--home` are the isolation mechanism. `ARC_HOME` is **retired**: the CLI warns and ignores the value.

```bash
export ARC_INSTANCES_DIR=/tmp/arc-svc-docs-514/instances
arc service start --instance docs514b --home /tmp/arc-svc-docs-514/home-b
```

`ARC_SERVICE_PORT` still exists, but it only affects the unnamed seed instance. Prefer a name, or pass `--port`.

Splash banner lines on stderr are omitted in the dumps below.

## Subcommands

Each subcommand carries its own `--help` and its own `Examples:` (see the [`--help`](#help) section at the bottom of this page). `arc service <bad-verb>` and `arc service` with no verb both print the group listing below, not a per-verb one.

| Subcommand | Aliases | What it does |
| --- | --- | --- |
| `list` | `ls`, `ps` | List every local instance with its status, port and home |
| `start` | | Start an instance, creating it on first use |
| `stop` | | Stop a running instance, keeping its record and data |
| `restart` | | Restart an instance from its recorded config — does not reconfigure; `stop` then `start` for that |
| `status` | | Report whether an instance is running, and on which port |
| `delete` | `rm`, `remove` | Delete an instance: its record and its data |
| `gc` | `prune` | Drop registry records whose process is gone |
| `url` | | Print an instance's base URL (and its blocklets') |
| `logs` | `log` | Print an instance's daemon log |

## Flags

Every subcommand accepts the shared globals — `--json`, `--view`, `--home`, `--instance` / `-i`, `--print` — plus its own extra flags:

| Flag | Subcommand(s) | Meaning |
| --- | --- | --- |
| `-i`, `--instance` | all | Named local ARC instance this command operates against. Omit for `default`. This is the only way to pick an instance |
| `--home` | all | Instance root. Used by `start` (create) and `arc did init`. On `restart` it is cross-checked against the recorded home rather than accepted as new config — matching it is a no-op, naming a different path is rejected (see [Failures](#failures)) |
| `--print` | all | Print one result field (for example `url`, `port`) as plain text — not a view; overrides `--json`/`--view`. See [`--print`](#print) below |
| `--port` | `start` | Listen port (0–65535). `0` = auto-assign. Omit: `default` uses `4900`, named instances use the recorded port or auto-assign |
| `--host` | `start` | Bind address (`localhost`, `0.0.0.0`, `::`, or a unicast IP). Default `localhost` |
| `--advertise` | `start` | Advertise over mDNS when bind is non-loopback (default `true`; `--no-advertise` disables) |
| `--blocklet` | `start` | Blocklet-parent or single-blocklet dir to serve (repeatable). Recorded on the instance |
| `--space-root` | `start` | Folder-as-DID-Space from `arc space init`. Omit to derive from `--home` |
| `--force` | `delete` | Stop a running instance before deleting it. Default `false` |
| `--dry-run` | `delete` | Print what would be removed without deleting it. Default `false` |
| `--yes` | `delete` | Skip the TTY confirmation prompt. Default `false` |
| `--follow` | `logs` | Stream new lines as they are written. Default `false` |

`--yaml` was removed, never implemented — see [Overview](../overview/).

`restart` has none of `start`'s config flags in its own `--help` — passing one is refused with a dedicated message, not yargs' generic "unknown argument" (that generic path is what genuinely-removed flags like `--blocklet-dir` hit; see [Removed and retired](#removed-and-retired)):

```bash
$ arc service restart --instance docs514a --port 4910
ERROR: restart does not reconfigure. use `stop` then `start` to change --port
```

`--home` is the one exception: it is a global flag, so `restart --home <same path as recorded>` succeeds silently (a no-op), and only a **different** path is rejected — with a different message and exit code than the config-flag guard above:

```bash
$ arc service restart --instance docs514a --home /tmp/somewhere-else
ERROR: --instance "docs514a" and --home "/tmp/somewhere-else" name different instances (instance "docs514a" is registered at "/tmp/arc-svc-docs-514/home-a")
```
(exit `5`, versus exit `1` for `--port`/`--host`/`--advertise`/`--space-root`/`--blocklet`.)

## States

| Status | Meaning |
| --- | --- |
| `starting` | Record claimed, process not yet `up` |
| `up` | Process is listening |
| `stopped` | Process exited through `stop`. `start` / `restart` reuse the record |
| `dead` | Process gone without a clean stop. `gc` removes only this state |

`list` shows the **recorded** port for every non-`up` row, suffixed `*` to mark it last-known rather than live (`stopped`/`dead` both get the suffix); `-` appears only when there is no recorded port at all (an instance that never reached `up`):

```
NAME          ID                PORT    STATUS   HOME                          SOURCES
docs514a      b719db414c5cc62  61497*  stopped  /tmp/arc-svc-docs-514/home-a  1
```

`status` exits `0` for `up`, `3` for `starting` / `stopped`, and `4` for `dead`. For anything but `up` it still reports the pid / port / URL from the last run, and marks them as such (`lastKnown` in `--json`, a `Note:` line in the human view).

## Start, list, status, url

Empty registry:

```bash
$ export ARC_INSTANCES_DIR=/tmp/arc-svc-docs-514/instances
$ arc service list
NAME          ID                PORT   STATUS   HOME                          SOURCES
(no instances)
```

Start a named instance. Port `61497` was kernel-assigned, not `4900`:

```bash
$ arc service start --instance docs514a --home /tmp/arc-svc-docs-514/home-a
  Instance: docs514a
  ID:       b719db414c5cc624
  Status:   up
  PID:      95665
  Port:     61497
  URL:      http://127.0.0.1:61497
  Home:     /tmp/arc-svc-docs-514/home-a
  Space:    /tmp/arc-svc-docs-514/home-a/.afs/spaces
  Sources:  -
  Version:  2.0.0-beta.48
  Commit:   5a5316bde
  Checkout: /tmp/arc-svc-docs-514/project
  Host:     localhost
  Started:  2026-09-10T01:52:25.130Z (up 2s)
```

Progress, log path, build id, and endpoints went to stderr. The instance record went to stdout — stderr on this capture (omitting the banner):

```
Starting AFS service...
AFS Service started
  Log:  /tmp/arc-svc-docs-514/home-a/.afs/daemon.log
  Build: 2.0.0-beta.48+5a5316bde (debug)
  Exec:  /path/to/arc/runtimes/node/dist/cli.mjs

  Endpoints:
    http://127.0.0.1:61497/            AUP Web Client
    http://127.0.0.1:61497/explorer    Explorer UI
    http://127.0.0.1:61497/ws          WebSocket (Explorer)
    http://127.0.0.1:61497/afs/*       REST API
    http://127.0.0.1:61497/mcp         MCP Streamable HTTP
```

`Build` / `Exec` come from `<home>/.afs/daemon.build.json`, which the daemon writes on boot; on an older daemon that has no sidecar the two lines are omitted rather than guessed. `Version` / `Commit` / `Checkout` describe the binary that is actually serving the instance — see [Identity fields](#identity-fields) below.

Record a blocklet source with `--blocklet` (repeatable). Same flag accepts a parent directory or a single blocklet directory:

```bash
$ arc service start --instance docs514b --home /tmp/arc-svc-docs-514/home-b \
    --blocklet /path/to/arc/blocklets/afs-preview-fixture --host 127.0.0.1 --no-advertise
  Instance: docs514b
  ID:       b719db414c5cc625
  Status:   up
  PID:      95666
  Port:     61498
  URL:      http://127.0.0.1:61498
  Home:     /tmp/arc-svc-docs-514/home-b
  Space:    /tmp/arc-svc-docs-514/home-b/.afs/spaces
  Sources:  /path/to/arc/blocklets/afs-preview-fixture
  Version:  2.0.0-beta.48
  Commit:   5a5316bde
  Checkout: /tmp/arc-svc-docs-514/project
  Host:     127.0.0.1
  Started:  2026-09-10T01:49:56.435Z (up 7s)
```

stderr for that run added an `Extra blocklet dirs:` line before the banner-omitted `AFS Service started`, and a `Blocklet:` block after `Endpoints:`:

```
Starting AFS service...
  Extra blocklet dirs: /path/to/arc/blocklets/afs-preview-fixture
AFS Service started
  Log:  /tmp/arc-svc-docs-514/home-b/.afs/daemon.log
  Build: 2.0.0-beta.48+5a5316bde (debug)
  Exec:  /path/to/arc/runtimes/node/dist/cli.mjs

  Endpoints:
    http://127.0.0.1:61498/            AUP Web Client
    http://127.0.0.1:61498/explorer    Explorer UI
    http://127.0.0.1:61498/ws          WebSocket (Explorer)
    http://127.0.0.1:61498/afs/*       REST API
    http://127.0.0.1:61498/mcp         MCP Streamable HTTP

  Blocklet: afs-preview-fixture
    http://afs-preview-fixture.localhost:61498/
    http://localhost:61498/?blocklet=afs-preview-fixture    (Safari / universal)
```

```bash
$ arc service list
NAME          ID                PORT   STATUS   HOME                          SOURCES
docs514a      b719db414c5cc624  61497  up       /tmp/arc-svc-docs-514/home-a  0
docs514b      b719db414c5cc625  61498  up       /tmp/arc-svc-docs-514/home-b  1
```

`status` reports everything `start` reported, for an instance you did not just start — same stdout/stderr split:

```bash
$ arc service status --instance docs514b
  Instance: docs514b
  ID:       b719db414c5cc625
  Status:   up
  PID:      95666
  Port:     61498
  URL:      http://127.0.0.1:61498
  Home:     /tmp/arc-svc-docs-514/home-b
  Space:    /tmp/arc-svc-docs-514/home-b/.afs/spaces
  Sources:  /path/to/arc/blocklets/afs-preview-fixture
  Version:  2.0.0-beta.48
  Commit:   5a5316bde
  Checkout: /tmp/arc-svc-docs-514/project
  Host:     127.0.0.1
  Started:  2026-09-10T01:49:56.435Z (up 3m)
```

Log path, build id, endpoints, blocklet URLs and (on a non-loopback bind) the LAN diagnostic go to stderr; the record goes to stdout. `start` and `status` print the same URL for the same instance — both use the registry's `http://127.0.0.1:<port>` form. `--json` suppresses the stderr blocks and carries all of it as data instead.

On a machine whose project root exposes many blocklets, `status` expands only the routes you named with `--blocklet` and counts the rest — this is a real capture against a full dev checkout, not a contrived number:

```
  Blocklets: 51 route(s) served — 50 not expanded; `arc service url` or --json lists them all
```

`--json` always carries every route in `urls.blocklets`.

```bash
$ arc service url --instance docs514b
http://127.0.0.1:61498/
```

stderr (banner omitted), same printer as `start`:

```
  Blocklet: afs-preview-fixture
    http://afs-preview-fixture.localhost:61498/
    http://localhost:61498/?blocklet=afs-preview-fixture    (Safari / universal)
```

```bash
$ arc service url --instance docs514b --print url
http://127.0.0.1:61498
```

`--print url` writes only the instance URL to stdout (no trailing slash in this capture), exit `0`. `$(arc service url --instance NAME)` stays that one line. Agents that need a blocklet address use `--json` and the **Host** URL (`http://afs-preview-fixture.localhost:…`). `?blocklet=` is the Safari fallback; it does not mount `/blocklets/<name>` for RPC.

### Identity fields

`Version` / `Commit` / `Branch` / `Sha` / `Checkout` describe **the binary serving this instance**, not the `arc` you typed. The daemon computes them at boot and writes them into its registry row, so a `status` from any shell reports the same values as `curl http://127.0.0.1:<port>/.well-known/arc/instance`.

For an `up` instance, `status` asks the daemon directly and reports the answer under `live`:

```json
"live": {
  "ok": true,
  "url": "http://127.0.0.1:61498/.well-known/arc/instance",
  "record": { "version": "2.0.0-beta.48", "commit": "5a5316bde", "pid": 95666, "port": 61498, "blocklets": 1 }
}
```

If the registry row and the daemon disagree — which is what `arc upgrade` does, swapping the binary under a running process — both values are reported and the differing fields are listed under `drift`:

```json
"drift": [{ "field": "version", "registry": "2.0.0-beta.48", "live": "2.0.0-beta.49" }]
```

The probe is best effort. If the process is alive but nothing answers on loopback in time — captured here from a `SIGSTOP`ped daemon, which is why the exact wording is a timeout rather than a refused connection — `status` falls back to the registry view and says so; the exit code is unchanged:

```
  Live:     unreachable (The operation was aborted due to timeout) — registry values only
```

(A daemon that is fully gone rather than merely unresponsive reports `dead` instead — see [States](#states) — and is not probed at all.)

## Restart, logs, stop, delete, gc

`restart` reuses the record. It does not take a new `--port`:

```bash
$ arc service restart --instance docs514b
  Instance: docs514b
  ID:       b719db414c5cc625
  Status:   up
  PID:      95700
  Port:     61498
  URL:      http://127.0.0.1:61498
  Home:     /tmp/arc-svc-docs-514/home-b
  Space:    /tmp/arc-svc-docs-514/home-b/.afs/spaces
  Sources:  /path/to/arc/blocklets/afs-preview-fixture
  Version:  2.0.0-beta.48
  Commit:   5a5316bde
  Checkout: /tmp/arc-svc-docs-514/project
  Host:     127.0.0.1
  Started:  2026-09-10T01:58:00.472Z (up 3s)
```

stderr says `AFS Service restarted` (not `started`), otherwise the same shape as `start`'s stderr above.

```bash
$ arc service logs --instance docs514b
{"ts":"2026-09-10T01:58:01.683Z","level":"info","service":"arc-node","ns":"node:boot","message":"boot vault-ready +652ms"}
{"ts":"2026-09-10T01:58:01.686Z","level":"info","service":"arc-node","ns":"node:boot","message":"boot did-space-ready +656ms"}
{"ts":"2026-09-10T01:58:02.235Z","level":"info","service":"arc-node","ns":"node:boot","message":"[code-agents] recover ok: claimed=0 marked=0 orphaned=0 deferred=0 locksScanned=0 locksReclaimed=0"}
```

Later boot lines omitted. `--follow` reprints existing lines then streams.

```bash
$ arc service stop --instance docs514b
Service stopped: docs514b
```

A `stopped` instance still reports its last pid / port / URL, and says in words that those are historical (exit `3`):

```bash
$ arc service status --instance docs514b
  Instance: docs514b
  ID:       b719db414c5cc625
  Status:   stopped
  PID:      95700
  Port:     61498
  URL:      http://127.0.0.1:61498
  Home:     /tmp/arc-svc-docs-514/home-b
  Space:    /tmp/arc-svc-docs-514/home-b/.afs/spaces
  Sources:  /path/to/arc/blocklets/afs-preview-fixture
  Version:  2.0.0-beta.48
  Commit:   5a5316bde
  Checkout: /tmp/arc-svc-docs-514/project
  Host:     127.0.0.1
  Started:  2026-09-10T01:58:00.472Z
  Note:     PID / Port / URL above are the LAST KNOWN values from this instance's previous run, not a live process.
```

In `--json` the same fact is `"lastKnown": true`, and there is no `live` key — a stopped instance is not probed. `list` prints `<port>*` for PORT (see [States](#states)). `start` on the same name reuses the record.

Each code block on this page is its own capture; instance names repeat across sections (`docs514a`, `docs514b`) without implying one continuous session — the four `delete` examples below use fresh throwaway names for exactly that reason, so none of them is a delete on a name a previous example already removed.

`delete` now has two output shapes for success, split by view the same way `arc afs delete` is (ArcBlock/arc#6055): the **default** (machine, non-TTY) view is a bare `OK <name>` — write's shape — and `--view human` is a sentence naming what was removed. Both instances below were `stopped` before the delete:

```bash
$ arc service delete --instance docs514x
OK docs514x

$ arc service delete --instance docs514y --view human
Removed instance "docs514y"
```

`delete` of a **running** instance fails without `--force` — this is also where the ArcBlock/arc#6301 prefix fix actually shows up: every failure line on this page now starts `ERROR: ` where the old capture had no prefix at all:

```bash
$ arc service delete --instance docs514z
ERROR: instance "docs514z" is running. stop it first, or use --force
```

`--force` stops first, then deletes — the accept-path counterpart to the reject above, same instance, same verb:

```bash
$ arc service delete --instance docs514z --force --yes
OK docs514z
```

`--dry-run` previews without touching anything, and works on either a stopped or a running instance:

```bash
$ arc service delete --instance docs514w --dry-run
Would delete instance docs514w at /tmp/arc-svc-docs-514/home-w (dry-run)

$ arc service delete --instance docs514w --dry-run --json
{
  "name": "docs514w",
  "removed": false,
  "home": "/tmp/arc-svc-docs-514/home-w",
  "dryRun": true,
  "homeRemoved": true
}
```

`homeRemoved` here means "the home directory *would be* removed by a real run", not that anything was removed — `removed: false` / `dryRun: true` on the same object say that already; read the three fields together, not `homeRemoved` alone.

`--yes` skips the interactive TTY confirmation prompt. In practice this rarely matters outside a real terminal: confirmation is TTY-only by design (`interactive` requires stdin *and* stdout to be a real TTY), so an agent, a pipe, or a test — anything already used to produce this page's dumps — proceeds without ever seeing the prompt, `--yes` or not. Pass it anyway for a script that might one day run from a terminal.

`gc` only collects `dead` (process gone without `stop`). `stopped` is kept:

```bash
$ arc service gc
Collected 1 dead instance
  docs514dead
kept 1

$ arc service gc
No dead instances to collect
```

After that `list` still showed the `stopped` and `up` rows; `docs514dead` was gone. With nothing `dead` left, `gc` says so in one line and still exits `0`. A separate, freshly-emptied registry (zero instances registered at all, not the one above) makes the point that `kept` is a real count down to `0`, not an empty answer — the same "renders to zero characters, not falsy" rule the [`--print`](#print) section covers next:

```bash
$ arc service gc --json
{
  "removed": [],
  "kept": 0
}
```

## `--print`

`--print <field>` reads one field out of the command's normal result and writes it to stdout as plain text, bypassing `--json`/`--view` entirely. ArcBlock/arc#6301 changed the rule for when a field counts as "no value": it used to be **falsy** (`false`, `0`, `""` were all treated as absent, printing nothing while still exiting `0` — indistinguishable from a real empty answer); it is now **renders to zero characters**. `false` and `0` are two-and-one characters respectively, so they are real answers and stay exit `0`. `Object.hasOwn` is used to find the field, not `in` (which would walk the prototype chain and answer `{}` for `--print __proto__`).

Accept path — a field whose real value is the boolean `false` still prints and exits `0` (this instance was started with `--no-advertise`):

```bash
$ arc service status --instance docs514b --print advertise
false
```

Accept path — a field whose real value is the number `0` still prints and exits `0` (an empty registry, so `gc`'s `kept` count is genuinely zero):

```bash
$ arc service gc --print kept
0
```

(The same rule covers a `0` port; that specific case cannot be produced from a live bind — the OS never actually hands back port `0` — so the CLI's own positive-control unit test drives it directly against a synthetic `{ port: 0 }` object: `runtimes/node/test/daemon/service-print-contract.test.ts:135`.)

Reject path — a field that **exists but carries no value** (`branch` / `sha` / `commit` on a checkout with no `.git`) is refused, not silently printed empty:

```bash
$ arc service status --instance docs514b --print branch
$ echo $?
1
```

stderr (banner omitted): `ERROR: field "branch" in result has no value`

Reject path — a field that does not exist in the result at all gets a different message, same exit code:

```bash
$ arc service status --instance docs514b --print nosuchfield
$ echo $?
1
```

stderr: `ERROR: no field "nosuchfield" in result`

`--print ""` used to be folded into "no `--print` given" and fall through to the full default view — so `arc service status --print "$FIELD"` with an unset `$FIELD` printed the entire human view instead of failing. It no longer does; an empty field name is looked up like any other, does not exist, and is refused the same way `nosuchfield` above is:

```bash
$ arc service status --instance docs514b --print ""
$ echo $?
1
```

stderr: `ERROR: no field "" in result`

## `--json` contract

**JSON is stdout only on success. On reject, stdout is always empty (0 bytes) — every failure, not just some.** This corrects an earlier version of this page that claimed the reject path put `{ "error": "…" }` on stdout; that was never true for `arc service`, and ArcBlock/arc#6301's fix note confirms the post-fix contract is explicitly "0 bytes of stdout" on every one of its nine reject scenes. The error message goes to stderr, `ERROR: `-prefixed, and the process exits non-zero.

Two different kinds of reject both land on this same 0-byte-stdout shape — worth checking side by side because they come from different code paths:

```bash
$ arc service status --instance no-such-xyz --json
$ echo $?
1
```
stderr: ``ERROR: no instance named "no-such-xyz". `arc service list` shows 2`` — this one never reaches the action's executor at all; instance resolution fails first.

```bash
$ arc service delete --instance docs514b --json
$ echo $?
1
```
stderr: `ERROR: instance "docs514b" is running. stop it first, or use --force` — this one runs inside `delete`'s own executor, which decides to fail *after* resolving the instance successfully.

Same shape either way: empty stdout, `ERROR: `-prefixed stderr, non-zero exit. `--json` does not change any of that — it only changes what a *successful* run would have printed.

**On success, the JSON is a superset of the human view.** Every URL, hostname and path the terminal prints is somewhere in the payload — `logFile`, `endpoints`, `blockletUrls`, `lan`, `build` — so an agent never has to scrape stderr.

```bash
$ arc service status --instance docs514b --json
{
  "name": "docs514b",
  "id": "b719db414c5cc625",
  "status": "up",
  "port": 61498,
  "url": "http://127.0.0.1:61498",
  "home": "/tmp/arc-svc-docs-514/home-b",
  "spaceRoot": "/tmp/arc-svc-docs-514/home-b/.afs/spaces",
  "blocklets": [
    "/path/to/arc/blocklets/afs-preview-fixture"
  ],
  "pid": 95666,
  "version": "2.0.0-beta.48",
  "commit": "5a5316bde",
  "branch": null,
  "sha": null,
  "checkout": "/tmp/arc-svc-docs-514/project",
  "startedAt": "2026-09-10T01:49:56.435Z",
  "urls": {
    "ui": "http://127.0.0.1:61498/",
    "blocklets": {
      "afs-preview-fixture": "http://127.0.0.1:61498/?blocklet=afs-preview-fixture"
    }
  },
  "host": "127.0.0.1",
  "advertise": false,
  "uptime": "3s",
  "logFile": "/tmp/arc-svc-docs-514/home-b/.afs/daemon.log",
  "endpoints": [
    { "url": "http://127.0.0.1:61498/", "label": "AUP Web Client" },
    { "url": "http://127.0.0.1:61498/explorer", "label": "Explorer UI" },
    { "url": "http://127.0.0.1:61498/ws", "label": "WebSocket (Explorer)" },
    { "url": "http://127.0.0.1:61498/afs/*", "label": "REST API" },
    { "url": "http://127.0.0.1:61498/mcp", "label": "MCP Streamable HTTP" }
  ],
  "blockletUrls": {
    "afs-preview-fixture": [
      { "url": "http://afs-preview-fixture.localhost:61498/", "label": "" },
      { "url": "http://localhost:61498/?blocklet=afs-preview-fixture", "label": "(Safari / universal)" }
    ]
  },
  "build": {
    "id": "2.0.0-beta.48+5a5316bde (debug)",
    "exec": "/path/to/arc/runtimes/node/dist/cli.mjs"
  },
  "live": {
    "ok": true,
    "url": "http://127.0.0.1:61498/.well-known/arc/instance",
    "record": {
      "version": "2.0.0-beta.48",
      "commit": "5a5316bde",
      "branch": null,
      "sha": null,
      "checkout": "/tmp/arc-svc-docs-514/project",
      "pid": 95666,
      "port": 61498,
      "blocklets": 1
    }
  }
}
```

Field groups: the first ten keys are the instance record; `version` … `urls` come from the registry row; `logFile` … `build` are what the human view printed; `live` / `drift` are the reconciliation against the running daemon. `lan` appears instead of nothing when the instance is bound to a non-loopback address, and carries the whole LAN diagnostic as `lines`.

`list` reports the record keys for every instance and omits the printed-facts keys — it prints no banner per row and does not probe. Note `sha` is populated here (a real git checkout) where the single-instance example above had `null` (a checkout with no `.git`) — both are real, from two different runs:

```bash
$ arc service list --json
{
  "instances": [
    {
      "name": "docs514a",
      "id": "b719db414c5cc624",
      "status": "up",
      "port": 61497,
      "url": "http://127.0.0.1:61497",
      "home": "/tmp/arc-svc-docs-514/home-a",
      "spaceRoot": "/tmp/arc-svc-docs-514/home-a/.afs/spaces",
      "blocklets": [],
      "pid": 95665,
      "version": "2.0.0-beta.48",
      "commit": "5a5316bde",
      "branch": null,
      "sha": "5a5316bdece751ee90416382b3ad851e565afa22",
      "checkout": "/tmp/arc-svc-docs-514/project",
      "startedAt": "2026-09-10T01:49:44.207Z",
      "urls": { "ui": "http://127.0.0.1:61497/", "blocklets": {} },
      "host": "localhost",
      "advertise": true,
      "uptime": "5s"
    }
  ]
}
```

`version` on every `list` row is the binary each instance is actually running — a quick way to see which instances an upgrade did not reach.

```bash
$ arc service stop --instance docs514b --json
{
  "name": "docs514b",
  "id": "b719db414c5cc625",
  "stopped": true,
  "pid": 95700
}

$ arc service delete --instance docs514b --json
{
  "name": "docs514b",
  "removed": true,
  "home": "/tmp/arc-svc-docs-514/home-b"
}
```

`--view json` is the same channel as `--json`.

`logs` is a stream and refuses `--json` — same 0-byte-stdout / stderr shape as every other reject:

```bash
$ arc service logs --instance docs514a --json
$ echo $?
1
```
stderr: `ERROR: logs is a stream and does not support --json`

yargs-level errors (unknown verb, missing required argument) also print no JSON even with `--json` — they never reach the point where `--json` would matter, and they print the subcommand's help on stderr instead (see [Failures](#failures)).

## Failures

Starting an instance that is already `up` (exit `1`). The hint now names the `--home` you started it with, not just the bare verb, because `restart` needs it too when `--home` was passed at start time:

```bash
$ arc service start --instance docs514b --home /tmp/arc-svc-docs-514/home-b
ERROR: instance "docs514b" is already running
       pid 95666, port 61498, started 39s ago
       use `arc service restart --instance docs514b --home /tmp/arc-svc-docs-514/home-b` or pick another name
```

`restart --port` (and the other config-only flags — see [Flags](#flags) for which ones and why `--home` is different) (exit `1`):

```bash
$ arc service restart --instance docs514b --port 4910
ERROR: restart does not reconfigure. use `stop` then `start` to change --port
```

`--space-root` must already be a DID Space:

```bash
$ arc service start --instance docs514c --home /tmp/arc-svc-docs-514/home-c \
    --space-root /tmp/arc-svc-docs-514/not-a-space
ERROR: /tmp/arc-svc-docs-514/not-a-space is not a DID Space. create it with `arc space init`
```

Unknown verb (exit `5`). yargs treats it as "not enough / wrong positional", prints the group's `--help` (shown in full under [`--help`](#help)) on stderr, and both together are prefixed once:

```bash
$ arc service foo
ERROR: Invalid values:
  Argument: action, Given: "foo", Choices: list, start, stop, restart, status, delete, gc, url, logs

arc service

Manage AFS background service

Commands:
  arc service list     List every local instance with its status, port and home
                       [aliases: ls, ps]
  ...
```

`arc service` with no verb at all is the same mechanism, different reason (exit `5`):

```bash
$ arc service
ERROR: Not enough non-option arguments: got 0, need at least 1

arc service
...
```

A leftover positional instance name (the verb, then a bare name, no `--instance`) is rejected on every verb, including `list` / `gc` — same mechanism again, this time printing the *subcommand's* own `--help` (exit `5`):

```bash
$ arc service status somename
ERROR: positional instance name was removed; use `--instance <name>` / `-i`

arc service status

Report whether an instance is running, and on which port
...
```

## Removed and retired

These used to be documented. They are gone:

| Old | Now |
| --- | --- |
| `arc service <action> [op] [dir] [options]` | `arc service <verb> [options]` |
| `arc service <action> [name]` | `arc service <verb> --instance <name>` / `-i` |
| `--blocklet-dir` | `--blocklet` (parent or single dir) |
| `--save` | Recorded automatically on the instance |
| `ARC_BLOCKLET_DIR` | Gone. Pass `--blocklet` |
| `arc service blocklet-dir add/list` | Gone |
| `arc service restart --port 4900` | `restart` refuses config flags |
| `ARC_HOME` | **Retired.** Warns and ignores |

Genuinely-removed flags no longer get a bespoke error — they now hit yargs' own unknown-argument handler, which offers a "Did you mean?" suggestion and dumps the subcommand's `--help`:

```bash
$ arc service start --instance docs514a --home /tmp/arc-svc-docs-514/home-a --blocklet-dir /tmp/nope
ERROR: Unknown arguments: blocklet-dir, blockletDir

Did you mean?
  --blocklet

arc service start
...

$ arc service start --instance docs514a --home /tmp/arc-svc-docs-514/home-a --save
ERROR: Unknown argument: save

arc service start
...
```

`ARC_HOME` is unaffected by the subcommand split — the warning still fires, still on its own line before the banner, and is not `ERROR: `-prefixed (it is a warning, not a `fail()`, so ArcBlock/arc#6301's unification does not touch it):

```bash
$ ARC_HOME=/tmp/retired-home arc service list
warning: ARC_HOME is ignored; instance root comes from the service name and --home, not env
```

## `--help`

The group-level `--help` — this is what an unknown verb also dumps (see [Failures](#failures)):

```text
arc service

Manage AFS background service

Commands:
  arc service list     List every local instance with its status, port and home
                       [aliases: ls, ps]
  arc service start    Start an instance, creating it on first use
  arc service stop     Stop a running instance, keeping its record and data
  arc service restart  Restart an instance from its recorded config (does not
                       reconfigure — stop then start for that)
  arc service status   Report whether an instance is running, and on which port
  arc service delete   Delete an instance: its record and its data [aliases: rm,
                       remove]
  arc service gc       Drop registry records whose process is gone [aliases:
                       prune]
  arc service url      Print an instance's base URL (and its blocklets')
  arc service logs     Print an instance's daemon log  [aliases: log]

Options:
      --json      Output in JSON format  [boolean]
      --view      Output view format (json is equivalent to --json). llm is
                  accepted globally; commands without an llm renderer fail
                  closed (declare ⇒ execute; arc#6037). [string] [choices:
                  "default", "llm", "human", "json"] [default: "default"]
      --home      Instance root — to pick which instance, use --instance. Used
                  by `arc service start` (create) and `arc did init` (identity).
                  In `--standalone`, sets DID Space and configDir; mounts come
                  from a cwd-walk of `.afs-config/config.toml`, not from --home.
                  [string]
  -i, --instance  Named local ARC instance this command operates against (see
                  `arc service list`). Omit for the default instance. [string]
      --print     Print one result field (e.g. url, port) as plain text — not a
                  view; overrides --json/--view [string]
  -h, --help      Show help  [boolean]
  -v, --version   Show version number  [boolean]

Examples:
  arc service list
      Show every local instance
  arc service start -i alice
      Start (or create) named instance alice
  arc service status -i alice
      Is alice running, and on which port?
  arc service logs -i alice
      Print alice's recent daemon logs
  arc service stop -i alice
      Stop alice without deleting it
  arc service delete -i alice --dry-run
      Preview deleting instance alice without removing it
```

Two of the nine subcommands' own `--help` — `start` (the widest flag set) and `delete` (the one with a destructive-verb flag trio) — to show the shape the other seven follow:

```text
arc service start

Start an instance, creating it on first use

Options:
      --json        Output in JSON format  [boolean]
      --view        Output view format (json is equivalent to --json). llm is
                    accepted globally; commands without an llm renderer fail
                    closed (declare ⇒ execute; arc#6037). [string] [choices:
                    "default", "llm", "human", "json"] [default: "default"]
      --home        Instance root — to pick which instance, use --instance. Used
                    by `arc service start` (create) and `arc did init`
                    (identity). In `--standalone`, sets DID Space and configDir;
                    mounts come from a cwd-walk of `.afs-config/config.toml`,
                    not from --home. [string]
  -i, --instance    Named local ARC instance this command operates against (see
                    `arc service list`). Omit for the default instance. [string]
      --print       Print one result field (e.g. url, port) as plain text — not
                    a view; overrides --json/--view [string]
      --port        Port to listen on (0-65535). 0 = auto-assign. Omit: default
                    uses 4900; named instances use the recorded port or
                    auto-assign [number]
      --host        Bind address (localhost, 0.0.0.0, ::, or a unicast IP)
                    [string] [default: "localhost"]
      --advertise   Advertise this instance over mDNS when bind is non-loopback
                    (use --no-advertise to disable) [boolean] [default: true]
      --blocklet    Blocklet-parent or single-blocklet dir to serve
                    (repeatable). Recorded on the instance. [array]
      --space-root  Folder-as-DID-Space created with `arc space init` (omit to
                    derive from home) [string]
  -h, --help        Show help  [boolean]
  -v, --version     Show version number  [boolean]

Examples:
  arc service start -i alice
      Start (or create) named instance alice

arc service delete

Delete an instance: its record and its data

Options:
      --json      Output in JSON format  [boolean]
      --view      Output view format (json is equivalent to --json). llm is
                  accepted globally; commands without an llm renderer fail
                  closed (declare ⇒ execute; arc#6037). [string] [choices:
                  "default", "llm", "human", "json"] [default: "default"]
      --home      Instance root — to pick which instance, use --instance. Used
                  by `arc service start` (create) and `arc did init` (identity).
                  In `--standalone`, sets DID Space and configDir; mounts come
                  from a cwd-walk of `.afs-config/config.toml`, not from --home.
                  [string]
  -i, --instance  Named local ARC instance this command operates against (see
                  `arc service list`). Omit for the default instance. [string]
      --print     Print one result field (e.g. url, port) as plain text — not a
                  view; overrides --json/--view [string]
      --force     Stop a running instance before deleting it [boolean] [default:
                  false]
      --dry-run   Print what would be removed without deleting it [boolean]
                  [default: false]
      --yes       Skip the TTY confirmation prompt  [boolean] [default: false]
  -h, --help      Show help  [boolean]
  -v, --version   Show version number  [boolean]

Examples:
  arc service delete -i alice --dry-run
      Preview deleting instance alice without removing it
```

The remaining seven (`stop`, `restart`, `status`, `gc`, `url`, `logs` plus the group's own `list`) follow the same shape as `start`/`delete` above minus the flags this page's [Flags](#flags) table already scopes to `start`/`delete`/`logs` — `logs` adds only `--follow`.

`--json`, `--view`, `--home`, and `--instance` / `-i` are global (declared once, apply to every `arc` command). `--home` is the instance root; to pick which instance, use `--instance`. See [Overview](../overview/).

---

## arc skill

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-skill/

`arc skill` is the CLI surface for **bundled ARC how-to booklets** (sometimes called L0): list them, print one, or copy them into host agent skill directories (`.agents/skills`, `.claude/skills`).

It is **not** (yet) a full agent-skill package manager like [`gh skill`](https://cli.github.com/manual/gh_skill), and it does **not** inventory skills that live only under live AFS mounts (`/{mount}/.skills`). Those remain AFS paths (`arc afs ls` / `read` / `exec`). See the engineering post [What arc skill is today](/en/articles/arc-cli-skill-catalog/) for the three-layer map and open design gap ([arc#1398](https://github.com/ArcBlock/arc/issues/1398)).

Booklets are short, offline-safe. After a daemon is up, **live AFS** (`arc afs ls` / `explain` / `read /.knowledge`) is the source of truth for mounts and actions. Booklet text must not invent paths the live tree does not have.

Requires a CLI build that includes the `skill` command (from ARC `2.0.0-beta.30` / epic [#3595](https://github.com/ArcBlock/arc/issues/3595) onward). Check with `arc --help | grep skill` or `arc skill --help`.

**Usage**

```bash
arc skill
arc skill list
arc skill show <name>
arc skill show all
arc skill install <name>
arc skill install all
```

`arc skill` with no subcommand is the same as `arc skill list`.

### Global options (all skill subcommands)

| Option | Meaning |
|--------|---------|
| `--json` | structured JSON instead of default text |
| `--view <default\|llm\|human\|json>` | rendering style for command **output** (not `--help`); `json` is equivalent to `--json` |
| `--instance <name>` / `-i` | which local ARC instance this runs against; omit for `default` (global, see [Overview](../overview/)) |
| `--home <dir>` | instance root (global). To pick which instance, use `--instance` |
| `-h`, `--help` | help for this command or subcommand |
| `-v`, `--version` | CLI version |

`--yaml` was removed (advertised on `--help` but never implemented); use `--json` or `--view json`.

---

## list

Print the skill index: names, one-line descriptions, and how to obtain a booklet.

```bash
arc skill list
# same:
arc skill
```

- **`--source <bundled|host|afs|all>`** (default `bundled`): where to list from — `bundled` is the L0 booklets shipped with this CLI, `host` reads `.agents`/`.claude` skill dirs already on this machine, `afs` reads mounted providers' `.skills` roots via the live AFS (daemon if running, else ad-hoc), `all` is the union of the three

**Example (text, abbreviated)**

```text
ARC skill index (L0 bootstrap — not a full manual)

Skills:
  daemon       Start, attach, and check the ARC daemon / service without breaking a live session.
  afs          Use AFS paths via `arc afs` (list/read/write/exec/explain) once a world is available.
  blocklet     Discover, scaffold, build, and inspect Arc blocklets via `arc blocklet` without reading the monorepo.
  mcp          Connect MCP clients (`arc mcp`) and explore the live AFS tool surface.

How to obtain:
  • Prefer per-name load: arc skill show <name>
  • Avoid full dump unless needed: arc skill show all
  • Install into host agent dirs (when available): arc skill install <name>
  • After a daemon is up, explore live AFS paths — this catalog is L0 bootstrap only

Commands:
  ...
```

**Example (JSON)**

```bash
arc skill list --json
```

```json
{
  "kind": "index",
  "skills": [
    {
      "name": "daemon",
      "description": "Start, attach, and check the ARC daemon / service without breaking a live session."
    },
    {
      "name": "afs",
      "description": "Use AFS paths via `arc afs` (list/read/write/exec/explain) once a world is available."
    },
    {
      "name": "blocklet",
      "description": "Discover, scaffold, build, and inspect Arc blocklets via `arc blocklet` without reading the monorepo."
    },
    {
      "name": "mcp",
      "description": "Connect MCP clients (`arc mcp`) and explore the live AFS tool surface."
    }
  ],
  "howTo": [
    "Prefer per-name load: arc skill show <name>",
    "Avoid full dump unless needed: arc skill show all",
    "Install into host agent dirs (when available): arc skill install <name>",
    "After a daemon is up, explore live AFS paths — this catalog is L0 bootstrap only"
  ]
}
```

The set of names is whatever this CLI build ships. Do not hardcode the list in agent memory across versions—run `list` again after an upgrade.

---

## show

Show one booklet body, or every booklet at once.

```bash
arc skill show <name>
arc skill show --name <name>
arc skill show all
```

| Argument / option | Required | Meaning |
|-------------------|----------|---------|
| `<name>` or `--name` | yes | skill id from the index, or `all` |

Prefer **one name**. `show all` concatenates every booklet (on the order of ~10KB of text in current builds)—use it only when you intentionally want a full dump.

**Example**

```bash
arc skill show daemon
```

```text
---
name: daemon
description: Start, attach, and check the ARC daemon / service without breaking a live session.
---

# ARC skill: daemon
...
```

**Errors**

Unknown name fails closed with the known list:

```bash
arc skill show not-a-skill
```

```text
ERROR: unknown skill 'not-a-skill'. Known: daemon, afs, blocklet, mcp. Prefer: arc skill list
```

---

## install

Copy a booklet (or every booklet) into host agent skill directories as `SKILL.md`. Offline; overwrites if the target already exists.

```bash
arc skill install <name>
arc skill install --name <name>
arc skill install all
```

| Argument / option | Required | Meaning |
|-------------------|----------|---------|
| `<name>` or `--name` | yes | skill id from the index, or `all` |

**Paths written** (under the current working directory):

- `.agents/skills/<name>/SKILL.md`
- `.claude/skills/<name>/SKILL.md`

**Example**

```bash
mkdir -p /tmp/demo-agent && cd /tmp/demo-agent
arc skill install afs
```

```text
Installed afs (2 file(s))
Policy: overwrite — same source as `arc skill show`; no second body tree

  /tmp/demo-agent/.agents/skills/afs/SKILL.md
  /tmp/demo-agent/.claude/skills/afs/SKILL.md
```

Body matches `arc skill show afs` (modulo a trailing newline). Re-run `install` after CLI upgrade to refresh installed skills.

---

## Built-in booklets (current shipping set)

| Name | Role |
|------|------|
| `daemon` | Start/attach/status for the ARC service without thrashing a live session |
| `afs` | Path ops + discover protocol + UI/WM multi-terminal samples |
| `blocklet` | `arc blocklet` discover / scaffold / build without reading the monorepo |
| `mcp` | Bridge MCP clients into live AFS |

After `daemon` + a running service, continue with live AFS:

```bash
arc service status
# start only if needed — see arc skill show daemon
arc afs ls /
arc afs explain /
arc afs read /.knowledge
```

`/.knowledge` leads with an **Agent bootstrap** section on live daemons. Prefer that over memorizing mount tables.

---

## Related

- [arc service](/en/docs/arc-cli/command-reference-service/) — background daemon lifecycle
- [arc afs](/en/docs/arc-cli/command-reference-afs/) — path operations after the world is up
- [arc mcp](/en/docs/arc-cli/command-reference-mcp/) — MCP bridge
- [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/) — package lifecycle

---

## arc space

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-space/

`arc space` manages local DID Space data, the per-app, per-user storage that backs DID Space. Ten user-facing subcommands: three read, one moves data, one deletes, five manage a folder-backed space — plus an eleventh, internal one; see [`sync-bench`](#sync-bench-internal) at the bottom of this page.

Captured against `arc` `2.0.0-beta.48`, commit `5a5316bde` (main, 2026-09-10) — pinned to the commit, not the semver: a second build has carried the same `2.0.0-beta.48` string. Run `arc --version` before you copy dumps.

```bash
arc space <subcommand> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

The inspection subcommands (`list`, `tree`, `path`, `rm`) take `--scope` to pick which DID Space to operate on, plus `--root-path`/`--user-did` to override where that data lives. Only `list` accepts `--scope all`; `tree`, `path` and `rm` take `instance|user`. The folder subcommands (`init`, `check`, `repair`, `set`, `migrate`, and `sync`) address a directory directly — a path already says which space it belongs to.

**Every subcommand's default (non-TTY) view is its own** — this page's own drift, found while recapturing it: `list`'s default already is the full human-readable block shown below; `check` and `migrate` default to **JSON**, not text; `sync` defaults to a condensed one-line-per-rejection summary, not the long-form explanation. `--view human` is the one view that is stable and consistent across every subcommand, and it is what every prose example on this page uses from here on — pass it explicitly rather than relying on the default, which differs by subcommand and is not this page's contract. `--json` is unaffected by any of this — it is always the full structured payload.

In the examples below, the demo space path is shortened to `~/notes`; everything else is copied verbatim from a real run.

## Inspecting what's stored

### arc space list

List app spaces with their file counts and roots.

**Usage**

```bash
arc space list [options]
```

- **`--scope <instance|user|all>`**: which DID Space to operate on (default `all`)
- **`--root-path <path>`**: root path for DID Space storage, overrides config
- **`--user-did <did>`**: user DID, overrides config; the root path falls back to the config default
- **`--all`**: show all entries (default caps at 100)

With no app spaces under the root, `list` prints one block per scope (`Instance DID Space` and `User DID Space`), each saying `(no app spaces)` — there is no single-line "nothing here" empty state; every response is scope-shaped:

```bash
$ arc space list --root-path ~/spaces
Instance DID Space  z1bp5ncJyUiKBv8BVCBH1RVnKks6u9VkW7G
  Root: ~/spaces
  (no app spaces)

User DID Space  z1bp5ncJyUiKBv8BVCBH1RVnKks6u9VkW7G
  Root: ~/spaces
  (no app spaces)
```

With at least one app present, each block gets a small table instead of `(no app spaces)`:

```bash
$ arc space list --root-path ~/spaces --view human
Instance DID Space  z1bp5ncJyUiKBv8BVCBH1RVnKks6u9VkW7G
  Root: ~/spaces
  DID                  Files  Last Modified
  ───                  ─────  ─────────────
  did:abt:notes-app        0  —

User DID Space  z1bp5ncJyUiKBv8BVCBH1RVnKks6u9VkW7G
  Root: ~/spaces
  DID                  Files  Last Modified
  ───                  ─────  ─────────────
  did:abt:notes-app        0  —
```

`list`'s default (non-TTY) view is already this same human-readable, per-scope block — it is the one subcommand on this page where `--view human` changes nothing. `--json` carries the same two groups as a `groups` array, each with `role`, `userDid`, `rootPath`, `apps`, and `total`.

### arc space tree

Show the file tree for one app space.

**Usage**

```bash
arc space tree <app-did> [options]
```

- **`--app-did <did>`** (required, also the first positional): app DID to inspect
- **`--scope <instance|user>`**: which DID Space (default `instance`)
- **`--path <path>`**: path inside the app fragment (default `/`)
- **`--depth <n>`**: maximum tree depth (default `99`)
- **`--limit <n>`**: maximum entries, unless `--all` (default `100`)
- **`--all`**: show all entries, ignores `--limit`
- **`--root-path <path>`** / **`--user-did <did>`**: same overrides as `list`

`--app-did` must be given positionally — `arc space tree --app-did <did>` alone, with no positional, is refused as a missing argument even though `--app-did` also appears in the flag table above and in `--help`'s `Options:` list. `tree` on an app DID with no space at all is a real reject (exit `5`, `App space not found: <did>`) — the accept-path counterpart is [`arc space path`](#arc-space-path) just below, which answers the same missing DID without erroring, because it only computes where the data *would* live.

### arc space path

Print the AFS path for an app DID Space fragment, useful when you want to feed it into `arc afs` commands directly.

**Usage**

```bash
arc space path <app-did> [path] [options]
```

- **`--app-did <did>`** (required, also the first positional): app DID to inspect
- **`--scope <instance|user>`**: which DID Space (default `instance`)
- **`--path <path>`**: path inside the app fragment (default `/`)
- **`--root-path <path>`** / **`--user-did <did>`**: same overrides as `list`

Unlike `tree`, `path` does not require the app space to actually exist — it prints the computed AFS path regardless, exit `0`:

```bash
$ arc space path did:abt:no-such-app --root-path ~/spaces
/spaces/z1bp5ncJyUiKBv8BVCBH1RVnKks6u9VkW7G/blocklets/no-such-app/system
```

## Moving data

### arc space sync

Move data between two subtrees — local folders, remote hosts, or one of each. Makes `--to` converge toward `--from`.

This is the one command for "move data from A to B", in either direction and between any two ends. Direction and both ends are arguments, never the command name — to pull instead of push, swap `--from` and `--to`.

It addresses spaces by path, which is why it has no `--server`, `--app-did` or `--scope`: a `layout=files` space puts real directories on disk, so a path already says which space and which fragment you mean. (`--scope` still applies to `list`/`tree`/`path`/`rm`, which address a space by DID.) Global `--instance` / `-i` still picks which local ARC instance the command talks to; it is not a DID Space id.

**Usage**

```bash
arc space sync --from <ref> --to <ref> [options]
```

Each `<ref>` is either a local folder or `https://<host>[/<sub>]` for a remote app's user fragment. The two forms are told apart by scheme alone, so a mistyped URL is never silently reinterpreted as a relative directory name.

- **`--from <ref>`** (required): source
- **`--to <ref>`** (required): destination
- **`--mirror`**: delete destination-only files (default: additive, nothing is removed)
- **`--dry-run`**: report the differences without writing anything
- **`--engine <auto|changelog|cursor|manifest>`** (default `auto`): force an engine. `auto` negotiates the strongest one both ends support. A named engine that is unavailable is an **error**, never a silent downgrade
- **`--verify`**: after syncing, recompute every destination file's CID against the source. Combined with `--dry-run` it *asserts* the destination already matches, exiting non-zero if not
- **`--full`**: ignore any recorded cursor and re-read everything — no cursor, and no reading either end's index; both trees are walked directly. The first sync into a destination is full either way; use this to rebuild a destination you no longer trust, or to sync a claimed folder that is deliberately written outside AFS (whose index is expected to lag, and which otherwise fails with an index-diverged error — see the note after the third example below)
- **`--init`**: claim a folder destination as `layout=files` (default when the source is claimed)
- **`--external-writes <none|possible>`** (default `possible`): query-freshness declaration for a claimed destination, only consulted when the destination is actually claimed
- **`--token <token>`**: access token for a remote endpoint, an alternative to browser auth
- **`--browser`**: open a browser for the auth flow (default `true`); pass **`--no-browser`** with `--token` for unattended runs

Every run below also prints a short progress trace on stderr (`Scanning source N files, destination M (…ms) / Comparing (…ms) / Syncing X/Y (…ms) / Total: …ms`, omitted from the stdout dumps below) and a `File list:` line stating whether each side answered from an index snapshot or fell back to a scan — neither is documented elsewhere on this page, so both are new since the last capture.

**Additive by default.** A first sync reports what it moved, and names the engine it negotiated along with why the others were rejected. `--view human` gives the long form of each rejection reason; the default (non-TTY) view gives a one-line summary instead — see the note above [Inspecting what's stored](#inspecting-what-s-stored) for why this page uses `--view human` throughout:

```bash
$ arc space sync --from src --to dst --view human
src → dst
Base path: /
Mode:      additive

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: the cursor engine mirrors (it deletes destination-only paths); this run is additive, so use --mirror to allow deletions or let the manifest engine handle it
File list: source scan (Operation not supported: paginated snapshot), destination scan (Operation not supported: paginated snapshot)

Added:     2
Modified:  0
Deleted:   0
Unchanged: 0

Transferred: 2 files
Verified:    no
Duration:    348ms
```

`src`/`dst` here are two plain, never-`arc space init`-ed folders — that is why `File list:` says `scan (Operation not supported: paginated snapshot)` for both: neither side has an index to snapshot from, so the manifest engine falls back to walking the tree directly. Files that exist only in the destination are left alone. Pass `--mirror` when you want the destination to become an exact copy — this second run also removed `b.txt` from `src` first, so `Deleted: 1` reflects a real removal, not a contrived number:

```bash
$ arc space sync --from src --to dst --mirror --view human
src → dst
Base path: /
Mode:      mirror (deletes destination-only files)

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: source is not a claimed DID Space, so it keeps no changelog ledger to take a cursor from
File list: source scan (Operation not supported: paginated snapshot), destination scan (Operation not supported: paginated snapshot)

Added:     0
Modified:  0
Deleted:   1
Unchanged: 1

Transferred: 0 files
Verified:    no
Duration:    322ms
```

When the **source** is itself a claimed `layout=files` space (`arc space init`), the same rejection reads differently — this is the wording worth remembering, because it names the actual remedy:

```
  not cursor: source is layout=files with externalWrites="possible" — the changelog cannot see edits made outside AFS; run `arc space set <from> external-writes=none` (only if the folder really is exclusively AFS-managed) to enable cursor-incremental sync
File list: source snapshot, destination snapshot
```

(Real capture, claimed source/destination — `File list:` now says `snapshot` on both sides with no fallback reason, because both have an index to read from.)

**`--dry-run` shows, `--verify` asserts.** Together they check a destination without touching it — the run below found one tampered file and exited `1`:

```bash
$ arc space sync --from src --to dst --dry-run --verify --view human
src ⇢ (dry-run) dst
Base path: /
Mode:      additive

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: the cursor engine mirrors (it deletes destination-only paths); this run is additive, so use --mirror to allow deletions or let the manifest engine handle it
File list: source scan (Operation not supported: paginated snapshot), destination scan (Operation not supported: paginated snapshot)

Added:     0
Modified:  1
Deleted:   0
Unchanged: 0

Transferred: 0 files
Verified:    no
Duration:    357ms
```

`--dry-run` needs both ends to exist already; only a real run creates the destination directory.

**New since the last capture: `--dry-run --verify` against a *claimed* destination that was hand-edited outside AFS refuses outright, rather than reporting the drift as `Modified`** — `--help`'s own text for `--full` names this exact failure:

```
$ arc space sync --from src-claimed --to dst-claimed --dry-run --verify --view human
ERROR: Provider "did-space-files" cannot reach its "query-freshness" dependency at "/": index has diverged from disk in 1 directory — /: a.txt (size-mismatch) — run `arc space repair --folder dst-claimed` to repair. Or re-run with --full to read both trees directly and ignore the indexes (slower, but it is the right choice for a folder that is deliberately written outside AFS).
```
(exit `5`.) Passing `--full` (or running `arc space repair --folder <dst>` first) is the accept-path counterpart — same tampered file, same command, one flag added, and it reports `Modified: 1` and exits `1` (the `--verify` mismatch exit, not a refusal) exactly like the plain-folder example above.

## Editing

### arc space rm

Delete a file or directory, recursively, inside a local app space. It goes through the space's ledger — a bare `rm -rf` leaves the index with a phantom row that only `arc space repair` clears.

**Usage**

```bash
arc space rm <app-did> <path> [options]
```

- **`--app-did <did>`** (required, also the first positional): target app DID
- **`--path <path>`** (required, also the second positional): path inside the app fragment
- **`--scope <instance|user>`**: which DID Space (default `user`)
- **`--root-path <path>`** / **`--user-did <did>`**: same overrides as `list`

Both positionals are required — `arc space rm <app-did>` alone (no path) is refused as "not enough non-option arguments", the same yargs-level guard `tree`/`path` hit above for a missing `--app-did`.

## Folder spaces

A claimed folder is a DID Space backed by a plain, hand-editable file tree plus a `.did-space/` index, as opposed to the `layout=cas` (content-addressed) form. These five commands claim a folder, check whether its index still agrees with disk, rebuild it when it doesn't, and convert a CAS space to the folder form.

### arc space init

Initialize a folder as a writable DID Space — creates `.did-space/` only.

**Usage**

```bash
arc space init <dir> [options]
```

- **`dir`** (required): folder to claim as a DID Space (a ledger, when `--source` is set)
- **`--external-writes <none|possible>`** (default `possible`): query-freshness declaration for the new space. `possible` — a human-initialized folder can always be hand-edited, so every query re-scans disk. `none` — pass only when something else (a daemon) will manage this folder exclusively; queries then answer straight from the index. The external-ledger form (`--source`) requires `possible`
- **`--source <path>`**: read-only truth layer for the external-ledger form; the ledger (`.did-space/config` + `space.db`) is created at `dir`, the source itself is never written

```bash
$ arc space init ~/notes
Initialized DID Space at ~/notes (layout=files, externalWrites=possible)
```

`init`'s default view is this same one-line text; `--json` gives `{ "dir", "layout", "externalWrites" }`.

Claiming a folder that already has files in it does **not** index them — `init` only creates `.did-space/`. Run `arc space repair --folder <dir>` afterwards, or `arc space check --folder <dir>` first to see what the index is missing.

### arc space check

Audit local DID Spaces: layout (migrated / needs migration / unreadable) and index-vs-disk freshness. Read-only — it never writes the index or the config. Exits non-zero when anything needs migrating, cannot be read, or has drifted.

**Usage**

```bash
arc space check [options]
```

- **`--folder <dir>`**: check exactly one claimed folder's freshness, skipping the layout sweep entirely
- **`--root <dir>`** (repeatable): root directory for the layout sweep. Default: this instance's space root **and** its sibling `<home>/.afs/work` — the host work ledger lives there, outside `root_path`, and a sweep that misses it reports a false all-clear
- **`--root-path <path>`**: root path override for the sweep

**`check`'s default (non-TTY) view is JSON**, not the text below — this is new since the last capture on this page, which showed the text as if it were the default. Every example below passes `--view human` for the readable form; drop it and you get the same data as `{ "folder", "layout", "externalWrites", "directoriesChecked", "fresh", "dirty" }` instead (identical payload whether you ask via the default view or `--json` explicitly).

Drift is reported per directory, with the remedy spelled out:

```bash
$ arc space check --folder ~/notes --view human
Check freshness: ~/notes (layout=files, externalWrites=possible)
Directories checked: 2
Result: DRIFT DETECTED — 2 of 2 directories disagree with disk

    /
      ! b.txt [missing-in-index]
      ! notes [missing-in-index]
    /notes
      ! a.md [missing-in-index]

Run `arc space repair --folder ~/notes` to repair (review the entries above first — it rebuilds the WHOLE index from disk).
```

A clean space says so and exits `0`:

```bash
$ arc space check --folder ~/notes --view human
Check freshness: ~/notes (layout=files, externalWrites=possible)
Directories checked: 2
Result: CLEAN — index agrees with disk
```

### arc space repair

Repair a claimed folder space by rebuilding its index from the real file tree. Use it after hand-editing files under a claimed folder, or after a bare `rm -rf` inside one.

**Usage**

```bash
arc space repair --folder <dir> [options]
```

- **`--folder <dir>`** (required): claimed folder to repair (must be `layout=files`)
- **`--index`** (default `true`): rebuild the folder-backend index from disk — the only repair this command performs today

```bash
$ arc space repair --folder ~/notes
Repaired index for ~/notes (layout=files)
Added:     2
Modified:  0
Deleted:   0
Unchanged: 0
Duration:  43ms
```

`repair`'s default view is this same text; `--json` gives `{ "folder", "layout", "added", "modified", "unchanged", "deleted", "elapsed" }` (note `elapsed`, not `Duration` — the two views use different key names for the same number).

### arc space set

Set a declaration on an *existing* `layout=files` DID Space.

**Usage**

```bash
arc space set <folder> <assignment>
```

- **`--folder <dir>`** (required, also the first positional): claimed folder to update (must already be `layout=files` — see `arc space init`)
- **`--assignment <key>=<value>`** (required, also the second positional): the declaration to set. `external-writes=none` — this folder is under exclusive (e.g. daemon) management, so queries answer straight from the index with no disk scan. `external-writes=possible` — the folder can still be hand-edited, so a query re-scans disk before every answer. Idempotent and reversible either direction; every other key already in `.did-space/config` is preserved untouched

```bash
$ arc space set ~/notes external-writes=none
Set externalWrites=none for ~/notes (layout=files)
```

### arc space migrate

Migrate a `layout=cas` DID Space in place to `layout=files` (copy → verify → atomic replace; the old CAS directory is kept for rollback).

**Usage**

```bash
arc space migrate <dir> --to-layout files [options]
```

- **`dir`** (required): claimed DID Space folder to migrate (must be `layout=cas`)
- **`--to-layout <files>`** (required): target layout — only `files` is supported
- **`--dry-run`**: report what would happen (space count, file count, byte count, expected result) — zero disk changes
- **`--external-writes <none|possible>`** (default `none`): query-freshness declaration for the resulting `layout=files` space. Default `none` because a `layout=cas` space's truth layer (`objects/<cid>` + `_metadata.db`) isn't something a human hand-edits, so "no external writer at migration time" is an assertable fact; pass `possible` only if this space has actually been treated as a plain hand-editable folder

**`migrate`'s default (non-TTY) view is JSON too**, same as `check`; `--view human` gives a short sentence-form summary instead.

Migrating a folder that is **already** `layout=files` is not an error — it is a real, idempotent accept path, exit `0`:

```bash
$ arc space migrate ~/notes --to-layout files --view human
Migrate ~/notes (layout=cas -> layout=files)
Already layout=files — nothing to migrate.
External writes: none
```

Running `arc space migrate` on a folder with no `.did-space/` at all *is* an error — a different one than "already migrated" above (exit `5`):

```bash
$ arc space migrate ~/plain-dir --to-layout files
ERROR: arc space migrate: ~/plain-dir is not a claimed DID Space (no .did-space/). Run `arc space init ~/plain-dir` first.
```

Rollback if a migration needs to be undone:

```bash
rm -rf "<dir>"
mv "<parent-of-dir>/.cas-backups/<dir-name>" "<dir>"
```

The pre-migration `layout=cas` directory is kept at `<parent-of-dir>/.cas-backups/<dir-name>` and is never deleted automatically. It deliberately sits one level below the space's own parent, in a container that is not itself a claimed space, so space enumeration — and therefore daemon boot — never rediscovers the backup.

## `sync-bench` (internal)

An eleventh subcommand exists on this build: `arc space sync-bench`, a SyncEngine throughput benchmark driven over `afs-rpc` (the `afs-rpc-batch` P6 driver). It requires `--server <url>` and `--token <token>` — a real remote endpoint, not a local folder — and seeds/benchmarks/cleans up throwaway files under a `--prefix` (default `e2e-batch/bench`). It has no read/write/inspect role in a space's data model the way the other ten do; see `arc space sync-bench --help` for its flags (`--blocklet`, `--files`, `--size`, `--single-op`, `--header`, `--cleanup`). Not documented further on this page.

---

## arc upgrade

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-upgrade/

`arc upgrade` upgrades the `arc` binary itself to the latest published release, or to a specific pinned version.

**Usage**

```bash
arc upgrade [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

- **`--check`**: only check whether an update is available, don't install it
- **`--to <version>`**: install a specific version instead of the latest published one
- **`--from <path>`**: debug channel — build this local git source tree and swap the running daemon's exec, instead of installing a published tarball
- **`--force`**: for the `--from` debug channel only — allow swapping to an older debug build (by default `--from` refuses that downgrade). Plain `--to <version>` has no such guard: it installs whatever version you name, even an older one, and still reports it as `upgraded`
- **`--base <url>`**: tarball host base URL (default `https://dl.arcblock.io`, env `ARC_INSTALL_BASE`)
- **`--install-script-base <url>`**: `install.sh` host base URL (default `https://arc.arcblock.io`, env `ARC_INSTALL_SCRIPT_BASE`)
- **`--dir <path>`**: install root (default `~/.arc`, env `ARC_INSTALL_DIR`)

**Example**

```bash
$ arc upgrade --check
already up to date (2.0.0-beta.48)
```

If a newer release is published, the message instead reads `update available: <current> → <latest> (run 'arc upgrade' to install)`.

---

## arc vault

URL: https://www.arcblock.io/en/docs/arc-cli/command-reference-vault/

`arc vault` is encrypted secret storage. Secrets are organized as `group/name`, for example `aws/access-key-id`.

```bash
arc vault <subcommand> [options]
```

Global flags (see [Overview](../overview/)): `--json`, `--view`, `--instance` / `-i` (which local ARC instance; omit for `default`), and `--home` (instance root; to pick which instance, use `--instance`).

### arc vault init

Initialize a new encrypted vault.

**Usage**

```bash
arc vault init [options]
```

- **`--vault-path <path>`**: path for the vault file (default `~/.afs-config/vault/vault.enc`). `--path` still works as a deprecated alias for `--vault-path`, but only on this one subcommand — `arc vault get/set/list/delete` all accept `--vault-path` too, but none of them ever accepted `--path` as an alias for it

**Example**

```bash
$ arc vault init --vault-path ./demo-vault.enc
Vault initialized at ./demo-vault.enc
Reused the existing master key (AFS_VAULT_KEY or OS keychain) — keep that source available.
```

The master key itself comes from `AFS_VAULT_KEY` or your OS keychain, not from this command, `arc vault init` just points a vault file at whichever key source is available.

### arc vault set

Store a secret.

**Usage**

```bash
arc vault set <group> <name> <value> [options]
```

- **`--group <group>`** (required): secret group, e.g. `aws`, `github`
- **`--name <name>`** (required): secret name, e.g. `token`, `access-key-id`
- **`--value <value>`** (required): the secret value
- **`--vault-path <path>`**: path to the vault file, defaults to the standard location

**Example**

```bash
$ arc vault set demo api-key sk-example-12345 --vault-path ./demo-vault.enc
OK demo/api-key
```

### arc vault get

Read a secret value.

```bash
arc vault get <group> <name> [--vault-path <path>]
```

**Example**

```bash
$ arc vault get demo api-key --vault-path ./demo-vault.enc
sk-example-12345
```

### arc vault list

List secrets. Aliased as `arc vault ls`.

**Usage**

```bash
arc vault list [group] [options]
```

- **`--group <group>`**: secret group to list, omit for all groups
- **`--vault-path <path>`**: path to the vault file

**Example**

```bash
$ arc vault list --vault-path ./demo-vault.enc
demo
```

### arc vault delete

Delete a secret or an entire group. Aliased as `arc vault rm`.

**Usage**

```bash
arc vault delete <group> [name] [options]
```

- **`--group <group>`** (required): secret group
- **`--name <name>`**: secret name, omit to delete the entire group
- **`--vault-path <path>`**: path to the vault file

**Example**

```bash
$ arc vault delete demo api-key --vault-path ./demo-vault.enc
Deleted demo/api-key
```

---

## Exit Codes

URL: https://www.arcblock.io/en/docs/arc-cli/exit-codes/

Every `arc` command exits with a number you can branch on. Having more than one non-zero value is the whole point: "the path you asked for is not there", "you mistyped the command", and "no daemon is running" want three different responses from a script, and nothing should have to pattern-match on English error text to tell them apart.

| Exit code | Meaning | Scope |
| --- | --- | --- |
| `0` | The command did what you asked | every command |
| `1` | Not there — or, for `service start`, already there | every command |
| `2` | Permission denied | reserved — no command in this release returns it (see below) |
| `3` | The instance is on record but is not running (`stopped`, `starting`) | `arc service status` |
| `4` | The instance is recorded as running, but its process is gone (`dead`) | `arc service status` |
| `5` | Runtime error, including every usage mistake | every command |
| `6` | The command needed a daemon and none was running | every command |
| `7` | `--view llm` was requested on a command that has no llm renderer | any command's `--view llm` |

**Mind the scope column.** `3` and `4` above are `arc service status`'s own reading of an instance record, not a promise about the whole CLI: elsewhere those two numbers carry the runtime's generic meanings — `3` a conflict, `4` a partial success — and `4` has a live producer, a batch `arc did issue` in which some providers succeeded and others failed. A script that reads `rc == 4` as "the daemon died" will misread that batch. Branch on `4` only for `arc service status`.

**`2` is in the enum but has no producer in this release** — the `2` section below shows how that was checked, not assumed. **`7` is scoped narrowly**: it only fires for `--view llm` on the commands that lack an `llm` renderer; every command still accepts `--view default` / `--view json` / `--view human`.

Each section below is a real run of the situation it describes, captured against `arc` `2.0.0-beta.48` (commit `5a5316bde`, 2026-09-10). The version number alone will not tell you which build you have — `2.0.0-beta.48` has named more than one binary this cycle — so run `arc --version` and compare its third field, the commit, against the one printed here before trusting any output on this page byte-for-byte. Read the table as "what these codes mean" rather than as the complete set of numbers `arc` can ever return: a command that fails in some way not listed here still exits non-zero, and new codes can appear in later releases.

## `0` — the command did what you asked

```bash
$ arc service list
NAME          ID                PORT   STATUS   HOME                          SOURCES
(no instances)
```

An empty result is still success. Finding nothing to list is not a failure — asking for a *specific* thing that is not there is what gets you `1`.

## `1` — not there, or already there

Reading a path that does not exist:

```bash
$ arc afs read /no-such-file --instance notes
ERROR: No data found for path: /no-such-file
```

Naming an instance that was never created:

```bash
$ arc service status --instance nope
ERROR: no instance named "nope". `arc service list` shows 1
```

And — the case worth remembering — starting an instance that is *already* up:

```bash
$ arc service start --instance notes
ERROR: instance "notes" is already running
       pid 93652, port 61430, started 15s ago
       use `arc service restart --instance notes` or pick another name
```

That last one is `1`, not `5`. The code means "what you named was not in the state you needed", which covers both a thing that is missing and a thing that is already there. It is not a usage mistake, so it is not `5`.

## `2` — permission denied, defined but not yet produced

The runtime's exit-code enum reserves `2` for `PermissionDeniedError`, and that class exists in the CLI's own error module. Nothing in this release throws it: no command constructs a `PermissionDeniedError`, and a permission failure raised by the AFS layer underneath the CLI is not translated into one — it just keeps propagating as an ordinary error, which lands on `5` like any other unhandled failure. This is checked, not assumed: an unreadable file, made with `chmod 000`, reproduces the real behavior directly.

```bash
$ arc afs read /vault/locked.txt --standalone
ERROR: EACCES: permission denied, open '/tmp/arc-perm-test/secret/locked.txt'
```

That command exits `5`. Treat `2` as a number the protocol has set aside for a distinction the CLI does not draw today, not as one you will see in practice.

## `3` — the instance exists but is not running

```bash
$ arc service stop --instance notes
Service stopped: notes
$ arc service status --instance notes
  Instance: notes
  ID:       ab5aa97074c454a0
  Status:   stopped
  PID:      93652
  Port:     61430
  URL:      http://127.0.0.1:61430
  Home:     /tmp/arc-docs-demo/notes
  Note:     PID / Port / URL above are the LAST KNOWN values from this instance's previous run, not a live process.
```

Several fields — `Version`, `Commit`, `Checkout`, `Space`, `Sources`, `Host` and `Started` — are elided above. The pid, port and URL are still reported after a stop, and the `Note:` line says in words that they are historical — in `--json` the same fact is a `lastKnown` marker.

`starting` returns `3` as well, which matters if you are writing a wait-for-up loop: `3` means "not ready", not "not coming". On a cold start the window is a few seconds, and a status poll walks `stopped` → `starting` (exit `3`) → `up` (exit `0`). Treat `3` as "keep waiting" and `4` as "stop waiting".

## `4` — recorded as running, but the process is gone

No ordinary sequence of commands gets you here, because this code describes damage rather than a choice. To see it, start an instance and kill its daemon outright, so the registry row still claims `up` while the process behind it no longer exists:

`start` prints a full status block of its own; the pid you need for the next step is on its `PID:` line. Both blocks below are trimmed to the fields that matter here.

```bash
$ arc service start --instance notes --home /tmp/arc-docs-demo/notes
  Instance: notes
  Status:   up
  PID:      95288
  Port:     61430
  Home:     /tmp/arc-docs-demo/notes
$ kill -9 95288
$ arc service status --instance notes
  Instance: notes
  ID:       ab5aa97074c454a0
  Status:   dead
  PID:      95288
  Port:     61430
  URL:      http://127.0.0.1:61430
  Home:     /tmp/arc-docs-demo/notes
  Note:     PID / Port / URL above are the LAST KNOWN values from this instance's previous run, not a live process.
```

`dead` is what you get from a crash, an OOM kill, or a reboot — anything that ends the process without going through `arc service stop`. The distinction from `3` is worth having: `stopped` is a state someone chose, `dead` is one nobody chose. `arc service gc` removes records in this state and only this state.

## `5` — runtime error, usage mistakes included

This is the broadest code. Every way of getting the command line wrong lands here. Each of the next three also prints the relevant usage text after what you see below — the full command list for the first, that command's own help for the other two. An unknown command:

```bash
$ arc serivce list
ERROR: Unknown command: "serivce"

Did you mean?
  arc serve
  arc service
```

an unknown option:

```bash
$ arc service list --bogus
ERROR: Unknown argument: bogus
```

a missing required argument:

```bash
$ arc space rm
ERROR: Not enough non-option arguments: got 0, need at least 2
```

and, past the command line, a request the runtime cannot route:

```bash
$ arc afs exec /no-such-action --instance notes
ERROR: No module found for path: /no-such-action in namespace 'default'
```

`5` also covers a command that ran correctly and reported a real-world problem — [`arc network doctor`](../command-reference-network/) exits `5` when any of its checks fails. So `5` on its own does not tell you whether you typed something wrong or something out there is broken; that is what the message is for.

## `6` — the command needed a daemon and none was running

```bash
$ arc afs ls /
ERROR: No AFS daemon is running for instance "default".
Start it with:  arc service start
Or use --standalone for ad-hoc mode (no runtime state)
```

The suggested command on the second line echoes back only the flags you actually typed — omit `--instance` and `--home` and it suggests the bare `arc service start`; pass `--instance foo --home ~/foo` yourself and it suggests exactly that back, never a value you did not type. `6` exists so this case is distinguishable from `5` without reading the message. An unmet precondition you can fix by starting a daemon is a different thing from a command that failed, and the error text names the fix. The same `6` comes back for a named instance whose daemon is `stopped` or `dead`, not only for `default`.

## `7` — `--view llm` was requested, but this command cannot render it

`--view llm` is accepted globally, but not every command has an `llm` renderer for it, and an unimplemented one fails closed instead of silently falling back to the default view. `arc network doctor` has no `llm` renderer:

```bash
$ arc network doctor --view llm
ERROR: --view llm is not implemented for `network doctor`. This command has no llm renderer (declare ⇒ execute; will not silently fall back to default).
```

`arc afs ls` does implement one, and the same flag on a command that supports it succeeds:

```bash
$ arc afs ls / --standalone --view llm
ENTRY /spaces CHILDREN=-1 DESC="Local DID Space logical roots"
ENTRY /peers CHILDREN=-1 DESC="Dispatchable ARC hosts (always includes local)"
ENTRY /ash CHILDREN=-1 DESC="ASH pipeline DSL for deterministic data pipelines"
ENTRY /dev CHILDREN=-1
ENTRY /modules CHILDREN=-1
ENTRY /team CHILDREN=-1
ENTRY /.knowledge KIND=afs:system CHILDREN=-1 DESC="Provider capability index"
ENTRY /.meta KIND=afs:system CHILDREN=-1 DESC="Root metadata and mount info"
ENTRY /.actions KIND=afs:system CHILDREN=-1 DESC="Root-level executable actions"
TOTAL 9
```

The distinction that matters for scripts: an unrecognized `--view` value (say, `--view bogus`) is a **usage** mistake caught by argument parsing, and exits `5` like any other bad flag —

```bash
$ arc service list --view bogus
ERROR: Invalid values:
  Argument: view, Given: "bogus", Choices: "default", "llm", "human", "json"
```

— while `--view llm` on a command with no `llm` renderer is a **valid, recognized** value that this particular command cannot honor, and exits `7`. Without the split, a script cannot tell "I typed the flag wrong" from "the flag is right but this command doesn't support it yet" without parsing English text either way.

---

## Install

URL: https://www.arcblock.io/en/docs/arc-cli/install/

`arc` ships as a prebuilt package for macOS and Linux, on both Intel and Arm. One command installs it:

```bash
curl -fsSL https://arc.arcblock.io/install.sh | bash
```

With no version argument the installer resolves the current published release. Pass `--version <v>` after `bash -s --` only when you deliberately want an older build.

The installer downloads the build for your platform, checks it against a checksum published from a second, independent origin, unpacks it under `~/.arc/versions/`, and points `~/.arc/current` at it. On macOS it inspects the code signature as well; a build that is not yet signed with ArcBlock's Developer ID produces a warning and the install continues. Finally it writes a PATH line into your shell profile and prints which file it changed. If the current shell still cannot find `arc`, open a new terminal.

## Confirm what you installed

```bash
arc --version
```

Every build prints its version:

```text
<version>
```

Newer builds add the short commit they were built from and its build date, as `<version> (<commit>) <build date>`. Both forms are correct. One version number can cover more than one build, so where you need to be exact about which `arc` you are running, the commit is the field that separates them.

Command pages here paste real terminal output. Where yours differs, `arc --help` on your own build is the authority.

## Move to a newer release later

`arc upgrade` replaces the installed binary with the current release, and `arc upgrade --check` reports whether a newer one exists without installing anything. See [arc upgrade](../command-reference-upgrade/).

With `arc` on your PATH, continue with the [Overview](../overview/) for the flags every command accepts.

---

## Overview

URL: https://www.arcblock.io/en/docs/arc-cli/overview/

`arc` is the command line tool for operating an ARC runtime instance. Every top-level command talks to one part of that runtime: `afs` is file system operations, `did` is identity and trust, `vault` is encrypted secrets, `deploy` handles deployment targets, `dsl` works with AUP DSL artifacts, and so on.

Version documented here: `2.0.0-beta.48 (5a5316bde)`, built 2026-09-10. `arc --version` always prints this three-field form — `<semver> (<commit>) <build date>` — because the same `beta.N` string gets reused across different builds; the commit is what actually pins the command surface. Run `arc --version` to check yours; commands and options can change between builds.

If `arc` is not on your PATH yet, start with [Install](/en/docs/arc-cli/install/).

`arc worker` manages ArcBlock's own Cloudflare deployments. It registers behind two gates that must both hold: a build-time flag that's off in any release build (so the binary you install with `install.sh` never has it), and a runtime check that the current working directory is inside a real `ArcBlock/arc` checkout, or `ARC_WORKER_DIR` is set explicitly (so even a debug build made from that checkout won't show `arc worker` when you run it from somewhere else). It isn't listed below.

`arc space sync-bench` is a hermetic benchmark driver for arc's own afs-rpc wire, not a product feature — there's nothing a third party would run it to accomplish with their own data. It registers behind the same build-time flag as `arc worker` (off in any release build), just without `arc worker`'s extra checkout-location check. It isn't listed below either.

`arc connect` and `arc explore` were removed: both duplicated things the daemon already does (`arc service start` prints every endpoint including `/explorer`, so there's no separate step to start-and-open). Use `arc service start` instead.

### Global options

Every command accepts the same flags:

- **`--json`**: print structured JSON instead of the default text output
- **`--view <default|llm|human|json>`**: pick a rendering style; `llm` is tuned for feeding output back into an agent, `human` for a person reading a terminal, `json` is equivalent to `--json`
- **`--instance <name>`** / **`-i`**: which local ARC instance this command operates against (see `arc service list`). Omit for the `default` instance. This is the only name for that axis
- **`--home <dir>`**: instance root. Used by `arc service start` (create), `--standalone` (ad-hoc), and `arc did init` (identity). To pick which instance, use `--instance`

`--json` and `--view` only change how the result prints. They apply to command **output**, not to `--help` itself; help text is always plain text. `--instance` and `--home` change which instance the command talks to.

An unrecognized flag is rejected (`ERROR: Unknown argument: <name>`, exit code `5`) — arc does not silently ignore a mistyped or removed option, and help/error text is always in English regardless of your system locale. `--yaml` was one such removed option (advertised on every command's `--help` but never implemented); use `--json` or `--view json` instead.

### When you mistype a command

A misspelled top-level command is not simply rejected — `arc` names the commands you probably meant, and then prints the full command list (trimmed after the suggestion here):

```bash
$ arc serivce list
ERROR: Unknown command: "serivce"

Did you mean?
  arc serve
  arc service
```

A near-tie offers every candidate rather than guessing between them: `serivce` is one edit away from both `serve` and `service`, so both are printed. Mistyping exits `5`, like any other usage mistake — [Exit Codes](../exit-codes/) covers what each code means.

The same mechanism catches a misspelled subcommand or a misspelled option, one level down — always scoped to just that one command's own choices, and always still exit `5`:

```bash
$ arc service strat
ERROR: Invalid values:
  Argument: action, Given: "strat", Choices: list, start, stop, restart, status, delete, gc, url, logs

Did you mean?
  arc service start
...
$ arc service start --instnace foo
ERROR: Unknown argument: instnace

Did you mean?
  --instance
...
```

Fix any of the three and the same command runs normally, exit `0`:

```bash
$ arc service list --help
arc service list

List every local instance with its status, port and home
...
```

### Previewing a destructive command

`--dry-run` is not a global flag. Six commands take one — `arc afs delete`, `arc blocklet build`, `arc deploy`, `arc service delete`, `arc space migrate`, and `arc space sync` — and three take `--yes` to skip a confirmation prompt: `arc afs delete`, `arc service delete`, and `arc did issuer reset` (`afs delete` and `service delete` take both). `arc space sync --dry-run` reports the entire plan and writes nothing (trimmed here to the summary; the engine-selection and timing lines are omitted).

```bash
$ arc space sync --from ./src --to ./dst2 --dry-run
./src ⇢ (dry-run) ./dst2
Base path: /
Mode:      additive

Added:     2
Modified:  0
Deleted:   0
Unchanged: 0

Transferred: 0 files
```

`Transferred: 0 files` is the point — the plan says two files would be added, and the destination is still empty afterwards. `arc blocklet build --dry-run` behaves the same way: it prints the manifest it would publish, and leaves no `dist/` behind.

Every other command has neither a preview nor a confirmation prompt. **`arc space rm` in particular has neither `--dry-run` nor `--yes`**: it removes a file or directory inside a local app space as soon as you press enter. Look before you delete, with `arc space tree <app-did>`.

### Command groups

::::card-group
::link-card{title="afs" description="File system operations: ls, read, write, delete, stat, exec, explain, search, subscribe, and mount management." icon="folder"}
::link-card{title="did" description="Identity and trust: generate a DID, issue and verify credentials, manage trusted issuers." icon="fingerprint"}
::link-card{title="vault" description="Encrypted secret storage: init, get, set, list, delete." icon="lock"}
::link-card{title="dsl" description="Validate, lint, format, generate, and inspect AUP DSL artifacts." icon="code"}
::link-card{title="collections" description="Scan content/ and generate the collections: fragment for blocklet.yaml." icon="layers"}
::link-card{title="space" description="Manage local DID Space data: list, tree, path, rm, sync between two subtrees, folder-space claim and repair, folder-layout migration." icon="database"}
::link-card{title="deploy" description="Register a blocklet with the local daemon, or publish it to a DID Space." icon="upload"}
::link-card{title="blocklet" description="Blocklet package and instance lifecycle: scaffold, build, check, deploy, fleet deploy." icon="package"}
::link-card{title="service" description="Manage named AFS background instances: list, start, stop, restart, status, delete, gc, url, logs." icon="power"}
::link-card{title="serve" description="Start a foreground AFS server over HTTP or MCP." icon="globe"}
::link-card{title="attach" description="Reverse-mount a local directory, or this host's HostFace, into a remote arc daemon." icon="plug"}
::link-card{title="drain" description="Long-running: watch the work ledger and dispatch ready work to an idle peer." icon="repeat"}
::link-card{title="mcp" description="Bridge stdio to a running AFS daemon's MCP endpoint." icon="terminal"}
::link-card{title="skill" description="Bundled how-to booklets: list, show, install into host agent skill dirs (not full skill package manager yet)." icon="book"}
::link-card{title="provider" description="Provider package operations: publish a provider's resources to CF Pages." icon="box"}
::link-card{title="upgrade" description="Upgrade arc itself to the latest release, or a pinned version." icon="arrow-up-circle"}
::link-card{title="network" description="Diagnose outbound connectivity: proxy discovery, DNS, HTTPS and WebSocket, each reported separately." icon="wifi"}
::link-card{title="completion" description="Print a bash, zsh, or fish tab-completion script to stdout: command names, subcommand names, instance names, and --recipe values." icon="keyboard"}
::::

---

## ArcBlock Jobs

URL: https://www.arcblock.io/en/docs/arcblock/

---

## ArcBlock Media Kit

URL: https://www.arcblock.io/en/docs/arcblock-media-kit/

> **Deprecated.** Current files live on [Media Assets](/en/docs/media-assets/). Keep this URL for history.

---

## AIGNE Logos

URL: https://www.arcblock.io/en/docs/arcblock-media-kit/77GaHmpWeDm0sUccOF9k3K1c/

## All image resources

[🗂️ Download AIGNE Logos Media Kit(SVG, PNG) ](https://www.arcblock.io/image-bin/uploads/07f4c546f3aa3aafb37d9c6fd8e9ea01.zip?filename=AIGNE%20Logos.zip)

## AIGNE

- <strong>AIGNE Logo</strong>

![AIGNE logo.png](https://media.arcblock.io/lib/7e/7ee6fde68e201f821dfeb27e08099833.w1600.webp)

- <strong>AIGNE Logo & Text(Light, Dark)</strong>

![AIGNE_light.png](https://media.arcblock.io/lib/e2/e29d59637e993c5bdd7eed0743243647.w1600.webp)    ![AIGNE_dark.png](https://media.arcblock.io/lib/db/db5570c77659f589e9ead87a233c7d7d.w1600.webp)

---

## AIGNE Hub

- <strong>AIGNE Hub Logo</strong>

![Hub logo.png](https://media.arcblock.io/lib/32/32acbee4360d587039eab6de1a5de507.w1600.webp)

- <strong>AIGNE Hub Logo & Text(Light, Dark)</strong>

![hub_light.png](https://media.arcblock.io/lib/99/9916119cb56249c0fd960f8613d14664.w1600.webp)    ![hub_dark.png](https://media.arcblock.io/lib/19/194efc0ff96ee91c860ae5dfb771e99e.w1600.webp)

---

## AIGNE Studio

- <strong>AIGNE Studio Logo</strong>

![Studio logo.png](https://media.arcblock.io/lib/b4/b4c91d0eb667e8988171188ee28ee786.w1600.webp)

- <strong>AIGNE Studio Logo & Text(Light, Dark)</strong>

![Studio_light.png](https://media.arcblock.io/lib/bb/bb5a69360bee45a8bdbb060080f709f4.w1600.webp)   ![Studio_dark.png](https://media.arcblock.io/lib/d9/d9e3aec7c9ef9446b666d4fd7ed4a062.w1600.webp)

---

## AIGNE Framework

- <strong>AIGNE Framework Logo</strong>

![Framework logo.png](https://media.arcblock.io/lib/aa/aa4e6d2472ecf3b65c106e37addc8ea3.w1600.webp)

- <strong>AIGNE Framework Logo & Text(Light, Dark)</strong>

![Framework_light.png](https://media.arcblock.io/lib/49/496b4249f4214dd03073a84052ab7c88.w1600.webp)   ![Framework_dark.png](https://media.arcblock.io/lib/ed/eda709e5a26fef15690969b7122fa12c.w1600.webp)

---

## AIGNE CLI

- <strong>AIGNE CLI Logo</strong>

![Cli logo.png](https://media.arcblock.io/lib/ef/ef2885f306752bc618e4d882134c544e.w1600.webp)

- <strong>AIGNE CLI Logo & Text(Light, Dark)</strong>

![CLI_light.png](https://media.arcblock.io/lib/9a/9a08d838108159a4a9d4a93b96a53722.w1600.webp)    ![CLI_dark.png](https://media.arcblock.io/lib/0e/0e95f5b03db842d9bbd3aec984c768a4.w1600.webp)

---

## AIGNE Observability

- <strong>AIGNE Observability Logo</strong>

![Obe logo.png](https://media.arcblock.io/lib/8c/8c6819590281dbdfa61bd90821b9a16a.w1600.webp)

- <strong>AIGNE Observability Logo & Text(Light, Dark)</strong>

![Observability logo_light.png](https://media.arcblock.io/lib/cd/cd4551d41d5050e628b083dcedf35614.w1600.webp)   ![Observability logo_dark.png](https://media.arcblock.io/lib/5f/5fc291c02bab0abcca789b8bb550c78d.w1600.webp)

---

## AIGNE CodeSmith

- <strong>AIGNE CodeSmith Logo</strong>

![CodeSmith logo.png](https://media.arcblock.io/lib/ef/ef2a984314d9cd97ac7f7b5f8f9035b5.w1600.webp)

- <strong>AIGNE CodeSmith Logo & Text(Light, Dark)</strong>

![CodeSmith_light.png](https://media.arcblock.io/lib/38/38d9f5aff004fa1afd77143692dacde9.w1600.webp)  ![CodeSmith_dark.png](https://media.arcblock.io/lib/a4/a451ceb3c2242a384070692f45d6835d.w1600.webp)

---

## AIGNE DocSmith

- <strong>AIGNE DocSmith Logo</strong>

![DocSmith logo.png](https://media.arcblock.io/lib/35/352db97eb4730e0da56ee83fceda718b.w1600.webp)

- <strong>AIGNE DocSmith Logo & Text(Light, Dark)</strong>

![DocSmith_light.png](https://media.arcblock.io/lib/57/57b8904e93eb1f6d98af80df4c262233.w1600.webp)  ![DocSmith_dark.png](https://media.arcblock.io/lib/ef/efac0510a143e453d6ad92808be613e4.w1600.webp)

---

## AIGNE WebSmith

- <strong>AIGNE WebSmith Logo</strong>

![WebSmith logo.png](https://media.arcblock.io/lib/c6/c623569a07caf8137952f5811e875a43.w1600.webp)

- <strong>AIGNE WebSmith Logo & Text(Light, Dark)</strong>

![WebSmith_light.png](https://media.arcblock.io/lib/5b/5b6848537697d0ad4e0ada33c887fb9a.w1600.webp)  ![WebSmith_dark.png](https://media.arcblock.io/lib/08/089ff947b2c48ce2e490abfd7d19d4cd.w1600.webp)

---

## AIGNE Components

- <strong>AIGNE Components Logo</strong>

![Components logo.png](https://media.arcblock.io/lib/8c/8c195a78b19f87b0ea571b6ca34913fb.w1600.webp)

- <strong>AIGNE Components Logo & Text(Light, Dark)</strong>

 ![Components_light.png](https://media.arcblock.io/lib/a8/a81eab2f435897090cce09f21b8e1926.png)  ![Components_dark.png](https://media.arcblock.io/lib/ba/badf3bb33145daaa6009b78e8b95d0e5.png)

---

## AIGNE Runtime

- <strong>AIGNE Runtime Logo</strong>

![Runtime logo.png](https://media.arcblock.io/lib/da/daaea4cfcbe7e1a4c20064e213d6ff55.w1600.webp)

- <strong>AIGNE Runtime Logo & Text(Light, Dark)</strong>

![Runtime_light.png](https://media.arcblock.io/lib/61/61ccad4e7a6d0b15daddd90d2b3fbace.w1600.webp)  ![Runtime_dark.png](https://media.arcblock.io/lib/b2/b22f3f82355065764a96f54b8aced383.w1600.webp)

---

##  AIGNE Font

-  AIGNE Font: [Google Font Link](https://fonts.google.com/?query=Audiowide)

![AIGNE Text.png](https://media.arcblock.io/lib/d6/d6c6c623df088ca95e8b5c7c440484aa.w1600.webp)

- AIGNE Series Products Font: [Google Font Link](https://fonts.google.com/specimen/Poppins?preview.text=poppins)

![font.png](https://media.arcblock.io/lib/c7/c76d0a721c931c8acfc320ea07e269b9.w1600.webp)

---

## ArcSphere Logos

URL: https://www.arcblock.io/en/docs/arcblock-media-kit/arcsphere-media-kit/

## All Brand Assets zip

[Download ArcSphere Brand Assets ZIP(SVG, PNG)](https://www.arcblock.io/image-bin/uploads/245e8ccce6ac8b003a9973da6d801a69.zip?filename=ArcSphere%20logo.zip)

## ArcSphere Logo & Text

![01.png](https://media.arcblock.io/lib/db/db0b16a2855d006b43e9421b56d8bd07.w1600.webp)   ![02.png](https://media.arcblock.io/lib/03/038362c0729229bb6b926a3b54a8dab4.w1600.webp)

![03.png](https://media.arcblock.io/lib/4f/4f866bb3504ec852e913089d2a084dd2.w1600.webp)   ![04.png](https://media.arcblock.io/lib/45/450deaf8c773de1953ff7b8dc563e78e.w1600.webp)

![05.png](https://media.arcblock.io/lib/8c/8ce9f7ceb7d445c0630d5aab3c4fdad0.w1600.webp)  ![06.png](https://media.arcblock.io/lib/12/12b35f94109f9862ac6149ab7805af0b.w1600.webp)

![09.png](https://media.arcblock.io/lib/45/451156c589e91009972b7d03a0992be7.w1600.webp)  ![10.png](https://media.arcblock.io/lib/46/46c6e58160267c0094417cb553bdf76a.w1600.webp)

## ArcSphere Logo

![11.png](https://media.arcblock.io/lib/85/8543578299bec89ecc61ca5c1a5fd977.w1600.webp)  ![12.png](https://media.arcblock.io/lib/eb/eb787de0532646e555f8d6be7c890549.w1600.webp)  ![13.png](https://media.arcblock.io/lib/26/2694ef28e1a2fdc74e9297b98f347ef5.w1600.webp)    ![17.png](https://media.arcblock.io/lib/40/40bd5e3576656510be4e8f1c845502b5.w1600.webp)

## ArcSphere font Logo

![20.png](https://media.arcblock.io/lib/b5/b5cc7c9b09f8a01851c79d102abe5acb.w1600.webp)  ![19.png](https://media.arcblock.io/lib/9c/9c9ea6f17e0370217be2af2d3b599429.w1600.webp)  ![21.png](https://media.arcblock.io/lib/ab/ab19456a0860a64ccbb9e8c88ddca42a.w1600.webp)

## ArcSphere UI Text

![18.png](https://media.arcblock.io/lib/9f/9fa38916910e610d71335a3dda790c34.w1600.webp)

[Download on Google fonts ](https://fonts.google.com/?query=Lexend)

---

## DID Logos

URL: https://www.arcblock.io/en/docs/arcblock-media-kit/did-logos/

## All image resources

[🗂 Download ArcBlock DID Logos Media Kit(SVG, PNG)](https://www.arcblock.io/image-bin/uploads/6e0a45195d5c738320ddd19a91615a47.zip?filename=DID%20logos.zip)

## DID

- <strong>DID Logo</strong>

![DID logo@4x.png](https://media.arcblock.io/lib/fe/feab879cf1a8f013312e94a91730ca44.w1600.webp)

---

## DID Names

- <strong>DID Names Logo</strong>

![Names logo.png](https://media.arcblock.io/lib/3d/3dfed589ecb0a71a132af5c645cad2d8.w1600.webp)

- <strong>DID Names Logo & Text(Light, Dark)</strong>

![DID Names-light.png](https://media.arcblock.io/lib/1d/1d9d675d3ae0784a5ab3b5a70694202f.w1600.webp)      ![DID Names-dark.png](https://media.arcblock.io/lib/39/39d85dd0e73958901f2f26988c98113f.w1600.webp)

---

## DID Spaces

- <strong>DID Spaces Logo</strong>

![Spaces logo.png](https://media.arcblock.io/lib/25/253611b0594dd39c8af50a8b447c8ab8.w1600.webp)

- <strong>DID Spaces Logo & Text(Light, Dark)</strong>

![DID Spaces-light.png](https://media.arcblock.io/lib/4a/4a2c969ff88af1e10b7ea3870e45fcb9.w1600.webp)     ![DID Spaces-dark.png](https://media.arcblock.io/lib/5e/5ee77c08f1c08fdb7444dbe930f1dd1b.w1600.webp)

---

## DID Connect

- <strong>DID Connect Logo</strong>

![Connect logo.png](https://media.arcblock.io/lib/e6/e6e90789ded21a011d459b1bb2304236.w1600.webp)

- <strong>DID Connect Logo & Text(Light, Dark)</strong>

![DID Connect-light.png](https://media.arcblock.io/lib/53/53fd8a4245ccabbbd913b90536ef14ab.w1600.webp)    ![DID Connect-dark.png](https://media.arcblock.io/lib/8b/8b7b1f7102b329a672e68eee8378620c.w1600.webp)

---

## DID Wallet

- <strong>DID Wallet Logo</strong>

![DID Wallet@4x.png](https://media.arcblock.io/lib/e2/e2d1255cb59e05870d9ae2ee986c9152.w1600.webp)

- <strong>DID Wallett Logo & Text(Light, Dark)</strong>

![DID Wallet-light@4x.png](https://media.arcblock.io/lib/f3/f391ad0596c6ef7e5375abc55ee15221.w1600.webp)     ![DID Wallet-dark@4x.png](https://media.arcblock.io/lib/63/639c632883139a3423fa79a175f918cb.w1600.webp)

---

### DID Logo Text Font

> [!NOTE]
> Brand typography

[Google fonts Link ->](https://fonts.google.com/specimen/Lato?query=Lato)

### DID Logo Colors

| Name | Description | Color |
|---|---|---|
| Brand Gradient | #079AFF | #079AFF |
| Logo Text | #000000 | #000000 |
| White Logo | #FFFFFF | #FFFFFF |

---

## ArcBlock Logos

URL: https://www.arcblock.io/en/docs/arcblock-media-kit/media-kit/

> **Deprecated.** Current files live on [Media Assets](/en/docs/media-assets/). Keep this URL for history.

## All image resources

[🗂 Download ArcBlock Logos Media Kit(SVG, PNG)](https://www.arcblock.io/image-bin/uploads/57bb3e2eb314d4ce612854b153dcbbab.zip?filename=ArcBlock-Logos.zip)

## ArcBlock Logo & Text

![Image](https://media.arcblock.io/lib/66/666b5c71fdfd2128b443c76e6179eb50.w1600.webp) ![Image](https://media.arcblock.io/lib/92/92c0fbf031e2a487d44fc4f91c143f43.w1600.webp)

![Image](https://media.arcblock.io/lib/63/639e1bbb7481eeeed33c39e875a3df7d.w1600.webp) ![Image](https://media.arcblock.io/lib/b8/b802d13a892707af83c0f57a2f994456.w1600.webp)

![Image](https://media.arcblock.io/lib/fa/fae02cbdad6d1340b3653b88f82295a6.w1600.webp) ![Image](https://media.arcblock.io/lib/82/82fabcf29b77e21663285e0368d4405f.w1600.webp)![Image](https://media.arcblock.io/lib/33/3311280269f53859df85d91bba08dcbd.w1600.webp) ![Image](https://media.arcblock.io/lib/8c/8cca6e8f2392eb40b00fec71cc1af478.w1600.webp)

## ArcBlock Logo

![Image](https://media.arcblock.io/lib/f6/f6f993de06bd5c410af6285e663312c3.w1600.webp) ![Image](https://media.arcblock.io/lib/4a/4ae9aae052bfbfb00f84d51a4d6e5a9b.w1600.webp) ![Image](https://media.arcblock.io/lib/ad/ad5acf624b032b8513c6bbfc36fe4ea3.w1600.webp) ![Image](https://media.arcblock.io/lib/23/23d90363dd498b0c1b44db8c837fa482.w1600.webp) ![Image](https://media.arcblock.io/lib/fa/fa3198c09a032156b83b6f87643eba35.w1600.webp) ![Image](https://media.arcblock.io/lib/bf/bf2278cd165503a58e9c430a4968cd2e.w1600.webp)
![Image](https://media.arcblock.io/lib/50/5074c75c4ff0649005629798fc63f0f4.w1600.webp)![Image](https://media.arcblock.io/lib/79/79be912f51680c985db9e0890257bf5b.w1600.webp)

## ArcBlock Text

![Image](https://media.arcblock.io/lib/d7/d752e6b54552ec16d1863d60bab18fa8.w1600.webp) ![Image](https://media.arcblock.io/lib/8a/8a6a26bfbcb774717a4e8fee49294b6b.w1600.webp)

## ABT Token

![Image](https://media.arcblock.io/lib/c9/c9c16d5c46f8c4edc79cf9c96a9900d7.w1600.webp)

## ArcBlock Logo Text Font

> [!NOTE]
> Brand typography

[Google fonts Link ->](https://fonts.google.com/specimen/Lato?query=Lato)

## ArcBlock Logo Colors

Pages Kit component data is missing; see the surrounding documentation.

---

## Payment Kit  Guide

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/

---

## How to Configure Additional Payment Methods

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/add-payment-mothods/

This guide explains how to configure <strong>additional payment options</strong> for <strong>EVM-compatible chains</strong>.

## 1. Add a Payment Method (EVM Chain)

Navigate to<strong>ayments → Settings → Payment Methods → Add Payment Method</strong>

![image.png](https://media.arcblock.io/lib/23/238e4c611b14f809d6b395628af5cc6b.w1600.webp)

Then, enter the following:

- <strong>Name</strong>: The name of the chain, e.g., “Ethereum” or “Base”
- <strong>Description</strong>: A short description of the network (e.g., "Polygon is a scalable Ethereum Layer 2 chain")
- <strong>RPC Endpoint</strong>: A valid node RPC URL, e.g.,
-
  - 👉 <strong>Where to get RPC endpoints?</strong>
  -
    - [Infura](https://www.infura.io/networks/ethereum)
    - [PublicNode](https://ethereum.publicnode.com)
    - [ChainList](https://chainlist.org)
  - Example:
  -
    - Ethereum: [`https://ethereum-rpc.publicnode.com`](https://ethereum-rpc.publicnode.com)
    - Base: [`https://base-rpc.publicnode.com`](https://base-rpc.publicnode.com)
- <strong>Explorer Host</strong>: The blockchain explorer for viewing transaction history, e.g.,
-
  - Example:
  -
    - Ethereum: [`https://etherscan.io/`](https://etherscan.io/)
    - Base: [`https://basescan.org/`](https://basescan.org/)

![image.png](https://media.arcblock.io/lib/50/502868af2a781fd0669256f99e2b1d9f.w1600.webp)

Once saved, the chain will be initialized and ready for use.

---

## 2. Add Currencies

![image.png](https://media.arcblock.io/lib/b1/b148b087b2518764dae7fe66d7af23ec.w1600.webp)

To enable tokens on the newly added chain:

<strong>Payments → Settings → [Your Method] → Add Currency</strong>

You have two options:

- <strong>Quick Add</strong>: Select a predefined currency from the list. All token info (contract, symbol, logo) will be prefilled.
- <strong>Manual Entry</strong>: Enter token info manually:
-
  - <strong>Token Name</strong>: e.g., "USDC"
  - <strong>Description</strong>: e.g., “Stablecoin for payments”
  - <strong>Contract Address</strong>: Must match the on-chain deployed token
  - <strong>Logo URL (optional)</strong>: Used in UI; default logo is used if not set

After saving, the currency will become available in checkouts and billing.

---

## 3. Deposit for Gas Fees

To perform transactions on a chain, your application wallet must have the chain's native token (e.g., ETH).

Steps:

1. Go to <strong>Payments → Settings → [Your Method]</strong>
2. Locate your <strong>application wallet address</strong> under the Deposit section
3. Use an external wallet to send the required gas token:
4.
  - ETH for Ethereum/Base
5. After the deposit, your wallet balance will appear in <strong>Overview</strong> and <strong>Settings</strong>

![image.png](https://media.arcblock.io/lib/ad/adf82a2d953de15ac159a628a7eb1cdc.w1600.webp)

### Ready to Use in Pricing

After completing the above steps, you can select the new payment method and its currencies when configuring <strong>product pricing</strong>.

---

## Development Guide

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/dev-guide/

# Overview

To programmatically integrate Payment Kit, you can refer to [DID Connect UI (React)](https://www.arcblock.io/docs/payment-kit-react) and [Payment Kit SDK (Node.js)](https://www.arcblock.io/docs/payment-kit-sdk).

This guide will also cover solutions to common developer scenarios:

- [Payment Kit Event Listening Mechanism](/en/docs/arcblock-payment-kit/events/)

- [How to activate the donation feature?](/en/docs/arcblock-payment-kit/enable-donate/)

- [Custom Notification Processing Guide](/en/docs/arcblock-payment-kit/manual-notification/)

- [ How to Configure Additional Payment Methods](/en/docs/arcblock-payment-kit/add-payment-mothods/)

---

## How to activate the donation feature?

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/enable-donate/

<strong>@blocklet/payment-react</strong> offers a robust tipping and donation feature.  Using the `CheckoutDonate` component and the optional `DonateProvider`, developers can easily integrate donation support for articles, content, and other services, seamlessly leveraging Blocklet's payment infrastructure.

This guide details how to enable tipping, including installing dependencies and integrating the necessary code.

## <strong>Step 1: Install the Payment Kit</strong>

Payment Kit powers the tipping feature. You need to download and install Payment Kit from the Blocklet Store:

- Test Store

[Payment Kit](https://test.store.blocklet.dev/blocklets/z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk)

- Store

[Payment Kit](https://store.blocklet.dev/blocklets/z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk)

###### <strong>Installation</strong>

1. Visit the link above to select the appropriate store for your environment (test or production).
2. Download and deploy the Payment Kit to your Blocklet application.
3. After installation, retrieve the `session` and `connectApi` configurations to connect to the Payment Kit's authentication and payment services.

> Note: Use the test store for development and debugging, and the production store for production environments.  Ensure your Payment Kit is running and communicating with your front-end application.

## <strong>Step 2: Install the @blocklet/payment-react package</strong>

Install the component library in your React project:

```javascript
npm install @blocklet/payment-react
```

## <strong>Step 3: Integrate the tipping component</strong>

You can integrate tipping functionality in two ways, depending on your needs:

### <strong>Method 1: Basic Usage — CheckoutDonate</strong>

Use the `CheckoutDonate` component directly for a simple, pre-configured donation integration.

```javascript
import { PaymentProvider, CheckoutDonate } from '@blocklet/payment-react';

function DonationButton() {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutDonate
        settings={{
          target: "post-123", // Required: Unique identifier for the donation instance (e.g., post ID)
          title: "支持作者", // Required: Title of the donation popup
          description: "如果这篇文章对你有帮助，不妨请我喝杯咖啡", // Required: Description for the donation
          reference: "https://your-site.com/posts/123", // Required: Reference link for the donation
          beneficiaries: [
            {
              address: "tip user did", // Required: Beneficiary address (replace with actual DID)
              share: "100", // Required: Percentage for the beneficiary
            },
          ],
          amount: {
            presets: ['1', '5', '10'], // Predefined donation amounts
            custom: false, // Whether to allow users to enter a custom amount
          },
          appearance: {
            button: {
              text: '打赏', // Text displayed on the button
              icon: '<Like />', // Custom icon (replace with actual JSX component)
              size: 'large', // Button size
              color: 'error', // Button color
              variant: 'contained', // Button style
            },

            history: {
              variant: 'default', // Display style for donation history
            },
          },
        }}
      />
    </PaymentProvider>
  );
}

export default DonationButton;
```

### <strong>Method 2: Advanced Usage — DonateProvider (Recommended)</strong>

From Payment Kit version 1.18.7 onward, `DonateProvider` allows centralized management of donation settings and activation status within Payment Kit, simplifying front-end code and facilitating dynamic control over donations.

```javascript
import { PaymentProvider, DonateProvider, CheckoutDonate } from '@blocklet/payment-react';

function DonationButton() {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <DonateProvider mountLocation="your-unique-donate-instance" description="Help locate this donation instance">
        <CheckoutDonate
          settings={{
            target: "post-123", // Required: Unique identifier
            title: "Support Author", // Required: Modal title
            description: "Buy me a coffee if this helped!", // Required: Description
            reference: "https://your-site.com/posts/123", // Required: Reference link
            beneficiaries: [{ address: "tip user did", share: "100" }], // Required: Beneficiaries
          }}
        />
      </DonateProvider>
    </PaymentProvider>
  );
}

export default DonationButton;
```

##### <strong>Configuration</strong>

- <strong>target</strong>: A unique string identifying the reward recipient (e.g., an article or other content).
- <strong>beneficiaries.address</strong>: Replace with the actual beneficiary's DID.
- <strong>DonateProvider</strong>: Requires Payment Kit version 1.18.7 or later for integrated management.

##### <strong>Important Considerations</strong>

- <strong>Version Compatibility</strong>: To use `DonateProvider`, you must use Payment Kit version 1.18.7 or later.  Otherwise, use the basic method.

---

## Enable SubGuard™ for subscriptions?

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/enable-overdraft-protection-on-launcher/

[Payment v1.17.0: Keep Your Subscription Running with SubGuard™ & Delegation Check](/en/articles/payment-kit-v117-sub-guard/#consumer-experience)

Enabling <strong>SubGuard</strong>™ for your application in Launcher ensures uninterrupted subscription services, even in cases of payment failures. This guide will walk you through the steps to activate this feature.

#### <strong>Step 1: Access the Application Management Page</strong>

Open [the Launcher app management page](https://launcher.arcblock.io/app/u/apps) to view all your apps. From there, you can choose which app you would like to manage.

#### <strong>Step 2: Access Your Subscription Details</strong>

1. Locate the application you want to enable <strong>SubGuard</strong>™, and click the <strong>Subscription</strong> button.

![image.png](https://media.arcblock.io/lib/8a/8ac9703c3f8869e3b4be6df3a69d002b.w1600.webp)

1. Access the subscription details page to review your current subscription information.

#### <strong>Step 3: Set Up SubGuard</strong>™

1. Locate the <strong>SubGuard</strong>™ section on the subscription details page.
2. Click the button to enable SubGuard™.
3. Set the staking amount to ensure it covers the following fees:
4.
  - Estimated billing amount for at least one cycle.
  - SubGuard™ service fee.

![image.png](https://media.arcblock.io/lib/80/803a51a35b35e5a52bc4a95606c9b454.w1600.webp)

Once the setup is finalized, the system will offer complete coverage for your subscription throughout the protection period, ensuring that service interruptions caused by payment failures are avoided.

#### <strong>About SubGuard™</strong>

<strong>Key Features:</strong>

- <strong>Continuity Assurance:</strong> Ensures your subscription services remain uninterrupted throughout the protection period.
- <strong>Flexible Billing:</strong> Users can settle bills manually without incurring service fees or let the system automatically settle bills using the staked amount after the protection period (with a service fee).
- <strong>Notification System:</strong> The system sends alerts if the staked amount is insufficient, helping users maintain their subscription status.

<strong>Supported Currencies:</strong>

- Currently supports Arcblock tokens (USD and ETH are not supported).

<strong>Closing</strong>  <strong>SubGuard</strong>™<strong>:</strong>

- After settling bills, users can disable  SubGuard™ at any time. If the subscription is canceled, any remaining stake will be refunded automatically.

#### #### <strong>Benefits of</strong>  <strong>SubGuard</strong>™

::::steps
:::step{title="Improving Subscription Reliability:"}
Minimizing service disruptions due to payment failures.
:::

:::step{title="Enhanced Flexibility:"}
Users can manage their billing and payment methods to suit their preferences.
:::

:::step{title="Seamless Experience:"}
Ideally suited for scenarios that require uninterrupted service.
:::
::::

By following these steps, you can leverage  SubGuard™ to ensure a smooth and secure subscription experience for your application. For more details or assistance, visit [Arcblock Community](https://community.arcblock.io/discussions/boards/payment-kit).

---

## Payment Kit Event Listening Mechanism

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/events/

Payment Kit provides two ways to listen for events, enabling you to respond to system events in a timely manner.

## Listening Modes

### Method 1: Using Webhooks

Suitable for distributed systems and supports cross-service communication.

1. Register a webhook endpoint

```javascript
const ensureWebhooks = async () => {
  const enabledEvents = [
    'customer.subscription.started',
    'customer.subscription.renewed',
  ];
  const result = await payment.webhookEndpoints.list({ page: 1, size: 100 });
  if (result.list.length) {
    const webhook = await payment.webhookEndpoints.update(result.list[0].id, {
      url: getUrl('/api/payment/callback'),
      enabled_events: enabledEvents,
    });
    logger.info('webhooks updated', webhook);
    return;
  }

  const webhook = await payment.webhookEndpoints.create({
    url: getUrl('/api/payment/callback'),
    enabled_events: enabledEvents,
  });
  logger.info('webhooks created', webhook);
};
```

1. Implement callback processing

```javascript
// api/routes/payment/callback.js
const { verifySig } = require('@blocklet/sdk/lib/middlewares/component');
router.post('/payment/callback', verifySig, (req, res) => {
    const event = req.body;
    switch(event.type) {
      case 'customer.subscription.started':
        await handleSubscriptionStart(event.data);
        break;
      case 'customer.subscription.renewed':
        await handleSubscriptionRenew(event.data);
        break;
    }
}

```

### Method 2: Using the Event Bus

Suitable for handling events within a single application, simplifying implementation.

```javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.subscribe((event) => {
  switch(event.type) {
    case 'customer.subscription.started':
      handleSubscriptionStart(event.data);
      break;
    case 'customer.subscription.renewed':
      handleSubscriptionRenew(event.data);
      break;
  }
});
```

## Event Type Descriptions

### Checkout Complete

- `checkout.session.completed` - Checkout session completed
- `checkout.session.nft_minted` - NFT minting complete

### Subscribing to Events

- `customer.subscription.created` - Customer subscription created
- `customer.subscription.started` - Subscription initiated
- `customer.subscription.renewed` - Customer subscription renewed
- `customer.subscription.upgraded` - Customer Subscription Upgraded
- `customer.subscription.updated` - Customer subscription updated
- `customer.subscription.deleted` - Subscription canceled
- `customer.subscription.paused` - Customer subscription paused
- `customer.subscription.resumed` - Subscription resumed

### Probationary Period Incident

- `customer.subscription.trial_start` - Trial Start Date
- `customer.subscription.trial_will_end` - Your trial will end soon.
- `customer.subscription.trial_end` - Trial End

### Payment Events

- `payment_intent.succeeded` - Payment successful
- `payment_intent.payment_failed` - Payment failed
- `invoice.paid` - Invoice payment completed
- `refund.succeeded` - Refund successful

---

## Custom Notification Processing Guide

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/manual-notification/

Payment Kit allows applications to handle notifications directly, offering two configuration options.

## Option 1: Subscription-Based Access Control

When creating a `checkoutSession`, use `subscription_data.notification_settings` to configure notification handling.

```javascript
const checkoutSession = await payment.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price_id: 'your_price_id', quantity: 1 }],
  subscription_data: {
    notification_settings: {
      self_handle: true,                           // enable custom processing
      include_events: ['customer.subscription.started']
    }
  }
});
```

## Approach 2: Global Management

Create global notification configurations using the `settings` API.

```javascript
// 1. create global setting
const setting = await payment.settings.create({
  type: 'notification',
  mountLocation: 'your.app.id',              // use component_did or custom global constant
  description: 'manual notification',
  componentDid: '', // optional, component did
  settings: {
    self_handle: true,                       //  enable custom processing
    include_events: [
      'customer.subscription.started',
      'customer.subscription.renewed'
    ]
  }
});

// 2. releated settings to checkout session
const checkoutSession = await payment.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price_id: 'your_price_id', quantity: 1 }],
  metadata: {
    setting_id: setting.id                // setting id or mountLocation value
  }
});
```

## Listening for Events

[Payment Kit 事件监听机制](/en/docs/arcblock-payment-kit/events/)


### Method 1: Using a Webhook

1. Register a webhook endpoint

```javascript
const enabledEvents = [
  'customer.subscription.started',
  'customer.subscription.renewed'，
  'manual.notification',
];

const webhook = await payment.webhookEndpoints.create({
  url: 'https://your-app.com/api/payment/callback',
  enabled_events: enabledEvents
});
```

1. Implement webhook processing

```javascript
// api/routes/payment/callback.js
module.exports = {
  post: async (req) => {
    const event = req.body;

    if (event.type === 'manual.notification') {
      await sendCustomEmail(event.data);
    }

    return { code: 'OK' };
  }
};
```

### Using the Event Bus

Use the `@blocklet/sdk` EventBus to listen for events within the application:

```javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.subscribe((event) => {
  if (event.type === 'manual.notification') {
    sendCustomEmail(event.data.object);
  }
});
```

### Notification Data Structure

```javascript
{
  type: 'customer.subscription.started', // original trigger event type
  data: {
    entity: any,                // Notify related entity data (subscription, billing information, etc.)
    userDid: string,
    context: {                  // Payment Kit Context information for notifications that have been processed
      [key: string]: any
    }
  }
}
```

## Best Practices

1. <strong>Selecting the Appropriate Configuration Level</strong>
2.
  - Subscription level: For scenarios where different subscriptions require different notification policies
  - Global level: Applies to all subscriptions that use a unified notification policy.
3. <strong>Listener Mode</strong>
4.
  - Webhook: Ideal for distributed systems, facilitating inter-service communication
  - EventBus: Ideal for managing events within a single application, offering a simpler implementation.

---

## Welcome to Payment Kit.

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/payment-intro/

Payment Kit is ArcBlock's powerful payment solution designed to help developers quickly and easily integrate diverse payment functionalities into their applications. From creating products and generating payment links to building sophisticated payment experiences, Payment Kit offers flexible and efficient support.

Here is an overview of its core features:

- <strong>Create Products:</strong> Payment Kit makes it easy to create and manage products and services, allowing you to define product details and build a solid foundation for your business.

- <strong>Payment Links</strong>: Create and share payment links in just a few steps to streamline transactions and improve the customer experience.

- <strong>Pricing Table</strong>: Create visually appealing and easy-to-understand pricing tables for your products to present pricing information, attract potential customers, and drive sales.

<strong>Pro Features 🔥</strong>

- <strong>Tip Feature</strong>: The `<CheckoutDonate />` component allows developers to easily integrate a tipping button into their applications, enabling users to quickly and conveniently support creators and service providers. [Get started now.](/en/docs/arcblock-payment-kit/enable-donate/)
- <strong>Payment Methods</strong>: Supports multiple payment methods and currencies to meet the needs of a global audience.
- <strong>API Integration</strong>: A dedicated JavaScript SDK facilitates the implementation of highly customized payment solutions for complex business requirements.

<strong>Payment Kit offers two robust SDKs</strong>:

- <strong>@blocklet/payment-js</strong>: A Node.js SDK for implementing backend payment logic. [Learn more ->  ](/en/docs/arcblock-payment-kit/payment-js/)
- <strong>@blocklet/payment-react</strong>: A React component library offering ready-to-use payment UI components.[Learn More ->](/en/docs/arcblock-payment-kit/payment-react/)

---

## <strong>Acquire the Payment Kit</strong>

[Payment Kit](https://store.blocklet.dev/blocklets/z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk)

## Getting Started and Using

- [安全](/en/docs/arcblock-payment-kit/security-g6CVr/)

- [安全](/en/docs/arcblock-payment-kit/security-g6CVr/)

---

## Stay Updated

For more information on Payment Kit releases and updates, see our official blog posts:

[ArcBlock Official Site](/en/articles/)

---

## Security

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/security-g6CVr/

- [How to configure and enable the Vault Wallet ](/en/docs/arcblock-payment-kit/vault-config/)

---

## User Guides

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/user-guide/

- [Enable SubGuard™ for subscriptions?](/en/docs/arcblock-payment-kit/enable-overdraft-protection-on-launcher/)

---

## How to configure and enable the Vault Wallet

URL: https://www.arcblock.io/en/docs/arcblock-payment-kit/vault-config/

## 1. Key Features of the Vault Wallet

### The Current State of Hot Wallets

Currently, all app revenue is stored by default in a <strong>hot wallet</strong>. While this facilitates real-time transactions, it also presents security risks.

- Constant internet connectivity increases vulnerability to network attacks
- All funds are concentrated in a single hot wallet

### The Value of Vault Wallet

Vault Wallet protects assets through physical isolation:

- <strong>Automatic Sweep</strong>: Automatically transfers funds when the hot wallet balance exceeds a predefined threshold.
- <strong>Funds Security</strong>: The majority of funds are held in offline storage.

## 2. Configure a Vault Wallet for the Application

### Prerequisites

- App Owner Privileges
- A valid wallet address (compatible with both ArcBlock native and ETH addresses)

### Procedure

![image.png](https://media.arcblock.io/lib/69/690ef53bb26f78d30d355b67e9daa033.w1600.webp)

::::steps
:::step{title="Go to the Blocklet Service Dashboard"}
:::
::::

::::steps
:::step{title="Select Operations → Advanced"}
:::
::::

::::steps
:::step{title="Setup Vault"}
:::
::::

> Your vault wallet address can be the same as your owner wallet address. Note that if you change your vault wallet address, the previous address will be considered insecure and can no longer be used as the vault wallet for this application.

## Enable Vault Wallet Support for Payment Currencies in Payment Kit

### Functionality

```javascript
Hot wallet balance monitoring → exceeds threshold → triggers automatic transfer → funds enter vault wallet
```

### Setup

::::steps
:::step{title="Configure Vault"}
:::
::::

- Navigation:	`Payment > Settings > Vault`

::::steps
:::step{title="Configure Currency Rules"}
:::
::::

- Select the currency (e.g., ETH/ABT)
- Input <strong>Deposit Threshold, Buffer Threshold</strong>
- Click Save

![image.png](https://media.arcblock.io/lib/0e/0e6e255a5e6e808ae1294ef88661956e.w1600.webp)

---

## AI Application Engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/ai-application-engineer-career/

> <em>Please send your resume to apply for this position:</em> [hr@arcblock.io](mailto:hr@arcblock.io)

## Job responsibilities

💡 Depending on individual abilities and interests, you can choose to participate in any number of the following jobs.

- Participate in the development and maintenance of AI Kit, AI Studio, and AI applications.
- Design and implement user-oriented product features, deliver high-quality, user-friendly WEB applications, and even cross-platform applications.
- Participate in the end-to-end architecture and support of various decentralized applications.
- Optimize the code coverage, delivery pipeline, and level of automation for the project responsible.

## Ability Requirements

- Familiar with AI API, with practical usage experience.
- Solid JavaScript, HTML, and CSS3 foundation, proficient in responsive layout, familiar with ES6, HTTP protocol.
- Familiar with any front-end framework, such as React.js, Vue.js, it is better to be familiar with React.js.
- Familiar with any backend framework, such as Express.js, Koa, etc.
- Familiar with computer networks, understand distributed systems, common security issues and prevention measures.
- Familiar with GraphQL, capable of designing and implementing well-functioning backend APIs.
- Ability to design architecture, implement engineering, and operate online maintenance according to system requirements.
- Used Jest, GitHub Actions, commonly seen libraries for logging and database interaction.
- Understanding common architectures and optimization methods for back-end systems, such as caching, load balancing.
- Strong self-learning ability and an open mindset, continuously learning new technologies and tools to improve the efficiency of the whole team.
- With good engineering literacy, such as code style, Git workflow, able to write high-quality front-end code.
- Familiar with Linux and Unix operating systems, familiar with Nginx, able to complete common operations and maintenance tasks.
- Familiar with Amazon AWS or other cloud computing platforms (such as Azure, Google Cloud, Digital Ocean, Alibaba Cloud, etc.)

## Bonus item

- Have a strong interest in AI, have used AI products extensively, and have their own insights.
- Own AI work.
- Experience in developing with Typescript
- Experience building front-end applications using React.js, experience with Docker.
- Familiar with basic blockchain conceptual models, linking common public chain operation mechanisms, better if you have developed applications on other public chains.
- Leadership capabilities, product capabilities, and best engineering practices demonstrated in past experiences.
- Good communication skills: Effective communication with peers and non-technical personnel, such as document writing.
- High-quality GitHub open source projects, technical blogs.
- Have experience using [Electron](https://www.electronjs.org/) and project experience, familiar with Service Worker.

---

## Android Engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/android-engineer-career/

> Please send your resume to apply for this position: [hr@arcblock.io](mailto:hr@arcblock.io)

## Job responsibilities

- Design and implement user-oriented product features, deliver high-quality software, including but not limited to: DID Wallet Android version, DID Wallet Android SDK.
- Optimize the delivery pipeline and level of automation for each project.
- Provide technical support for our customers and partners.

## Ability requirements

- Having more than 2 years of practical development experience in Android, familiar with Android SDK and related technologies for development, debugging, optimization, release, and integration.
- Proficient in mastering the Kotlin language.
- Familiar with Android threads, processes, Bundles, and Handler mechanisms.
- Familiar with Android custom drawing and animation implementation;
- Proficient in using OkHttp, Retrofit, RxJava, Glide, Gson and other common third-party libraries.
- Proficient in using git.
- Understand or be familiar with Javascript/Node.js projects.
- Based on product requirements design solutions, ability to drive product landing.
- Strong self-learning ability and a relatively open mindset, constantly learning new technologies and tools to improve the efficiency of the entire team.

## Bonus points

- Familiar with basic concepts and algorithms of blockchain.
- Have experience developing with other backend languages.
- Experience in developing Native Apps for iOS.
- High-quality GitHub open source projects, technical blogs.
- Familiar with any modern front-end framework, such as React, Vue.js, Angular.
- Leadership capabilities, product capabilities, and best engineering practices demonstrated in past experiences.
- Good communication skills: effectively communicate with peers, non-technical personnel, such as document writing.
- Familiar with Amazon AWS or other cloud computing tools and technologies such as Azure, Google Cloud, Alibaba Cloud, etc.

---

## Full-Stack JS Engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/full-stack-js-engineer-career/

> <em>Please send your resume to apply for this position:</em> [hr@arcblock.io](mailto:hr@arcblock.io)

## Job Responsibilities

💡 You can choose to participate in any of the following jobs based on your ability and interest

- Design and implement user-facing product features to deliver high quality, smooth user experience web applications, even cross-platform applications
- Participate in the design, implementation, and delivery of [<strong>Blocklet Server</strong>](https://www.npmjs.com/package/@blocklet/cli) kernel functionality and console functionality, ensuring high performance and security
- Participate in the design, implementation, delivery and stable operation and maintenance of [<strong>Blocklet Launcher</strong>](https://launcher.arcblock.io/home/) functionality, and extend it to more cloud platforms
- Participate in the iteration of [<strong>Blocklet SDK</strong>](https://www.npmjs.com/package/@blocklet/sdk), design and improvement of <strong>Blocklet Service</strong>, and provide efficient application development framework.
- Participate in the development iterations of the [<strong>blockchain</strong>](https://main.abtnetwork.io/explorer) and its [<strong>SDK</strong>](https://www.npmjs.com/package/@ocap/client) to help improve the performance, security and scalability of each layer of the chain
- Participate in the end-to-end architecture and support of various decentralized applications, such as our Rollup solution
- Optimize code coverage, delivery pipeline, and automation levels for projects under your responsibility

## Competency Requirements

- Solid <strong>JavaScript</strong>, <strong>HTML</strong>, <strong>CSS3</strong> skills, familiar with responsive layout, familiar with <strong>ES6</strong>, <strong>HTTP</strong> protocol
- Familiarity with any front-end framework, such as <strong>React.js</strong>, <strong>Vue.js</strong>, familiarity with React.js is a plus
- Familiarity with any back-end frameworks, such as <strong>Express.js</strong>, Koa, etc.
- Familiar with computer networks, understanding of distributed systems, common security issues and means to prevent them
- Familiar with <strong>GraphQL</strong>, able to design and implement a good back-end API
- Ability to design, engineer and implement architecture based on system requirements and go live for operations and maintenance
- Have used <strong>Jest</strong>, <strong>GitHub Actions</strong>, common logging, DB interaction libraries
- Understanding of common back-end system architecture and optimization methods, such as <strong>caching</strong>, <strong>load balancing</strong>
- Strong <strong>self-learning</strong> ability and <strong>open-mindedness</strong>, constantly learning new technologies and tools to improve the efficiency of the whole team
- <strong>Good engineering skills</strong>, such as code style, <strong>Git workflow</strong>, and ability to write high quality front-end code
- Familiar with <strong>Linux</strong>, Unix operating systems, Nginx, and the ability to perform common operations and maintenance tasks
- Familiar with <strong>Amazon AWS</strong> or other cloud computing platforms (e.g. Azure, Google Cloud, Digital Ocean, Ali Cloud, etc.)

## Bonus points

- Experience building front-end applications using <strong>React.js</strong> and experience using <strong>Docker</strong>
- Familiarity with basic <strong>blockchain</strong> conceptual models, links to common public chain operating mechanisms, and application development on other public chains is a plus
- Demonstrated <strong>leadership</strong>, product capability, and engineering best practices from past experience
- Good presentation skills: effective communication with peers, non-technical staff, and then documentation for example
- High quality GitHub <strong>open source projects</strong>, technical blogs
- Experience with <strong>Electron</strong> and projects, familiarity with <strong>Service Worker</strong>

---

## arcblock/hr-assistant

URL: https://www.arcblock.io/en/docs/arcblock/hr-assistant/

---

## iOS Engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/ios-engineer-career/

> <em>Please send your resume to apply for this position</em>: [hr@arcblock.io](mailto:hr@arcblock.io)

## Job Responsibilities

- Design and implement user-oriented product features, deliver high-quality software, including but not limited to: DID Wallet iOS version, DID Wallet iOS SDK.
- Optimize the delivery pipelines and automation levels of each project.
- Provide technical support for our customers and partners.

## Ability requirement

- Have 2 years or more experience in Internet or blockchain industry, good engineering literacy, such as coding style, Git workflow.
- Has rich experience in mobile application development, strict requirements for the quality of mobile products, and pursues perfection in details.
- Possess a solid foundation in Swift (required), Object-C language, and understanding language features.
- Can achieve more complex interfaces and visual effects, handle the logical relationship with data well, and ensure stability.
- Familiar with the packaging and publishing process, with experience in AppStore application deployment.
- According to product requirements, design solutions, and promote the ability to land products.
- Strong self-learning ability and a relatively open mindset, continuously learning new technologies and tools to improve the efficiency of the entire team.

## Bonus points

- Familiar with basic concepts and algorithms of blockchain.
- Have experience in developing with other backend languages
- Experience in developing native apps for Android
- High-quality GitHub open source projects, technical blogs.
- Familiar with any modern front-end frameworks, such as React, Vue.js, Angular.
- Leadership ability, product ability, engineering best practices capability displayed in past experiences.
- Good communication skills: effectively communicate with colleagues and non-technical staff, such as document writing.
- Familiar with Amazon AWS or other cloud computing tools and technologies such as Azure, Google Cloud, Alibaba Cloud, etc.

---

## Join Us

URL: https://www.arcblock.io/en/docs/arcblock/join-us/

## Why join ArcBlock?

ArcBlock aims to reconstruct and optimize the way blockchain applications connect with ordinary users and developers, by combining blockchain technology, cloud computing, and token economy, providing developers with diverse tools and services to facilitate more efficient and convenient development and deployment of decentralized applications. We are gradually building a complete platform and forming a rich application ecosystem. Most of our products will be open source, and some products have already been open sourced.

Currently, the products we have released include:

- [Blocklet Server](https://www.npmjs.com/package/@blocklet/cli):  [Operating system for decentralized applications](https://developer.blocklet.io/), also a basic developer tool, can connect to any [App Store](https://store.blocklet.dev/) that follows the same protocol to find, purchase, install, and manage [Decentralized applications.](https://www.blocklet.io/).
- [DID wallet](https://www.didwallet.io/): Convenient for users to manage their digital assets and digital identities, fully compatible with Ethereum, decentralized WEB3, DID wallet.
- [Blockchain Framework.](https://chain.abtnet.io/): A feature-rich, layered and scalable blockchain framework that enables developers to quickly launch their own application chains, supporting cross-chain transactions and contract mechanisms.

The products we release need to meet high quality, high performance, high reliability, and scalability requirements, and support large-scale, 24/7 operation. We need your help to make this happen.

If you can adapt to remote work, manage your own time, appreciate transparency in company culture, collaborate with an international team distributed globally, pursue engineering quality, focus on development efficiency, love to learn and research the latest technology, then our Full Stack Engineer position will be very suitable for you!

Full-stack engineers are important forces driving the growth of [ArcBlock](https://www.arcblock.io/) platform, participating in weekly team planning meetings, all-staff briefings, and responsible for core products such as wallets, nodes, and blockchain frameworks for users.

Submitting a resume? Please send an email to [hr@arcblock.io](mailto:hr@arcblock.io)

## Referral Reward Program

For each of our positions, once officially hired (after passing the probation period), the referrer will be rewarded with 1,000 ABT or an equivalent amount in cash (the method of reward will be determined by the company according to local legal requirements, etc.).

- If it is a self-recommendation, the reward will be granted to the hired employee.
- For referrers, the recommended relationship must be confirmed by the hired employee.
- The referral reward program does not apply to HR service agencies or individuals contracted with the company, or to internal employees who have a direct leadership with the position.

ArcBlock reserves the right to modify and interpret the details of the referral reward program at any time.

## How do we work?

- We use GitHub to host all of our code, task management and tracking are also based on GitHub.
- We use GitHub Actions to run tests, build, package, and release products.
- We use [Blocklet Server](https://www.npmjs.com/package/@blocklet/cli) to deploy all websites, applications, chains. Blocklet Server is our own product.
- We use JavaScript to develop most applications and SDKs, heavily utilizing React.js, MUI, and Node.js.
- We use Markdown to write various documents, blogs, and pages, and use Notion to manage internal knowledge.
- We advocate for results-oriented approach, and will ensure the elegance of the solution through code review.
- We advocate automation, reducing the initial cost and delivery time of projects as much as possible.
- We try our best not to reinvent the wheel. The vast majority of modules and services are designed with reusability in mind from the beginning.

## What can we offer?

- Choose work equipment according to your needs. The basic configuration is a MacBook Pro + a large high-definition display screen.
- All remote methods, free and flexible time, colleagues distributed in different places.
- Competitive salary, token incentive plan, diversified and flexible salary schemes.
- A working atmosphere full of trust, end-to-end empowerment. As long as you have the willingness and ability, you can fully hold the product, technology design, and research and development on your own.
- Rapid growth, technology-first, focus on delivery, user-centric, goal-oriented team.
- To assist employees in their growth, expenses related to work-related skills training courses and technical conferences can be reimbursed directly.
- At least 10 days of paid annual leave each year, plus flexible paid sick leave.

## What positions are currently open?

- [What is our recruitment process?](/en/docs/arcblock/recruitment-process/)

- [WEB Front-end Engineer (Filled)](/en/docs/arcblock/web-front-end-engineer-career/)

- [Android Engineer (Filled)](/en/docs/arcblock/android-engineer-career/)

- [AI Application Engineer (Filled)](/en/docs/arcblock/ai-application-engineer-career/)

- [iOS Engineer (Filled)](/en/docs/arcblock/ios-engineer-career/)

- [Full-Stack JS Engineer (Filled)](/en/docs/arcblock/full-stack-js-engineer-career/)

- [JS backend engineer (Filled)](/en/docs/arcblock/js-backend-engineer-career/)

- [UI/UX designer (Filled)](/en/docs/arcblock/ui-ux-designer/)

- [Site Reliability Engineer (Filled)](/en/docs/arcblock/sre-jd/)

- [HR 助理（已招满）](/en/docs/arcblock/hr-assistant/)

---

## JS backend engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/js-backend-engineer-career/

> <em>Please send your resume to apply for this position</em>: [hr@arcblock.io](mailto:hr@arcblock.io)

## Job Responsibilities

- Design and implement user-oriented product features, deliver high-quality, high-performance, secure backend services.
- Participate in discussions, design, implementation, and delivery of [Blocklet Server](https://www.npmjs.com/package/@blocklet/cli) kernel functions, providing stable, high-performance application runtimes.
- Participate in the design, implementation, delivery, and stable operation of [Blocklet Launcher](https://launcher.arcblock.io/) functionality, and extend it to more cloud platforms.
- Participate in the iteration of [Blocklet SDK](https://www.npmjs.com/package/@blocklet/sdk), design and improve the Blocklet Service, providing an efficient application development framework.
- Participate in the development iteration of [Asset chain](https://main.abtnetwork.io/) and [SDK](https://www.npmjs.com/package/@ocap/client), assist in improving the performance, security, and scalability of each layer of the chain.
- Participate in the backend architecture and support of various decentralized applications, such as our Rollup solution.
- Optimize the code coverage, delivery pipeline, and automation level of the responsible project.

## Ability requirements

- Familiar with the <strong>JavaScript</strong> language, proficient in using frameworks such as <strong>Express.js</strong>, <strong>Koa</strong>, etc.
- Familiar with computer networks, understand distributed systems, common security issues, and prevention measures.
- Familiar with <strong>GraphQL</strong>, able to design and implement well-structured backend APIs.
- The ability to design architecture, implement engineering, and operate online according to system requirements.
- Using <strong>Jest</strong>, <strong>GitHub Actions</strong>, common logging, and database interaction libraries.
- Understanding common architectures and optimization methods for backend systems, such as caching, load balancing.
- Strong self-learning ability and an open mindset, continuously learning new technologies and tools to improve the efficiency of the entire team.
- Having good engineering literacy, such as coding style, Git workflow, able to write high-quality front-end code.
- Familiar with Linux and Unix operating systems, familiar with Nginx, able to complete common operation and maintenance tasks.
- Familiar with <strong>Amazon AWS</strong> or other cloud computing platforms (such as <strong>Azure</strong>, <strong>Google Cloud</strong>, <strong>Digital Ocean</strong>, <strong>Alibaba Cloud</strong>, etc.)

## Extra credit points

- Experience in building front-end applications using React.js, experience with Docker.
- Familiar with basic blockchain concepts and models, understand common public chain operation mechanisms, better if you have experience in application development on other public chains.
- Leadership abilities, product capabilities, and best engineering practices demonstrated in past experiences.
- Good communication skills: effective communication with peers, non-technical personnel, and document writing.
- High quality GitHub open source projects, technical blogs.

---

## What is our recruitment process?

URL: https://www.arcblock.io/en/docs/arcblock/recruitment-process/

What are the steps to successfully join ArcBlock? How should one prepare? You can take a look at two articles written by CEO.

[How to easily pass through ArcBlock's recruitment process](/en/articles/how-to-get-through-arcblock-interview-process/)

[How to successfully pass the interview of ArcBlock's UI/UX designer](/en/articles/2021-01-22-how-to-get-through-ux-interview-process/)

---

## Site Reliability Engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/sre-jd/

<em>Please send your resume to apply for this position</em>: [hr@arcblock.io](mailto:hr@arcblock.io)

### Job Responsibilities

- Organize and implement comprehensive and automated online service data collection, monitoring, and alarm processes
- Responsible for the daily operation and maintenance of Blocklet Server in online servers, such as upgrades and diagnostics
- Responsible for automated, standardized online service data, team code, and knowledge base backups
- Responsible for daily security protection of online services, such as SQL injection, denial of service tools, etc.
- Responsible for providing basic data, error, and log collection services for online services, such as Sentry
- Assist in building team data dashboards, such as team leaderboards, requiring basic application development capabilities

### Skills Required

- Familiar with Node.js language for quick understanding of basic usage of Blocklet Server
- Familiar with Linux, Unix operating systems, Nginx, Shell, and able to complete common operations tasks
- Familiar with computer networks, with the ability to troubleshoot problems throughout the entire process
- Familiar with common security issues and prevention methods, able to use cloud services or self-developed solutions
- Familiar with the operation and use of common monitoring solutions, such as Sentry, InfluxDB
- Familiar with common databases such as SQLite for backup, recovery, and performance optimization
- Familiar with basic usage of cloud computing platforms such as Amazon AWS, Google Cloud
- Good engineering literacy, such as code style, Git workflow, able to write high-quality script code
- Strong self-learning ability and open mindset, continuously learning new technologies and tools to improve the efficiency of the entire team
- Sense of ownership, safeguarding the performance, security, and reliability of online services

### Bonus Points

- Demonstrated leadership, product, and engineering best practices in past experiences
- Good communication skills: effective communication with peers, non-technical personnel, and document writing
- High-quality GitHub open source projects, technical blogs

---

## UI/UX designer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/ui-ux-designer/

## Main responsibilities

- Work closely with multiple developers to advance the implementation of the project together.
- Participate in the construction of ArcBlock [UX Library](https://arcblock.github.io/ux), building a well-crafted business layer component library.
- Suggest improvements to existing products and propose feasible design solutions

## Ability requirements

- Passionate about your role and proactive in staying informed about cutting-edge developments in product design through various channels
- Proficient in Figma, familiar with its component design and variable-related functions.
- Solid visual design skills, attention to detail, strong control over color and layout.
- Excellent communication skills and team spirit, effective collaboration with different team members.
- We do not encourage the use of high-precision redline design approach, but we hope you can provide the team with a design style and specification guidance at a higher dimensionality.

## Bonus points

- Having a personal website that is maintained long-term or showcasing works on platforms like Dribbble.
- Understand design implementation, such as HTML and CSS.

---

## WEB Front-end Engineer (Filled)

URL: https://www.arcblock.io/en/docs/arcblock/web-front-end-engineer-career/

> Please send your resume to apply for this position: [hr@arcblock.io](mailto:hr@arcblock.io)

## Job Responsibilities

- Design and implement user-facing product features to deliver high quality, smooth user experience WEB applications, even cross-end applications
- Participate in the discussion, design, implementation and delivery of [<strong>Blocklet Server</strong>](https://www.npmjs.com/package/@blocklet/cli) console features, providing a complete decentralized application development workbench
- Participate in the iteration of the WEB version of [DID wallet](https://web.abtwallet.io/) to provide a secure, efficient and easy-to-use WEB wallet service, similar to Metamask
- Participate in the development of various decentralized applications, such as [Blocklet Store](https://store.blocklet.dev/), [Block Browser](https://main.abtnetwork.io/explorer) and other existing modules and new projects
- Participate in the construction of ArcBlock [UX Library](https://arcblock.github.io/ux/?path=/story/documentation-introduction--page) to build a business layer component library with excellent experience
- Optimize the code coverage, delivery pipeline, and automation level of the projects you are responsible for

## Competency requirements

- Solid <strong>JavaScript</strong>, <strong>HTML</strong>, <strong>CSS3</strong> skills, familiar with responsive layout, familiar with <strong>ES6</strong>, <strong>HTTP</strong> protocol
- Familiarity with any front-end framework, such as <strong>React.js</strong>, <strong>Vue.js</strong>, preferably React.js
- Familiarity with any front-end component library, such as <strong>Material UI</strong>, <strong>Ant Design</strong>, familiarity with Material UI is a plus
- Have used automated testing tools such as <strong>Jest</strong>, <strong>Cypress</strong>, and <strong>GitHub Actions</strong>
- Familiarity with front-end build tools, such as <strong>Webpack</strong>, <strong>Rollup</strong>, <strong>Vite</strong>, etc.
- Good engineering skills, such as code style, Git workflow, and ability to write high quality front-end code
- Combine front-end solutions based on product design and push the product to launch
- Strong self-learning ability and open mind, constantly learning new technologies and tools to improve the efficiency of the whole team

## Extra points

- Experience with [Electron](https://www.electronjs.org/) and projects, familiar with <strong>Service Worker</strong>
- Experience using [Node.js](https://nodejs.org/en/), [Express](http://expressjs.com/index.html) backend, hands-on experience with <strong>SSR</strong>, <strong>SSG</strong>, familiar with <strong>GraphQL</strong>
- Familiarity with Amazon <strong>AWS</strong> or other cloud computing (e.g. Azure, Google Cloud, Aliyun, etc.) tools and technologies
- Familiarity with basic blockchain conceptual models, preferably having done application development on other public chains
- Demonstrated leadership, product capability, and engineering best practices from previous experience
- Good presentation skills: effective communication with peers, non-technical staff, and then documentation for example
- High quality GitHub open source projects, technical blogs
- Familiarity with <strong>Linux</strong>, <strong>Unix</strong> systems and common command line tools

---

## ArcBridge Node

URL: https://www.arcblock.io/en/docs/arcbridge/

---

## How to add stake for your node?

URL: https://www.arcblock.io/en/docs/arcbridge/add-stake-for-arcbridge-node/

1. Login to your ArcBridge Node, and open "Stake" page
2. Click "Add Stake" on the Stake page

![image.png](https://media.arcblock.io/lib/fa/fa779c179cc01a204c9b4162516fe28b.w1600.webp)

1. Input stake amount in the stake dialog:

![image.png](https://media.arcblock.io/lib/db/dbb64553a64830086424456b40b3ab3e.w1600.webp)

1. Complete the stake with your DID Wallet or send the QRCode to others

![image.png](https://media.arcblock.io/lib/04/04e1d4624d3e895ba1bf5723c6ecceb5.w1600.webp)

---

## Join ArcBridge

URL: https://www.arcblock.io/en/docs/arcbridge/EEvpZgb-AsljVGGoqBvVWtWv/

You can join ArcBridge by just run the following blocklet:

[ArcBridge Node](https://store.blocklet.dev/blocklets/z8iZqeUACK955YaBWqEd8aKg3tTki1GpvE2Wu)

Detailed video and blog tutorial by z1TTxpjeYVMyNVwRbBjrhxa4E94UaDd6ZX9 can be found here:

::embed{url="https://x.com/i/status/1766226689896358229"}

---

## ARC Architecture

URL: https://www.arcblock.io/en/docs/architecture/

---

## AFS UI

URL: https://www.arcblock.io/en/docs/architecture/afs-ui/

**AFS UI** is the architecture name for projecting AFS resources and capabilities into something a human or agent can interact with. It answers: given paths, providers, and operations, which UI device and contract present them?

It is **not** a third large authoring board next to AUP and Web Device. Author interactive apps in [AUP](/en/docs/aup/). Author static sites in [Web Device](/en/docs/web-device/). Use this page only to keep those targets aligned with AFS.

## What exists in current code

Checked against ARC source `44fbd616f` and packages at `2.0.0-beta.31` in tree:

| Piece | Package / location | Role today |
| --- | --- | --- |
| AUP types and pure helpers | `@aigne/afs-aup` (`packages/aup`) | Semantic node graph, validation helpers, degradation helpers shared by devices |
| Interactive UI device runtime | `@aigne/afs-ui` (`providers/runtime/ui`) | Sessions, AUP app loading, node store, event/exec wiring, web-page surfaces |
| Web Device provider | `@aigne/afs-web-device` (`providers/runtime/web-device`) | Reads site trees (pages, content, `.web/`) and renders static HTML; can render supported AUP shells for sites |
| AFS provider base | `@aigne/afs` (`packages/core`) | Mounts, list/read/write/search/exec, capability and access modes |

AUP node fields that connect UI to AFS include `src` (read-only binding), `bind` (read-write binding), `propBind` (server-resolved prop paths), and events that map to AFS `exec`. Those fields are part of the AUP contract, not a separate “AFS UI API.”

## Architecture relationship

```text
AFS (paths + providers + operations)
  └─ AFS UI (projection lens)
       ├─ AUP + UI runtime  → interactive sessions / device renderers
       └─ Web Device        → static HTML sites and content objects
```

| Concern | Owned by | Notes |
| --- | --- | --- |
| Path operations and provider capability | AFS | UI cannot invent an operation the provider does not declare |
| Semantic tree, events, degradation | AUP | Device must report capabilities; support is not universal |
| Session handshake and interactive render | UI runtime (`@aigne/afs-ui`) | Present-tense behaviour is version- and target-specific |
| Site directories, markdown content, themes | Web Device | Separate from interactive session protocol |
| Comments / collections surfaces on sites | Web Device + UI surface code | Platform surfaces exist; not a guarantee that every site enables them |

## What draft architecture docs claim that this page does not

Internal draft materials (for example `docs/architecture/afs-ui.md` in the ARC repo) describe a broader vision: every UI element as an AFS path, a full `/dev/ui` device model, window managers, and multi-backend renderers. Treat those as **archaeology and design intent**.

This public page only states:

1. AFS UI is a useful **lens** for relating UI to AFS.
2. **AUP** and **Web Device** are the documented authoring and runtime contracts.
3. There is **no** public, versioned “implement any third-party AFS UI device” extension guide with a guaranteed E2E sample for external authors—unless and until a sibling board documents one against current code.

Do not infer:

- Every AFS path has a UI
- Every UI can write through AFS
- Every renderer supports the same primitives
- Old ArcBlock admin UIs are shipped as stable ARC products

## Where to go next

| Task | Board |
| --- | --- |
| Author or validate AUP source | [AUP](/en/docs/aup/) |
| Device capabilities and degradation | [AUP device capabilities](/en/docs/aup/device-capabilities-degradation/) (and related AUP pages) |
| Build a static site | [Web Device](/en/docs/web-device/) |
| Mount data or implement a provider | [AFS](/en/docs/afs/) |
| Package the app | [Blocklets](/en/docs/blocklets/) |
| Caller and session data views | [Identity & Data Spaces](/en/docs/identity-data-spaces/) |

---

## ARC and AFS

URL: https://www.arcblock.io/en/docs/architecture/arc-and-afs/

Name the layers by what you depend on:

| Name | Role | You reach it when… |
| --- | --- | --- |
| **AFS** | Path-based resource and capability abstraction | You list, read, write, search, exec, or mount a path |
| **ARC** | Runtime product shell around AFS | You start a service, run a Blocklet, open a session, or use the CLI against a live instance |

AFS does not know how HTTP arrived or which process hosts it. ARC does: it boots the host, mounts providers, applies identity and session context, and exposes operational tools.

## What AFS owns

AFS is implemented as the `@aigne/afs` core and provider base classes. A provider declares a name, access mode, and the operations it implements. Core operations you will see in the CLI and provider contract include:

| Operation family | Purpose |
| --- | --- |
| `list` / `read` / `write` / `delete` | Directory and entry access |
| `stat` | Metadata without full content |
| `search` | Provider-defined content search inside a path |
| `exec` | Actions exposed as executable paths |
| `explain` | Human- and agent-oriented description of a path or concept |
| `mount` | Attach a provider at a path |

A path is an interface boundary. It is not evidence that all data lives in one store. Check the provider’s declared capabilities before treating an operation as part of your application contract. Full operation semantics: [AFS core contract](/en/docs/afs/core-contract/).

## What ARC owns

ARC is the host that makes AFS useful as a product:

- Loads and mounts providers (for example Web Device, DID Space, UI device modules)
- Runs Blocklet packages and instances
- Builds session and caller views used by interactive and site surfaces
- Exposes `arc` CLI groups (`afs`, `blocklet`, `service`, `dsl`, `space`, `did`, and others)

Installed CLI surface checked for this board: `arc` `2.0.0-beta.28`. Command reference: [ARC CLI](/en/docs/arc-cli/).

## Start with the right name

| Task | Start with | Why |
| --- | --- | --- |
| Implement or debug a path operation | AFS | The provider and operation contract decide behaviour |
| Author a provider package | AFS | Mount and capability rules live there |
| Run or package an application | Blocklet on ARC | Lifecycle is package/instance, not a raw path |
| Render a static site | Web Device (AFS provider) via ARC | Site layout is a Web Device concern hosted by ARC |
| Drive an interactive AUP app | AUP session under ARC UI runtime | Session and device handshake are runtime concerns |
| Inspect who is calling | Identity board | Caller and DID Space are not AFS operation names |

## What this page does not claim

- It does not publish a stable third-party “plug in any UI device” extension API.
- It does not equate every historical Blocklet Server or DID product name with a current ARC module.
- It does not expand experimental remote deploy or instance-DID lifecycle paths into present-tense contracts; those belong on the boards that can re-verify them.

Next: [Product layers](../product-layers/) for ownership, or [AFS](/en/docs/afs/) for operations.

---

## Contracts and evidence

URL: https://www.arcblock.io/en/docs/architecture/contracts-and-evidence/

Every present-tense product sentence needs a status. Without one, readers treat vision, history, and shipping behaviour as the same contract.

## Status vocabulary

| Status | Meaning | Allowed on public pages | Required evidence |
| --- | --- | --- | --- |
| **Current contract** | Behaviour you may design against for a named target runtime | Yes, as “supports / does / rejects” | Current source or types **and** tests or observed local run on the target version |
| **Architecture** | How layers fit; orientation only | Yes, clearly as explanation | Consistent with current structure; must not invent new public APIs |
| **Experimental / gap** | Incomplete, partial, or not E2E-verified | Yes, only if labelled as such | State what is missing or unproven; do not soften into a promise |
| **Lineage** | Why an older name still appears | Yes, with explicit non-promises | Product records, reference apps, or dependency facts—not feature parity |
| **Unresolved** | Needs a product or engineering decision | Prefer issue / review notes; short public caution only | Name the decision; do not invent a default |

## Evidence order (mandatory)

1. **Current code, types, tests, and a local run** prove “now supports.”
2. **Merged PRs** prove a change landed once. Re-check the current tree; later commits may have removed or narrowed it.
3. **Planning docs, open issues, draft architecture notes, articles** are archaeology. They may guide research; they do not establish a public contract alone.
4. When sources conflict, **public docs state the current implementation**, and the conflict goes to `research-ledger.md` or an issue comment—not into a marketing rewrite.

## How to classify a sentence

| Draft sentence | Correct status | Rewrite pattern |
| --- | --- | --- |
| “`arc afs ls` lists a path” | Current contract | Keep only after running it on the documented CLI version |
| “AFS UI relates UI work to AFS paths” | Architecture | Keep as explanation; do not add “stable extension API” |
| “Instance DID lifecycle is complete for all remotes” | Experimental / gap (if unproven) | Say what is verified locally; mark remote lifecycle separately |
| “Discuss Kit was absorbed into ARC” | Lineage | State reference Blocklet / surfaces; deny full old-feature equivalence |
| “Third parties can ship any UI device” | Unresolved / not current | Do not publish as contract until code + E2E sample exist |

## What each board type should carry

| Board type | Primary status mix |
| --- | --- |
| Architecture (this board) | Architecture + lineage; pointers to contracts |
| AFS / AUP / Web Device / Blocklets / Identity / CLI | Mostly current contract; mark experimental gaps explicitly |
| Product marketing pages | May use lineage language; never invent developer contracts |

## Version pinning

When a page includes commands or field-level behaviour:

1. Name the **CLI or package version** used for verification.
2. Show **actual** outputs or error shapes when the page teaches a command.
3. If your install differs, re-run before treating the page as authority.

This board’s orientation facts were checked with `arc` `2.0.0-beta.28` and ARC source `44fbd616f`. Sibling boards may pin their own versions; prefer the stricter or more recent check for operational work.

## Red lines that override status

Reader-visible text still follows site positioning constraints (product and technical claims only; no price or return promises; no banned marketing phrases; no claiming unimplemented features as shipped). Architecture status does not excuse a §1C overclaim.

## Related pages

- Map and reading order: [Overview](../overview/)
- Old product names: [Product lineage](../product-lineage/)
- Term index: [Reference](../reference/)

---

## Mental model

URL: https://www.arcblock.io/en/docs/architecture/mental-model/

Hold these terms as boundaries, not as synonyms.

| Term | Think of it as | Do not treat it as |
| --- | --- | --- |
| **AFS** | A path-addressable filesystem of resources and capabilities | A single physical database or cloud bucket |
| **Provider** | A module that owns a mount path and implements operations it declares | Proof that every operation exists on every path |
| **AFS UI** | An architecture lens: UI work expressed relative to AFS paths and devices | A third public authoring product equal to AUP and Web Device |
| **AUP** | A declarative semantic UI tree (nodes, events, bindings, degradation) | HTML, CSS, or a site content model |
| **Web Device** | An AFS provider that reads site trees and renders static HTML | An interactive AUP session or a general app runtime |
| **Blocklet** | A package you author and an instance you run | Only a website, or only a UI file |
| **DID / caller** | Verified identity context the runtime attaches to a request or session | A path string that happens to look like a DID |
| **DID Space** | DID-scoped persistent storage mounted through AFS | A second parallel filesystem protocol |
| **Data Space** | A documentation term for caller data context and views | A separate public SDK or lifecycle API |
| **ARC** | The runtime and CLI shell that hosts AFS, sessions, and Blocklets | The same thing as AFS |

## How the pieces connect

1. **AFS** answers “where is the resource, and which operations does its provider support?”
2. **AFS UI** answers “when that resource is shown or edited, which device and UI contract applies?”
3. **AUP** answers interactive presentation: semantic trees, sessions, device capabilities, degradation.
4. **Web Device** answers site presentation: pages, content objects, themes, static HTML.
5. **Blocklet** answers packaging: what you ship, how you run it locally, and how it binds surfaces to AFS.
6. **Identity and data spaces** answer “who is acting, and which data view do they receive?”
7. **ARC CLI** is the operational entry for inspecting and driving those layers from a machine.

## Reading order

| If you are… | Read first |
| --- | --- |
| New to ARC and need vocabulary | This page, then [ARC and AFS](../arc-and-afs/) |
| Choosing which guide owns a task | [Product layers](../product-layers/) |
| Connecting UI work to AFS paths | [AFS UI](../afs-ui/), then [AUP](/en/docs/aup/) or [Web Device](/en/docs/web-device/) |
| Implementing resources or providers | [AFS](/en/docs/afs/) |
| Shipping an application unit | [Blocklets](/en/docs/blocklets/) |
| Handling sign-in, membership, or user data | [Identity & Data Spaces](/en/docs/identity-data-spaces/) |
| Checking whether a sentence is a product promise | [Contracts and evidence](../contracts-and-evidence/) |
| Chasing an old product name | [Product lineage and boundaries](../product-lineage/) |

## Contract vs explanation vs lineage

- **Public contract** — behaviour you can depend on after source, tests, and a local run agree. Sibling boards own these.
- **Architecture explanation** — how layers fit; useful for orientation, not a substitute for types and commands.
- **Lineage** — why an older name still appears; never a full feature-equivalence claim.

Internal ARC materials also use **AOS** for portable operating-system semantics (session, HTTP surface, scheduling) that ARC hosts. This public board does not treat AOS as a separate developer documentation product. When a task needs session or caller detail, use [Identity & Data Spaces](/en/docs/identity-data-spaces/) and the AUP session pages.

---

## ARC Architecture

URL: https://www.arcblock.io/en/docs/architecture/overview/

ARC has several developer surfaces. They are related, but they do not share one undifferentiated contract. Use this board to choose the right layer before following a task-specific guide.

| If you need to understand | Read next | Do not infer |
| --- | --- | --- |
| Path-based resources and provider behaviour | [AFS](/en/docs/afs/) | A global search, storage, or provider capability that has not been documented for the target runtime |
| A declarative interface tree, state, or renderer boundary | [AUP](/en/docs/aup/) | That every AUP node has the same support on every target |
| A static site backed by AFS paths | [Web Device](/en/docs/web-device/) | That a site layout is an interactive AUP session |
| A package and instance lifecycle | [Blocklets](/en/docs/blocklets/) | That every older Blocklet Server behaviour remains part of ARC |
| Identity, a DID Space, or a data-space term | [Identity & Data Spaces](/en/docs/identity-data-spaces/) | A complete remote lifecycle or trust model that has not been verified end to end |
| How CLI commands map to these layers | [ARC CLI](/en/docs/arc-cli/) | That every CLI group is a separate product with its own public API |

## System map

Read the stack from the bottom up when you need a resource, and from the outside in when you need a product boundary:

| Layer | What it answers | Primary developer surface |
| --- | --- | --- |
| **AFS** | How do I address data and capabilities by path? | Operations, mounts, providers |
| **AFS UI** | How do UI concerns relate to AFS resources? | Architecture lens only (this board) |
| **AUP** | How do I describe an interactive interface tree? | Declarative UI contract and DSL |
| **Web Device** | How do I build and render a static site? | Site directories, content, components |
| **Blocklet** | How do I package and run an application? | Package, instance, local run, publish boundary |
| **Identity / data spaces** | Who is calling, and which data view do they get? | Caller context, DID Space, session views |
| **ARC + CLI** | How do I start, inspect, and operate the runtime? | `arc` commands and the host process |

AFS is the resource and capability layer. ARC is the runtime and product shell that mounts providers, runs Blocklets, and exposes CLI and service entry points. AFS UI is not a third large authoring board equal to AUP or Web Device; it explains how those targets relate back to AFS.

For ownership and the layer diagram, see [Product layers](../product-layers/). For how ARC and AFS are named separately, see [ARC and AFS](../arc-and-afs/).

## A map, not a substitute for a contract

The architecture map may explain why two parts belong together. It does not turn an internal plan, an old product page, or a source directory into a public API. Treat current source, target-version tests, and a local run as the evidence for a present-tense claim. Classification rules live on [Contracts and evidence](../contracts-and-evidence/).

The phrase **AFS UI** appears in ARC architecture material as a way to relate UI concerns to AFS-oriented resources. In this board it is an architectural lens, not an independent public extension API. AUP and Web Device remain separate, target-specific documentation surfaces.

## Read by task

| Goal | Start here |
| --- | --- |
| Learn the vocabulary and reading order | [Mental model](../mental-model/) |
| Separate ARC (runtime) from AFS (filesystem) | [ARC and AFS](../arc-and-afs/) |
| Choose which board owns a task | [Product layers](../product-layers/) |
| Place interactive UI vs static sites on AFS | [AFS UI](../afs-ui/) |
| Decide whether a claim is current contract or lineage | [Contracts and evidence](../contracts-and-evidence/) |
| Resolve an older ArcBlock product name | [Product lineage and boundaries](../product-lineage/) |
| Collect public board links and terms | [Reference](../reference/) |

## Version boundary

Facts on this board were checked against:

- Installed CLI: `arc` `2.0.0-beta.28` (`arc --version`)
- ARC source snapshot: `44fbd616f` (`packages/core`, `packages/aup`, `providers/runtime/ui`, `providers/runtime/web-device`, `providers/basic/did-space`, `providers/basic/members`)
- Package names observed in that tree: `@aigne/afs`, `@aigne/afs-aup`, `@aigne/afs-ui`, `@aigne/afs-web-device`, `@aigne/afs-did-space` (each `2.0.0-beta.31` in source)

Task-specific commands, fields, and renderer support belong on the sibling boards. Re-check those boards when your installed `arc` version differs.

---

## Product layers

URL: https://www.arcblock.io/en/docs/architecture/product-layers/

Choose a layer from the problem you are solving, not from a directory name or an old product label.

## Layer map

| Layer | Owns | Does not own | Developer entry |
| --- | --- | --- | --- |
| **AFS** | Paths, mounts, provider operations, capability declarations | Site themes, AUP primitives, Blocklet release policy | [AFS](/en/docs/afs/) |
| **AFS UI** | How UI devices relate to AFS (architecture explanation) | A portable third-party device SDK promised as product | [AFS UI](../afs-ui/) (this board) |
| **AUP** | Semantic UI tree, events, bindings, sessions, degradation rules | Website content model, package lifecycle | [AUP](/en/docs/aup/) |
| **Web Device** | Static site trees, pages, content objects, components, HTML render | Interactive session protocol, identity lifecycle | [Web Device](/en/docs/web-device/) |
| **Blocklet** | Package vs instance, local run, manifest/check, composition boundary | Core AFS op semantics, AUP node catalogue | [Blocklets](/en/docs/blocklets/) |
| **Identity & data spaces** | Caller context, DID-scoped storage, session data views, membership surfaces | AFS provider authoring, site markdown pipeline | [Identity & Data Spaces](/en/docs/identity-data-spaces/) |
| **ARC CLI / runtime** | Host process, service lifecycle, operational commands | Replacing the contracts of the layers above | [ARC CLI](/en/docs/arc-cli/) |

![ARC product layers: ARC hosts AFS, Blocklet, and identity; AFS projects through AFS UI into AUP and Web Device](https://raw.githubusercontent.com/ArcBlock/loop-agent-assets/main/arcblock-site/docs-architecture-20260810/architecture-product-layers-20260811064544.svg)

*ARC hosts the runtime. AFS, Blocklet, and identity are primary developer surfaces. AFS UI is the lens that connects AFS resources to AUP and Web Device.*

## Decision table

| You are trying to… | Correct layer | Common mistake |
| --- | --- | --- |
| List or write a path, mount a provider | AFS | Assuming every mount supports search or exec |
| Describe buttons, forms, and state for an interactive app | AUP | Copying Web components into the AUP semantic contract |
| Publish pages, posts, or a marketing site | Web Device | Treating layout AUP as a full interactive session |
| Ship an installable unit with config and surfaces | Blocklet | Calling a single `.aup` file “the Blocklet” |
| Know who signed in and which user data they may see | Identity | Trusting a path segment that looks like a DID |
| Understand how UI and AFS fit without picking a target yet | AFS UI (this board) | Inventing a third authoring product |
| Run `arc service` / `arc blocklet` / `arc afs` | ARC CLI | Treating CLI help as the only product contract |

## Composition, not collapse

A Blocklet often **uses** AFS providers, AUP apps, and Web Device sites. That composition does not merge their contracts:

- Web Device remains an AFS provider (`@aigne/afs-web-device`) that renders site trees.
- Interactive AUP runs through the UI runtime (`@aigne/afs-ui`) and AUP types (`@aigne/afs-aup`).
- DID Space (`@aigne/afs-did-space`) is a storage provider; session views project caller data into AFS paths.

When two layers disagree in documentation, keep the claim on the layer that owns the behaviour, and link the other for context. Do not “average” them into one API.

## Where evidence lives

| Claim type | Prefer |
| --- | --- |
| Present-tense operation or field | Sibling board + current source/tests for that layer |
| “How layers fit” | This architecture board |
| Old product name | [Product lineage](../product-lineage/) |

Classification rules: [Contracts and evidence](../contracts-and-evidence/).

---

## architecture/product-layers/visuals

URL: https://www.arcblock.io/en/docs/architecture/product-layers/visuals/

---

## Product lineage and boundaries

URL: https://www.arcblock.io/en/docs/architecture/product-lineage/

Older ArcBlock material still uses product names that appear next to ARC. Use this index to find the **current developer entry** and the **hard non-promises**. Status values:

| Status | Meaning |
| --- | --- |
| `current` | Actively documented ARC surface or product dependency you can open today |
| `reference implementation` | Example app or pattern used to prove a contract; not a full platform product |
| `external dependency` | Capability consumed from another package or service, not re-documented here as a full ARC product board |
| `historical only` | Name retained for archaeology; not a supported upgrade path |
| `unresolved` | Evidence incomplete; do not invent a successor product |

## Mapping table

| Old name / alias | Why readers still see it | Current ARC home | Developer entry | What is **not** promised | Status |
| --- | --- | --- | --- | --- | --- |
| **Discuss Kit** | Standalone discussion Blocklet; site product record `superseded` / `mergedInto: arc` | Replicated discussion data as a **reference Blocklet** (`blocklets/discuss-kit`); parts of comments/collections surfaces in Web Device / UI runtime | [Blocklets · Discuss Kit lineage](/en/docs/blocklets/discuss-kit-lineage/) · [Blocklets](/en/docs/blocklets/) | Full former board/blog/wiki/bookmark/message platform feature set | `reference implementation` |
| **DID Connect** | Sign-in and credential presentation in older apps and docs | Runtime identity and membership integration (for example `@arcblock/did-connect-service` used by members provider); broader DID Connect docs remain for the protocol/SDK family | [Identity · DID Connect](/en/docs/identity-data-spaces/did-connect/) · [Identity overview](/en/docs/identity-data-spaces/) · existing DID Connect docs boards | That the former admin or user-centre UI is a stable ARC product face | `external dependency` (service/SDK) + `current` (caller/session integration on Identity board) |
| **DID Spaces / DID Space** | Personal or app data space branding and docs | **DID Space** as current AFS provider (`@aigne/afs-did-space`) and user-facing space tooling (`arc space`, related Blocklets) | [Identity · DID Space](/en/docs/identity-data-spaces/did-space/) · [Identity overview](/en/docs/identity-data-spaces/) | That every remote lifecycle, trust, and multi-instance path is one finished public contract | `current` (local/provider contract as documented on Identity board) with **experimental/gap** for unproven remote lifecycle |
| **Data Space** | Marketing and conceptual language around “data belonging to a DID” | **Documentation term** for caller data context and session views—not a second backend product | [Identity · Data Space term](/en/docs/identity-data-spaces/data-space-term/) | A separate public SDK, provider package, or lifecycle API named “Data Space” | `current` as terminology only |
| **Media Kit** | Standalone media Blocklet; site product `superseded` / `mergedInto: arc` | Partial media publishing, rendering, delivery, and upload-related pieces around Web Device / DID Space / CDN helpers—not a single named successor product | Task-specific Web Device / Identity pages as they document media paths; do **not** assume a Media Kit board | Full former uploader, plugin suite, remote-source pipeline, asset-library UI, or migration contract | `unresolved` successor product · partial capabilities only |
| **Image Bin** | Older asset/image library naming tied to media workflows | No verified full ARC equivalent product board in this documentation set | None as a first-class ARC developer board | That Image Bin features are fully present under another name | `historical only` / `unresolved` |
| **Blocklet Server** (and related Server-era tooling) | Long-running packaging and hosting vocabulary | ARC **Blocklet** package/instance model and CLI (`arc blocklet`) | [Blocklets](/en/docs/blocklets/) · [ARC CLI blocklet](/en/docs/arc-cli/) | That every Server-era behaviour, API, or admin screen remains | `lineage` → current Blocklet contract is narrower and re-specified |
| **AFS UI** (as if it were a product SKU) | Draft architecture documents use the phrase | Architecture lens on this board; authoring via AUP + Web Device | [AFS UI](../afs-ui/) · [AUP](/en/docs/aup/) · [Web Device](/en/docs/web-device/) | A third public authoring product or guaranteed third-party device SDK | `architecture` (not a separate product board) |

## How to use a row

1. Read **Why readers still see it** so you do not delete the name from mental models that external material still uses.
2. Open **Developer entry** for operational work.
3. Read **What is not promised** before writing migration, sales, or “feature parity” language.
4. If status is `unresolved` or `historical only`, do not invent a replacement name in public docs.

## Evidence notes (not a contract)

| Name | Primary evidence used for this table |
| --- | --- |
| Discuss Kit | Site `content/products/discuss-kit` (`superseded`, `mergedInto: arc`); ARC `blocklets/discuss-kit` README as replicated collection reference; Web Device comments-surface code |
| DID Connect | `@arcblock/did-connect-service` dependency in `providers/basic/members`; Identity board structure |
| DID Space | `@aigne/afs-did-space` provider package; Identity board DID Space pages |
| Data Space | Identity board terminology pages; no separate provider package named data-space |
| Media Kit | Site product `superseded`; no complete Media Kit migration evidence in ARC tree for this board |
| Image Bin | Name appears in historical material; no verified full successor board |

Update a row only after re-checking current code. A merged PR that once added a path is not enough if the tree no longer contains it.

Related: [Contracts and evidence](../contracts-and-evidence/) · [Reference](../reference/)

---

## Reference

URL: https://www.arcblock.io/en/docs/architecture/reference/

This page is an **index**, not a second copy of sibling APIs. Follow the link for fields, commands, and versioned behaviour.

## Sibling boards

| Board | What it owns | Entry |
| --- | --- | --- |
| AFS | Paths, operations, providers, catalog boundaries | [/en/docs/afs/](/en/docs/afs/) |
| AUP | Declarative UI tree, DSL, sessions, degradation | [/en/docs/aup/](/en/docs/aup/) |
| Web Device | Static sites, content objects, components, HTML render | [/en/docs/web-device/](/en/docs/web-device/) |
| Blocklets | Package, instance, local run, publish boundary | [/en/docs/blocklets/](/en/docs/blocklets/) |
| Identity & Data Spaces | Caller, DID Space, session views, boundaries | [/en/docs/identity-data-spaces/](/en/docs/identity-data-spaces/) |
| ARC CLI | Command groups and operational surface | [/en/docs/arc-cli/](/en/docs/arc-cli/) |
| Architecture (this board) | System map, AFS UI lens, lineage, evidence rules | [Overview](../overview/) |

## Term index

| Term | One-line meaning | Start here |
| --- | --- | --- |
| AFS | Path-addressable resource and capability layer | [ARC and AFS](../arc-and-afs/) · [AFS](/en/docs/afs/) |
| Provider | Module mounted at a path that implements declared operations | [AFS providers](/en/docs/afs/providers/) |
| AFS UI | Architecture lens projecting AFS into UI devices | [AFS UI](../afs-ui/) |
| AUP | Declarative semantic UI contract | [AUP overview](/en/docs/aup/) |
| Web Device | AFS provider for static website trees | [Web Device overview](/en/docs/web-device/) |
| Blocklet | Package and instance unit for applications | [Blocklets overview](/en/docs/blocklets/) |
| Package vs instance | Immutable reusable unit vs configured deployment | [Package and instance](/en/docs/blocklets/package-and-instance/) |
| DID | Identifier in verified caller context | [Identity overview](/en/docs/identity-data-spaces/) |
| DID Space | DID-scoped persistent storage provider | [DID Space](/en/docs/identity-data-spaces/did-space/) |
| Data Space | Documentation term for caller data context | [Data Space term](/en/docs/identity-data-spaces/data-space-term/) |
| Session view | Runtime projection of caller/instance data into AFS paths | [Identity session data](/en/docs/identity-data-spaces/session-data/) |
| Current contract | Present-tense claim backed by code + test/run | [Contracts and evidence](../contracts-and-evidence/) |
| Lineage | Historical name mapping without feature parity | [Product lineage](../product-lineage/) |
| ARC | Runtime and CLI shell hosting the layers above | [Overview](../overview/) · [ARC CLI](/en/docs/arc-cli/) |

## Package names (source tree)

Useful when matching docs to repositories. Versions below are from ARC source snapshot `44fbd616f` (package.json `2.0.0-beta.31`); installed CLI used for orientation: `2.0.0-beta.28`.

| Package | Role |
| --- | --- |
| `@aigne/afs` | AFS core |
| `@aigne/afs-aup` | AUP types and pure helpers |
| `@aigne/afs-ui` | Interactive UI device runtime |
| `@aigne/afs-web-device` | Web Device provider |
| `@aigne/afs-did-space` | DID Space provider |

## Architecture pages on this board

| Page | Responsibility |
| --- | --- |
| [Overview](../overview/) | System map and task routing |
| [Mental model](../mental-model/) | Vocabulary and reading order |
| [ARC and AFS](../arc-and-afs/) | Runtime vs filesystem boundary |
| [Product layers](../product-layers/) | Ownership table and layer diagram |
| [AFS UI](../afs-ui/) | UI projection lens and code evidence |
| [Contracts and evidence](../contracts-and-evidence/) | Status vocabulary |
| [Product lineage](../product-lineage/) | Old name mapping table |

If a sibling link 404s on a partial deploy, open the board root and use its nav. Do not invent alternate URLs.

---

## AUP

URL: https://www.arcblock.io/en/docs/aup/

---

## Author with DSL

URL: https://www.arcblock.io/en/docs/aup/author-with-dsl/

This section explains how to maintain DSL sources, organize an app/page/shell, express values and interaction, and generate JSON artifacts only when a compatibility consumer needs them. It does not teach hand-editing JSON as the default workflow.

## Read in this order

1. [DSL source model](../dsl-source-model/) before choosing DSL-first or JSON-first inputs.
2. [App, page, and shell](../dsl-app-page-shell/) for the app-level declaration surface.
3. [Nodes, values, and sugar](../dsl-nodes-values-sugar/) and [events, navigation, and visibility](../dsl-events-navigation-visibility/) for page source.
4. [Components, loops, and i18n](../dsl-components-loops-i18n/) for compile-time reuse and locale content.
5. [Generate, lint, and migrate](../dsl-generate-lint-migrate/) to maintain artifacts without confusing formatting with validation.

---

## Caller identity and safety

URL: https://www.arcblock.io/en/docs/aup/caller-identity-safety/

An AUP tree is not an access-control list. Hiding a node, naming a data path, or rendering a button never grants a caller the right to read, write, execute, or bridge that resource.

## Session substitutions have narrow semantics

`$session.*` has two distinct roles:

- A presentation condition can read session facts, such as `$session.authenticated` or `$session.role == owner`.
- Path substitution occurs only in `src`, `bind`, and `propBind`, not in general props, events, or execution arguments.

For example:

```aup
input display-name
  bind="/user/persons/$session.did/profile/display-name"
```

The server performs per-session path substitution from own fields; missing values remain unresolved tokens rather than inventing an identity. The client cannot assert its own caller identity by sending a UI message.

## The renderer is not the authorization authority

AFS/provider/runtime policy decides whether a resolved read, write, or `exec` action is allowed. UI visibility and navigation are only presentation. Likewise, validation that rejects `javascript:` or `..` is useful input safety; it does not replace service-side permission policy.

Frames, bridges, remote surfaces, and write-capable flows each need their own trust, origin, session, and scope review. A same-looking button on two targets can still be backed by different authorization contexts.

For embedding rules, see [Frames, bridges, and embedded surfaces](../frames-bridges-embedded-surfaces/). For data-binding semantics, see [Events, state, and bindings](../events-state-bindings/).

---

## AUP capability tour

URL: https://www.arcblock.io/en/docs/aup/capability-tour-slides/

## AUP is a semantic tree

AUP is not a CSS framework and not a page template language. You author a **semantic tree** of named node types. A target device reports what it can render; the runtime degrades or refuses the rest.

This deck is a **web slideshow** tour: one Markdown record, `slides: true`, hosted on Web Device docs. It shows what a **deck path** can host—not ordinary article document caps.

<!--
Teaching point: capability is reported by the device. Deck uses DEVICE_CAPS_DECK so demos stay honest about slideshow product truth.
-->

---

## Document caps vs deck caps

| Cap profile | What it means on this site |
| --- | --- |
| **document** | Ordinary articles: native subset, partial time, forced degradation for interactive types |
| **deck** (`DEVICE_CAPS_DECK`) | This slideshow: document natives **plus** chart/map/calendar/overlay/canvas/explorer/surface/chat shells |
| **web-full** | Full interactive Web (Showcase / apps): session, write paths, multi-window |

**This deck** uses `DEVICE_CAPS_DECK` (arc#4005 / #4011 / #4012). Human lock (#4006): only **rtc** and **camera-preview** are hard excludes; other surfaces ship as **readonly + authored data** demos. Ordinary articles still degrade chart→table and map→media.

<!--
Needs ARC with #4011+#4013+#4012. Older ARC may degrade or empty-shell some slides.
-->

---

# Basic interface

---

## `view` — native

Portable container. On document, tabs and steps are static UI chrome (panel switch only—no session, no `exec`).

::::view{id="aup-tour-view-tabs" mode="tabs" label="Package manager"}
:::view{label="pnpm"}
Install with `pnpm install`.
:::

:::view{label="npm"}
Install with `npm install`.
:::
::::

<!--
Outer fence needs more colons than nested containers. view ≠ layout.aup site section.
-->

---

## `text` — native

Ordinary Markdown body is the main `text` path. Callouts become text-admonition presentation on document.

> [!NOTE] Portable copy
> This callout is document content. It does not run actions or write AFS data.

<!--
text is the default readable surface. Do not smuggle layout chrome into text props.
-->

---

## `media` — native

Semantic media node (image path here). Same-site / whitelist rules for frames are separate.

::media{id="aup-tour-media-img" type="image" src="https://media.arcblock.io/lib/2f/2f757138def2b3fc.w1600.webp" alt="Illustrative documentation asset" caption="Document-target media illustration"}

<!--
Missing src → placeholder. Inline ![alt](src) is a different MD structure path (see later slide).
-->

---

## `input` — native

Unbound form control on document. Typing changes only the browser control—no bind, session, or AFS write.

::input{id="aup-tour-input-name" type="text" label="Name" placeholder="Local browser only" value="Ada"}

::input{id="aup-tour-input-ack" type="checkbox" label="I understand this stays local"}

<!--
Always give an explicit id. Multi-field live submit forms are out of contract for public docs.
-->

---

## `action` — native

Navigation-only on document. No `exec`, no destructive confirm from a static sample.

::action{label="Open live example contract" href="/en/docs/aup/live-example-contract/" variant="primary"}

::action{label="Label only — not a navigation target" variant="secondary"}

<!--
Unsafe href schemes are rejected. Missing href → non-link chrome.
-->

---

## `overlay` — deck open shell

Open dialog chrome on this deck (readonly). Dismiss bus / session confirm stay interactive.

:::overlay{id="aup-tour-overlay-dialog" mode="dialog" title="Confirm layout" message="This shell is open by default so the slide shows real chrome—not a screenshot." open="true"}
::action{label="Understood" variant="primary"}
:::

| Fact | Boundary |
| --- | --- |
| Deck path | **partial** open shell (arc#4012) |
| Ordinary document | still **unsupported** → text |
| Session dismiss / confirm bus | interactive only |

<!--
Demo is visual proof of the type on deck—not a product modal with live events.
-->

---

# Structure and time

---

## `table` — native (GFM path)

GFM tables render on the document target. Prefer an author-written table when the page needs data.

| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |

<!--
Do not confuse an AUP table empty-state (“No data”) with a chart. Ordinary articles still degrade chart→table; this deck keeps a live shell (next slides).
-->

---

## `time` — partial

Document reports **partial**. Display mode is a static snapshot, not a live clock.

::time{id="aup-tour-time-display" mode="display" value="2026-02-21T14:30:00Z"}

No continuous client ticker on this path. Clock/countdown product claims belong to interactive targets after re-verification.

<!--
partial ≠ broken. State the limit in the same breath as the sample.
-->

---

## `chart` — quarterly bar

::chart{id="aup-tour-chart-bar" variant="bar" labels='["Q1","Q2","Q3","Q4"]' data='[89,78,81,61]' label="2024" height="360px" title="Quarterly"}

<!--
Title + chart only. Deck partial shell (Chart.js). Ordinary articles still chart→table.
-->

---

## `map` — Paris

::map{id="aup-tour-map-paris" tileStyle="carto-voyager" center='[48.8566,2.3522]' zoom="12" height="380px" markers='[{"lat":48.8584,"lng":2.2945,"label":"Eiffel Tower"},{"lat":48.8606,"lng":2.3376,"label":"Louvre"},{"lat":48.853,"lng":2.3499,"label":"Notre-Dame"}]'}

<!--
Visual-first: title + map only (no boundary table — keeps the 720 frame). Deck shell + Leaflet enhance (#4011/#4013). Ordinary articles still degrade.
-->

---

## `calendar` — August 2026

::calendar{id="aup-tour-calendar" year="2026" month="8" title="August 2026" events='[{"date":"2026-08-14","label":"Tour ship","intent":"success"},{"date":"2026-08-21","label":"Review","intent":"info"}]'}

<!--
Title + month grid only. Readonly events; no write path.
-->

---

# Interactive surface

---

## `chat` — deck readonly + data

Authored messages only. Input bar is disabled—no session bus, no write (human #4006).

::chat{id="aup-tour-chat" title="Support sample" messages='[{"role":"user","text":"Can slides host chat chrome?"},{"role":"assistant","text":"Yes — readonly shells with sample data. Live session stays on interactive targets."}]'}

| Fact | Boundary |
| --- | --- |
| Deck path | **partial** readonly shell |
| Write / session / agent runtime | **not** on this tour |
| Ordinary document | still unsupported |

<!--
Readonly data demo proves type hosting—not a live support product.
-->

---

## `rtc` — excluded (human #4006)

| Fact | Boundary |
| --- | --- |
| Deck path | **unsupported** (hard exclude) |
| Shared chain | unsupported → annotated text |
| What this deck does | **No RTC / camera-preview demo** |

Media permissions and peer sessions are not slideshow product demos. `camera-preview` widget is excluded for the same reason.

<!--
Only hard excludes after Robert APPROVE on #4006: rtc + camera-preview.
-->

---

## `explorer` — deck static tree

Authored items only—not path-backed AFS browse.

::explorer{id="aup-tour-explorer" title="Workspace" root="/docs/aup" items='[{"name":"overview","kind":"dir"},{"name":"capability-tour-slides","kind":"dir"},{"name":"README.md","kind":"file","path":"/docs/aup/README.md"}]'}

| Fact | Boundary |
| --- | --- |
| Deck path | **partial** static shell |
| Path-backed live AFS | interactive / session only |
| Pair with afs-list | static children only on docs |

<!--
Distilled from explorer.aup list chrome—not WM multi-panel.
-->

---

## `editor` — native (experimental)

Document registers an editor renderer as a local textarea. Typing stays in the browser—no IDE, no AFS write-back.

::editor{id="aup-tour-editor" language="json" label="Example snippet" value="{ \"ok\": true }"}

Markdown attribute strings are not guaranteed to match AUP JSON booleans (`readOnly`). Prefer JSON/DSL when the prop must be strict.

<!--
experimental status stays on the eyebrow of the unit page; this deck only shows the local control.
-->

---

## `canvas` — deck drawing shell

Host + canvas; progressive enhance enables local pen (no AFS persistence).

::canvas{id="aup-tour-canvas" width="560" height="220" label="Sketch pad" background="#f8fafc"}

| Fact | Boundary |
| --- | --- |
| Deck path | **partial** shell + local pen enhance |
| Ordinary document | **unsupported** → media → text |
| Persist strokes / multi-user | interactive only |

<!--
WebGL hero and photo-story remain separate widgets—not this primitive.
-->

---

## `surface` — deck host shell

Labeled host region + children. Taxonomy: primitive `surface` ≠ `wm-surface` ≠ layout surface dirs.

:::surface{id="aup-tour-surface" title="Resource panel" variant="default"}
Static surface body — authored children only. No session view selector on this deck.
:::

| Fact | Boundary |
| --- | --- |
| Deck path | **partial** host shell |
| Session expand / path browse | interactive only |
| Confusion | do not rename site chrome as this primitive |

<!--
Taxonomy discipline stays: primitive ≠ widget ≠ layout-component.
-->

---

## `afs-list` — document (static children)

Document can render list chrome. Path-backed live AFS data is **not** closed on public docs—use static children only.

:::afs-list{id="aup-tour-afs-list-static" layout="list" itemStyle="row"}
Static row one — authored as document children, not fetched.

Static row two — still not an AFS path proof.
:::

Empty / loading chrome without children is documented on the unit page; this tour only shows the static-children path.

<!--
No arbitrary AFS path in docs. Fixture origins are a separate contract.
-->

---

# Document-hostable widgets

Widgets are **not** the 18 cross-device primitives. Deck SSR now registers focused shells for many of them (arc#4012 / #4008 / #4009). Array/object props as **JSON strings** are coerced (same as chart/map). Nested portal chrome for app-header still needs object props from DSL.

<!--
Do not pass actions='[...]' to app-header from MD — still expects real arrays and can throw.
-->

---

## `app-header` — document shell

Document registers `app-header` and emits the same `.aup-app-header*` chrome classes as the interactive path. Nested `brand` / `nav` / `actions` need **object** props (Showcase / AUP DSL). Markdown directive attributes are always strings, so this slide shows the registered shell only—not a full portal header.

::app-header{id="aup-tour-app-header" variant="compact"}

| Fact | Boundary |
| --- | --- |
| Document RENDERERS | **yes** (static) |
| MD live brand/nav/actions | **not** — string attrs are not JSON-coerced |
| Session / search / microBar | interactive / AFS only |

Unit page: [app-header](/en/docs/aup/widgets/app-header/). Showcase: `prim-app-header`.

<!--
Do not pass actions='[...]' from MD — renderAppHeader expects an array and throws a scoped aup-render-error.
-->

---

## `app-footer` — document shell

Document renders a static footer. The legacy top-level `copyright` string is MD-safe and produces the bottom bar. Multi-column `brand` / `columns` / `social` need object props (same MD string-attr limit as header).

::app-footer{id="aup-tour-app-footer" copyright="© 2026 ArcBlock documentation demo — static document shell"}

Unit page: [app-footer](/en/docs/aup/widgets/app-footer/). Showcase: `prim-app-footer`.

<!--
copyright alone is enough for a docs-safe live sample. Do not invent financial or legal copy beyond a demo label.
-->

---

## `ticker` — document static

Document RENDERERS force `data-mode="static"`: children separated by bullets—not a continuous scroll ticker.

:::ticker{id="aup-tour-ticker"}
Document surface

Static children

No live scroll on this path
:::

Interactive scroll/flip modes stay on web-full. Unit page: [ticker](/en/docs/aup/widgets/ticker/).

<!--
Children are text nodes. Intent/speed props are interactive concerns; document stays static.
-->

---

## `broadcast` — document static shell

Document RENDERERS treat `broadcast` as a view-like container: children render, live channel / director wiring does not.

:::broadcast{id="aup-tour-broadcast"}
Static broadcast shell — authored children only. No shared channel, no AI director, no live viewer count on document.
:::

Role expansion (live-badge, lower-third, …) is interactive. Unit page: [broadcast](/en/docs/aup/widgets/broadcast/).

<!--
Honest static shell, not a live show claim.
-->

---

## `deck` — this tour is the host

This record is already a deck: front matter `slides: true` + `layout: slides` builds the player. Document reports `deck` as **partial** host chrome—not a nested product deck inside each slide.

| Fact | Boundary |
| --- | --- |
| Host | This capability-tour record |
| Authoring | `##` slides, `---` dividers, optional media-fill bodies |
| Nested `::deck` | Not required for this tour |

You are inside the demo. Unit page: [deck](/en/docs/aup/widgets/deck/). Markdown slides guide: [markdown-slides](/en/docs/web-device/markdown-slides/).

<!--
Meta slide — do not embed a second deck widget for its own sake.
-->

---

## `frame` — document partial

Sandboxed iframe via AUP `type: "frame"`. Same trust boundary as embeds: http(s) or allow-listed paths; unknown/unsafe src becomes an error or link fallback.

::frame{id="aup-tour-frame" src="https://www.youtube.com/embed/jNQXAC9IVRw" title="Me at the zoo (frame taxonomy)" aspectRatio="16 / 9"}

`::embed{url=…}` is the Markdown authoring path that often compiles toward frame-shaped nodes. This slide names the **widget type** explicitly. Document capability is **partial**. Unit page: [frame](/en/docs/aup/widgets/frame/).

<!--
Taxonomy: frame widget ≠ privileged iframe API. Keep sandbox defaults.
-->

---

## `key-value-list` — deck shell

::key-value-list{id="aup-tour-kv" title="Release" items='[{"label":"Status","value":"Stable"},{"label":"Channel","value":"docs"},{"label":"Caps","value":"DEVICE_CAPS_DECK"}]'}

Unit page: [key-value-list](/en/docs/aup/widgets/key-value-list/). Showcase: `prim-key-value-list`.

<!--
items JSON string coerced on SSR. Interactive formatters (did/bignum) stay richer on web-full.
-->

---

## `breadcrumb` — deck shell

::breadcrumb{id="aup-tour-breadcrumb" items='[{"label":"Docs","href":"/en/docs/"},{"label":"AUP","href":"/en/docs/aup/"},{"label":"Capability tour"}]'}

AUP widget—not the site layout `page-breadcrumb` chrome. Unit page: [breadcrumb](/en/docs/aup/widgets/breadcrumb/).

<!--
Taxonomy: site chrome ≠ this widget type.
-->

---

## `chip` — deck shell

::chip{id="aup-tour-chip-stable" label="Stable" color="success" count="3"}

::chip{id="aup-tour-chip-info" label="Deck shell" color="info"}

::chip{id="aup-tour-chip-warn" label="Readonly" color="warning"}

Unit page: [chip](/en/docs/aup/widgets/chip/). Dismiss events stay interactive.

<!--
String props are MD-safe; count coerced from string.
-->

---

## `pagination` — deck static chrome

::pagination{id="aup-tour-pagination" page="2" pageSize="10" total="47"}

Buttons disabled—no page events on this tour. Unit page: [pagination](/en/docs/aup/widgets/pagination/).

<!--
Static status only; list pagination wiring is interactive.
-->

---

## `tooltip` — deck shell

:::tooltip{id="aup-tour-tooltip" content="Native title + visible hint for deck proof" placement="top"}
Hover target (and visible tip below)
:::

Unit page: [tooltip](/en/docs/aup/widgets/tooltip/).

<!--
Deck shows content openly; hover-only bubbles remain interactive concern.
-->

---

## `entity-overview` — deck shell

::entity-overview{id="aup-tour-entity" title="Sample entity" cards='[{"title":"Identity","items":[{"label":"Name","value":"Tour demo"},{"label":"Kind","value":"docs"}]},{"title":"Caps","items":[{"label":"Path","value":"deck"},{"label":"Write","value":"no"}]}]'}

Unit page: [entity-overview](/en/docs/aup/widgets/entity-overview/).

<!--
cards JSON string. Full tx-detail compositions stay on Showcase.
-->

---

## `terminal` — deck readonly transcript

::terminal{id="aup-tour-terminal" title="arc CLI" lines='["$ arc --version","2.0.0-beta.35","$ arc blocklet check blocklets/arcblock","ok"]'}

Not a live PTY / xterm WebSocket. Unit page: [terminal](/en/docs/aup/widgets/terminal/).

<!--
Authored lines only — endpoint sessions are interactive.
-->

---

## `moonphase` — deck shell

::moonphase{id="aup-tour-moon" date="2026-08-14"}

Pure math shell (no CDN). Unit page: [moonphase](/en/docs/aup/widgets/moonphase/).

<!--
date prop optional; defaults to today when omitted.
-->

---

## `globe` — world markers

::globe{id="aup-tour-globe" center='[20,0]' zoom="2" height="380px" markers='[{"lat":37.77,"lng":-122.42,"label":"SF"},{"lat":48.86,"lng":2.35,"label":"Paris"},{"lat":35.68,"lng":139.69,"label":"Tokyo"}]'}

<!--
Title + map shell only (Leaflet, not WebGL). Dark tiles by default.
-->

---

## `comments-surface` — deck readonly

::comments-surface{id="aup-tour-comments" title="Thread sample" comments='[{"author":"Ada","body":"Readonly comments prove the type hosts on deck.","at":"2026-08-14"},{"author":"Grace","body":"Write path and session stay off this tour.","at":"2026-08-14"}]'}

Human #4006: data demo OK; no write. Live article mount is a separate site toggle.

<!--
Not the article bottom comments component path—authored AUP node only.
-->

---

## `wm` — single-panel shell

:::wm{id="aup-tour-wm" title="Panel"}
Single-panel window chrome for deck geometry (1280×720). Not multi-window desktop.
:::

Human #4006: single-panel OK; full desktop geometry stays Showcase `wm-desktop.aup`.

<!--
wm-surface reuses the same single-panel shell on SSR.
-->

---

## `agent` — deck readonly (chat alias)

::agent{id="aup-tour-agent" title="Assistant sample" messages='[{"role":"user","text":"What can deck host?"},{"role":"assistant","text":"Readonly agent chrome with sample turns—no agent runtime on this tour."}]'}

Same shell as chat. No AFS write / agent loop.

<!--
Honest alias: type agent, data-mode readonly.
-->

---

## `wm-surface` — same single-panel shell

:::wm-surface{id="aup-tour-wm-surface" title="Surface panel"}
Same SSR as `wm`. Taxonomy: widget `wm-surface` ≠ primitive `surface`.
:::

<!--
Dedicated type slide so the matrix row is not only a footnote on wm.
-->

---

## `xeyes` — static gaze

::xeyes{id="aup-tour-xeyes" eyes="2" title="xeyes" size="md"}

Mouse tracking stays interactive. Deck hosts the chrome.

---

## `searchable-dropdown` — closed list

::searchable-dropdown{id="aup-tour-dropdown" placeholder="Pick a runtime" value="bun" options='[{"label":"Bun","value":"bun"},{"label":"Node","value":"node"},{"label":"Workers","value":"workers"}]'}

Filter / onChange stay interactive.

---

## `afs-stat` — label + value

::afs-stat{id="aup-tour-stat" label="Open PRs" value="12"}

---

## `afs-preview` — path + snippet

::afs-preview{id="aup-tour-preview" title="README" path="/docs/aup/README.md" preview="# AUP\nSemantic tree. Device reports caps."}

---

## `afs-dropzone` — dashed host

::afs-dropzone{id="aup-tour-dropzone" label="Drop into /inbox" target="/inbox"}

Ingest / grant PUT stay off this tour.

---

## `natal-chart` — planets table

::natal-chart{id="aup-tour-natal" variant="planets-table" data='{"planets":{"Sun":[45.2],"Moon":[120.5],"Mercury":[12]}}'}

Astrochart CDN stays on web-full.

---

## `finance-chart` — candle table

::finance-chart{id="aup-tour-finance" variant="candlestick" data='[{"time":"2026-08-12","open":10,"high":12,"low":9,"close":11},{"time":"2026-08-13","open":11,"high":13,"low":10,"close":12},{"time":"2026-08-14","open":12,"high":12.5,"low":11,"close":11.5}]'}

TradingView stays interactive.

---

## `skills` — authored names

::skills{id="aup-tour-skills" items='[{"name":"issue-audit"},{"name":"land"},{"name":"verification"}]'}

Live registry stays off this tour.

---

## `text-highlight` — marks

::text-highlight{id="aup-tour-highlight" content="Deck can host ==highlighted== phrases without an iframe."}

---

## `type-block` — authored DSL

::type-block{id="aup-tour-type-block" mode="shuffle" content="AUP is a semantic tree."}

Iframe type-block runtime stays interactive.

---

## `hero-widget` — title + desc

::hero-widget{id="aup-tour-hero" title="Capability tour" desc="Readonly host for the WebGL/iframe hero." style="cube"}

---

## `webgl-hero` — GPU placeholder

::webgl-hero{id="aup-tour-webgl" title="WebGL hero"}

---

## `progress-bar-3d` — CSS stand-in

::progress-bar-3d{id="aup-tour-progress" value="64" title="Load"}

---

## `photo-story` — stills

::photo-story{id="aup-tour-photos" title="Plates" items='[{"src":"plates/01-bridge.jpg","alt":"Bridge"},{"src":"plates/02-ridge.jpg","alt":"Ridge"}]'}

---

## `text-image-expand` — pair

::text-image-expand{id="aup-tour-tie" src="plates/03-harbor.jpg" text="Harbor plate. Expand/hover stays interactive."}

---

## `scroll-explainer` — stacked steps

::scroll-explainer{id="aup-tour-scroll" title="How a slide ships" items='[{"title":"Author Markdown"},{"title":"Deck SSR shell"},{"title":"Enhance where JS exists"}]'}

---

## `block-revealer` — already open

:::block-revealer{id="aup-tour-revealer" title="Revealed"}
Enter/scroll reveal stays interactive. This slide starts open.
:::

---

## `post-editor` — readonly

::post-editor{id="aup-tour-post" title="Draft" value="Readonly chrome. Publish path stays off this tour."}

---

## `share-panel` — URL chrome

::share-panel{id="aup-tour-share" title="Share" url="https://new.arcblock.io/en/docs/aup/capability-tour-slides/" text="AUP capability tour"}

Native share sheet / QR stay interactive.

---

## `provider-card` — catalog chrome

::provider-card{id="aup-tour-provider" name="DID Space" description="Deployment storage. Card chrome only on this deck."}

---

## `connection-gate` — status

::connection-gate{id="aup-tour-gate" title="Connect" status="disconnected"}

Auth/connect stay off the slideshow.

---

## `blocklet-embed` — address only

::blocklet-embed{id="aup-tour-embed" title="Embedded blocklet" src="https://new.arcblock.io/"}

Nested live session stays off this tour.

---

## `auto-surface` — host

:::auto-surface{id="aup-tour-auto-surface" title="Auto surface"}
Fixture chrome. Session expand stays interactive.
:::

---

## `auto-fire` — no fire

::auto-fire{id="aup-tour-auto-fire" title="auto-fire" exec="/dev/agent/.actions/run" dedupKey="tour"}

Would exec on mount. Deck: no fire.

---

## `url-default` — no navigation

::url-default{id="aup-tour-url-default" title="url-default" match="/app/today" redirect="/app/today/2026-08-14"}

Canonicalize-on-mount stays off this tour.

---

# Markdown surface

---

## Admonition (GFM callout)

Same path as `text` admonition—shown again as an authoring surface you type in Markdown.

> [!TIP] Prefer same-line titles
> A bare marker uses locale defaults; an explicit title on the marker line always wins.

> [!WARNING] Unknown markers
> `[!FIXME]` stays an ordinary blockquote, not callout chrome.

<!--
Bare markers localize (NOTE→说明 on zh). Unit page: web-device/markdown/gfm-admonition.
-->

---

## Steps (`::::steps`)

Tutorial chrome lands on document `view` rendering. Outer fence must wrap each `:::step`.

::::steps
:::step{title="Name the target"}
Document vs web-full first—then pick primitives the target reports.
:::

:::step{title="Demo or label"}
Native → live MD sample. Unsupported → one honest “not on document” slide.
:::
::::

<!--
:::step outside ::::steps has no full steps contract.
-->

---

## YouTube partial

Prose keeps the embed partial — normal deck padding, no `data-media-fill`. Supported providers render as a sandboxed frame; unrecognized URLs stay ordinary links.

::embed{url="https://youtu.be/jNQXAC9IVRw"}

This is the `frame` / embed path—not a general privileged iframe API.

<!--
Same-site deck embeds need framing CSP overrides; external YouTube is the whitelist path shown here.
-->

---

## GFM table (MD structure)

Author tables in ordinary Markdown when the document needs data. Live chart on **this deck** is a separate experimental node (generic directive)—not a general MD chart contract for all docs. Do not smuggle a chart through a GFM table.

| Cap | document article | this deck (`DEVICE_CAPS_DECK`) | web-full |
| --- | --- | --- | --- |
| `table` | native | native | webview |
| `chart` | unsupported → table/text | partial shell (Chart.js) | chart |
| `map` | unsupported → media/text | partial shell (Leaflet) | map |

<!--
GFM path ≠ every AUP table prop. Empty AUP table chrome is not a chart.
-->

---

## Image (Markdown structure)

Inline images are a structure path distinct from `::media`, but both are document-reachable media presentation.

![Illustrative documentation asset](https://media.arcblock.io/lib/2f/2f757138def2b3fc.w1600.webp)

Prefer `::media` when you need caption / type props as an AUP node; use `![alt](src)` for ordinary article figures.

<!--
Trust boundaries for remote assets still apply. Item-local media is preferred for product plates.
-->

---

## Link card + navigation action

Cards are Markdown directives that compose with `action` for navigation-only CTAs.

::link-card{title="Primitive taxonomy" description="18 cross-device primitives vs 42 Web-only widgets—keep the layers separate." icon="book" href="/en/docs/aup/primitive-support-matrix/"}

:::action-card{title="Device caps and degradation" description="Shared chains, document article policy, and deck chart/map shells." icon="layers"}
::action{label="Open degradation guide" href="/en/docs/aup/device-capabilities-degradation/" variant="primary"}
:::

<!--
Cards are MD surface, not new primitives. Keep href navigation-only on docs.
-->

---

# Deck media host

---

## One stage · many media modes

The deck is a **1280×720 media host**, not just prose cards.

| Mode | Feel |
| --- | --- |
| **Single plate** | One photo, edge-to-edge |
| **Mosaic** | Bento tiles fill the stage |
| **Grid** | Equal tiles fill the stage |
| **Stage / video** | 16:9 box, full-bleed loop, YouTube |
| **Tweet clamp** | Tall embed scrolls *inside* the stage |

Next pages: **one effect each** — visual first.

<!--
Intro only. Unit guides: media-gallery, media-gallery-immersive, markdown-embeds.
-->

---

## Single plate

::media{type="image" src="plates/01-bridge.jpg" alt="Bridge"}

<!--
Solo media + optional title → media-fill. One photo, full stage.
-->

---

## Mosaic

::gallery{folder="plates" layout="mosaic"}

<!--
Bento layout, full-bleed under media-fill. Hero tile + companions from plates/.
-->

---

## Grid

::gallery{folder="plates" layout="grid" cols="3"}

<!--
Equal tiles, full-bleed. cols=3 with three item-local plates.
-->

---

## Sized stage

::gallery{folder="plates" layout="stage" ratio="16:9" width="100%"}

<!--
Title + sized stage. ratio/width set the plate box; object-fit cover inside the frame.
-->

---

## Full-bleed · plates

::gallery{folder="video-plates" layout="stage"}

<!--
Solo media body → media-fill when ARC supports it. Cover+video immersion; still plates stay stills.
-->

---

## Full-bleed · YouTube

::embed{url="https://youtu.be/jNQXAC9IVRw"}

<!--
Solo youtube → media-fill. Tweet embeds stay out of media-fill by design.
-->

---

## Tweet clamp

::embed{url="https://x.com/arcblock_io/status/1955367769672950142"}

<!--
Title + tweet only. autoHeight clamps to remaining frame height and scrolls inside.
-->

---

## What this deck proves

- **One Markdown record** → player + reading transcript (`slides: true`)
- **Deck ≠ document article** — interactive shells on `DEVICE_CAPS_DECK`
- **Hard excludes** — only `rtc` and camera-preview (#4006)
- **Widgets** — one focused readonly+data slide each (arc#4009); web-full stays richer
- **Media host** — single · mosaic · grid · stage · full-bleed · tweet

<!--
Short close. Deep contracts live on unit pages, not this slide.
-->

---

## Keep exploring

::action{label="Primitive taxonomy" href="/en/docs/aup/primitive-support-matrix/" variant="primary"}

::action{label="Widgets hub" href="/en/docs/aup/widgets/" variant="secondary"}

::action{label="Device capabilities" href="/en/docs/aup/device-capabilities-degradation/" variant="secondary"}

::action{label="Markdown slides" href="/en/docs/web-device/markdown-slides/" variant="secondary"}

<!--
Navigation-only close — no long list overflow.
-->

---

## CLI diagnostics

URL: https://www.arcblock.io/en/docs/aup/cli-diagnostics-reference/

Run diagnostics from the smallest relevant directory. Each command has a distinct responsibility:

| Command | Primary boundary | Writes? | Failure means |
| --- | --- | --- | --- |
| `arc dsl format <dir> --check` | Formatting drift | No | Source would be reformatted |
| `arc dsl format <dir> --write` | Formatting normalization | Yes | The command could not safely format source |
| `arc dsl lint <dir>` | DSL static authoring issues | No | Error-level lint findings; warnings still need review |
| `arc dsl validate <dir>` | Parsed AUP/DSL semantics | No | A source/configuration contract is invalid |
| `arc dsl generate <dir> --check` | Compatibility-artifact drift | No | Materialized output would differ |
| `arc dsl generate <dir> --write` | Compatibility-artifact materialization | Yes | Output could not be generated safely |
| `arc blocklet check <dir>` | Combined source checks, Content Space when present, and selected profile structure | No | The declared blocklet shape is invalid for that check |

`dsl validate` scans AUP sources and Web layouts, including `pages/**/layout.aup`, object-level `content/**/layout.aup`, and `layouts/*.aup`. A passing scan does not inspect reader-facing visual hierarchy or all runtime target behavior.

## A simple acceptance order

```bash
arc dsl lint .
arc dsl validate .
arc blocklet check .
arc blocklet build .
arc blocklet run .
```

The first four establish increasingly broader static/build evidence. The final command is where a person or a clean acceptance agent opens the actual URL, checks the intended interaction, and records what was observed.

I18n migration is a separate narrow maintenance operation. It does not automatically translate content or reliably resolve every historical locale structure; review its diff rather than treating it as a generic upgrade command.

For source-generation detail, see [Generate, lint, and migrate](../dsl-generate-lint-migrate/). Web-site diagnostic categories remain target-specific and are outside this AUP reference.

---

## Core concepts

URL: https://www.arcblock.io/en/docs/aup/concepts/

This section follows runtime semantics: how an AUP tree expresses intent, how events and data change it, how a session delivers change to a renderer, and how missing device capability produces an explicit degradation or refusal.

## Read in this order

1. [Semantic tree](../semantic-tree/) for the node/data/child model.
2. [Events, state, and bindings](../events-state-bindings/) for declared interaction and data directions.
3. [Sessions, patches, and scenes](../sessions-patches-scenes/) for the interactive delivery path.
4. [Device capabilities and degradation](../device-capabilities-degradation/) for target-specific support rather than assumed portability.
5. [Caller identity and safety](../caller-identity-safety/) before treating a UI condition as authorization.

---

## Custom primitives and Web widgets

URL: https://www.arcblock.io/en/docs/aup/custom-primitives-web-widgets/

The current source has two different registries:

- **18 shared primitives** are the cross-device vocabulary used by capability negotiation.
- **42 Web-only widgets** are available in the Web runtime but are not a portability promise for other renderers.

Those counts describe the current checkout, not a permanent API-size guarantee. Before making a portability statement, use the primitive name and target support matrix rather than a widget’s visual resemblance to a native control.

## Add a custom name carefully

A blocklet can declare custom primitive names, or ARC can scan a Web Component manifest so DSL and structural validation accept those names. That extends the set of names an author may use. It does **not** create a renderer implementation on every device, add a degradation chain, or grant the component a privileged data/action capability.

Use a custom type when the target and its component contract are deliberately part of the product. Use a shared primitive when the intended meaning fits an existing portable contract. Do not call a Web-only widget a “primitive” merely because a page needs it.

## Keep three component concepts separate

| Concept | Owns | Does not imply |
| --- | --- | --- |
| AUP shared primitive | Portable semantic intent | Identical native presentation everywhere |
| Web widget | A Web runtime capability | Support by every device renderer |
| Web Device component | Reusable site HTML/CSS/interaction presentation | A new cross-device AUP primitive |

Unknown/custom types without a degradation chain pass through unchanged. They are not automatically converted to text. Plan a concrete target acceptance test before publishing a custom-type example.

See [Primitive taxonomy and evidence](../primitive-support-matrix/). The site-component layer belongs to the target's Web Device documentation, not to this portable-primitive reference.

---

## Device capabilities and degradation

URL: https://www.arcblock.io/en/docs/aup/device-capabilities-degradation/

Capability is neither guessed by a page author nor invented solely by a renderer. The client/device reports `DeviceCaps` during session handshake; AUP defines the capability shape and shared degradation chains; a concrete target presents from the reported capability.

`DeviceCaps` contains at least `platform`, `formFactor`, and a `primitives` map. Current primitive-capability values are:

| Value | Meaning |
| --- | --- |
| `native` | Fully implemented by a native renderer |
| `webview` | Fully implemented by a WebView renderer |
| `partial` | Renderable, with some unsupported props |
| `unsupported` | Cannot be directly rendered; try the shared degradation chain |

Display, input, and features can add device context. They are not authorization switches that let an author bypass target renderer support.

## Primitives with an explicit chain today

The shared degradation table in `2.0.0-beta.25` currently defines only these nine chains:

| Original type | Try in order |
| --- | --- |
| `globe` | `map` → `media` → `text` |
| `chart` | `table` → `text` |
| `map` | `media` → `text` |
| `editor` | `input` → `text` |
| `canvas` | `media` → `text` |
| `rtc` | `unsupported` |
| `calendar` | `table` → `text` |
| `time` | `text` |
| `overlay` | `text` |

The current algorithm treats `native`, `webview`, and `partial` as supported. If a chain reaches `unsupported` or finds no supported fallback, the tree receives an explicit text/unsupported marker. That is not a guarantee of an equivalent experience.

In particular, an unknown or custom type with no explicit degradation chain currently passes through unchanged rather than automatically becoming `text`. “There is degradation” therefore does not mean every node displays safely on every device.

## Chart on the static document target

`chart` is a cross-device primitive and can render with Chart.js on a full interactive Web surface. The **static document** target used for site docs is different:

| Fact | Current boundary |
| --- | --- |
| Document capability | `DEVICE_CAPS_DOCUMENT` does **not** list `chart`, so the value is `unsupported` |
| Shared chain | `chart` → `table` → `text` |
| What you get on document | A **table**, not a live chart. No Chart.js, canvas, or CDN load on this path |
| Data reshape | When the runtime includes the static reshape ([arc#3447](https://github.com/ArcBlock/arc/issues/3447) / [arc#3458](https://github.com/ArcBlock/arc/pull/3458)), inline `labels` / `datasets` (or single-series `data`) become real table columns and rows instead of an empty “No data” table |
| Version gate | The published version string `2.0.0-beta.28` is **before** that reshape commit. A CLI that only reports `2.0.0-beta.28` but is built from a later checkout may already reshape; a pure pre-reshape build may still show “No data”. Treat **live chart in docs** as unsupported until a release both declares document chart capability (or a dedicated document chart renderer) **and** is re-verified on this site |
| Markdown authoring | There is **no** defined `::chart` Markdown directive. Do not invent one in site content |
| Docs sample policy | Public docs must **not** present a live chart sample as a document capability. Prefer a plain Markdown or AUP `table` when the page needs data on the static target |

Measured on this documentation baseline with `arc --version` `2.0.0-beta.28` against a local Arc checkout that already contains the reshape: document still reports `chart` as `unsupported`, and `renderToHtml` of an inline bar chart yields a populated semantic `<table>` (including caption when `title` is set), not a chart graphic. Full evidence lives in the internal capability matrix (`docs/aup/capability-matrix.md` §0.6).

## Primitives versus Web widgets

There are currently 18 cross-device primitives and 42 Web-only widgets. A Web-only widget can have a renderer in the Web runtime but is not part of the cross-device `DeviceCaps.primitives` table. When you use `terminal`, `frame`, `breadcrumb`, or a similar widget, treat it as a Web-target capability and accept it in a browser rather than assuming a mobile/terminal fallback.


## Slides / deck path (web)

Ordinary **document** pages use `DEVICE_CAPS_DOCUMENT`. A tree that contains a **deck** (Markdown `slides: true`) may use `DEVICE_CAPS_DECK` so selected interactive types keep progressive-enhance / readonly shells instead of the article degradation chain: **chart**, **map**, **calendar**, **overlay**, **canvas**, **explorer**, **surface**, **chat**, and **globe** (map-shell variant) under arc#4005 / #4011 / #4012. That path is **not** a general product claim that every document page can host live Chart.js or Leaflet — ordinary articles still degrade those types.

Markdown directive attributes remain strings; deck demos that pass JSON arrays as attributes also need runtime coercion (arc#4013).

## Author acceptance order

1. Start with primitives the target you support explicitly reports.
2. When using one of the nine degradable types, write down the text/table/media fallback that remains acceptable.
3. Open the same tree on a real target and inspect presentation and any user-visible degradation marker.
4. Give a Web-only widget its own Web acceptance; do not copy that success into a cross-device conclusion.

For the full name taxonomy, read [Primitive taxonomy and evidence](/en/docs/aup/primitive-support-matrix/). For the transport boundary of interactive updates, read [Sessions, patches, and scenes](/en/docs/aup/sessions-patches-scenes/).

---

## App, page, and shell

URL: https://www.arcblock.io/en/docs/aup/dsl-app-page-shell/

An `app` declaration is the DSL’s authoring manifest. It can name a default page, tone/palette/mode/branding values, wrapper or shell, locales, page order, page discovery, overrides, and explicit pages. It compiles to AUP configuration; it is not a second runtime or a replacement for blocklet routing.

## A small app with an inline page

```aup
app "Nimbus" {
  default home
  locales [en, zh]

  shell {
    header {
      brand "Nimbus" -> href "/"
      action "Home" -> page home
    }
    footer "Nimbus"
  }

  page home "Home" {
    view {
      h1 "Welcome"
    }
  }
}
```

`shell` and an explicit `wrapper "wrapper.json"` cannot be combined. A shell generates wrapper material that places the page content slot between header and footer; it is a concise app frame, not a full application framework.

## Choose one page-discovery form deliberately

Pages may be defined inline, declared as an external tree/settings/scaffold, or discovered through a limited declaration such as `pages from "pages/*.aup"`. That latter form is resolved by ARC’s page parser; it is not a general glob language that works outside the runtime.

Inline pages compile to `pages/<name>.json`. Named page navigation is checked against declared pages, which makes a missing page a source problem rather than a browser surprise.

The currently built-in recipe names are narrow (`settings-shell`, `workspace-shell`, `marketing-site`, and `scaffold-app`). Do not document an arbitrary recipe name as available until the target runtime has accepted it.

Next, read [Nodes, values, and sugar](../dsl-nodes-values-sugar/) and [Events, navigation, and visibility](../dsl-events-navigation-visibility/).

---

## Components, loops, and i18n

URL: https://www.arcblock.io/en/docs/aup/dsl-components-loops-i18n/

These three features solve different problems. Do not use a compile-time loop where the product needs a live data list, or use a visibility condition where the product needs authorization.

## Components are compile-time composition

`component name(params...) {}` defines a page-level macro. `use name(...)` supports positional arguments, named arguments, and defaults. If the component has explicit IDs or internal event targets and is used more than once, `use ... as namespace` prefixes the expansion so each use remains distinct.

## Static `for` is not a data query

```aup
page index {
  component card(page, label="Open") {
    button "card-$page" $label primary -> page $page
  }

  view {
    for page in [home, settings] {
      use card($page)
    }
  }
}
```

`for x in [...] {}` expands a static array at compile time, with `$index`, `$first`, and `$last` in context. It is not a source-driven or live data list. Use `afs-list`/`repeat` for a runtime list whose data path and target behavior are explicitly supported.

`include`/`partial` require a runtime include resolver; `import` brings in component definitions only and does not create page nodes. Include/component expansion has a default depth boundary and reports cycles rather than trying to resolve them indefinitely.

## Localize source, not guesswork

After an app declares `locales [en, zh]`, a page can include one `i18n {}` block:

```aup
i18n {
  title { en "Welcome" zh "欢迎" }
}

h1 :title
```

The shorthand compiles to a translation key. A key can also reference existing source material. Missing inline translations can fall back during rendering, while strict locale checks can report coverage gaps; an unknown i18n key fails. This feature does not automatically translate copy or replace Web Device’s localized content-object system.

For data-driven list semantics, see [Events, state, and bindings](../events-state-bindings/). Site content objects and their locale files belong to the target's Web Device layer, not to this DSL page.

---

## Events, navigation, and visibility

URL: https://www.arcblock.io/en/docs/aup/dsl-events-navigation-visibility/

The DSL `->` is not a universal arrow. The current parser treats it as button/action click shorthand; other nodes need an explicit `on <event> -> ...`. First decide whether you need an in-page update, AUP page navigation, an AFS action, or browser URL navigation.

## Current action shapes

```aup
button open "Open" primary -> page details
button load "Load" primary -> set viewer src "/items/42"
button bump "Bump" primary -> set dial state {value: 7, dirty: true}
action -> exec "/.auth/logout"
action -> navigate "/.well-known/service/login"
```

Their boundaries are:

| DSL form | Compiled intent |
| --- | --- |
| `-> page details` | `set.page` on `_root`, switching to a named AUP page |
| `-> set <id> src ...` | Update the target node's data path |
| `-> set <id> state ...` | Update the target node's UI-local state |
| `-> exec ...` | Call an AFS action |
| `-> navigate ...` | Client-side browser-level URL navigation |

The old JSON `page: "details"` is a deprecated shortcut. New DSL should use `-> page details`, so generated output uses the current `_root` + `set.page` form.

When one update must set `src`, `props`, or multiple state fields together, use complete `events={...}`. One-line sugar does not cover every compound update. Make the event object explicit rather than combining competing click handlers for one logical action.

## Visibility is not yet one fully typed cross-device promise

The current DSL compiler accepts and emits a `visible` condition field, and Showcase DSL uses it. At the same time, the base `AUPNode` TypeScript interface does not list `visible` as a universal field. This documentation therefore treats it as a conditional field supported by the DSL/runtime at this target version, not a guarantee that every renderer has identical visibility semantics.

When using it:

1. Keep the core tree understandable without the visibility condition.
2. Accept both true and false conditions in the real target renderer.
3. Do not use hidden UI as authorization. A hidden control must not be the only barrier to an unauthorized AFS action.

For the full event/state/caller-scope boundary, read [Events, state, and bindings](/en/docs/aup/events-state-bindings/) and [Caller identity and safety](/en/docs/aup/caller-identity-safety/).

---

## Generate, lint, and migrate

URL: https://www.arcblock.io/en/docs/aup/dsl-generate-lint-migrate/

These commands answer different questions. A green command is useful evidence, but it is not a substitute for running the app in its intended renderer.

```bash
arc dsl format ./hello-aup --write
arc dsl lint ./hello-aup
arc dsl validate ./hello-aup
arc dsl generate ./hello-aup --check
```

## Read each result correctly

| Command | What it examines | Does it write? | What a green result does **not** prove |
| --- | --- | --- | --- |
| `format --write` | DSL source formatting | Yes | That the source is valid or runnable |
| `format --check` | Whether formatting would change files | No | That generated artifacts are current |
| `lint` | Authoring-level DSL problems | No | That the full app configuration and target renderer agree |
| `validate` | Parsed DSL/configuration semantics | No | That a browser/device presents the intended interaction |
| `generate --check` | Whether compatibility artifacts would change | No | That a source-first app must keep JSON on disk |
| `generate --write` | The same artifacts | Yes | That the generated app passed a runtime acceptance test |

On a fresh `minimal-app` scaffold in ARC `2.0.0-beta.25`, `format --write` rewrites three DSL sources. `format_changed` is the diagnostic from `format --check` when formatting would alter files; it is not the normal success result of the `--write` command.

## Treat generated JSON as compatibility work

DSL-first apps can expose compatible JSON virtually. A project only needs physical JSON when a specific compatibility consumer asks for materialized files. Use the following decision order:

1. Keep the `.aup` source authoritative.
2. Run `generate --check` in CI or before handing the project to a consumer that expects generated files.
3. Run `generate --write` only when that consumer actually needs the physical artifact, then review the diff like any other derived output.
4. Do not delete a JSON-first app merely to make it look DSL-first; JSON remains a supported source form.

For an AUP app configuration, a present `.aup/app.aup` takes precedence. If it is absent, ARC can read `.aup/app.json` as source. If the DSL file exists but is invalid, ARC fails rather than silently falling back to old JSON. That makes an invalid source visible instead of masking it with a stale artifact.

## Use a narrow migration loop

When converting an existing source, do not change source language, UI behavior, and deployment boundary in one step:

1. Format, lint, and validate the current source.
2. Generate in check mode and inspect what would differ.
3. Materialize only if a real downstream consumer needs it.
4. Run `arc blocklet check` for the declared profile, then run the blocklet locally and inspect the actual target.

See [CLI diagnostics](../cli-diagnostics-reference/) for the command boundary and [Sources, artifacts, and JSON compatibility](../source-artifact-json-compatibility/) for loader priority.

---

## DSL language reference

URL: https://www.arcblock.io/en/docs/aup/dsl-language-reference/

This is a working language map, not a promise that every name found in a historical Showcase is a released, portable API. The current parser/compiler and positive/negative tests are the source of truth for exact grammar.

## 1. App manifest

Use `app` to declare app-level defaults, pages/page discovery, ordering, overrides, wrapper or shell, locales, and presentation values. `shell` and an explicit wrapper are mutually exclusive. See [App, page, and shell](../dsl-app-page-shell/).

## 2. Page source

Within a page, the main authoring forms are:

| Form | Purpose |
| --- | --- |
| `page` | Names a source page and its tree |
| `i18n {}` | Declares the page’s inline locale table |
| `component` / `use` | Compile-time reusable composition |
| `include` / `partial` / `import` | Resolver-backed source reuse, with different scope limits |
| `for` | Compile-time expansion of a static array |
| AUP node | The emitted semantic UI tree |

## 3. Node common tail

Most node authoring combines an optional ID, an inline value, `key=value` props, children, and one of the data/interaction clauses:

```text
from <path>             # source
show if <condition>     # presentation condition
on <event> -> <action>  # explicit event
-> <action>             # action/button click shorthand only
```

Use `-> page <name>` for named-page navigation and `-> set <id> props|src|state ...` for the supported local update shorthand. Values are data literals, not arbitrary JavaScript expressions.

## 4. Compilation and checks

The DSL compiles to an AUP tree, app/page JSON compatibility material, and inline locale tables. Use formatting, lint, validation, optional generation, and blocklet checks in their respective roles; no single one is a browser/device acceptance result.

```bash
arc dsl format . --check
arc dsl lint .
arc dsl validate .
```

Keep cross-renderer primitive support out of this grammar page. That belongs to [Primitive taxonomy and evidence](../primitive-support-matrix/); it prevents a convenient DSL spelling from being mistaken for universal device support.

---

## Nodes, values, and sugar

URL: https://www.arcblock.io/en/docs/aup/dsl-nodes-values-sugar/

DSL node sugar keeps authoring concise; it does not create a separate renderer contract. The compiler lowers common forms into semantic AUP nodes:

| DSL form | Compiles to |
| --- | --- |
| `stack`, `row`, `grid`, `card` | `view` |
| `h1`, `h2`, `h3`, `p`, `badge` | `text` |
| `button`, `tab` | `action` |
| `repeat` | `afs-list` |

An inline literal becomes `text.content` or `action.label`; `key=value` supplies properties. Values can be strings, numbers, booleans, `null`, objects, or arrays. The DSL has compile-time `+` and `*` operations and macro substitution; it is not a general JavaScript expression language.

## Data, visibility, and events

```aup
button rename "Rename" primary ->
  set headline props {content: "Renamed"}

button load "Load" primary ->
  set list src "/modules/index"
```

`from` sets `src`; `show if` sets `visible`; and `on <event> -> ...` can bind an explicitly named event. A bare `->` is reserved for the click shorthand on `action`/`button`.

`show if` is presentation control, not authorization. A hidden tree is not an AFS access policy.

## Be explicit when another node refers to an ID

The compiler can infer stable IDs when authors omit them. When an event target, patch, test anchor, or another node must name the target, give it an explicit ID. It makes the source easier to review and avoids accidental identity changes during a refactor.

`-> page` lowers to the current root update `{ target: "_root", set: { page } }`; use the DSL form rather than writing legacy top-level page fields into new source.

For runtime semantic fields, see [Nodes, events, and messages](../node-event-message-reference/). For compile-time components and loops, continue to [Components, loops, and i18n](../dsl-components-loops-i18n/).

---

## DSL source model

URL: https://www.arcblock.io/en/docs/aup/dsl-source-model/

AUP DSL is the authoring surface for a DSL-first app. For that kind of app, the runtime reads `.aup/app.aup` first and reads `.aup/app.json` as JSON source only when DSL is absent. When a source exists but cannot parse, fix the DSL instead of expecting JSON to mask the failure. JSON-first apps remain a supported input form.

`minimal-app` identifies these files as sources an author should change:

| Source | Purpose |
|---|---|
| `.aup/app.aup` | App tree and page registration |
| `pages/**/layout.aup` | Web page layout |
| `.web/components/**/component.dsl` | Source for a Web-component manifest |
| `agents/**/agent.dsl` | Source for an agent manifest |
| `seed/settings/**/settings.aup` | Settings source |

Some JSON is generated by the recipe immediately; other `.aup` compatibility artifacts materialize only after `arc dsl generate --write`. Do not decide whether a file is authoring source just because it currently exists on disk. Inspect the recipe’s `source DSL`, `AFS data`, and `generated compatibility artifacts` sections first.

This model remains version-bound. Runtime compilation can expose AUP app/page/wrapper JSON virtually; only a compatibility consumer that explicitly needs on-disk output requires materialized `.aup/*.json`. Current source and the DSL Showcase both show that some runtime/reviewer workflows still consume JSON, so run the checks required by that consumer before deleting or ignoring an artifact.

---

## Events, state, and bindings

URL: https://www.arcblock.io/en/docs/aup/events-state-bindings/

“A value changed” is not one kind of operation in an interface. AUP distinguishes reading data, writing data back, projecting data into a prop, storing UI-local state, and handling a user event. Choose the contract first so the renderer, AFS scope, and tests know who owns what.

## Four data/state relationships

| Form | Current meaning | Do not infer |
| --- | --- | --- |
| `src` | A read-only AFS data path | Automatic write authority |
| `bind` | A read/write AFS binding, often used by input | Every path is readable and writable |
| `propBind` | A server-managed read-only `dotted prop path → AFS path` binding | A renderer itself calls AFS or manages subscriptions |
| `state` | A UI-local state object | All state is necessarily client-only or persistent |

`propBind` resolves its initial value before first render and updates props through a patch when its source changes. Input validation is explicitly marked as client-only transient state; the lifecycle of other `state` must be accepted against the behavior of its app/renderer rather than assumed from one blanket rule.

The current DSL can compile `from "path"` to `src`, and accepts `bind=...`, `propBind={...}`, `state={...}`, and `events={...}`. Path validation rejects `javascript:` and `..`; that is not a promise that an arbitrary AFS path receives access authority.

## Three results of an event

An `AUPEvent` can:

1. Call an AFS action with `exec` and optional `args`.
2. Update a node's `src`, `props`, `state`, or `events` through `target` + `set`.
3. Perform client-side browser-level URL navigation through `navigate`.

The current preferred named-page navigation sets `target` to `_root` and uses `set: { page: "name" }`. The older JSON form `page: "name"` is deprecated. New DSL can use `-> page details`, which compiles to the preferred root/set form.

These DSL snippets use shapes accepted by the current parser:

```aup
button open "Open" primary -> page details
button load "Load" primary -> set viewer src "/items/42"
button bump "Bump" primary -> set dial state {value: 7, dirty: true}
action -> exec "/.auth/logout"
action -> navigate "/.well-known/service/login"
```

`->` is click sugar for buttons/actions. Other nodes should explicitly use `on <event> -> ...`. When one update needs a compound set, such as `src` and `props` together, use complete `events={...}` rather than expecting one-line sugar to express every combination.

## Accept observable behavior

First verify one thing: does an input or action produce the intended patch or page change? Then verify that an AFS action runs only in the correct caller scope. Finally inspect renderer loading, validation, or animation state. Collapsing all three into “the button can be clicked” hides errors in read/write authority, update targets, and navigation semantics.

Read [Sessions, patches, and scenes](/en/docs/aup/sessions-patches-scenes/) next for how updates propagate through an interactive session.

---

## Example: AFS data binding

URL: https://www.arcblock.io/en/docs/aup/example-afs-data-binding/

The current DSL Showcase contains a `list-template` source example built around `afs-list`. It is useful because it shows the opposite of a compile-time `for`: the item template is rendered from a runtime data list rather than expanded from a literal array.

## Read the example at the correct layer

- `afs-list` expresses a runtime list/template intent.
- The data path is resolved through the runtime/AFS path boundary.
- A renderer and session still determine whether the result can be presented.
- Readability of a path does not imply write permission, `exec` permission, or a portable renderer experience.

Do not convert the sample into a generic promise that a particular legacy alias or sample path exists in every blocklet. Use the current product’s declared path and a real caller/session when testing.

## Acceptance sequence

1. Declare the smallest read-only source path for the app under test.
2. Run source validation and the relevant blocklet checks.
3. Start the registered app locally with a caller/session that is entitled to the path.
4. Observe the item template, an empty result, and a denied/unavailable result distinctly.
5. Only add bindings or actions after the read boundary is understood.

This page deliberately does not turn a Showcase source file into a public data endpoint. For source syntax, see [Nodes, values, and sugar](../dsl-nodes-values-sugar/); for authorization, see [Caller identity and safety](../caller-identity-safety/).

---

## Example: interaction flow

URL: https://www.arcblock.io/en/docs/aup/example-interaction-flow/

The current DSL Showcase contains an `overlays` source example with `open`/`close` behavior and state. It is useful for explaining an interaction flow as a sequence of semantic intent:

1. A visible control emits an explicit event.
2. The event targets a named node/state change.
3. The next tree/presentation is produced by the runtime and target renderer.
4. A later control reverses or changes that state.

This is different from treating an overlay as a browser-only DOM trick. The source can establish that the current compiler understands the declarations; a target acceptance test must establish focus behavior, device presentation, dismissal behavior, and any caller/permission boundary.

## Test a flow as observations

For an actual product flow, record each step as an observable fact:

| Step | Record |
| --- | --- |
| Entry | target, runtime version, starting page/session state |
| Trigger | exact node/event the reviewer invoked |
| Intermediate result | visible tree/presentation and expected state change |
| Exit | close/back/dismiss behavior and final state |
| Boundary | any required caller identity, data scope, or target limitation |

Do not say that a Showcase source file “has passed a flow test” unless that exact registered target, version, and sequence were run. For event authoring, see [Events, navigation, and visibility](../dsl-events-navigation-visibility/); for session updates, see [Sessions, patches, and scenes](../sessions-patches-scenes/).

---

## Example: local state and events

URL: https://www.arcblock.io/en/docs/aup/example-local-state-events/

The current DSL Showcase registers a `set-sugar` page. Its source contains a compact authoring example:

```aup
button rename "Rename" primary ->
  set headline props {content: "Renamed"}

button load "Load" primary ->
  set list src "/modules/index"
```

The first action targets a named node’s props; the second changes a named node’s data source. Both compile into the AUP node/event contract described elsewhere in this board.

## What this example proves

- The current DSL parser/compiler accepts these two `set` shorthand forms in Showcase source.
- The named target makes the intended local update inspectable in source.
- The file is registered in the current DSL Showcase app page map.

## What it does not prove

- A remote deployment or any historical static Showcase page is live.
- `/modules/index` is readable in every session, scope, or target.
- Every renderer presents the same update or interaction.

To turn this into a product claim, run the registered app locally in the target runtime, trigger each action, and record the target, URL, version, and observable result. Do not cite the source file alone as an end-to-end acceptance result.

Read [Events, state, and bindings](../events-state-bindings/) for the contract and [Caller identity and safety](../caller-identity-safety/) for the permission boundary.

---

## Example: minimal app

URL: https://www.arcblock.io/en/docs/aup/example-minimal-app/

`minimal-app` is the smallest currently documented **complete ARC app** recipe. It is deliberately more than a single AUP file: the recipe provides one Web page, one AUP app, one agent, and a settings-shell source/defaults. Its profile checks declared pages/capabilities and structural limits; it does not by itself prove that every capability has a live end-to-end instance configuration.

## Reproduce the example

```bash
arc blocklet recipe explain minimal-app
arc blocklet create ./hello-aup --recipe minimal-app --name hello-aup

arc dsl format ./hello-aup --write
arc dsl lint ./hello-aup
arc dsl validate ./hello-aup
arc blocklet check ./hello-aup --profile minimal-app
arc blocklet run ./hello-aup
```

On ARC `2.0.0-beta.25`, creation reports 18 files and prints an absolute path for the next validation step. The local run prints both a `<name>.localhost` URL and a universal query URL; use the first in Chrome/Firefox and the query URL where the subdomain form is not available.

## What was actually accepted

The recipe was created in an isolated local directory, then formatted, linted, validated, and checked against `minimal-app`. In a direct local run, the root screen showed the app name, `App`, `Agent`, and `Settings`, plus the recipe’s “A tiny complete app.” description. That confirms the bounded local route, not an external deployment or every possible renderer/device interaction.

The settings defaults are seeded into `/instance` at activation time. A new scaffold and a passing profile should therefore not be described as already carrying a live user-instance setting before that activation boundary exists.

## Extend it without losing the evidence

1. Keep the first run unchanged and record its browser result.
2. Make one source change at a time: a page, one interaction, or a declared data path.
3. Repeat the command chain and inspect the target that owns the claim.
4. Use `generate --check` only when validating compatibility artifacts; it is not required to make the source-first local app run.

For the source/artifact distinction, read [Sources, artifacts, and JSON compatibility](../source-artifact-json-compatibility/). A minimal static content site is a separate target-specific Web Device path, not a variant of this complete-app recipe.

---

## Example: Web layout

URL: https://www.arcblock.io/en/docs/aup/example-web-layout/

The Web Device first-site guide created a locally accepted layout:

```aup
page index {
  hello main title="Hello, Web Device" text="This page is rendered by a local blocklet."
}
```

`hello` is a site component under `.web/components/hello/`; its manifest, renderer, and stylesheet form the site presentation layer. In ARC `2.0.0-beta.25`, this layout was built and opened through a direct local blocklet run.

## What this is an example of

- An AUP page layout composing a Web Device site component.
- A static Web page with a declared route, site configuration, and local browser acceptance.
- A useful separation between page structure and reusable HTML/CSS implementation.

## What it is not an example of

- A claim that every native AUP primitive is valid as a Web layout section.
- An interactive AUP session, patch sequence, or cross-device renderer proof.
- A DID Space deployment.

Use the direct static-tree renderer only for target-supported nodes, and use Web components for reusable layout sections. The full site file tree and commands belong to the target-specific Web Device documentation. For the two Web-facing AUP paths, see [AUP on Web Device](../on-web-device/).

---

## Examples and evidence

URL: https://www.arcblock.io/en/docs/aup/examples/

This section distinguishes locally accepted paths from source-level examples. Every leaf identifies its source, registered entry, available verification record, and known limit. A Showcase’s physical file, static prose, or declared domain alone is not evidence of a publicly runnable example.

## Choose evidence deliberately

1. [Live example contract](../live-example-contract/) establishes the read-only document pattern and its first document-target render.
2. [Minimal app](../example-minimal-app/) is the current locally run recipe path.
3. [Local state and events](../example-local-state-events/) is a registered source example; its target acceptance remains a separate check.
4. [AFS data binding](../example-afs-data-binding/) and [interaction flow](../example-interaction-flow/) are source examples with their stated runtime boundaries.
5. [Web layout](../example-web-layout/) explains the source-to-Web distinction without claiming a general native-layout recipe.

---

## Build a first AUP app

URL: https://www.arcblock.io/en/docs/aup/first-app/

This path uses `minimal-app` because the current CLI explicitly provides it and can explain its sources, generated artifacts, and checks. It creates a complete slice rather than pretending to be a pure-AUP app.

## Inspect the recipe boundary first

```bash
arc blocklet recipe explain minimal-app
```

On `2.0.0-beta.25`, the output identifies `web`, `aup`, `agent`, and `settings` capabilities, and lists source DSL, AFS data, compatible artifacts, and the profile check.

## Create the app

```bash
arc blocklet create ./hello-aup --recipe minimal-app --name hello-aup
```

In this page's verification, the CLI confirmed 18 created files and printed a next validation command using the **resolved absolute path** of the created directory. That absolute path depends on where you create the project, so do not treat it as tutorial syntax.

```text
Created minimal app blocklet "hello-aup" with 18 file(s).
```

After creation, read these sources instead of editing generated artifacts:

| File | Role |
|---|---|
| `.aup/app.aup` | DSL source for the AUP app |
| `pages/index/layout.aup` | DSL source for the Web page layout |
| `.web/components/app-hero/component.dsl` | DSL source for the site-component manifest |
| `agents/app-agent/agent.dsl` | DSL source for the agent manifest |
| `seed/settings/.../settings.aup` | Settings source |

The recipe also writes some JSON compatibility artifacts, but it does not materialize `.aup/app.json`, `.aup/pages/*.json`, or `.aup/wrapper.json` in advance. If a consumer explicitly needs them, read [Generate, lint, and migrate](../dsl-generate-lint-migrate/); do not hand-edit them when no consumer needs them.

Continue to [Validate, run, and inspect](../validate-run-inspect/).

---

## Frames, bridges, and embedded surfaces

URL: https://www.arcblock.io/en/docs/aup/frames-bridges-embedded-surfaces/

Embedding crosses a trust boundary. It needs a narrower claim than “the page can show another page.”

## Frame and bridge in an interactive AUP Web session

This section describes the interactive AUP Web-session renderer. In that renderer, use `frame` for an isolated document context or controlled embed. A capability bridge at `window.aup` is available only when the frame is explicitly bridge-enabled, trusted, and same-origin. Third-party embeds should remain isolated by default; a bridge is not a general cross-origin SDK.

The Web Device document target is a different path. Its static `frame` output and Markdown content embeds do not establish a `window.aup` bridge, parent session, or general data/action access. Treat an embedded document frame as third-party content unless a separate interactive-session contract says otherwise.

Before enabling one, make the following decisions visible in review:

1. Which exact origin is trusted?
2. Which data path and actions are available to the embed?
3. How are session lifetime, parent/child messages, and failure handled?
4. What browser/device target actually passed the intended interaction?

## Surface in an interactive AUP Web session

In the interactive AUP Web-session renderer, `surface` can render an AFS path or connect to a remote AUP endpoint. Nested-session behavior still depends on the runtime and connection context. Do not promise that any remote endpoint, cross-origin transport, or nested event flow will work merely because the `surface` node parses.

`terminal` is a distinct WebSocket terminal widget, not the AUP protocol itself. It therefore carries its own endpoint, authorization, and lifecycle review rather than inheriting a blanket AUP trust claim.

The first documentation edition has one direct document-target input example, but it does not use a frame, bridge, or surface. A full runtime demo still needs its own origin, least-privilege data scope, and browser acceptance before it belongs in a reference page.

---

## Get started

URL: https://www.arcblock.io/en/docs/aup/getting-started/

This section uses the current `minimal-app` recipe as its boundary. First separate AUP, DSL, and renderer responsibilities; then create the smallest complete app containing Web, AUP, an agent, and settings, and inspect it directly on your machine.

## Read in this order

1. [Product layers and scope](../product-layers/) to decide whether the task is AUP, DSL, a renderer, or a Web Device site.
2. [Build a first AUP app](../first-app/) to create the verified beta.25 `minimal-app` boundary.
3. [Validate, run, and inspect](../validate-run-inspect/) to distinguish source checks from the direct local acceptance URL.

---

## Live examples: scope and contract

URL: https://www.arcblock.io/en/docs/aup/live-example-contract/

A reference page can place source and actual renderer output next to each other. The page itself remains read-only. A live example may expose only the interaction the represented node already owns. It never becomes an editor for the source, manifest, or documentation.

Do not treat every rendered object as the same kind of component. Markdown directives become an AUP tree for the document target; native AUP primitives have their own target-specific support; and a Web Device `.web` component belongs in a page layout, not in a generic Markdown directive. This page proves only the document-target Markdown → AUP path.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Unbound document-target `input`, plus `view` mode `tabs` as static UI chrome |
| Boundaries | No `bind`, session patch, AFS write, `exec`, multi-field form, or layout-component API |
| Author entry | Content Markdown directives (`::input`, `::::view`) |
| Surface | Web Device **document** target (static prerender + browser form controls) |
| Public status | `released` for these two nodes on document |
| Fallback / failure | Missing `id` → unstable DOM id collision risk; unknown tab children still render as panels without switching JS requirements beyond radio/CSS |
| Verification | `arc --version` = `2.0.0-beta.28`; routes below; narrow viewport still shows controls |

For every published example, record in the same place: the source that produces the node; the data or manifest boundary; the target that renders it; and the exact behavior the reader should observe, including what is deliberately absent.

## A document-target text input

This example is an unbound AUP `input` node. It has no `bind`, event, action, source path, or write capability. Type in it if useful. The field changes only as a browser form control; no document, manifest, AFS record, or session setting is changed. A browser may restore a form value when it reloads a page, which is browser behavior rather than AUP persistence.

Give every field an explicit `id`. The content reader promotes that attribute to the node’s top-level `id` (arc#3321). Without it, multiple inputs on one page can share a broken DOM id.

Source:

```markdown
::input{id="docs-live-name" type="text" label="Name" placeholder="Type only in this example" value="Ada"}
```

Rendered:

::input{id="docs-live-name" type="text" label="Name" placeholder="Type only in this example" value="Ada"}

The same Web Device document renderer that reads this page renders the field. This is a real document-target result, but it is not evidence of a bound form, an AUP session patch, or persistence. Use it only as evidence for one unbound field, not as a copyable multi-field live form pattern.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| No `id` on `::input` | Field still renders; DOM id is unstable across fields on the same page |
| `bind` / session fields in Markdown here | Not part of this contract; do not invent them on a docs page |
| Narrow viewport | Label, control, and placeholder remain readable; no second layout mode is required |

## A document-target `view` with mode `tabs`

`view` is a released cross-device primitive. On the document target, `mode="tabs"` is static UI: radio inputs and panels, not a separate widget session. Author tabs with a generic container directive so nested panel bodies survive (arc#2598).

Source:

`````markdown
::::view{id="docs-live-tabs" mode="tabs" label="Package manager"}
:::view{label="pnpm"}
Install with `pnpm install`.
:::

:::view{label="npm"}
Install with `npm install`.
:::
::::
`````

Rendered:

::::view{id="docs-live-tabs" mode="tabs" label="Package manager"}
:::view{label="pnpm"}
Install with `pnpm install`.
:::

:::view{label="npm"}
Install with `npm install`.
:::
::::

Switching tabs only changes which panel is visible in the browser. It does not write content, open an AUP session, or run shell commands. The outer fence needs more colons than nested containers, same as other container directives.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Leaf `::view` with no body | Empty panel / no body content |
| Outer fence with too few colons | Parser misreads structure; panels may drop |
| No `label` on the tabs container | Tabs still render; accessible name on the tablist is omitted |
| Treating tabs as layout `.web` components | Wrong surface — layout components use `layout.aup`, not this directive |

## What a list must add

An `afs-list` reference needs a separate contract. Its source must name the list layout and template; its data section must name a read-only fixture or a declared AFS path; and the page must identify the renderer/session that actually resolved it. A static document target can render literal child nodes, but it does not by itself prove that a source-backed list can read an arbitrary path.

The current Showcase `list-basic` source is useful evidence for that next slice: it binds `afs-list` to packaged `data/items` and has no write action on the list itself. Before it becomes an embedded runtime sample, use a dedicated minimal demo origin rather than the full Showcase, keep its fixture data read-only, and verify that the frame has no bridge, write, or `exec` path. This page does **not** claim a verified live `afs-list` sample.

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `input`, `view`, `::input` |
| Implementation | `providers/runtime/web-device/src/content-reader.ts` (directive → AUP, id promotion); `renderer/primitives/input.ts`; `renderer/primitives/view.ts` (tabs) |
| Tests | `content-reader.test.ts` (id promotion, nested tabs); `renderer/primitives.test.ts` (tabs ARIA / radio) |
| Public routes | `/en/docs/aup/live-example-contract/` · `/zh/docs/aup/live-example-contract/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` then open those routes (desktop + ~390px width) |
| Accept | Source fence matches rendered control; typing stays local; tab switch does not network-write |

For the isolation boundary, read [Frames, bridges, and embedded surfaces](../frames-bridges-embedded-surfaces/). For static Web Device versus an interactive AUP session, read [AUP on Web Device](../on-web-device/).

---

## Nodes, events, and messages

URL: https://www.arcblock.io/en/docs/aup/node-event-message-reference/

This reference describes the AUP tree contract that an author can intentionally write against. It does not make every internal session message a long-term authoring API.

## Node fields

An AUP node has a required `id` and `type`. The current public node shape also has these optional fields:

| Field | Authoring role | Boundary |
| --- | --- | --- |
| `props` | Static presentation/input properties | Its valid keys depend on `type` |
| `src` | A read-oriented data source | It does not itself grant write access |
| `bind` | A normal read/write binding for a supported input flow | The receiving node and target still decide what they support |
| `propBind` | Server-managed binding for a dotted property path to an AFS path | Use only where the owning component declares it |
| `state` | Application state supplied with the node | Do not treat renderer-local transient UI as universally persistent state |
| `events` | Named interactions and their actions | The event name is defined by the node/renderer contract |
| `children` | Nested semantic nodes | A type may constrain its child shape |
| `testId` | Stable test-oriented identifier | It is not reader-facing copy or routing identity |

`type` names a semantic capability, not a particular HTML tag or native widget. See [Primitive taxonomy and evidence](../primitive-support-matrix/) before documenting a capability as cross-device.

## Events and navigation

For current DSL authoring, `->` is the click shorthand for `button` and `action`. Other nodes use an explicit `on <event> ->` form. A page change uses the canonical root-state update:

```text
button open "Open" primary -> page details
```

which compiles to a target of `"_root"` with `set.page`. The earlier top-level `page:` shape is a compatibility form, not the preferred contract for new source.

## Messages: use the right level of abstraction

Interactive delivery begins with a rendered tree and may subsequently use tree-versioned patches. Those messages let a session keep a target surface synchronized; authors normally express them through nodes, state, and events rather than constructing patch transport by hand. A static Web Device page can render a supported tree without opening that interactive session.

Read [Events, state, and bindings](../events-state-bindings/) for task-oriented examples and [Patches, scenes, and capabilities](../patches-scenes-capabilities-reference/) for the update boundary.

---

## AUP on Web Device

URL: https://www.arcblock.io/en/docs/aup/on-web-device/

Web Device is a Web-facing site provider, not a layer that collapses every AUP and website concept together. It has two currently verifiable AUP paths: a supported AUP tree can render directly to static HTML, and a page-layout AUP can compose site components for reusable Web presentation. These are related paths, not permission to place arbitrary native primitives directly into a Web layout section.

| Concern | AUP | Web Device |
| --- | --- | --- |
| Tree, event, state, capability/degradation | Defines the semantic contract | Uses the target renderer's support boundary |
| Static HTML | Can produce it from a supported tree | Owns the Web renderer, page assembly, and build |
| Page directories, content objects, locales, SEO, and themes | Does not define them | Organizes them through `pages/`, `content/`, and `.web/` |
| Site components | Can be referenced by a layout | Live in `.web/components/` as reusable Web implementation |

## Choose the right path

When arranging branded components, content lists, or themed styles in a site page, start with Web Device's `pages/` and `.web/components/`, then use an AUP layout for structure. When verifying a cross-device interactive tree, session patch, or device capability, start with an AUP app and its target renderer.

The paths share AUP semantics but require different acceptance:

- AUP-app browser acceptance observes session, navigation, event, and patch behavior.
- Web Device acceptance observes static pages, locales, links, SEO, and build output.
- One green path does not replace the other. Static HTML success is not interactive-session success; an AUP app running is not proof that a content site has correct routes and SEO.

## A minimal order for a site author

1. In Web Device, create `.route/web`, `.web/site.yaml`, and `pages/index/` first.
2. Use Web components for reusable layout sections. Treat direct native-tree static rendering as its own supported-renderer path, not as a replacement for the layout component contract.
3. Use AUP's event/state contract for interaction and Web Device's source/binding contract for content objects.
4. Run DSL/site checks, build, and real browser acceptance separately.

Do not treat hidden UI, static rendering, or a page component as AFS authorization. Caller identity and scope remain a separate boundary. Site-building steps belong to the target-specific Web Device layer, not to this AUP board.

## Related evidence

For a live document-surface walk of the 18 primitives, Markdown directives, and deck media host (gallery / YouTube media-fill / tweet clamp) on this site: [AUP capability tour](/en/docs/aup/capability-tour-slides/). The tour is evidence for the document target only; it does not replace device capability reports or Web Device site acceptance.

---

## AUP

URL: https://www.arcblock.io/en/docs/aup/overview/

AUP is ARC’s declarative UI model. An application describes a semantic interface tree, data, and interaction first. Interactive AUP is normally presented by an ARC session and target renderer; Web Device can also render a supported AUP tree directly to static HTML.

Keep three layers distinct:

| Layer | Owns | Does not own |
|---|---|---|
| AUP | The semantic node/event/state/data contract and shared degradation rules | The HTML or native-control implementation for one device |
| AUP DSL | The readable, source-first authoring form and generation tools | A second UI model |
| Device and renderer | Reporting actual `DeviceCaps` during handshake and implementing presentation and target-side degradation from them | The application’s business intent |

For AUP app configuration, the current loader prefers `.aup/app.aup`. Only when it is absent does it load `.aup/app.json` as JSON source; a present but invalid DSL source fails instead of silently falling back. JSON-first apps remain supported, while DSL-first apps can expose or materialize compatible JSON on demand. These are different input/artifact roles for one AUP model, not two products.

## Start from the task

| If you need to | Start here |
|---|---|
| Create and run a first complete AUP app | [Get started](../getting-started/) |
| Understand trees, events, sessions, and capabilities | [Core concepts](../concepts/) |
| Author and maintain source with DSL | [Author with DSL](../author-with-dsl/) |
| Understand how ARC runs it on device surfaces | [Run in ARC](../run-in-arc/) |
| Inspect source examples and their evidence boundaries | [Examples and evidence](../examples/) |
| Look up an exact, versioned contract | [Reference](../reference/) |

## Relationship to Web Device

Web Device is a Web-facing AUP target: it can statically render supported AUP trees to HTML and lets site pages use AUP to compose Web components. It is not a replacement for an interactive AUP session; a site also has its own `.web/` components, pages, themes, content, and routing conventions. Components are one layer for richer HTML, CSS, and interaction on the Web, not the only valid form of an AUP tree.

Site directories, content objects, and themes belong to the Web Device layer and are intentionally outside this AUP board. For AUP semantics, DSL, sessions, or degradation, remain in this board.

## Evidence and versions

This board does not treat stale Showcase counts or an unregistered Showcase page file as evidence of a current deployed demo. Implementation semantics are grounded in current source and tests. Its command-bearing pages were run with `arc` `2.0.0-beta.25`; a page that has been filled in identifies its source, test, and runtime boundary. The non-rendered board ledger preserves archaeology and human decisions.

---

## Patches, scenes, and capabilities

URL: https://www.arcblock.io/en/docs/aup/patches-scenes-capabilities-reference/

This reference separates three related but different concerns: keeping an interactive tree current, selecting a presentation for a target, and describing a device-level scene.

## Render first; patch a known tree

An interactive session starts from a rendered AUP tree. Later changes can be sent as patches against a tree version. The current patch vocabulary includes `create`, `update`, `remove`, and `reorder` operations. That is a renderer/session synchronization mechanism, not a request for application authors to edit arbitrary transport messages.

When a state change is simple, express it as state/event intent in DSL or AUP source. Let the runtime determine the resulting tree update. A target that misses or rejects an update must not be assumed to have applied the author's intended state merely because a source file validated.

## Capabilities are reported by the target

The AUP model contains shared degradation rules; the actual device capability set (`DeviceCaps`) is reported during handshake and the renderer applies target presentation. Current primitive support values are:

```text
native | webview | partial | unsupported
```

Those values describe a target’s relation to a primitive, not a universal quality score for the whole app.

The current shared degradation contract is deliberately small. The canonical list of its nine chains is in [Device capabilities and degradation](../device-capabilities-degradation/); keep that target-specific acceptance guidance next to the chain list rather than copying it into every reference page.

A custom or unknown type without a chain passes through unchanged; it is not automatically converted to text. This is why a cross-device claim requires a concrete primitive and target check.

## Scene is not a generic UI escape hatch

The runtime has scene-oriented delivery surfaces, but their lower-level transport details are not a stable shortcut around node/event/state authoring. Use a scene only when the relevant target contract and acceptance test are known. Do not use a frame, bridge, or embedded surface to bypass capability or data-scope review.

For the current primitive inventory, see [Primitive taxonomy and evidence](../primitive-support-matrix/). For safe authoring of state changes, see [Events, state, and bindings](../events-state-bindings/).

---

## Primitive taxonomy and evidence

URL: https://www.arcblock.io/en/docs/aup/primitive-support-matrix/

“The parser accepts a type” and “the type works on this device” are different statements. This reference first gives the current type taxonomy, then leaves the final support decision to actual `DeviceCaps`, the target renderer, and local acceptance.

## The 18 cross-device primitives

| Group | Current types |
| --- | --- |
| Basic interface | [`view`](../primitives/view/), [`text`](../primitives/text/), [`media`](../primitives/media/), [`input`](../primitives/input/), [`action`](../primitives/action/), [`overlay`](../primitives/overlay/) |
| Structure and time | [`table`](../primitives/table/), [`time`](../primitives/time/), [`chart`](../primitives/chart/), [`map`](../primitives/map/), [`calendar`](../primitives/calendar/) |
| Interactive surface | [`chat`](../primitives/chat/), [`rtc`](../primitives/rtc/), [`explorer`](../primitives/explorer/), [`editor`](../primitives/editor/), [`canvas`](../primitives/canvas/), [`surface`](../primitives/surface/), [`afs-list`](../primitives/afs-list/) |

Those 18 names form the cross-device primitive table and are the subject of the capability map. Open [AUP primitives](../primitives/) for one contract page per name. For each type, a device reports `native`, `webview`, `partial`, or `unsupported`; do not substitute the table for a real target report.

## The 42 Web-only widgets

The current type table also contains 42 Web widgets. They include presentation/site-oriented types such as `frame`, `terminal`, `breadcrumb`, `pagination`, `tooltip`, `comments-surface`, `blocklet-embed`, `webgl-hero`, and `wm-surface`. They can have a renderer in the Web runtime, but they are not cross-device primitives and do not enter the guaranteed `DeviceCaps.primitives` scope.

To avoid writing “60 types” as “60 cross-device capabilities,” use these rules for documentation and examples:

| Claim | Required evidence |
| --- | --- |
| A primitive works on one target | That target's capability report plus real presentation acceptance |
| A primitive has a fallback | A currently listed degradation chain, verified on the target |
| A Web widget works | Web runtime/browser acceptance |
| A custom type works | Target registration/renderer plus real acceptance |

When an unknown/custom type has no shared chain, the current degradation implementation passes it through unchanged rather than automatically turning it into safe text. Before taking a custom type to a second renderer, design both its presentation and failure boundary.

## Nearby references

- For device reports, the nine explicit degradation chains, and their failure shape: [Device capabilities and degradation](/en/docs/aup/device-capabilities-degradation/).
- For node, props, data binding, and children semantics: [Semantic tree](/en/docs/aup/semantic-tree/).
- For static HTML boundaries in Web Device: [AUP on Web Device](/en/docs/aup/on-web-device/).
- For a document-surface walk of the 18 primitives, Markdown host, and deck media demos: [AUP capability tour](/en/docs/aup/capability-tour-slides/).

This page is the `2.0.0-beta.25` type taxonomy, not a cross-version, cross-device compatibility promise.

---

## AUP primitives

URL: https://www.arcblock.io/en/docs/aup/primitives/

These pages document the **18 AUP cross-device primitives** from `AUP_PRIMITIVES`. Each name has its own page. They are not Web Device layout components and not the 42 Web-only widgets.

| Rule | Meaning |
| --- | --- |
| One page per primitive | Capability and sample boundary stay scoped to a single type |
| Document vs full-web | Document capability comes from `DEVICE_CAPS_DOCUMENT`, not from Showcase success |
| Sample honesty | Docs-safe samples show source + real render; unsupported types say so |
| Not widgets | `frame`, `terminal`, `breadcrumb`, … belong to the Web-only widget set |

## Basic interface

| Primitive | Document (current) | Page |
| --- | --- | --- |
| `view` | native | [view](./view/) |
| `text` | native | [text](./text/) |
| `media` | native | [media](./media/) |
| `input` | native | [input](./input/) |
| `action` | native | [action](./action/) |
| `overlay` | unsupported | [overlay](./overlay/) |

## Structure and time

| Primitive | Document (current) | Page |
| --- | --- | --- |
| `table` | native | [table](./table/) |
| `time` | partial | [time](./time/) |
| `chart` | unsupported (no live chart) | [chart](./chart/) |
| `map` | unsupported | [map](./map/) |
| `calendar` | unsupported | [calendar](./calendar/) |

## Interactive surface

| Primitive | Document (current) | Page |
| --- | --- | --- |
| `chat` | unsupported | [chat](./chat/) |
| `rtc` | unsupported | [rtc](./rtc/) |
| `explorer` | unsupported | [explorer](./explorer/) |
| `editor` | native (no writable IDE promise) | [editor](./editor/) |
| `canvas` | unsupported | [canvas](./canvas/) |
| `surface` | unsupported | [surface](./surface/) |
| `afs-list` | native renderer; data contract open | [afs-list](./afs-list/) |

## Read next

- [Primitive taxonomy and evidence](../primitive-support-matrix/) — 18 vs 42 widgets
- [Device capabilities and degradation](../device-capabilities-degradation/) — chains and chart boundary
- [Custom primitives and Web widgets](../custom-primitives-web-widgets/) — portability vs Web-only
- [Live examples: scope and contract](../live-example-contract/) — what a docs sample may claim

---

## `action` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/action/

`action` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `action` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `released` |
| Document capability | `native` |
| Shared degradation chain | None (document reports native) |
| Author entry | AUP tree · Markdown `::action` (often inside action-card) · DSL |
| Document renderer / notes | `renderer/primitives/action.ts` (`safeHref`); cards synthesize action nodes |
| Showcase evidence | form / portal pages; document cards path on markdown unit pages |

## When to use

You need a labeled operation: navigation `href`, or (on interactive targets) `events.click` / `exec`.

## When not to use

On public docs, use navigation-only actions. Do not promise AFS `exec` or destructive confirmations from a static document sample.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Navigation-only action on document |
| Boundaries | No `exec`, no AFS write, no session |
| Author entry | `::action{…}` |
| Surface | Web Device **document** |
| Public status | `released` |
| Fallback / failure | Unsafe `href` schemes rejected; missing `href` → non-link span/button chrome |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (navigation action)

This example places an ordinary navigation `href` with no event, `exec`, or data write.

Source:

```markdown
::action{label="Open live example contract" href="/en/docs/aup/live-example-contract/" variant="primary"}
```

Rendered:

::action{label="Open live example contract" href="/en/docs/aup/live-example-contract/" variant="primary"}

### Non-link label (no href)

Source:

```markdown
::action{label="Label only — not a navigation target" variant="secondary"}
```

Rendered:

::action{label="Label only — not a navigation target" variant="secondary"}

Card composition: [action-card](/en/docs/web-device/markdown/action-card/).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `javascript:` / `data:` href | Rejected by `safeHref`; not a clickable privileged link |
| Missing `href` | Non-link presentation (`span` / button path without navigation) |
| Expecting `exec` or AFS write | Out of contract on static document samples |
| Nested inside action-card | Still navigation-only unless a separate interactive runtime is proven |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `action` |
| Implementation | `content-reader.ts` (generic `::action`); `renderer/primitives/action.ts` (`safeHref`) |
| Public routes | `/en/docs/aup/primitives/action/` · `/zh/docs/aup/primitives/action/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · click navigation action → ordinary navigation only |
| Accept | Primary action navigates; label-only action is not a privileged write; no `exec` |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `afs-list` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/afs-list/

`afs-list` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `afs-list` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `experimental` |
| Document capability | `native` (renderer present; **data contract open**) |
| Shared degradation chain | None |
| Author entry | AUP + source/fixture (`layout`, `itemStyle`, `from` / `src`) · container directive with static children |
| Document renderer / notes | `renderer/primitives/afs-list.ts` (static children; empty+src → “Loading…”; empty no src → “No items”) |
| Showcase evidence | `list-basic.aup` and related list-* pages (`from "data/items"`) |

## When to use

Declarative lists over AFS paths or packaged fixtures on interactive targets.

## When not to use

Do not bind arbitrary AFS paths in public docs. Do not claim verified live list sampling without a read-only fixture origin.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Honest empty-state and static-children rendering on document |
| Boundaries | No write actions; no arbitrary AFS path; no frame bridge; **not** proof that a path resolves on this site |
| Author entry | Container directive `:::afs-list{…}` |
| Surface | Web Device **document** |
| Public status | `experimental` |
| Fallback / failure | No children + no src → “No items”; no children + src → “Loading…” (static) |
| Verification | Routes below · empty states only; path-backed live data still open |

## Document sample (empty — no items)

Source:

```markdown
:::afs-list{id="docs-prim-afs-list-empty" layout="list" itemStyle="row"}
:::
```

Rendered:

:::afs-list{id="docs-prim-afs-list-empty" layout="list" itemStyle="row"}
:::

## Document sample (src without children — loading chrome)

This shows the static renderer’s loading empty state. It does **not** fetch an AFS path on this documentation site.

Source:

```markdown
:::afs-list{id="docs-prim-afs-list-loading" layout="list" itemStyle="row" src="data/items"}
:::
```

Rendered:

:::afs-list{id="docs-prim-afs-list-loading" layout="list" itemStyle="row" src="data/items"}
:::

## Document sample (static children)

Pre-populated children render as list items. This is not evidence of AFS `list()` resolution.

Source:

````markdown
:::afs-list{id="docs-prim-afs-list-static" layout="list" itemStyle="row"}
Static row one — authored as document children, not fetched.

Static row two — still not an AFS path proof.
:::
````

Rendered:

:::afs-list{id="docs-prim-afs-list-static" layout="list" itemStyle="row"}
Static row one — authored as document children, not fetched.

Static row two — still not an AFS path proof.
:::

Showcase `list-basic` binds `afs-list` to packaged `data/items` with no write action on the list itself — useful evidence for a future embedded sample with a dedicated read-only fixture origin. See [Live examples: scope and contract](../../live-example-contract/) (“What a list must add”).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Empty list, no `src` | “No items” empty chrome |
| Empty list with `src` | “Loading…” static chrome (no fetch proof here) |
| Arbitrary AFS path on public docs | Out of contract |
| Expecting write / drop / mutate | Out of contract |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `afs-list` |
| Implementation | `renderer/primitives/afs-list.ts`; caps `device-caps.ts` |
| Public routes | `/en/docs/aup/primitives/afs-list/` · `/zh/docs/aup/primitives/afs-list/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · confirm empty / loading / static-children chrome |
| Accept | Empty states match; page states data contract open; no arbitrary path claim |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `calendar` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/calendar/

`calendar` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `calendar` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported (document)` |
| Document capability | `unsupported` |
| Shared degradation chain | calendar → table → text |
| Author entry | AUP/DSL on supporting interactive targets |
| Document renderer / notes | No document native calendar renderer; chain applies |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/calendar.aup` |

## When to use

Month/week/day calendar composition with events on a capable target.

## When not to use

Do not assume a degraded table preserves calendar semantics. No document live sample.

## Document sample

**Not provided.** Document capability is `unsupported`. Shared chain: `calendar` → `table` → `text`. The fallback table is not a calendar product surface.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `canvas` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/canvas/

`canvas` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `canvas` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported (document)` |
| Document capability | `unsupported` |
| Shared degradation chain | canvas → media → text |
| Author entry | AUP on interactive/visual targets |
| Document renderer / notes | No document native canvas path; chain applies |
| Showcase evidence | Interactive runtime / visual demos (not document sample) |

## When to use

Freeform drawing or pixel surfaces on capable devices.

## When not to use

Do not ship canvas demos as static docs capability.

## Document sample

**Not provided.** Document capability is `unsupported`. Shared chain: `canvas` → `media` → `text`.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `chart` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/chart/

`chart` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `chart` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `experimental` |
| Document capability | `unsupported` |
| Shared degradation chain | chart → table → text (document yields a table, not Chart.js) |
| Author entry | AUP/DSL on interactive Web · **no** `::chart` Markdown directive |
| Document renderer / notes | Full-web Chart.js path; document: degrade + optional static reshape to table (arc#3458) |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/chart.aup` |

## When to use

Full interactive Web surface with chart capability and Chart.js presentation.

## When not to use

Do not publish a live chart as a document capability. Do not invent `::chart` in site content.

## Document sample

**No live chart sample.** Facts on the static document target:

| Fact | Current boundary |
| --- | --- |
| Document capability | `DEVICE_CAPS_DOCUMENT` does **not** list `chart` → `unsupported` |
| Shared chain | `chart` → `table` → `text` |
| What you get | A **table**, not a Chart.js graphic; no CDN chart load on this path |
| Data reshape | When the runtime includes static reshape (arc#3458), inline `labels`/`datasets` become table columns/rows instead of an empty “No data” table |
| Markdown | **No** defined `::chart` directive |
| Docs policy | Prefer an author-written Markdown or AUP `table` when the page needs data |

Showcase `chart` is evidence for the **interactive** surface only. Upstream issue closed ≠ docs-safe live chart (see [Device capabilities and degradation](../../device-capabilities-degradation/) and internal capability-matrix §0.5–0.6).

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |


## Deck path exception (not a general MD chart dialect)

On **document articles**, chart stays on the degradation chain (table/text). There is still **no** product-wide `::chart` Markdown dialect for arbitrary docs.

On a **`slides: true` deck**, the runtime may use `DEVICE_CAPS_DECK` (arc#4005 / #4011) so chart stays a progressive-enhance shell. Markdown array props arrive as strings and need coercion (arc#4013). Capability-tour demos are **deck-scoped evidence**, not a rewrite of this unit contract for every page.

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `chat` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/chat/

`chat` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `chat` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported (document)` |
| Document capability | `unsupported` |
| Shared degradation chain | No shared document degradation chain |
| Author entry | AUP session · web-chat / web-full caps (`DEVICE_CAPS_WEB_CHAT`) |
| Document renderer / notes | Interactive renderers; not document-native |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/chat.aup` (often composed with `afs-list`) |

## When to use

Messaging surfaces that require session identity, channel lists, and message streams.

## When not to use

Do not paste a chat shell into static docs. Identity and permission prerequisites apply.

## Document sample

**Not provided.** Document reports `unsupported` for `chat`. There is no document degradation chain that invents a safe chat UI. Use Showcase `chat` and a real session for acceptance.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `editor` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/editor/

`editor` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `editor` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `experimental` |
| Document capability | `native` (renderer present; public sample is local-only) |
| Shared degradation chain | editor → input → text (when unsupported) |
| Author entry | AUP tree / DSL · generic Markdown `::editor{…}` |
| Document renderer / notes | `renderer/primitives/editor.ts` (textarea; `readOnly` only when boolean `true` in AUP props) |
| Showcase evidence | Composition pages using editor nodes |

## When to use

Code or long-form edit surfaces on targets that implement editor.

## When not to use

Do not claim collaborative editing, LSP, multiplayer, or write-back from a docs page.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Honest document-target editor control (local textarea only) |
| Boundaries | No LSP, no multiplayer, no AFS write, no IDE product promise |
| Author entry | `::editor{…}` generic directive |
| Surface | Web Device **document** |
| Public status | `experimental` |
| Fallback / failure | When unsupported: chain to input → text; empty value → empty textarea |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (local textarea)

Document registers an `editor` renderer. The sample below is an unbound control: typing changes only the browser textarea. Markdown attributes are strings — do not assume `readOnly=true` from MD attributes sets boolean `true` the way AUP JSON does. Prefer AUP JSON/DSL when you need a strict read-only prop.

Source:

```markdown
::editor{id="docs-prim-editor" language="json" label="Example snippet" value="{ \"ok\": true }"}
```

Rendered:

::editor{id="docs-prim-editor" language="json" label="Example snippet" value="{ \"ok\": true }"}

AUP JSON shape (interactive / when you need boolean `readOnly`):

```json
{
  "id": "snippet",
  "type": "editor",
  "props": {
    "label": "Example",
    "language": "json",
    "readOnly": true,
    "value": "{ \"ok\": true }\n"
  }
}
```

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Typing in the document sample | Local browser state only; no document/AFS write |
| Expecting LSP / multiplayer | Out of contract |
| Unsupported target | Degrades via editor → input → text |
| MD `readOnly="true"` string | Not guaranteed to equal AUP boolean `true` |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `editor` |
| Implementation | `renderer/primitives/editor.ts`; caps `device-caps.ts`; chain `degradation.ts` |
| Public routes | `/en/docs/aup/primitives/editor/` · `/zh/docs/aup/primitives/editor/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; type stays local |
| Accept | Textarea renders with seed value; no network write; experimental status visible |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `explorer` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/explorer/

`explorer` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `explorer` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported (document)` |
| Document capability | `unsupported` |
| Shared degradation chain | No shared chain (pass-through / unknown handling) |
| Author entry | AUP composition (often `afs-list` + widgets) on interactive targets |
| Document renderer / notes | Document RENDERERS: none for explorer; Showcase composes primitives/widgets |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/explorer.aup` |

## When to use

IDE-style directory browser compositions with declarative select/navigate retargeting.

## When not to use

Do not treat explorer as a single layout component. Document has no native explorer renderer.

## Document sample

**Not provided.** Document capability is `unsupported`. Explorer demos are multi-node compositions (see Showcase `explorer`) and require interactive data paths. Read [afs-list](../afs-list/) for the list half of that composition — still without a closed live data contract on this site.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `input` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/input/

`input` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `input` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `released` |
| Document capability | `native` |
| Shared degradation chain | None (document reports native) |
| Author entry | AUP tree · Markdown `::input{…}` (generic directive → type) |
| Document renderer / notes | `renderer/primitives/input.ts`; content-reader id promotion (arc#3321) |
| Showcase evidence | form-* Showcase pages; document path verified on live-example-contract |

## When to use

You need a form control (text, select, checkbox, …) as a semantic node.

## When not to use

Do not put `bind`, multi-field forms, or session writes on a public docs page. Give every field an explicit `id`.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Unbound document-target input |
| Boundaries | No `bind`, session patch, AFS write, `exec`, or multi-field form product |
| Author entry | `::input{…}` |
| Surface | Web Device **document** |
| Public status | `released` |
| Fallback / failure | Missing `id` → unstable DOM id across fields; unknown type may degrade presentation |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (unbound text input)

This field is an unbound AUP `input`. Typing changes only the browser form control. No document, manifest, AFS record, or session setting is written.

Source:

```markdown
::input{id="docs-prim-input-name" type="text" label="Name" placeholder="Type only in this example" value="Ada"}
```

Rendered:

::input{id="docs-prim-input-name" type="text" label="Name" placeholder="Type only in this example" value="Ada"}

### Additional control (checkbox)

Source:

```markdown
::input{id="docs-prim-input-ack" type="checkbox" label="I understand this stays local"}
```

Rendered:

::input{id="docs-prim-input-ack" type="checkbox" label="I understand this stays local"}

Full shared contract: [Live examples: scope and contract](../../live-example-contract/).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| No `id` on `::input` | Field still renders; DOM id is unstable across fields on the same page |
| `bind` / session fields in Markdown here | Not part of this contract; do not invent them on a docs page |
| Multi-field live form with submit | Out of contract for public docs |
| Narrow viewport | Label, control, and placeholder remain readable |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `input` · `::input` |
| Implementation | `content-reader.ts` (id promotion); `renderer/primitives/input.ts` |
| Public routes | `/en/docs/aup/primitives/input/` · `/zh/docs/aup/primitives/input/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · type in the field; reload may restore browser form state only |
| Accept | Source matches control; typing stays local; no network write on change |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `map` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/map/

`map` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `map` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported (document)` |
| Document capability | `unsupported` |
| Shared degradation chain | map → media → text |
| Author entry | AUP/DSL on full-web (Leaflet / MapLibre in Showcase) |
| Document renderer / notes | No document native map renderer; chain applies |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/map.aup` |

## When to use

Interactive map/globe UI on a target that reports map support.

## When not to use

Do not embed live maps in static docs. Tile CDN and JS map stacks are not document capabilities.

## Document sample

**Not provided.** Document capability is `unsupported`. Shared chain: `map` → `media` → `text`. Accept maps on Showcase `map` (full-web), not as a docs live sample.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

## Deck path exception

Ordinary **document** pages do not embed a live map. A **`slides: true` deck** may keep a map progressive-enhance shell under `DEVICE_CAPS_DECK` (arc#4005 / #4011 + #4013). Tour demos are deck-scoped evidence only.

---

## `media` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/media/

`media` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `media` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `released` |
| Document capability | `native` |
| Shared degradation chain | None (document reports native) |
| Author entry | AUP tree · generic Markdown directive `::media{…}` · Markdown images (separate img path) |
| Document renderer / notes | `renderer/primitives/media.ts` |
| Showcase evidence | Markdown image path; Showcase media-heavy pages |

## When to use

You need a semantic media node with type (`image` / `video` / `audio` / `avatar`) and optional caption.

## When not to use

Do not treat unrestricted third-party embeds as trusted media. Same-site / whitelist rules for frames are separate ([embed](/en/docs/web-device/markdown/embed/)). Inline Markdown `![alt](src)` is a different structure path ([image](/en/docs/web-device/markdown/image/)).

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Document-target `media` image with caption |
| Boundaries | No video/audio product promise on this page; trust/whitelist for arbitrary embeds is separate; missing `src` → placeholder |
| Author entry | Generic leaf directive `::media{…}` (Markdown → AUP `type: media`) |
| Surface | Web Device **document** |
| Public status | `released` |
| Fallback / failure | Missing `src` → empty placeholder figure; unsupported type falls through to image rendering |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (image)

This sample uses the generic Markdown → AUP path (`::media` → `type: media`). The asset is a static documentation image URL used elsewhere on this site. It is **not** evidence of video, audio, avatar, or unrestricted third-party embedding.

Source:

```markdown
::media{id="docs-prim-media-img" type="image" src="https://media.arcblock.io/lib/2f/2f757138def2b3fc.w1600.webp" alt="Illustrative documentation asset" caption="Document-target media illustration"}
```

Rendered:

::media{id="docs-prim-media-img" type="image" src="https://media.arcblock.io/lib/2f/2f757138def2b3fc.w1600.webp" alt="Illustrative documentation asset" caption="Document-target media illustration"}

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Missing `src` | Empty `aup-media` placeholder (no broken remote load as the sample contract) |
| Unknown `type` | Falls through to image rendering path |
| Expecting frame / iframe embed API | Wrong surface — use `::embed` / frame rules |
| Inline `![alt](src)` | Separate MD structure path, not this AUP `media` node sample |

Source (missing `src` — placeholder only):

```markdown
::media{id="docs-prim-media-empty" type="image" alt="Missing source becomes a placeholder"}
```

Rendered:

::media{id="docs-prim-media-empty" type="image" alt="Missing source becomes a placeholder"}

Minimal AUP JSON shape (interactive / full-web authoring; same renderer keys):

```json
{
  "id": "hero-shot",
  "type": "media",
  "props": {
    "type": "image",
    "src": "/assets/example.png",
    "alt": "Example",
    "caption": "Caption"
  }
}
```

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `media` |
| Implementation | `content-reader.ts` (generic directive → type name); `renderer/primitives/media.ts` |
| Public routes | `/en/docs/aup/primitives/media/` · `/zh/docs/aup/primitives/media/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; confirm figure + caption and empty placeholder |
| Accept | Image sample shows figure/caption; empty `src` is placeholder; page does not claim video/audio/frame |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `overlay` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/overlay/

`overlay` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `overlay` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `experimental` |
| Document capability | `unsupported` |
| Shared degradation chain | overlay → text |
| Author entry | AUP session / interactive Web (Showcase `overlays`) |
| Document renderer / notes | No dedicated document renderer for full overlay chrome; chain degrades to text |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/overlays.aup` |

## When to use

Alert, confirm, toast, HUD, or multi-step choice UI on a target that reports overlay support.

## When not to use

Do not put live overlay samples on static docs. Document cannot host modal interaction chrome.

## Document sample

**Not provided.** `DEVICE_CAPS_DOCUMENT` leaves `overlay` at the default `unsupported`. Shared chain: `overlay` → `text`. Public docs must not fake modal/toast UI.

Author and accept overlays on an interactive AUP session (Showcase `overlays` page), not on this site’s static document target.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `rtc` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/rtc/

`rtc` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `rtc` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported` |
| Document capability | `unsupported` |
| Shared degradation chain | rtc → unsupported |
| Author entry | AUP on targets with realtime media capability |
| Document renderer / notes | Not on document RENDERERS as a native path |
| Showcase evidence | Not a document sample; interactive runtime only |

## When to use

Realtime audio/video collaboration on a device that grants media permissions.

## When not to use

Never claim RTC from static documentation. Chain has no useful document fallback.

## Document sample

**Not provided.** Shared chain: `rtc` → `unsupported` (explicit). Static docs must not simulate camera/mic UI as product capability.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `surface` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/surface/

`surface` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `surface` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `unsupported (document)` |
| Document capability | `unsupported` |
| Shared degradation chain | No shared chain |
| Author entry | AUP / widget surface mounts on supporting runtimes |
| Document renderer / notes | Document unsupported; see frames/surfaces docs for Web Device mounts |
| Showcase evidence | Interactive surfaces / comments-surface etc. (widgets may host surfaces) |

## When to use

Host a named interactive surface mount in an AUP tree where the runtime defines that surface.

## When not to use

Do not equate AUP `surface` with Web Device `surfaces/*` layout mounts (docs-page, pagination, …). Different layers.

## Document sample

**Not provided.** Document capability is `unsupported`. No shared degradation chain invents a safe stand-in. For Web Device page chrome surfaces, use Web Device documentation — not this primitive page.

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `table` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/table/

`table` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `table` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `released` |
| Document capability | `native` |
| Shared degradation chain | Empty AUP table → “No data” body (not a degradation chain) |
| Author entry | AUP tree (`columns`/`rows`) · GFM pipe tables (Markdown path, often HTML text) |
| Document renderer / notes | `renderer/primitives/table.ts` |
| Showcase evidence | report / finance compositions; GFM path verified on document unit pages |

## When to use

You need semantic columns and rows as an AUP `table` node, or a static GFM table in content Markdown.

## When not to use

Do not confuse a **chart** degradation table with an author-written table. GFM tables are not a deep AUP `table` props contract.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static columnar content in docs (GFM path) |
| Boundaries | Not an editable grid; not chart fallback chrome; not every AUP table prop combination |
| Author entry | Pipe table in Markdown |
| Surface | Web Device **document** |
| Public status | `released` (GFM path verified) |
| Fallback / failure | Malformed pipes → ordinary Markdown / broken table; empty AUP table → “No data” (AUP path) |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (GFM table)

This is the Markdown/GFM path on the document target. It is **not** a live claim of every AUP `table` prop combination.

Source:

```markdown
| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |
```

Rendered:

| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |

Unit page: [GFM table](/en/docs/web-device/markdown/gfm-table/).

### AUP node shape (source-only on this page)

Interactive / full-web authoring uses explicit `columns` / `rows`. Empty AUP tables render a “No data” cell. That string is table empty-state chrome, not proof of a chart.

```json
{
  "id": "rates",
  "type": "table",
  "props": {
    "columns": [
      { "key": "name", "label": "Name" },
      { "key": "value", "label": "Value" }
    ],
    "rows": [{ "name": "alpha", "value": "1" }]
  }
}
```

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Malformed pipes | Ordinary Markdown / broken table, not a runtime error surface |
| Empty body rows in GFM | Author content only — no automatic “No data” chrome from the chart chain |
| Assuming AUP `table` props from a GFM sample | Wrong path depth; write AUP JSON/DSL when you need that node |
| Chart degradation table | Separate unsupported chart path — not this sample |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `table` · GFM table |
| Implementation | `content-reader.ts` (table case); `renderer/primitives/table.ts` |
| Public routes | `/en/docs/aup/primitives/table/` · `/zh/docs/aup/primitives/table/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; compare source fence to rendered table |
| Accept | Source and rendered table match; no edit controls; no chart claim |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `text` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/text/

`text` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `text` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `released` |
| Document capability | `native` |
| Shared degradation chain | None (document reports native) |
| Author entry | AUP tree · Markdown blocks · GFM callouts → text admonition |
| Document renderer / notes | `renderer/primitives/text.ts` (includes admonition) |
| Showcase evidence | Markdown body path; admonition labels via `content-reader.ts` `ADMONITION_LOCALIZED_LABELS` |

## When to use

You need semantic text, headings (`level`), code/quote formats, badges, or admonitions.

## When not to use

Do not use `text` to smuggle layout chrome or site hero copy contracts that belong to Web Device components.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static callout / admonition presentation on document |
| Boundaries | Not editable; not a toast/overlay; not a full AUP `text` props reference for every format |
| Author entry | `> [!NOTE]`-style blockquote (Markdown → document text admonition) |
| Surface | Web Device **document** |
| Public status | `released` |
| Fallback / failure | Unknown marker → ordinary blockquote; bare marker uses locale default title |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (admonition via GFM)

On the document target, a GitHub-style callout becomes text-admonition presentation. This proves the Markdown → document path for callouts. It is **not** a full AUP `text` node props reference (`level` / `format` / `variant` live in AUP JSON/DSL).

Source (custom title on the marker line):

```markdown
> [!NOTE] Portable copy
> This callout is document content. It does not run actions or write AFS data.
```

Rendered:

> [!NOTE] Portable copy
> This callout is document content. It does not run actions or write AFS data.

Source (bare marker — label comes from locale defaults):

```markdown
> [!TIP]
> Prefer a same-line custom title when the English word is not the label you want.
```

Rendered:

> [!TIP]
> Prefer a same-line custom title when the English word is not the label you want.

Bare markers use the reader’s default label for the content locale. English keeps English defaults; **zh** defaults are applied at read time (`NOTE`→说明, `TIP`→提示, `IMPORTANT`→重要, `WARNING`→警告, `CAUTION`→注意). An explicit same-line title always wins.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `[!FIXME]` or other unknown marker | Plain blockquote, not callout chrome |
| Marker not on the first line of the quote | Not recognized as admonition |
| Expecting dismiss / editor controls | Static document content only |
| Assuming this is AUP `format: markdown` inside an interactive page | Wrong surface; that path is not this sample |

Unit page for the structure alone: [GFM admonition](/en/docs/web-device/markdown/gfm-admonition/).

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `text` · GFM admonition |
| Implementation | `content-reader.ts` (`ADMONITION_MARKER_RE`, `ADMONITION_LOCALIZED_LABELS`); `renderer/primitives/text.ts` |
| Public routes | `/en/docs/aup/primitives/text/` · `/zh/docs/aup/primitives/text/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; on zh locale, bare markers show Chinese default titles |
| Accept | Source matches rendered callout; unknown marker stays a quote; no edit controls |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `time` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/time/

`time` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `time` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `experimental` |
| Document capability | `partial` |
| Shared degradation chain | time → text (when unsupported) |
| Author entry | AUP tree / DSL · generic Markdown `::time{…}` |
| Document renderer / notes | `renderer/primitives/time.ts` (`<time>` element; clock mode snapshots at render) |
| Showcase evidence | `blocklets/showcase-dsl/.aup/pages/time.aup` |

## When to use

You need a semantic time value (formatted display, clock, countdown) on a supporting target.

## When not to use

Do not claim a ticking live clock on the static document target. Document is partial: static snapshot only.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static `<time>` presentation on document (display mode) |
| Boundaries | No live clock promise on document; no picker session |
| Author entry | `::time{…}` |
| Surface | Web Device **document** (partial) |
| Public status | `experimental` |
| Fallback / failure | Missing value → empty display; unsupported → text chain; clock mode is prerender snapshot |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (display mode)

Source:

```markdown
::time{id="docs-prim-time-display" mode="display" value="2026-02-21T14:30:00Z"}
```

Rendered:

::time{id="docs-prim-time-display" mode="display" value="2026-02-21T14:30:00Z"}

Accept interactive clock/countdown on Showcase `time`, not as a docs live ticker.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `mode="clock"` on document | Snapshot at prerender/request time — not a continuous client ticker |
| Missing `value` in display mode | Empty / blank time text |
| Unsupported target | Chain to text |
| Treating this as a date picker | Out of contract |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `time` |
| Implementation | `renderer/primitives/time.ts`; caps partial in `device-caps.ts` |
| Public routes | `/en/docs/aup/primitives/time/` · `/zh/docs/aup/primitives/time/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; confirm static `<time>` text |
| Accept | Display sample shows formatted time; page states partial / no live clock |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## `view` primitive

URL: https://www.arcblock.io/en/docs/aup/primitives/view/

`view` is an **AUP cross-device primitive**, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in `AUP_PRIMITIVES` and appears in every target's `DeviceCaps.primitives` map as `native`, `webview`, `partial`, or `unsupported`.

## Contract

| Field | Value |
| --- | --- |
| Primitive name | `view` |
| Layer | AUP cross-device primitive (`AUP_PRIMITIVES`) |
| Public status | `released` |
| Document capability | `native` |
| Shared degradation chain | None (document reports native) |
| Author entry | AUP tree · DSL · Markdown container directives (`::::view`, steps) |
| Document renderer / notes | `renderer/primitives/view.ts` (tabs / steps / card modes) |
| Showcase evidence | Composition across Showcase pages; tabs path verified on document |

## When to use

Need a semantic container, panel grouping, `mode=tabs`, or `mode=steps` that other devices can interpret.

## When not to use

Do not use `view` as a Web Device `layout.aup` section stand-in for portal-header, content-card, or other site components.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static tabs chrome on the document target |
| Boundaries | No session patch, no `exec`, no layout-component API |
| Author entry | Generic container directive `::::view` |
| Surface | Web Device **document** |
| Public status | `released` on document |
| Fallback / failure | Missing `label` omits accessible tablist name; wrong fence depth drops panels |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Document sample (tabs)

This is an unbound document-target `view` with `mode="tabs"`. Switching tabs only changes which panel is visible in the browser. It does not open an AUP session or write content.

Source:

`````markdown
::::view{id="docs-prim-view-tabs" mode="tabs" label="Package manager"}
:::view{label="pnpm"}
Install with `pnpm install`.
:::

:::view{label="npm"}
Install with `npm install`.
:::
::::
`````

Rendered:

::::view{id="docs-prim-view-tabs" mode="tabs" label="Package manager"}
:::view{label="pnpm"}
Install with `pnpm install`.
:::

:::view{label="npm"}
Install with `npm install`.
:::
::::

The outer fence needs more colons than nested containers. Same contract as [Live examples: scope and contract](../../live-example-contract/).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Leaf `::view` with no body | Empty panel / no body content |
| Outer fence with too few colons | Parser misreads structure; panels may drop |
| No `label` on the tabs container | Tabs still render; accessible name on the tablist is omitted |
| Treating tabs as layout `.web` components | Wrong surface — layout components use `layout.aup`, not this directive |

## Document sample (steps mode via `view`)

`mode="steps"` is also available on a generic `view` container. The Markdown-native tutorial path is `::::steps` / `:::step` (see [steps](/en/docs/web-device/markdown/steps/)); both land on document `view` rendering.

Source:

`````markdown
::::view{id="docs-prim-view-steps" mode="steps" label="Two checks"}
:::view{title="Check the surface"}
Confirm you are on the document target, not a layout section.
:::

:::view{title="Check the fence depth"}
Outer containers need more colons than nested ones.
:::
::::
`````

Rendered:

::::view{id="docs-prim-view-steps" mode="steps" label="Two checks"}
:::view{title="Check the surface"}
Confirm you are on the document target, not a layout section.
:::

:::view{title="Check the fence depth"}
Outer containers need more colons than nested ones.
:::
::::

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `view` |
| Implementation | `providers/runtime/web-device/src/content-reader.ts` (generic container); `renderer/primitives/view.ts` (tabs / steps) |
| Public routes | `/en/docs/aup/primitives/view/` · `/zh/docs/aup/primitives/view/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` then open those routes (desktop + ~390px) |
| Accept | Source fence matches rendered tabs/steps; tab switch does not network-write; fence errors do not crash the page |

## Evidence anchors

| Item | Value |
| --- | --- |
| Registry | `packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES` |
| Document caps | `providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT` |
| Degradation | `packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS` |
| Internal matrix | `docs/aup/capability-matrix.md` (internal, non-routed) |
| Taxonomy hub | [Primitive taxonomy and evidence](../../primitive-support-matrix/) |
| Sample contract rules | [Live examples: scope and contract](../../live-example-contract/) |

## Nearby pages

- [All primitives](../)
- [Device capabilities and degradation](../../device-capabilities-degradation/)
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- [Semantic tree](../../semantic-tree/)

---

## Product layers and scope

URL: https://www.arcblock.io/en/docs/aup/product-layers/

Choose a layer from the problem to solve, not from a directory name or a Showcase first:

| Task | Read first | Do not assume |
|---|---|---|
| Describe an interface tree, event, or state | Core concepts in this board | Every node presents the same way on every device |
| Check actual device capability and shared degradation rules | Capability/renderer and core concepts | The renderer alone defines the capability contract |
| Write an app or page in maintainable source | The DSL section in this board | DSL is a separate runtime protocol |
| Build a static site, content page, or theme | The target's Web Device documentation | AUP itself defines a site’s directory or content model |
| Browse a visual example | The matching Showcase example | A physical source file is necessarily an accessible, deployed demo |

`minimal-app` is the first verified path, but it is not a recipe that creates only one AUP file. It creates one Web page, one AUP app, one agent, and settings-shell source/defaults. Its profile checks declared pages, capabilities, and structural limits; activation seeds the settings defaults into `/instance`, so the profile itself is not proof that all four capabilities have run end to end.

This draft uses AUP as the short name. Source material contains multiple long-form and historical terms; until product naming is settled, no extra protocol promise should be inferred from one older expansion.

---

## Reference

URL: https://www.arcblock.io/en/docs/aup/reference/

This section collects exact, versioned contracts page by page. It will not substitute static Showcase prose, old syntax, or an unregistered source file for runtime, type, and test evidence. Where the current public contract is incomplete, the page names that boundary instead of inventing one.

## Read by question

- [Nodes, events, and messages](../node-event-message-reference/) and [patches, scenes, and capabilities](../patches-scenes-capabilities-reference/) for tree/session message shapes.
- [Primitive type taxonomy and evidence](../primitive-support-matrix/) for current shared-versus-Web-only names and explicit degradation chains.
- [AUP primitives](../primitives/) — **one page per** cross-device primitive (`view` … `afs-list`; 18 pages). Not layout components.
- [AUP Web-only widgets](../widgets/) — **one page per** `AUP_WIDGETS` name (42 pages). Not primitives and not Web Device layout components.
- [DSL language reference](../dsl-language-reference/) for the authored language map, followed by [CLI diagnostics](../cli-diagnostics-reference/) for maintenance commands.
- [Sources, artifacts, and JSON compatibility](../source-artifact-json-compatibility/) and [release compatibility](../release-compatibility/) before carrying source or artifacts across versions.

---

## Release compatibility

URL: https://www.arcblock.io/en/docs/aup/release-compatibility/

The AUP contract can be observed through four distinct layers. They can move at different speeds:

| Layer | What it can establish |
| --- | --- |
| Installed `arc` CLI/runtime | Commands that were actually run, local behavior, diagnostics |
| Current source checkout | Implementation semantics currently under development/review |
| Generated JSON/artifacts | What a chosen compatibility consumer expects at that point |
| Showcase source/README/static page | Examples and history, not proof of a current registered deployment |

This board’s command-bearing paths were exercised with `arc 2.0.0-beta.25`. Implementation-derived statements point to the current inspected source and should be rechecked when the installed runtime differs.

## Check a target rather than assuming “latest”

```bash
arc --version
arc dsl validate .
arc blocklet check .
arc blocklet run .
```

Record the version, source/artifact form, registered page/route, target renderer, and observed result. A physical Showcase page file does not by itself prove that a route is registered or that a remote deployment is current.

JSON-first and DSL-first are both supported source arrangements. A DSL-first project may expose JSON virtually or materialize it for a particular consumer. A passing build on a newer runtime must not be used to declare compatibility with an older runtime or an untested device renderer.

When a new behavior is discovered, preserve its target version and evidence before turning it into a public reference claim.

---

## Renderers, sessions, and support

URL: https://www.arcblock.io/en/docs/aup/renderers-sessions-support/

“Supported” has at least three different meanings. Keep them separate when reading a Showcase or reviewing an app:

| Claim | Evidence needed |
| --- | --- |
| ARC can load the source | The source is selected by the loader and passes its relevant validation |
| A target can render the tree | That renderer has a presentation path for the relevant node/capability combination |
| An interaction works | A real session/target acceptance test observed the expected change |

The first does not establish the second, and neither establishes the third.

## Interactive AUP uses a session

For an interactive AUP app, ARC starts from a rendered tree and can send versioned patch updates to a target renderer. The server-side store validates a patch batch before applying it atomically: one failed operation does not intentionally leave a partially applied batch. This is session synchronization, not a promise of distributed persistence or cross-device transaction semantics.

The target reports its actual `DeviceCaps` during handshake. The renderer then chooses its own presentation and may apply a defined degradation path. An event shape alone does not guarantee that every device or renderer supports the same interaction.

## Static Web Device is a separate path

Web Device can render a supported AUP tree directly into static HTML. It can also use page layouts that compose Web components. Neither path automatically makes every native primitive valid as a Web layout section, and static HTML rendering does not open an interactive AUP session.

When a document needs a specific device claim, name the primitive, target, ARC version, and observed acceptance. “It rendered once in a Showcase file” is not enough.

For shared primitive boundaries, see [Primitive taxonomy and evidence](../primitive-support-matrix/). For patches and degradation, see [Patches, scenes, and capabilities](../patches-scenes-capabilities-reference/).

---

## Run in ARC

URL: https://www.arcblock.io/en/docs/aup/run-in-arc/

This section explains how ARC loads AUP into a session, chooses a renderer, and applies support/degradation behavior, while keeping Web Device, frames, and embedded surfaces as distinct boundaries.

## Read in this order

1. [Renderers, sessions, and support](../renderers-sessions-support/) for the target/transport boundary.
2. [Custom primitives and Web widgets](../custom-primitives-web-widgets/) before treating a parser-accepted name as portable.
3. [AUP on Web Device](../on-web-device/) for the static-tree versus Web-layout distinction.
4. [Frames, bridges, and embedded surfaces](../frames-bridges-embedded-surfaces/) for same-origin and trust boundaries.

---

## Semantic tree

URL: https://www.arcblock.io/en/docs/aup/semantic-tree/

The smallest AUP unit is a node. A tree says what exists in an interface, how nodes nest, and which data or events relate to them. It does not make browser CSS, an iOS view, or terminal character art into protocol facts.

The current `AUPNode` has these core fields:

| Field | Purpose | Constraint for an author |
| --- | --- | --- |
| `id` | Stable identity in a tree | Unique within that tree; do not use mutable display text as an id |
| `type` | A primitive, Web widget, or registered custom type | Check target support first |
| `props` | Static, type-specific attributes | Use only keys supported for that type |
| `children` | Child nodes | Nest only where the container semantics allow it |
| `src` | Read-only AFS data binding | Expresses a read, not write authority |
| `bind` | Read/write AFS binding, often for input | Use only on an authorized writable path |
| `state` | Local UI state | Do not treat it as persistent business data |
| `events` | Declared user interaction | Use the event contract rather than hiding business logic in a renderer |

A conceptual tree can be written as:

```text
view (id: profile)
├── text (id: profile-title)
└── action (id: open-settings)
```

Here `view` expresses a container, while `text` and `action` express content and an operation. How a device arranges the nodes, how a button looks, or whether a fallback is needed are target-presentation concerns. An author should not rely on incidental CSS in one renderer to change the meaning of the tree.

## Primitives and Web widgets

The current core type table defines 18 cross-device primitives, including `view`, `text`, `media`, `input`, `action`, `table`, `chat`, `editor`, `canvas`, and `afs-list`. The Web runtime additionally registers Web-only widgets such as `frame`, `terminal`, `breadcrumb`, `pagination`, and `tooltip`. The latter can be implemented by a Web renderer but are not automatically cross-device primitives, and do not automatically occur in every device's `DeviceCaps.primitives` map.

Do not claim that an unknown or custom type works cross-device merely because a parser accepts it. Build a small example for the target renderer and accept it in a real device/browser. For fallback behavior, see [Device capabilities and degradation](/en/docs/aup/device-capabilities-degradation/).

## Keep data separate from UI state

`src` expresses a read-only data path; `bind` expresses a read/write binding. Both are UI-to-AFS path contracts and do not grant read or write permission by themselves. `state` is UI-local state such as the selected tab or expansion; input validation can also be renderer-transient state and should not be mistaken for a persistent AFS record.

Read [Events, state, and bindings](/en/docs/aup/events-state-bindings/) next to decide whether an operation should execute an AFS action, change the tree, or perform browser-level navigation.

---

## Sessions, patches, and scenes

URL: https://www.arcblock.io/en/docs/aup/sessions-patches-scenes/

Initial rendering and later updates are not the same thing in interactive AUP. Current message types send a full-tree `render` first, then incremental `patch` updates carrying a `treeVersion`. Web Device's static HTML path does not require this interactive-session pipeline as the prerequisite for every Web page.

## The current patch boundary

A patch contains these operations:

| Operation | Effect |
| --- | --- |
| `create` | Create a node under a specified parent |
| `update` | Change allowed fields on an existing node |
| `remove` | Remove a node |
| `reorder` | Change child ordering |

A current `update` can change `src`, `props`, `state`, `events`, `propBind`, or `children`. This is why authors need stable `id` values: patches target node identity, not display copy or a renderer's temporary DOM.

Do not treat this list as a forever-stable guarantee for every transport detail. This page uses it as the authoring and debugging model for `2.0.0-beta.25`; a cross-version client/server combination still needs actual release-compatibility acceptance.

## What scenes and capabilities own

The device in a session reports capability and context during handshake. That affects whether the same semantic tree appears as native, webview, partial, or fallback presentation. AUP's shared degradation chain only handles replacement order for some primitives; it does not replace decisions about scene, identity, AFS scope, or write authority.

Keep these questions separate:

- “Did the tree update the intended node?” is an event/patch question.
- “Can this target present the primitive?” is a `DeviceCaps`/degradation question.
- “May this operation read or write the path?” is a caller-identity/AFS-scope question.
- “Did a Web page get static HTML?” is a Web Device renderer/build question.

## Debug in order

1. Use one visible node state change to verify that an event produces a patch.
2. In the same session, verify named-page navigation uses the current `_root` + `set.page` form.
3. Then inspect capability differences and fallback on a second target.
4. Run a static Web Device build separately; its success does not prove an interactive session.

For event fields, read [Events, state, and bindings](/en/docs/aup/events-state-bindings/). For device differences, read [Device capabilities and degradation](/en/docs/aup/device-capabilities-degradation/).

---

## Sources, artifacts, and JSON compatibility

URL: https://www.arcblock.io/en/docs/aup/source-artifact-json-compatibility/

ARC supports both readable DSL source and JSON source for the same AUP model. The important distinction is not “new versus old”; it is which file is the current source for a particular app and which file is merely a compatibility artifact.

## App-configuration loading order

For the app configuration boundary in ARC `2.0.0-beta.25`:

1. If `.aup/app.aup` exists, ARC uses it as source.
2. If it does not exist, ARC can read `.aup/app.json` as JSON source.
3. If the DSL file exists but cannot be compiled, the load fails. ARC does not silently substitute an old JSON file.

That third rule is deliberate: a stale artifact must not make a broken source appear healthy.

## Three legitimate project shapes

| Shape | Source of truth | When JSON exists |
| --- | --- | --- |
| JSON-first | The authored JSON files | They are the source, not a compatibility residue |
| DSL-first, virtual artifacts | `.aup` files | ARC can expose compatible JSON without putting each artifact on disk |
| DSL-first, materialized artifacts | `.aup` files | A named compatibility consumer requires physical JSON files |

The regular AUP Showcase is a useful reminder that JSON-first remains supported. Conversely, the existence of generated JSON beside a DSL source does not make JSON the authoring authority.

## Do not infer a release contract from a file list

Generated app, page, or wrapper JSON can vary by source and consumer. A file being present in one recipe or Showcase tree is not proof that every AUP app must commit it. When a consumer needs materialized output, use `arc dsl generate --check` first, then `--write`, and record that consumer in the project’s own delivery contract.

The compatibility boundary is intentionally narrow: it does not promise that every historical JSON layout, every physical Showcase page, or every generated artifact is a current deployed surface. Verify the current source, registered configuration, and target runtime separately.

See [Generate, lint, and migrate](../dsl-generate-lint-migrate/) for the workflow and [Release compatibility](../release-compatibility/) for version boundaries.

---

## Validate, run, and inspect

URL: https://www.arcblock.io/en/docs/aup/validate-run-inspect/

From the parent directory that contains `hello-aup/`, run these commands in order:

```bash
arc dsl format ./hello-aup --write
arc dsl lint ./hello-aup
arc dsl validate ./hello-aup
arc blocklet check ./hello-aup --profile minimal-app
```

On `2.0.0-beta.25`, `format --write` rewrites three DSL source files in a newly created recipe into canonical format. That output means formatting wrote files; `format_changed` is a diagnostic reported by check mode. Run `format --write` first, then lint, validate, and the profile check. The verified check result includes AUP `agent`, `home`, and `settings` pages, one Web section, and one agent.

## Run directly

```bash
arc blocklet run ./hello-aup
```

ARC reuses or starts a local daemon and prints two actual access URLs. Do not deploy to DID Space for the first acceptance, and do not guess a host or port. In Chrome or Firefox, prefer the first `<name>.localhost` URL; use the second URL with `?blocklet=<name>` where needed, including Safari. Once the session connects, you should see:

- the `hello-aup` blocklet name;
- `App`, `Agent`, and `Settings` navigation;
- the heading `A tiny complete app.`;
- body text explaining that the blocklet contains Web, AUP, an agent, and settings.

The browser check proves renderer, session, and generated app work together. Lint, validation, and check do not replace it.

## When to generate JSON compatibility artifacts

Do not treat this command as the default check immediately after creation:

```bash
arc dsl generate ./hello-aup --check
```

The new recipe deliberately does not prewrite `.aup/app.json`, `.aup/pages/*.json`, or `.aup/wrapper.json`, so that check first reports them stale. Run these commands only when a compatibility consumer needs materialized artifacts:

```bash
arc dsl generate ./hello-aup --write
arc dsl generate ./hello-aup --check
```

This also creates the compatibility artifacts and a `.aup/man/home.yaml` documentation scaffold. A successful generation does not mean every manual page or permission declaration is complete.

---

## AUP Web-only widgets

URL: https://www.arcblock.io/en/docs/aup/widgets/

This hub lists every name in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). Each link opens a **single-widget** reference page.

**These are AUP Web-only widgets — not cross-device primitives; not Web Device layout components.**

For the portable 18, see [Primitive taxonomy and evidence](../primitive-support-matrix/). For the conceptual split, see [Custom primitives and Web widgets](../custom-primitives-web-widgets/). Layout components (for example `content-card`) belong under Web Device documentation, not under `widgets/`.

## All 42 widgets

- [`afs-stat`](./afs-stat/)
- [`afs-preview`](./afs-preview/)
- [`afs-dropzone`](./afs-dropzone/)
- [`agent`](./agent/)
- [`app-footer`](./app-footer/)
- [`app-header`](./app-header/)
- [`auto-fire`](./auto-fire/)
- [`auto-surface`](./auto-surface/)
- [`block-revealer`](./block-revealer/)
- [`blocklet-embed`](./blocklet-embed/)
- [`broadcast`](./broadcast/)
- [`camera-preview`](./camera-preview/)
- [`comments-surface`](./comments-surface/)
- [`deck`](./deck/)
- [`entity-overview`](./entity-overview/)
- [`finance-chart`](./finance-chart/)
- [`frame`](./frame/)
- [`globe`](./globe/)
- [`hero-widget`](./hero-widget/)
- [`key-value-list`](./key-value-list/)
- [`moonphase`](./moonphase/)
- [`natal-chart`](./natal-chart/)
- [`photo-story`](./photo-story/)
- [`post-editor`](./post-editor/)
- [`progress-bar-3d`](./progress-bar-3d/)
- [`scroll-explainer`](./scroll-explainer/)
- [`skills`](./skills/)
- [`terminal`](./terminal/)
- [`text-highlight`](./text-highlight/)
- [`text-image-expand`](./text-image-expand/)
- [`ticker`](./ticker/)
- [`type-block`](./type-block/)
- [`url-default`](./url-default/)
- [`webgl-hero`](./webgl-hero/)
- [`wm`](./wm/)
- [`wm-surface`](./wm-surface/)
- [`xeyes`](./xeyes/)
- [`breadcrumb`](./breadcrumb/)
- [`chip`](./chip/)
- [`pagination`](./pagination/)
- [`searchable-dropdown`](./searchable-dropdown/)
- [`tooltip`](./tooltip/)

## Counts

| Registry | Count | Source |
| --- | --- | --- |
| `AUP_PRIMITIVES` | 18 | `packages/aup/src/aup-types.ts` |
| `AUP_WIDGETS` | 42 | same file |
| Pages under `widgets/<name>/` | 42 | this board |

If the script-diff against `AUP_WIDGETS` ever disagrees, treat the Arc source array as canonical and update this hub.

---

## afs-dropzone

URL: https://www.arcblock.io/en/docs/aup/widgets/afs-dropzone/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Writable-directory drop/paste surface for AFS ingest. Pure client renderer: no AFS list/read in the renderer; uploads and paste go through ingest/upload dispatch.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree `type: "afs-dropzone"` with server-provided props (`target`, conflict policy, labels, result).

## Surfaces

Interactive Web only. Not document-safe content sample.

## Fallback

No shared degradation chain. Requires live session + write grant.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/dropzone.ts` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"afs-dropzone"`` |
| Ingest plane | `providers/runtime/ui/src/ingest-handler.ts` |
| Tests | `providers/runtime/ui/test/renderers/dropzone.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## afs-preview

URL: https://www.arcblock.io/en/docs/aup/widgets/afs-preview/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Server-driven file preview: set `src` to an AFS file path; the server stats the file and drives presentation. Pairs with `afs-stat` in explorer layouts.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree / DSL `type: "afs-preview"`. Registry category `subsystem` in `aup-registry.ts`.

## Surfaces

Interactive Web. Client switch maps to `renderAupView` after server work.

## Fallback

No degradation chain. Document target has no dedicated renderer.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts; packages/aup/test/aup-widget-registration.test.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`afs-preview`)` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"afs-preview"`` |
| Showcase | `blocklets/showcase/.aup/pages/explorer.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `explorer` under `blocklets/showcase`

---

## afs-stat

URL: https://www.arcblock.io/en/docs/aup/widgets/afs-stat/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Renders a compact AFS path statistic (file/dir metadata) as a view-shaped surface after server expansion. Used inside explorer and auto-surface flows.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree / DSL node `type: "afs-stat"` with `src` to an AFS path. Server expansion (`auto-surface` / node expansion) materializes children; the interactive Web client treats the node like a view.

## Surfaces

Interactive Web (`web-full`). Not a document-target RENDERERS entry.

## Fallback

No shared `DEGRADATION_CHAINS` entry. Missing renderer → unknown presentation. Not in `DeviceCaps.primitives`.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts (`AUP_WIDGETS`)` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"afs-stat"` → `renderAupView`` |
| Expansion / usage | `providers/runtime/ui/src/auto-surface.ts; `aup-node-expansion.ts`` |
| Showcase | `blocklets/showcase/.aup/pages/explorer.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `explorer` under `blocklets/showcase`

---

## agent

URL: https://www.arcblock.io/en/docs/aup/widgets/agent/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Interactive agent chat surface scoped by `src` (tool/read/exec boundaries) with optional `dataPath` for conversation persistence. Client reuses the chat renderer.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree / DSL `type: "agent"`. Registry documents `mode`, `welcome`, `dataPath`, and config events.

## Surfaces

Interactive Web session. Not a static document renderer entry.

## Fallback

No degradation chain as a widget. Requires session, identity, and AFS scope review.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts; packages/aup/src/aup-dsl.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`agent`)` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"agent"` → `renderAupChat`` |
| Handlers | `providers/runtime/ui/src/agent-handler.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## app-footer

URL: https://www.arcblock.io/en/docs/aup/widgets/app-footer/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Brand shell footer for interactive AUP apps: optional brand block, link columns, and social slots. Also has a static document primitive renderer for site-like shells.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP app shell node `type: "app-footer"`. Showcase page `prim-app-footer`.

## Surfaces

Interactive Web + document RENDERERS (`app-footer`). Not Markdown content contract.

## Fallback

No shared degradation chain. Empty props produce minimal chrome.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`app-footer`)` |
| Interactive renderer | `providers/runtime/ui/src/web-page/renderers/app-footer.ts` |
| Document renderer | `providers/runtime/web-device/src/renderer/primitives/app-footer.ts; RENDERERS in render-to-html.ts` |
| Showcase | `blocklets/showcase/.aup/pages/prim-app-footer.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `prim-app-footer` under `blocklets/showcase`

---

## app-header

URL: https://www.arcblock.io/en/docs/aup/widgets/app-header/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Brand shell header — server-driven navigation chrome. Renderer emits AUP events rather than owning client-side routing policy.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP app shell `type: "app-header"`. Showcase `prim-app-header`, `session`, `session-chrome`.

## Surfaces

Interactive Web + document RENDERERS. Site layout `portal-header` is a different layout-component.

## Fallback

No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`app-header`)` |
| Interactive renderer | `providers/runtime/ui/src/web-page/renderers/app-header.ts` |
| Document renderer | `providers/runtime/web-device/src/renderer/primitives/app-header.ts; RENDERERS in render-to-html.ts` |
| Showcase | `blocklets/showcase/.aup/pages/prim-app-header.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `prim-app-header` under `blocklets/showcase`

---

## auto-fire

URL: https://www.arcblock.io/en/docs/aup/widgets/auto-fire/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Invisible mount-time AFS `exec` trigger with sessionStorage dedupe. Used to kick a generation skill when a surface mounts, without a user click.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree `type: "auto-fire"` with props `exec`, optional `args`, and `dedupKey`.

## Surfaces

Interactive Web only. Renders a hidden span.

## Fallback

No degradation chain. Unsafe to place in public docs samples (side-effecting).

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/auto-fire.ts` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"auto-fire"`` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## auto-surface

URL: https://www.arcblock.io/en/docs/aup/widgets/auto-surface/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

AFS directory pattern renderer. Resolves a source path server-side, classifies common shapes, and expands into a presentable tree.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP / DSL `type: "auto-surface"`. Registered page in showcase `auto-surface`.

## Surfaces

Interactive Web. Client switch maps to `renderAupView` after expansion.

## Fallback

No degradation chain. Expansion failures must be visible (server path).

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`auto-surface`)` |
| Expansion | `providers/runtime/ui/src/auto-surface.ts; `aup-preview-tree.ts`` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"auto-surface"`` |
| Showcase | `blocklets/showcase/.aup/pages/auto-surface.json; app.json route `auto-surface`` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `auto-surface` under `blocklets/showcase`

---

## block-revealer

URL: https://www.arcblock.io/en/docs/aup/widgets/block-revealer/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Animated block reveal: a colored block slides across to reveal content underneath. Dual path: interactive AUP renderer and Web Device layout widget package.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP node `type: "block-revealer"`, or Web Device layout `widget` mount from `providers/runtime/web-device/widgets/block-revealer/`.

## Surfaces

Interactive Web AUP + Web Device client widget. Not document static RENDERERS.

## Fallback

No JS → no animation. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`block-revealer`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/block-revealer.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/block-revealer/manifest.json` |
| Tests | `providers/runtime/ui/test/renderers/batch-widgets.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## blocklet-embed

URL: https://www.arcblock.io/en/docs/aup/widgets/blocklet-embed/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Embeds another blocklet page tree into the host tree. Expanded server-side by `portal-setup` / `expandTree`; failure is always visible (never blank).

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree `type: "blocklet-embed"` with target blocklet identity. Not a layout-component.

## Surfaces

Interactive Web session after server expansion. Unexpanded client sees unknown type.

## Fallback

Expansion error node (visible). No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Expansion | `providers/runtime/ui/src/portal-setup.ts (`blocklet-embed` expand path)` |
| Path safety | `providers/runtime/ui/src/path-safety.ts` |
| Tests | `providers/runtime/ui/test/blocklet-embed*.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## breadcrumb

URL: https://www.arcblock.io/en/docs/aup/widgets/breadcrumb/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Server-provided breadcrumb trail (`items` with label/href). AUP UI component factory in `packages/aup/src/components/breadcrumb.ts`. Distinct from site layout-component `page-breadcrumb`.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "breadcrumb"` via `createBreadcrumb` or raw node. Path parsing must stay server-side (Renderer Purity).

## Surfaces

Interactive Web AUP component. Not Web Device layout `page-breadcrumb`.

## Fallback

No degradation chain. Empty items → empty trail.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts (UI components section)` |
| Factory | `packages/aup/src/components/breadcrumb.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/breadcrumb.ts` |
| Tests | `packages/aup/test/components/breadcrumb.test.ts; providers/runtime/ui/test/widget-renderers-993.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## broadcast

URL: https://www.arcblock.io/en/docs/aup/widgets/broadcast/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Live/broadcast chrome composition: semantic roles (live-badge, clock, lower-third, ticker, …) expand into standard nodes and placements.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree `type: "broadcast"`. Document target also registers a static renderer.

## Surfaces

Interactive Web + document RENDERERS (`broadcast`).

## Fallback

No shared degradation chain. Experimental for public product claims.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Interactive renderer | `providers/runtime/ui/src/web-page/renderers/broadcast.ts` |
| Document renderer | `providers/runtime/web-device/src/renderer/primitives/broadcast.ts; RENDERERS in render-to-html.ts` |
| Matrix | `blocklets/arcblock/content/docs/aup/capability-matrix.md §2` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## camera-preview

URL: https://www.arcblock.io/en/docs/aup/widgets/camera-preview/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Native-only live camera viewfinder widget (iOS/Android design path). Registered so structure verify accepts the type; intentionally not a web/cli DeviceCaps primitive.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree `type: "camera-preview"` for native targets that implement it. No WebView degrade path by design.

## Surfaces

Native mobile (not interactive web-full, not document). Web client has no dedicated case → unknown.

## Fallback

No web renderer; no shared degradation chain. Do not claim web document support.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts (`camera-preview` in `AUP_WIDGETS`)` |
| Contract test | `packages/aup/test/aup-camera-preview-registration.test.ts` |
| Caps note | `DeviceCaps presets fill primitives only — camera-preview never appears in caps maps` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## chip

URL: https://www.arcblock.io/en/docs/aup/widgets/chip/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Compact label chip with optional count badge, semantic color, and dismissible affordance.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "chip"` via `createChip` or raw node (`label`, `color`, `count`, `dismissible`).

## Surfaces

Interactive Web.

## Fallback

No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Factory | `packages/aup/src/components/chip.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/chip.ts` |
| Tests | `providers/runtime/ui/test/chip-renderer.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## comments-surface

URL: https://www.arcblock.io/en/docs/aup/widgets/comments-surface/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Platform comment thread surface (compose, list, reactions, pagination). AUP wrapper wires props and events; host-agnostic bundle implements the browser DOM.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "comments-surface"` or Web Device site-level mount when `.web/comments` enables comments (site-server path). Front matter can suppress per item.

## Surfaces

Interactive site / AUP session. Requires identity/auth configuration when `requireAuth` is set.

## Fallback

Site comments flag off → not mounted. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| AUP renderer wrapper | `providers/runtime/ui/src/web-page/renderers/comments-surface.ts` |
| Bundle | `providers/runtime/ui/src/web-page/surfaces/comments-surface-bundle.ts` |
| Web Device runtime | `providers/runtime/web-device/src/comments-surface-runtime.ts; site-server.ts comments mount` |
| Showcase | `blocklets/showcase/.aup/pages/comments.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `comments` under `blocklets/showcase`

---

## deck

URL: https://www.arcblock.io/en/docs/aup/widgets/deck/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Slide deck presentation surface for multi-slide content. Web Device slides path pairs front matter `slides: true` with the slides widget package.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "deck"` in interactive apps; document/slides via content front matter + `providers/runtime/web-device/widgets/slides/` and `slides.ts`.

## Surfaces

Interactive Web + document partial renderer + slides player.

## Fallback

Without slides marking, content stays ordinary document. See markdown-slides docs.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Interactive renderer | `providers/runtime/ui/src/web-page/renderers/deck.ts` |
| Document renderer | `providers/runtime/web-device/src/renderer/primitives/deck.ts; RENDERERS` |
| Slides widget | `providers/runtime/web-device/widgets/slides/manifest.json; src/slides.ts` |
| Matrix | `capability-matrix.md §2 `deck` — verified path #290` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

Public document-target behavior is covered by existing verified docs (see Related). This page is the AUP widget taxonomy entry; do not treat Showcase as a live embed on www.arcblock.io.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Related doc: /en/docs/web-device/markdown-slides/

---

## entity-overview

URL: https://www.arcblock.io/en/docs/aup/widgets/entity-overview/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Multi-card grid wrapper for the top of detail pages. Cards commonly embed `key-value-list` and related overview fields.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "entity-overview"` with child cards. Registry category `component`.

## Surfaces

Interactive Web. Not document RENDERERS.

## Fallback

No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`entity-overview`)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/entity-overview.ts` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"entity-overview"`` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## finance-chart

URL: https://www.arcblock.io/en/docs/aup/widgets/finance-chart/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Trading-oriented chart presentation (candlestick/OHLC/etc.) implemented with TradingView Lightweight Charts on the interactive Web client. In the client switch, finance variants are selected off the `chart` primitive by `props.variant`; the name remains an `AUP_WIDGETS` entry for type acceptance.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

Prefer authoring portable intent via `chart` + finance `variant` on interactive Web. Standalone `type: "finance-chart"` is registered in `AUP_WIDGETS` but is not a separate `case` in core.ts (falls through to unknown unless expanded).

## Surfaces

Interactive Web chart path. Document target: `chart` is unsupported with table/text reshape — not a finance-chart sample.

## Fallback

Document chart reshape is for primitive `chart`, not a finance widget contract. No `DEGRADATION_CHAINS.finance-chart`.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts (`finance-chart`)` |
| Renderer fragment | `providers/runtime/ui/src/web-page/renderers/finance-chart.ts` |
| Dispatch | `providers/runtime/ui/src/web-page/core.ts `case "chart"` finance variants → `renderAupFinanceChart`` |
| Showcase (chart page) | `blocklets/showcase/.aup/pages/finance.json (uses chart nodes)` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `finance` under `blocklets/showcase`

---

## frame

URL: https://www.arcblock.io/en/docs/aup/widgets/frame/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Sandboxed iframe / embed isolation for page fragments. Interactive sessions may enable a same-origin capability bridge; document embeds stay link/iframe constrained.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "frame"`; Markdown `::embed` may compile toward frame-shaped nodes on the document target.

## Surfaces

Interactive Web + document partial renderer. Trust boundaries apply.

## Fallback

Rejected/unknown embed URLs degrade to plain links on the document path.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Interactive renderer | `providers/runtime/ui/src/web-page/renderers/frame.ts` |
| Document renderer | `providers/runtime/web-device/src/renderer/primitives/frame.ts; RENDERERS; content-embed.ts` |
| Matrix | `capability-matrix.md §2 `frame` — verified #290` |
| Related docs | `frames-bridges-embedded-surfaces; web-device/markdown-embeds` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

Public document-target behavior is covered by existing verified docs (see Related). This page is the AUP widget taxonomy entry; do not treat Showcase as a live embed on www.arcblock.io.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Related doc: /en/docs/aup/frames-bridges-embedded-surfaces/
- Related doc: /en/docs/web-device/markdown-embeds/

---

## globe

URL: https://www.arcblock.io/en/docs/aup/widgets/globe/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

3D globe map presentation (MapLibre GL path on interactive Web). Showcase authors `type: "globe"`. Shared degradation chain: globe → map → media → text.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP tree `type: "globe"`, or `map` with `props.variant: "globe"` (client map case). Showcase page `globe`.

## Surfaces

Interactive Web (globe/map renderers). Document: unsupported via chain (map→media→text).

## Fallback

`DEGRADATION_CHAINS.globe = ["map","media","text"]` in packages/aup/src/degradation.ts.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Globe renderer | `providers/runtime/ui/src/web-page/renderers/globe.ts` |
| Map variant dispatch | `providers/runtime/ui/src/web-page/core.ts case `"map"` + variant globe` |
| Degradation | `packages/aup/src/degradation.ts` |
| Showcase | `blocklets/showcase/.aup/pages/globe.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `globe` under `blocklets/showcase`

---

## hero-widget

URL: https://www.arcblock.io/en/docs/aup/widgets/hero-widget/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Rich hero section with multiple layout styles (cube, grid, showcase, stack, timeline, orbit, tree). Available as AUP node and Web Device widget package.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "hero-widget"` or layout `widget` mount from `web-device/widgets/hero-widget/`.

## Surfaces

Interactive Web / layout widget. Not document RENDERERS. Not a site layout-component like `landing-hero`.

## Fallback

No JS → static empty host. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`hero-widget`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/hero-widget.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/hero-widget/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## key-value-list

URL: https://www.arcblock.io/en/docs/aup/widgets/key-value-list/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Compact two-column label/value layout for entity overviews and detail pages.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "key-value-list"`. Showcase `prim-key-value-list`.

## Surfaces

Interactive Web.

## Fallback

No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`key-value-list`)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/key-value-list.ts` |
| Showcase | `blocklets/showcase/.aup/pages/prim-key-value-list.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `prim-key-value-list` under `blocklets/showcase`

---

## moonphase

URL: https://www.arcblock.io/en/docs/aup/widgets/moonphase/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Moon phase visualization for a single date or full month grid (SVG illumination + phase name).

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "moonphase"` with props `mode` (`today`|`month`), `date`, `locale`. Showcase route `moonphase`.

## Surfaces

Interactive Web. Not document RENDERERS.

## Fallback

No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`moonphase`)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/moonphase.ts` |
| Showcase | `blocklets/showcase/.aup/pages/moonphase.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `moonphase` under `blocklets/showcase`

---

## natal-chart

URL: https://www.arcblock.io/en/docs/aup/widgets/natal-chart/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Astrological natal chart visualization powered by @astrodraw/astrochart on the interactive Web client.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "natal-chart"`. Showcase route `natal`.

## Surfaces

Interactive Web. Not document RENDERERS.

## Fallback

No degradation chain. Treat as experimental/demo-oriented.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`natal-chart`)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/natal-chart.ts` |
| Showcase | `blocklets/showcase/.aup/pages/natal.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `natal` under `blocklets/showcase`

---

## pagination

URL: https://www.arcblock.io/en/docs/aup/widgets/pagination/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Page controls for collection lists (`page`, `pageSize`, `total`) with optional `onChange` events. Also mirrored as a Web Device surface package for site collection indexes.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "pagination"` via `createPagination`, or Web Device surface `providers/runtime/web-device/surfaces/pagination/`.

## Surfaces

Interactive Web AUP + Web Device collection surface. Showcase `list-pagination`.

## Fallback

No shared degradation chain. Surface empty when totals are zero depends on host.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Factory | `packages/aup/src/components/pagination.ts` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/pagination.ts` |
| Web Device surface | `providers/runtime/web-device/surfaces/pagination/manifest.json` |
| Showcase | `blocklets/showcase/.aup/pages/list-pagination.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `list-pagination` under `blocklets/showcase`

---

## photo-story

URL: https://www.arcblock.io/en/docs/aup/widgets/photo-story/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Visual storytelling with scroll, slideshow, and autoplay modes. Dual path: AUP renderer and Web Device widget package.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "photo-story"` or layout widget mount from `web-device/widgets/photo-story/`.

## Surfaces

Interactive Web / layout widget. Not document RENDERERS.

## Fallback

No JS → no motion modes. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`photo-story`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/photo-story.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/photo-story/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## post-editor

URL: https://www.arcblock.io/en/docs/aup/widgets/post-editor/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Built-in create/edit surface for posts collections (title+body form, modal compose, server `PostsHandler`).

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "post-editor"` with `props.mode` and `props.postSource`. Write path — not a read-only docs sample.

## Surfaces

Interactive Web session with posts backend.

## Fallback

No degradation chain. Requires auth and collection permissions.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/post-editor.ts` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"post-editor"`` |
| Handler | `providers/runtime/ui/src/posts-handler.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## progress-bar-3d

URL: https://www.arcblock.io/en/docs/aup/widgets/progress-bar-3d/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

CSS 3D progress bar with perspective, fill animation, and style variants (striped/heat/dotted).

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "progress-bar-3d"` or Web Device widget package mount.

## Surfaces

Interactive Web / layout widget.

## Fallback

No shared degradation chain. Without JS, static markup only if host emits it.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`progress-bar-3d`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/progress-bar-3d.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/progress-bar-3d/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## scroll-explainer

URL: https://www.arcblock.io/en/docs/aup/widgets/scroll-explainer/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Step-by-step scroll-driven explainer with text steps and sticky media. Dual AUP + Web Device widget path.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "scroll-explainer"` or layout widget from `web-device/widgets/scroll-explainer/`.

## Surfaces

Interactive Web / layout widget.

## Fallback

No JS → no scroll coupling. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`scroll-explainer`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/scroll-explainer.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/scroll-explainer/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## searchable-dropdown

URL: https://www.arcblock.io/en/docs/aup/widgets/searchable-dropdown/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Dropdown with optional search and option list (pre-fetched or `src` collection-query path). Filtering for large sets is server-side.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "searchable-dropdown"` via `createSearchableDropdown` (`options`/`value`/`searchable`/`placeholder`, optional `src`, `onChange`).

## Surfaces

Interactive Web.

## Fallback

No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Factory | `packages/aup/src/components/searchable-dropdown.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/searchable-dropdown.ts` |
| Tests | `packages/aup/test/components/searchable-dropdown.test.ts; widget-renderers-993.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## skills

URL: https://www.arcblock.io/en/docs/aup/widgets/skills/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Drop-in UI for managing an `@aigne/afs-skills` mount. Expanded server-side into searchable list + create toolbar; never reaches a dedicated client renderer as `skills`.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "skills"` with `src` to the skills mount. Events: `select`, `create`.

## Surfaces

Interactive Web after `expandSkills` (skills-surface.ts).

## Fallback

No client case for raw `skills` type (expands away). No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`skills`)` |
| Expansion | `providers/runtime/ui/src/skills-surface.ts (`expandSkills`)` |
| Portal wiring | `providers/runtime/ui/src/portal-setup.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## terminal

URL: https://www.arcblock.io/en/docs/aup/widgets/terminal/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

xterm.js WebSocket terminal widget with its own endpoint protocol — independent of the AUP session protocol.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "terminal"` with `props.endpoint` (and optional rows/font). Requires live connection.

## Surfaces

Interactive Web only. Snapshot mode shows a placeholder.

## Fallback

Missing endpoint → placeholder. No shared degradation chain. Trust/endpoint review required.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`terminal`)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/terminal.ts` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"terminal"`` |
| Related | `frames-bridges-embedded-surfaces (terminal boundary note)` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## text-highlight

URL: https://www.arcblock.io/en/docs/aup/widgets/text-highlight/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Animated text highlighting (reveal/glow and related modes). Dual AUP + Web Device widget path.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "text-highlight"` or layout widget from `web-device/widgets/text-highlight/`.

## Surfaces

Interactive Web / layout widget.

## Fallback

No JS → no animation. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`text-highlight`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/text-highlight.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/text-highlight/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## text-image-expand

URL: https://www.arcblock.io/en/docs/aup/widgets/text-image-expand/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Interactive text-over-image component that expands on hover/click or scroll coupling. Dual AUP + Web Device widget path.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "text-image-expand"` or layout widget from `web-device/widgets/text-image-expand/`.

## Surfaces

Interactive Web / layout widget.

## Fallback

No JS → static host only. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`text-image-expand`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/text-image-expand.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/text-image-expand/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## ticker

URL: https://www.arcblock.io/en/docs/aup/widgets/ticker/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Horizontal ticker for child items in scroll, flip, or static modes.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "ticker"` with children items and mode props. Document RENDERERS includes ticker.

## Surfaces

Interactive Web + document RENDERERS.

## Fallback

No shared degradation chain. Experimental for product claims.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Interactive renderer | `providers/runtime/ui/src/web-page/renderers/ticker.ts` |
| Document renderer | `providers/runtime/web-device/src/renderer/primitives/ticker.ts; RENDERERS` |
| Matrix | `capability-matrix.md §2` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## tooltip

URL: https://www.arcblock.io/en/docs/aup/widgets/tooltip/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Tooltip wrapper with content, placement, and trigger. Anchors wrap children nodes.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "tooltip"` via `createTooltip` (`content`, `placement`, `trigger`, children).

## Surfaces

Interactive Web. Showcase uses tooltips inside key-value / tx-detail pages.

## Fallback

No degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Factory | `packages/aup/src/components/tooltip.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/tooltip.ts` |
| Tests | `packages/aup/test/components/tooltip.test.ts` |
| Showcase usage | `blocklets/showcase/.aup/pages/prim-key-value-list.json; tx-detail.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

No docs-safe live sample on this site yet. Use the listed Showcase source / factory API as a source-only reference. Run Showcase locally if you need interactive acceptance.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `prim-key-value-list` under `blocklets/showcase`

---

## type-block

URL: https://www.arcblock.io/en/docs/aup/widgets/type-block/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Animated typing / shuffle / matrix-style typographic block. Dual AUP + Web Device script-tag widget path.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "type-block"` or layout widget from `web-device/widgets/type-block/`.

## Surfaces

Interactive Web / layout widget.

## Fallback

No JS → no animation. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`type-block`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/type-block.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/type-block/manifest.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## url-default

URL: https://www.arcblock.io/en/docs/aup/widgets/url-default/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Invisible client helper that canonicalizes a pathname on mount via `history.replaceState` when a route is missing a capture segment.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "url-default"` with props `match` and `redirect` (already template-resolved).

## Surfaces

Interactive Web only. Renders nothing visible.

## Fallback

No degradation chain. Side-effecting — not a public docs sample.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/url-default.ts` |
| Interactive switch | `providers/runtime/ui/src/web-page/core.ts case `"url-default"`` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Not docs-safe.** Side effects, write paths, native-only surfaces, or trust-sensitive endpoints make a public sample inappropriate. Keep this page as a boundary and evidence index.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## webgl-hero

URL: https://www.arcblock.io/en/docs/aup/widgets/webgl-hero/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

WebGL decorative background with many shader modes. Dual AUP + Web Device script-tag widget path.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "webgl-hero"` or layout `widget` mount from `web-device/widgets/webgl-hero/`.

## Surfaces

Interactive Web / layout widget. Not document capability.

## Fallback

No WebGL/JS → empty decoration. No shared degradation chain.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`webgl-hero`)` |
| AUP renderer | `providers/runtime/ui/src/web-page/renderers/webgl-hero.ts` |
| Web Device widget | `providers/runtime/web-device/widgets/webgl-hero/manifest.json` |
| Matrix | `capability-matrix.md §2 webgl-hero row` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## wm

URL: https://www.arcblock.io/en/docs/aup/widgets/wm/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Window-manager container for multi-surface desktop/panel layouts inside an interactive AUP Web session.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "wm"` with `wm-surface` children and strategy/dock props. Showcase `wm-desktop`.

## Surfaces

Interactive Web session only.

## Fallback

No shared degradation chain. Complex session semantics — not a static sample.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`wm` examples)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/wm.ts` |
| Session logic | `providers/runtime/ui/src/aup-wm-session-logic.ts; wm-layout.ts` |
| Showcase | `blocklets/showcase/.aup/pages/wm-desktop.json` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `wm-desktop` under `blocklets/showcase`

---

## wm-surface

URL: https://www.arcblock.io/en/docs/aup/widgets/wm-surface/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

A window/surface inside a `wm` container (desktop-widget mode, dock/panel geometry, nested content).

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

Child of `wm`: `type: "wm-surface"` with title/surfaceName/dock props. Not a standalone document component.

## Surfaces

Interactive Web, only meaningful under `wm`.

## Fallback

Standalone node is not a document RENDERERS entry; client treats unknown outside wm wiring.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`wm-surface`)` |
| Renderer / patches | `providers/runtime/ui/src/web-page/renderers/wm.ts; core.ts wm-surface patch paths` |
| Session logic | `providers/runtime/ui/src/aup-wm-session-logic.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`
- Showcase route (local ARC): `wm-desktop` under `blocklets/showcase`

---

## xeyes

URL: https://www.arcblock.io/en/docs/aup/widgets/xeyes/

**AUP Web-only widget — not a cross-device primitive; not a Web Device layout component.**

The name is registered in `AUP_WIDGETS` (`packages/aup/src/aup-types.ts`). It can be accepted by structure verification and implemented by a Web runtime (or native target where noted). It is **not** one of the 18 cross-device `AUP_PRIMITIVES`, does **not** enter `DeviceCaps.primitives` via `fillPrimitives`, and is **not** a Web Device theme/site layout component (for example `content-card` or `page-breadcrumb`).

## Purpose

Classic X11-style eyes that follow the pointer. Demo/component widget.

## Boundaries

- Do not document this type as a portable primitive.
- Do not mix it with Web Device layout-component reference pages under `widgets/`.
- A parser-accepted name is not a portability or product-readiness claim.

## Author entry

AUP `type: "xeyes"` with eyes/size/color props.

## Surfaces

Interactive Web.

## Fallback

No degradation chain. Not a product surface claim.

## Evidence

| Source | Path |
| --- | --- |
| Registration | `packages/aup/src/aup-types.ts` |
| Registry | `providers/runtime/ui/src/aup-registry.ts (`xeyes`)` |
| Renderer | `providers/runtime/ui/src/web-page/renderers/xeyes.ts` |
| Tests | `providers/runtime/ui/test/renderers/batch-widgets.test.ts` |

Paths are relative to the Arc repository checkout used for this documentation baseline.

## Sample

**Internal / experimental for public samples.** Registration and renderers exist in the interactive Web runtime (and sometimes Web Device widget packages), but this site does not ship a docs-safe live sample. Do not infer product readiness from the type name alone.

## Related

- [Widgets hub](../) — navigation only
- [Primitive taxonomy](../../primitive-support-matrix/) — 18 vs 42 boundary
- [Custom primitives and Web widgets](../../custom-primitives-web-widgets/)
- Internal matrix: `docs/aup/capability-matrix.md`

---

## Blockchain Guide

URL: https://www.arcblock.io/en/docs/blockchain/

---

## Blockchain SDK (Node.js)

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/

---

## API Reference

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/api-reference-8cbd10/

Welcome to the OCAP Client API Reference. This section provides a comprehensive and searchable reference for all available classes, methods, and data types. Whether you're looking for the specifics of a GraphQL method, the parameters for a transaction helper, or the structure of a response object, you'll find the detailed information you need here.

Explore the following sections to dive deeper into the client's capabilities:

::::card-group
::link-card{title="Helper Methods" description="Detailed documentation for core client helper methods, such as `getType`, `decodeTx`, and `fromUnitToToken`." icon="code" href="/en/docs/blockchain-sdk-nodejs/api-reference-client-methods-8cbd10/"}
::link-card{title="Query & Mutation Methods" description="A complete list of all available GraphQL query and mutation methods for reading from and writing to the chain." icon="database" href="/en/docs/blockchain-sdk-nodejs/api-reference-query-mutation-methods-8cbd10/"}
::link-card{title="High-level API" description="Reference for high-level functions that simplify common workflows like transferring tokens and managing assets." icon="zap" href="/en/docs/blockchain-sdk-nodejs/api-reference-transaction-helpers-8cbd10/"}
::link-card{title="Low-level API" description="Learn how to manually construct, sign, and send transactions for full control over the transaction lifecycle." icon="cpu" href="/en/docs/blockchain-sdk-nodejs/api-reference-low-level-api-8cbd10/"}
::link-card{title="Data Types" description="Defines all the custom data structures, input parameters, and response objects used throughout the client API." icon="box" href="/en/docs/blockchain-sdk-nodejs/api-reference-data-types-8cbd10/"}
::::

---

## Helper Methods

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/api-reference-client-methods-8cbd10/

The `GraphQLClient` class is the primary interface for interacting with an OCAP-powered blockchain. It provides a comprehensive set of methods for querying the chain state, sending transactions, and subscribing to real-time events. It is designed to work seamlessly in both Node.js and browser environments.

**Client Initialization**

```javascript
const GraphQLClient = require('@ocap/client');

// Connect to the Beta chain
const client = new GraphQLClient('https://beta.abtnetwork.io/api');

(async () => {
  const res = await client.getChainInfo();
  console.log('Connected to chain:', res.info.network);
})();
```

This section provides a detailed reference for the core helper methods of the `GraphQLClient` class.

## Constructor

### new GraphQLClient(endpoint, autoInit)

Creates a new instance of the `GraphQLClient`.

<strong>Parameters</strong>

- **endpoint** `string` *(required)* — The absolute URL of the GraphQL endpoint for the blockchain node (e.g., https://beta.abtnetwork.io/api).
- **autoInit** `boolean` (default: `true`) — If true, the client will automatically fetch and cache essential chain information (the "context") upon initialization. This is recommended for most use cases.

<strong>Example</strong>

**Creating a Client Instance**

```javascript
const client = new GraphQLClient('https://beta.abtnetwork.io/api', true);
```

## Core Methods

These methods provide fundamental functionality for interacting with the client and the chain.

### getContext()

Fetches and caches essential chain information, such as the chain ID, native token details, and transaction fee configurations. This method is called automatically if `autoInit` is enabled in the constructor. Subsequent calls will return the cached context.

<strong>Returns</strong>

- **Promise<object>** `object` — A promise that resolves to the context object containing chain metadata.
  - **chainId** `string` — The unique identifier of the blockchain network.
  - **consensus** `string` — The consensus engine version.
  - **token** `object` — Information about the native token.
    - **address** `string` — The address of the native token contract.
    - **decimal** `number` — The number of decimal places for the native token.
    - **symbol** `string` — The symbol of the native token (e.g., TBA).
  - **txConfig** `object` — Transaction fee and gas configuration.

<strong>Example</strong>

**Fetching Chain Context**

```javascript
async function logChainToken() {
  const context = await client.getContext();
  console.log(`Native Token Symbol: ${context.token.symbol}`);
}

logChainToken();
```

### setGasPayer(wallet)

Configures a wallet to act as a "gas payer." When set, this wallet will sponsor the transaction fees for transactions sent through this client instance, enabling gasless experiences for users. For more details, see the [Gas Payment](/en/docs/blockchain-sdk-nodejs/core-concepts-gas-payment-8cbd10/) concept guide.

<strong>Parameters</strong>

- **wallet** `WalletObject` *(required)* — A wallet object with address, publicKey, and secretKey properties, equipped with a sign method.

### decodeTx(input)

Deserializes a transaction from various formats into a human-readable JavaScript object.

<strong>Parameters</strong>

- **input** `Buffer | string` *(required)* — The transaction data to decode. Can be a Buffer or a string in hex, base58, or base64 format.

<strong>Returns</strong>

- **object** `object` — The decoded transaction object.

### getType(name)

Retrieves the Protobuf message class for a given type name. This is useful for advanced scenarios where you need to manually construct or inspect Protobuf messages.

<strong>Parameters</strong>

- **name** `string` *(required)* — The name of the Protobuf message type (e.g., 'Transaction', 'TransferTx').

<strong>Returns</strong>

- **class | null** `object` — The message class constructor, or null if not found.

## Event Subscription

The client supports real-time event subscriptions over WebSockets, allowing your application to react instantly to on-chain events.

### subscribe(topic, callback)

Establishes a WebSocket connection and subscribes to a specific event topic.

<strong>Parameters</strong>

- **topic** `string` *(required)* — The event topic to subscribe to (e.g., 'newBlock', 'tx:transfer').
- **callback** `function` *(required)* — A function to execute when an event is received. It receives the event payload as its only argument.

### unsubscribe(topic, callback)

Removes a previously registered callback for a specific topic.

<strong>Parameters</strong>

- **topic** `string` *(required)* — The event topic to unsubscribe from.
- **callback** `function` *(required)* — The specific callback function to remove.

<strong>Example</strong>

**Subscribing to New Blocks**

```javascript
const handleNewBlock = (block) => {
  console.log(`New block received! Height: ${block.height}`);

  // Unsubscribe after receiving one block
  client.unsubscribe('newBlock', handleNewBlock);
  console.log('Unsubscribed from newBlock events.');
};

client.subscribe('newBlock', handleNewBlock);
console.log('Subscribed to newBlock events...');
```

## Token Utility Methods

These helpers simplify conversions between the human-readable token amount and the on-chain base unit representation.

### fromUnitToToken(value)

Converts a value from the chain's base unit (a large integer string) to a standard decimal string, based on the native token's decimal places.

<strong>Parameters</strong>

- **value** `string` *(required)* — The amount in the chain's base unit.

<strong>Returns</strong>

- **string** `string` — The amount in the standard token unit.

### fromTokenToUnit(amount)

Converts a standard decimal amount into the chain's base unit representation (a BN.js instance).

<strong>Parameters</strong>

- **amount** `number | string` *(required)* — The token amount in its standard decimal form.

<strong>Returns</strong>

- **BN** `object` — A BN.js instance representing the value in the chain's base unit.

<strong>Example</strong>

**Token Amount Conversion**

```javascript
async function convertToken() {
  // Convert 100 TBA to its base unit
  const unitAmount = await client.fromTokenToUnit(100);
  console.log(`100 TBA is ${unitAmount.toString()} in base units.`);

  // Convert it back
  const tokenAmount = await client.fromUnitToToken(unitAmount.toString());
  console.log(`${unitAmount.toString()} base units is ${tokenAmount} TBA.`);
}

convertToken();
```

## Method Discovery

The client dynamically generates methods for every transaction type supported by the connected OCAP node. These discovery methods allow you to programmatically list all available transaction-related functions.

### getTxSendMethods()

Returns an array of all available `send...Tx` method names. These methods handle the full lifecycle of signing and sending a transaction.

### getTxEncodeMethods()

Returns an array of all available `encode...Tx` method names. These methods prepare and serialize a transaction into a buffer, but do not sign it.

### getTxSignMethods()

Returns an array of all available `sign...Tx` method names. These methods encode and then sign a transaction, returning the signed transaction object.

### getTxMultiSignMethods()

Returns an array of all available `multiSign...Tx` method names, used for multi-signature workflows.

<strong>Example</strong>

**Listing Available Transaction Methods**

```javascript
const sendMethods = client.getTxSendMethods();
console.log('Available send methods:', sendMethods);
// Example output: [ 'sendPokeTx', 'sendTransferTx', ... ]
```

---

## Data Types

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/api-reference-data-types-8cbd10/

This section provides a comprehensive reference for all the custom data structures, input parameters, and response objects used throughout the OCAP Client API. Understanding these types is essential for effectively interacting with the OCAP blockchain.

## Core Types

These are fundamental data structures used across various API calls.

### Any

A generic container for protobuf messages, allowing for flexible data structures.

- **typeUrl** `string` — A URL-like string that uniquely identifies the type of the serialized message.
- **value** `string` — The serialized message content as a string.

### Multisig

Represents a multi-signature, often used in transactions requiring multiple approvals.

- **signer** `string` — The address of the signer.
- **pk** `string` — The public key of the signer.
- **signature** `string` — The signature generated by the signer.
- **delegator** `string` — The address of the delegator, if the signature is delegated.
- **data** `Any` — Optional arbitrary data associated with the signature.

### PageInfo

Contains pagination details for list-based query responses.

- **cursor** `string` — A cursor for fetching the next page of results.
- **next** `boolean` — Indicates if there is a next page of results available.
- **total** `number` — The total number of items matching the query.

### StateContext

Provides context about the creation and last modification of a state object.

- **genesisTx** `TransactionInfo` — The transaction that created this state object.
- **renaissanceTx** `TransactionInfo` — The transaction that last updated this state object.
- **genesisTime** `string` — The timestamp when the state object was created.
- **renaissanceTime** `string` — The timestamp when the state object was last updated.

### Wallet Objects

These types define the structure of wallets used for signing transactions.

#### WalletObject

- **publicKey** `string`
- **secretKey** `string`
- **type** `WalletTypeObject`

#### WalletTypeObject

- **pk** `number`
- **role** `number`
- **hash** `number`
- **address** `number` — Defaults to base58btc

#### WalletType

- **pk** `KeyType`
- **hash** `HashType`
- **address** `EncodingType`
- **role** `RoleType`

## Input & Filter Types

These objects are used to provide parameters and filters for GraphQL queries.

### General Filter Inputs

- **AccountFilterInput** `object`
  - **accounts** `array<string>`
- **AddressFilterInput** `object`
  - **sender** `string`
  - **receiver** `string`
  - **direction** `Direction`
- **AssetFilterInput** `object`
  - **assets** `array<string>`
- **DelegationFilterInput** `object`
  - **delegations** `array<string>`
- **FactoryFilterInput** `object`
  - **factories** `array<string>`
- **RangeFilterInput** `object`
  - **from** `string`
  - **to** `string`
- **RollupFilterInput** `object`
  - **rollups** `array<string>`
- **StakeFilterInput** `object`
  - **stakes** `array<string>`
- **TimeFilterInput** `object`
  - **startDateTime** `string`
  - **endDateTime** `string`
  - **field** `string`
- **TokenFactoryFilterInput** `object`
  - **tokenFactories** `array<string>`
- **TokenFilterInput** `object`
  - **tokens** `array<string>`
- **TxFilterInput** `object`
  - **txs** `array<string>`
- **TypeFilterInput** `object`
  - **types** `array<string>`
- **ValidatorFilterInput** `object`
  - **validators** `array<string>`
- **ValidityFilterInput** `object`
  - **validity** `Validity`

### Pagination Inputs

#### PageInput

- **cursor** `string`
- **size** `number`
- **order** `array<PageOrderInput>`

#### PageOrderInput

- **field** `string`
- **type** `string`

### Request-Specific Inputs

These objects are used as parameters for specific query and mutation methods.

- **RequestEstimateGasInput** `object`
  - **typeUrl** `string`
  - **tx** `string`
- **RequestGetAccountStateInput** `object`
  - **address** `string`
  - **keys** `array<string>`
  - **height** `number`
  - **traceMigration** `boolean`
- **RequestGetAccountTokensInput** `object`
  - **address** `string`
  - **token** `string`
- **RequestGetBlockInput** `object`
  - **height** `number`
- **RequestGetBlocksInput** `object`
  - **paging** `PageInput`
  - **heightFilter** `RangeFilterInput`
  - **emptyExcluded** `boolean`
- **RequestListTransactionsInput** `object`
  - **paging** `PageInput`
  - **timeFilter** `TimeFilterInput`
  - **addressFilter** `AddressFilterInput`
  - **typeFilter** `TypeFilterInput`
  - **validityFilter** `ValidityFilterInput`
  - **factoryFilter** `FactoryFilterInput`
  - **tokenFilter** `TokenFilterInput`
  - **assetFilter** `AssetFilterInput`
  - **accountFilter** `AccountFilterInput`
  - **txFilter** `TxFilterInput`
  - **rollupFilter** `RollupFilterInput`
  - **stakeFilter** `StakeFilterInput`
  - **delegationFilter** `DelegationFilterInput`
  - **tokenFactoryFilter** `TokenFactoryFilterInput`

## State Objects

These types represent the state of various entities on the blockchain, such as accounts, assets, and tokens.

### AccountState

Represents the state of a user account.

- **balance** `string`
- **nonce** `string`
- **numTxs** `string`
- **address** `string`
- **pk** `string`
- **type** `WalletType`
- **moniker** `string`
- **context** `StateContext`
- **issuer** `string`
- **gasBalance** `string`
- **migratedTo** `array<string>`
- **migratedFrom** `array<string>`
- **numAssets** `string`
- **tokens** `array<IndexedTokenInput>`
- **data** `Any`

### AssetState

Represents the state of a non-fungible asset (NFT).

- **address** `string`
- **owner** `string`
- **moniker** `string`
- **readonly** `boolean`
- **transferrable** `boolean`
- **ttl** `number`
- **consumedTime** `string`
- **issuer** `string`
- **parent** `string`
- **endpoint** `NFTEndpoint`
- **display** `NFTDisplay`
- **tags** `array<string>`
- **context** `StateContext`
- **data** `Any`

### AssetFactoryState

Represents the state of an asset factory, which is used to mint new assets.

- **address** `string`
- **owner** `string`
- **name** `string`
- **description** `string`
- **settlement** `string`
- **limit** `number`
- **trustedIssuers** `array<string>`
- **input** `IndexedFactoryInput`
- **output** `CreateAssetTx`
- **hooks** `array<AssetFactoryHook>`
- **data** `Any`
- **context** `StateContext`
- **balance** `string`
- **tokens** `array<IndexedTokenInput>`
- **numMinted** `number`
- **display** `NFTDisplay`
- **lastSettlement** `string`

### DelegateState

Represents the state of a delegation, where one account authorizes another to perform actions on its behalf.

- **address** `string`
- **ops** `array<DelegateState_OpsEntry>`
- **from** `string`
- **to** `string`
- **context** `StateContext`
- **data** `Any`

### StakeState

Represents the state of a stake, which can involve tokens or assets.

- **address** `string`
- **sender** `string`
- **receiver** `string`
- **tokens** `array<IndexedTokenInput>`
- **assets** `array<string>`
- **revocable** `boolean`
- **message** `string`
- **revokeWaitingPeriod** `number`
- **revokedTokens** `array<IndexedTokenInput>`
- **revokedAssets** `array<string>`
- **slashers** `array<string>`
- **nonce** `string`
- **context** `StateContext`
- **data** `Any`

### TokenState

Represents the state of a fungible token.

- **address** `string`
- **issuer** `string`
- **name** `string`
- **description** `string`
- **symbol** `string`
- **unit** `string`
- **decimal** `number`
- **icon** `string`
- **totalSupply** `string`
- **initialSupply** `string`
- **maxTotalSupply** `string`
- **foreignToken** `ForeignToken`
- **tokenFactoryAddress** `string`
- **context** `StateContext`
- **data** `Any`

### TokenFactoryState

Represents the state of a token factory, used for minting and burning tokens.

- **address** `string`
- **tokenAddress** `string`
- **reserveAddress** `string`
- **currentSupply** `string`
- **reserveBalance** `string`
- **owner** `string`
- **feeRate** `number`
- **curve** `CurveConfig`
- **context** `StateContext`
- **token** `TokenState`
- **reserveToken** `TokenState`
- **data** `Any`

## Transaction Payloads (ITX)

These types define the `itx` (inner transaction) object for various transaction types.

### AccountMigrateTx

- **pk** `string`
- **type** `WalletType`
- **address** `string`
- **data** `Any`

### AcquireAssetV2Tx

- **factory** `string`
- **address** `string`
- **assets** `array<string>`
- **variables** `array<VariableInput>`
- **issuer** `NFTIssuer`
- **data** `Any`

### CreateAssetTx

- **moniker** `string`
- **data** `Any`
- **readonly** `boolean`
- **transferrable** `boolean`
- **ttl** `number`
- **parent** `string`
- **address** `string`
- **issuer** `string`
- **endpoint** `NFTEndpoint`
- **display** `NFTDisplay`
- **tags** `array<string>`

### DelegateTx

- **address** `string`
- **to** `string`
- **ops** `array<DelegateOp>`
- **data** `Any`

### ExchangeTx

- **to** `string`
- **sender** `ExchangeInfo`
- **receiver** `ExchangeInfo`
- **expiredAt** `string`
- **data** `Any`

### StakeTx

- **address** `string`
- **receiver** `string`
- **inputs** `array<TransactionInput>`
- **locked** `boolean`
- **message** `string`
- **revokeWaitingPeriod** `number`
- **slashers** `array<string>`
- **nonce** `string`
- **data** `Any`

### TransferTx

- **to** `string`
- **value** `string`
- **assets** `array<string>`
- **data** `Any`

## Response Wrappers

These types are the top-level objects returned by API queries, containing a status code and the requested data.

### ResponseGetAccountState

- **code** `string`
- **state** `AccountState`

### ResponseGetAssetState

- **code** `string`
- **state** `AssetState`

### ResponseGetBlock

- **code** `string`
- **block** `BlockInfo`

### ResponseGetChainInfo

- **code** `string`
- **info** `ChainInfo`

### ResponseGetTx

- **code** `string`
- **info** `TransactionInfo`

### ResponseListTransactions

- **code** `string`
- **page** `PageInfo`
- **transactions** `array<IndexedTransaction>`

### ResponseSendTx

- **code** `string`
- **hash** `string`

---

## Low-level API

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/api-reference-low-level-api-8cbd10/

The Low-level API provides granular control over the entire transaction lifecycle. Unlike the [High-level API](/en/docs/blockchain-sdk-nodejs/api-reference-transaction-helpers-8cbd10/) which abstracts away the details, these methods allow you to manually construct, encode, sign, and send transactions. This is ideal for advanced scenarios, such as multi-signature workflows where different parties need to sign a transaction before it's broadcasted.

This API is organized into four main groups of methods, each corresponding to a stage in the transaction lifecycle:

::::steps
:::step{title="Encode"}
Prepare a transaction and serialize it into a binary buffer.
:::

:::step{title="Sign"}
Add a digital signature to an encoded transaction.
:::

:::step{title="Multi-sign"}
Add multiple digital signatures to a transaction.
:::

:::step{title="Send"}
Broadcast a signed transaction to the blockchain.
:::
::::

## Encoding Transactions

Encoding is the first step in creating a transaction. The `encode[Type]Tx` methods take the core transaction data (`itx`) and wrap it in a standard transaction structure, adding necessary details like the `chainId` and `nonce`. The result is a human-readable transaction object and a binary buffer ready for signing.

There is an `encode` method for every transaction type supported by the chain. You can get a full list by calling `client.getTxEncodeMethods()`.

### encode[Type]Tx(payload)

Encodes a transaction without signing it.

<strong>Parameters</strong>

- **tx** `object` *(required)* — The transaction data object.
  - **itx** `object` *(required)* — The inner transaction object specific to the transaction type.
  - **from** `string` — Sender's address. If not provided, it's derived from the wallet.
  - **nonce** `number` — Transaction nonce. Defaults to `Date.now()` if not set.
  - **chainId** `string` — The chain ID. Fetched from the connected node if not provided.
- **wallet** `WalletObject` *(required)* — The wallet object used to derive the sender's address and public key.
- **delegator** `string` — The address of the account delegating permissions, if applicable.

<strong>Returns</strong>

- **Promise<object>** `Promise<object>` — A promise that resolves to an object containing the encoded transaction.
  - **object** `object` — The human-readable transaction object.
  - **buffer** `Buffer` — The serialized transaction binary buffer, ready for signing.

<strong>Example</strong>

**TransferV2Tx**

```javascript
const { encodeTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

const { object, buffer } = await encodeTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10), // Transfer 10 native tokens
    },
  },
  wallet: senderWallet,
});

console.log('Encoded TX Object:', object);
console.log('Buffer to Sign:', buffer.toString('hex'));
```

## Signing Transactions

The `sign[Type]Tx` methods build on the encoding step by adding a digital signature. These methods encode the transaction and then use the provided wallet to sign the resulting binary buffer.

You can get a full list of available signing methods by calling `client.getTxSignMethods()`.

### sign[Type]Tx(payload)

Encodes and signs a transaction.

<strong>Parameters</strong>

- **tx** `object` *(required)* — The transaction data object, same as for encoding.
- **wallet** `WalletObject` *(required)* — The wallet used to sign the transaction.
- **delegator** `string` — The address of the delegator, if applicable.
- **encoding** `string` — Optional encoding for the output ('base16', 'hex', 'base58', 'base64'). If omitted, returns the transaction object.

<strong>Returns</strong>

- **Promise<object|string>** `Promise<object|string>` — A promise that resolves to the signed transaction object, or an encoded string if `encoding` is specified.

<strong>Example</strong>

**TransferV2Tx**

```javascript
const { signTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

const signedTx = await signTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10),
    },
  },
  wallet: senderWallet,
});

console.log('Signed TX:', signedTx);
```

## Sending Transactions

The `send[Type]Tx` methods are responsible for broadcasting a transaction to the blockchain. These methods can perform the signing step implicitly if an unsigned transaction and a wallet are provided, or they can send a transaction that has already been signed.

A full list of send methods is available via `client.getTxSendMethods()`.

### send[Type]Tx(payload)

Signs (if necessary) and sends a transaction to the chain.

<strong>Parameters</strong>

- **tx** `object` *(required)* — The transaction object. Can be signed or unsigned.
- **wallet** `WalletObject` *(required)* — The wallet to sign the transaction. Still required for identifying the sender even if the transaction is pre-signed.
- **signature** `string` — A pre-computed signature for the transaction. If provided, the wallet will not be used to sign again.
- **delegator** `string` — The address of the delegator, if applicable.
- **commit** `boolean` (default: `false`) — Whether to wait for the transaction to be committed to a block before resolving.

<strong>Returns</strong>

- **Promise<string>** `Promise<string>` — A promise that resolves to the transaction hash.

<strong>Example: Auto-Signing</strong>

**TransferV2Tx**

```javascript
const { sendTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

// The client will sign this transaction using senderWallet before sending.
const txHash = await sendTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10),
    },
  },
  wallet: senderWallet,
});

console.log('Transaction sent with hash:', txHash);
```

<strong>Example: Sending a Pre-Signed Transaction</strong>

**TransferV2Tx**

```javascript
// Assume signedTx is from the sign[Type]Tx example
const { sendTransferV2Tx } = client;

const txHash = await sendTransferV2Tx({
  tx: signedTx, // Pass the entire signed transaction object
  wallet: senderWallet,
});

console.log('Pre-signed transaction sent with hash:', txHash);
```

## Multi-Signature Transactions

For workflows requiring multiple signatures (like an atomic swap), the `multiSign[Type]Tx` methods are used. The process involves one party signing the transaction first (using a standard `sign[Type]Tx` method), and subsequent parties adding their signatures using the corresponding `multiSign[Type]Tx` method.

You can get a list of transactions that support multiple signatures via `client.getTxMultiSignMethods()`.

### multiSign[Type]Tx(payload)

Adds a signature to a transaction that already has one or more signatures.

<strong>Parameters</strong>

- **tx** `object` *(required)* — The transaction object, which should already contain at least one signature.
- **wallet** `WalletObject` *(required)* — The wallet of the current signer.
- **delegator** `string` — The address of the delegator for the current signer, if applicable.
- **data** `any` — Optional data to include with the signature.
- **encoding** `string` — Optional encoding for the output ('base16', 'hex', 'base58', 'base64').

<strong>Returns</strong>

- **Promise<object|string>** `Promise<object|string>` — A promise that resolves to the transaction object with the new signature added.

<strong>Example: Atomic Swap (</strong><strong>`ExchangeV2Tx`</strong><strong>)</strong>

**ExchangeV2Tx**

```javascript
// Wallets for two parties
const aliceWallet = fromRandom();
const bobWallet = fromRandom();

// 1. Alice prepares and signs the initial exchange transaction
const exchangeTx = {
  itx: {
    to: bobWallet.address,
    sender: {
      value: await client.fromTokenToUnit(10), // Alice offers 10 tokens
    },
    receiver: {
      value: await client.fromTokenToUnit(5), // Alice demands 5 tokens
    },
  },
};

const signedByAlice = await client.signExchangeV2Tx({
  tx: exchangeTx,
  wallet: aliceWallet,
});

// 2. Alice sends `signedByAlice` to Bob. Bob adds his signature.
const signedByBoth = await client.multiSignExchangeV2Tx({
  tx: signedByAlice,
  wallet: bobWallet,
});

// 3. Bob sends `signedByBoth` back to Alice. Alice sends the final transaction.
const txHash = await client.sendExchangeV2Tx({
  tx: signedByBoth,
  wallet: aliceWallet, // The sender wallet is used to submit
});

console.log('Atomic swap transaction sent:', txHash);
```

---

## Query & Mutation Methods

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/api-reference-query-mutation-methods-8cbd10/

The OCAP Client interacts with the blockchain through GraphQL. Methods are categorized into two main types:

- <strong>Queries</strong>: These are read-only operations used to fetch data from the blockchain, such as retrieving the state of an account, listing transactions, or getting general chain information. They do not alter the state of the chain.
- <strong>Mutations</strong>: These are write operations that modify the state of the blockchain. Sending a transaction is the primary example of a mutation.

This section provides a complete reference for all available query and mutation methods provided by the client.

## Query Methods

Queries are used to retrieve data from the blockchain. Here is a complete list of all available query methods.

### getAccountState

Retrieves the current state of a specific account, including its balance, nonce, and other details.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the account to query.
- **height** `string` — Query the state at a specific block height.
- **keys** `string[]` — Specific fields to retrieve.
- **traceMigration** `boolean` — If true, traces the account's migration history.

<strong>Returns</strong>

- **ResponseGetAccountState** `object` — An object containing the response code and the account state.
  - **code** `string` — The status code of the response (e.g., 'OK').
  - **state** `AccountState` — The detailed state of the account.

### getAssetState

Retrieves the current state of a specific asset (NFT).

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the asset to query.
- **height** `string` — Query the state at a specific block height.
- **keys** `string[]` — Specific fields to retrieve.

<strong>Returns</strong>

- **ResponseGetAssetState** `object` — An object containing the response code and the asset state.
  - **code** `string` — The status code of the response.
  - **state** `AssetState` — The detailed state of the asset.

### getFactoryState

Fetches the state of a specific asset factory.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the factory to query.

<strong>Returns</strong>

- **ResponseGetFactoryState** `object` — An object containing the response code and the factory state.
  - **code** `string` — The status code of the response.
  - **state** `AssetFactoryState` — The detailed state of the asset factory.

### getDelegateState

Retrieves the state of a delegation relationship.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the delegation to query.
- **height** `string` — Query the state at a specific block height.
- **keys** `string[]` — Specific fields to retrieve.

<strong>Returns</strong>

- **ResponseGetDelegateState** `object` — An object containing the response code and the delegation state.
  - **code** `string` — The status code of the response.
  - **state** `DelegateState` — The detailed state of the delegation.

### getTokenState

Fetches the state of a specific fungible token.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the token to query.

<strong>Returns</strong>

- **ResponseGetTokenState** `object` — An object containing the response code and the token state.
  - **code** `string` — The status code of the response.
  - **state** `TokenState` — The detailed state of the token.

### getEvidenceState

Retrieves an evidence record by its hash.

<strong>Parameters</strong>

- **hash** `string` *(required)* — The hash of the evidence to retrieve.

<strong>Returns</strong>

- **ResponseGetEvidenceState** `object` — An object containing the response code and the evidence state.
  - **code** `string` — The status code of the response.
  - **state** `EvidenceState` — The detailed state of the evidence.

### getForgeState

Fetches the overall configuration and state of the OCAP blockchain.

<strong>Parameters</strong>

- **height** `string` — Query the state at a specific block height.
- **keys** `string[]` — Specific fields to retrieve.

<strong>Returns</strong>

- **ResponseGetForgeState** `object` — An object containing the response code and the chain state.
  - **code** `string` — The status code of the response.
  - **state** `ForgeState` — The detailed state of the OCAP chain.

### getTokenFactoryState

Retrieves the state of a specific token factory.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the token factory to query.

<strong>Returns</strong>

- **ResponseGetTokenFactoryState** `object` — An object containing the response code and the token factory state.
  - **code** `string` — The status code of the response.
  - **state** `TokenFactoryState` — The detailed state of the token factory.

### getTx

Fetches a single transaction by its hash.

<strong>Parameters</strong>

- **hash** `string` *(required)* — The hash of the transaction to retrieve.

<strong>Returns</strong>

- **ResponseGetTx** `object` — An object containing the response code and transaction details.
  - **code** `string` — The status code of the response.
  - **info** `TransactionInfo` — The detailed information of the transaction.

### getBlock

Retrieves a single block by its height.

<strong>Parameters</strong>

- **height** `string` *(required)* — The height of the block to retrieve.

<strong>Returns</strong>

- **ResponseGetBlock** `object` — An object containing the response code and block details.
  - **code** `string` — The status code of the response.
  - **block** `BlockInfo` — The detailed information of the block.

### getBlocks

Retrieves a list of blocks, with optional filters.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **heightFilter** `RangeFilterInput` — Filter blocks by a height range.
- **emptyExcluded** `boolean` — If true, blocks with no transactions are excluded.

<strong>Returns</strong>

- **ResponseGetBlocks** `object` — An object containing pagination info and a list of blocks.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **blocks** `BlockInfoSimple[]` — An array of simplified block objects.

### getUnconfirmedTxs

Fetches transactions that are in the mempool but not yet confirmed.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.

<strong>Returns</strong>

- **ResponseGetUnconfirmedTxs** `object` — An object containing pagination info and a list of unconfirmed transactions.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **unconfirmedTxs** `UnconfirmedTxs` — Details of unconfirmed transactions.

### getChainInfo

Retrieves general information about the blockchain.

<strong>Parameters</strong>

This method does not take any parameters.

<strong>Returns</strong>

- **ResponseGetChainInfo** `object` — An object containing the response code and chain information.
  - **code** `string` — The status code of the response.
  - **info** `ChainInfo` — The detailed information of the chain.

### getConfig

Fetches the node's configuration.

<strong>Parameters</strong>

- **parsed** `boolean` — If true, returns the parsed configuration.

<strong>Returns</strong>

- **ResponseGetConfig** `object` — An object containing the response code and the configuration.
  - **code** `string` — The status code of the response.
  - **config** `string` — The node's configuration as a string.

### getNetInfo

Retrieves network information, including connected peers.

<strong>Parameters</strong>

This method does not take any parameters.

<strong>Returns</strong>

- **ResponseGetNetInfo** `object` — An object containing the response code and network information.
  - **code** `string` — The status code of the response.
  - **netInfo** `NetInfo` — Detailed network information.

### getNodeInfo

Retrieves information about the specific node being queried.

<strong>Parameters</strong>

This method does not take any parameters.

<strong>Returns</strong>

- **ResponseGetNodeInfo** `object` — An object containing the response code and node information.
  - **code** `string` — The status code of the response.
  - **info** `NodeInfo` — Detailed information about the node.

### getValidatorsInfo

Fetches information about the current set of validators.

<strong>Parameters</strong>

This method does not take any parameters.

<strong>Returns</strong>

- **ResponseGetValidatorsInfo** `object` — An object containing the response code and validators information.
  - **code** `string` — The status code of the response.
  - **validatorsInfo** `ValidatorsInfo` — Detailed information about the validators.

### getForgeStats

Retrieves various statistics about the blockchain's activity.

<strong>Parameters</strong>

This method does not take any parameters.

<strong>Returns</strong>

- **ResponseGetForgeStats** `object` — An object containing the response code and chain statistics.
  - **code** `string` — The status code of the response.
  - **forgeStats** `ForgeStats` — Various statistics about the OCAP chain.

### listAssetTransactions

Lists all transactions related to a specific asset.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the asset.
- **paging** `PageInput` — Pagination settings.

<strong>Returns</strong>

- **ResponseListAssetTransactions** `object` — An object containing pagination info and a list of transactions.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **transactions** `IndexedTransaction[]` — An array of transaction objects.

### listAssets

Lists all assets, with filters for owner or factory.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **ownerAddress** `string` — Filter assets by the owner's address.
- **factoryAddress** `string` — Filter assets by the factory's address.
- **timeFilter** `TimeFilterInput` — Filter assets by a time range.

<strong>Returns</strong>

- **ResponseListAssets** `object` — An object containing pagination info and a list of assets.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **assets** `IndexedAssetState[]` — An array of asset state objects.

### listBlocks

Lists blocks with various filtering options.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **proposer** `string` — Filter blocks by the proposer's address.
- **timeFilter** `TimeFilterInput` — Filter blocks by a time range.
- **heightFilter** `RangeFilterInput` — Filter blocks by a height range.
- **numTxsFilter** `RangeFilterInput` — Filter blocks by the number of transactions.
- **numInvalidTxsFilter** `RangeFilterInput` — Filter blocks by the number of invalid transactions.

<strong>Returns</strong>

- **ResponseListBlocks** `object` — An object containing pagination info and a list of blocks.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **blocks** `IndexedBlock[]` — An array of block objects.

### listTopAccounts

Lists accounts with the highest balance of a specific token.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **tokenAddress** `string` — The address of the token. If not provided, it defaults to the native token.
- **timeFilter** `TimeFilterInput` — Filter accounts by a time range.

<strong>Returns</strong>

- **ResponseListTopAccounts** `object` — An object containing pagination info and a list of top accounts.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **accounts** `IndexedAccountState[]` — An array of account state objects.

### listTransactions

A powerful method to list transactions with a wide range of filters.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **timeFilter** `TimeFilterInput` — Filter transactions by a time range.
- **addressFilter** `AddressFilterInput` — Filter transactions by sender or receiver address.
- **typeFilter** `TypeFilterInput` — Filter by transaction type.
- **validityFilter** `ValidityFilterInput` — Filter by transaction validity.
- **factoryFilter** `FactoryFilterInput` — Filter by factory address.
- **tokenFilter** `TokenFilterInput` — Filter by token address.
- **assetFilter** `AssetFilterInput` — Filter by asset address.
- **accountFilter** `AccountFilterInput` — Filter by account address.
- **txFilter** `TxFilterInput` — Filter by transaction hash.
- **rollupFilter** `RollupFilterInput` — Filter by rollup address.
- **stakeFilter** `StakeFilterInput` — Filter by stake address.
- **delegationFilter** `DelegationFilterInput` — Filter by delegation address.
- **tokenFactoryFilter** `TokenFactoryFilterInput` — Filter by token factory address.

<strong>Returns</strong>

- **ResponseListTransactions** `object` — An object containing pagination info and a list of transactions.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **transactions** `IndexedTransaction[]` — An array of transaction objects.

### listTokens

Lists all fungible tokens on the chain.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **issuerAddress** `string` — Filter tokens by the issuer's address.
- **timeFilter** `TimeFilterInput` — Filter tokens by a time range.

<strong>Returns</strong>

- **ResponseListTokens** `object` — An object containing pagination info and a list of tokens.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **tokens** `IndexedTokenState[]` — An array of token state objects.

### listFactories

Lists all asset factories on the chain.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **ownerAddress** `string` — Filter factories by the owner's address.
- **addressList** `string[]` — A list of factory addresses to query.
- **timeFilter** `TimeFilterInput` — Filter factories by a time range.

<strong>Returns</strong>

- **ResponseListFactories** `object` — An object containing pagination info and a list of factories.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **factories** `IndexedFactoryState[]` — An array of factory state objects.

### getAccountTokens

Retrieves the token balances for a specific account.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the account.
- **token** `string` — Specific token address to query.

<strong>Returns</strong>

- **ResponseGetAccountTokens** `object` — An object containing the response code and a list of account tokens.
  - **code** `string` — The status code of the response.
  - **tokens** `AccountToken[]` — An array of token balance objects.

### getStakeState

Fetches the state of a specific stake.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the stake to query.
- **height** `string` — Query the state at a specific block height.
- **keys** `string[]` — Specific fields to retrieve.

<strong>Returns</strong>

- **ResponseGetStakeState** `object` — An object containing the response code and the stake state.
  - **code** `string` — The status code of the response.
  - **state** `StakeState` — The detailed state of the stake.

### listStakes

Lists all stake records, with optional filters.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **addressFilter** `AddressFilterInput` — Filter stakes by sender or receiver address.
- **timeFilter** `TimeFilterInput` — Filter stakes by a time range.
- **assetFilter** `AssetFilterInput` — Filter stakes by asset address.

<strong>Returns</strong>

- **ResponseListStakes** `object` — An object containing pagination info and a list of stakes.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **stakes** `IndexedStakeState[]` — An array of stake state objects.

### getRollupState

Retrieves the state of a specific rollup.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the rollup to query.
- **height** `string` — Query the state at a specific block height.
- **keys** `string[]` — Specific fields to retrieve.

<strong>Returns</strong>

- **ResponseGetRollupState** `object` — An object containing the response code and the rollup state.
  - **code** `string` — The status code of the response.
  - **state** `RollupState` — The detailed state of the rollup.

### listRollups

Lists all rollups on the chain.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **tokenAddress** `string` — Filter rollups by token address.
- **foreignTokenAddress** `string` — Filter rollups by foreign token address.
- **timeFilter** `TimeFilterInput` — Filter rollups by a time range.

<strong>Returns</strong>

- **ResponseListRollups** `object` — An object containing pagination info and a list of rollups.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **rollups** `IndexedRollupState[]` — An array of rollup state objects.

### getRollupBlock

Fetches a specific block from a rollup sidechain.

<strong>Parameters</strong>

- **hash** `string` — The hash of the rollup block.
- **height** `string` — The height of the rollup block.
- **rollupAddress** `string` *(required)* — The address of the rollup.

<strong>Returns</strong>

- **ResponseGetRollupBlock** `object` — An object containing the response code and the rollup block.
  - **code** `string` — The status code of the response.
  - **block** `RollupBlock` — The detailed information of the rollup block.

### listRollupBlocks

Lists blocks from a rollup sidechain.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **rollupAddress** `string` *(required)* — The address of the rollup.
- **tokenAddress** `string` — Filter by token address.
- **proposer** `string` — Filter by proposer address.
- **validatorFilter** `ValidatorFilterInput` — Filter by validator.
- **txFilter** `TxFilterInput` — Filter by transaction hash.
- **timeFilter** `TimeFilterInput` — Filter by time range.

<strong>Returns</strong>

- **ResponseListRollupBlocks** `object` — An object containing pagination info and a list of rollup blocks.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **blocks** `IndexedRollupBlock[]` — An array of rollup block objects.

### listRollupValidators

Lists the validators for a specific rollup.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **rollupAddress** `string` *(required)* — The address of the rollup.

<strong>Returns</strong>

- **ResponseListRollupValidators** `object` — An object containing pagination info and a list of rollup validators.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **validators** `IndexedRollupValidator[]` — An array of rollup validator objects.

### listDelegations

Lists all delegation records.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **from** `string` — Filter by the delegator's address.
- **to** `string` — Filter by the delegatee's address.
- **timeFilter** `TimeFilterInput` — Filter by time range.

<strong>Returns</strong>

- **ResponseListDelegations** `object` — An object containing pagination info and a list of delegations.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **delegations** `IndexedDelegationState[]` — An array of delegation state objects.

### search

Performs a keyword search for accounts, assets, or transactions.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **keyword** `string` *(required)* — The keyword to search for.

<strong>Returns</strong>

- **ResponseSearch** `object` — An object containing pagination info and search results.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **results** `SearchResult[]` — An array of search result objects.

### estimateGas

Estimates the gas required for a transaction.

<strong>Parameters</strong>

- **typeUrl** `string` *(required)* — The type URL of the transaction.
- **tx** `string` *(required)* — The encoded transaction string.

<strong>Returns</strong>

- **ResponseEstimateGas** `object` — An object containing the response code and the gas estimate.
  - **code** `string` — The status code of the response.
  - **estimate** `GasEstimate` — The estimated gas.

### listTokenFlows

Traces the flow of tokens between accounts.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **accountAddress** `string` *(required)* — The address of the account to trace.
- **tokenAddress** `string` — The address of the token to trace.
- **depth** `number` — The depth of the trace.
- **direction** `TokenFlowDirection` — The direction of the flow (IN or OUT).

<strong>Returns</strong>

- **ResponseListTokenFlows** `object` — An object containing pagination info and token flow data.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **data** `IndexedTokenFlow[]` — An array of token flow objects.

### verifyAccountRisk

Assesses the risk profile of a given account.

<strong>Parameters</strong>

- **accountAddress** `string` *(required)* — The address of the account to verify.
- **tokenAddress** `string` — The address of the token for context.

<strong>Returns</strong>

- **ResponseVerifyAccountRisk** `object` — An object containing the response code and the risk verification result.
  - **code** `string` — The status code of the response.
  - **data** `VerifyAccountRiskResult` — The result of the risk verification.

### getTokenDistribution

Retrieves the distribution statistics for a given token.

<strong>Parameters</strong>

- **tokenAddress** `string` *(required)* — The address of the token.

<strong>Returns</strong>

- **ResponseGetTokenDistribution** `object` — An object containing the response code and token distribution data.
  - **code** `string` — The status code of the response.
  - **data** `TokenDistribution` — The token distribution statistics.

### listTokenFactories

Lists all token factories on the chain.

<strong>Parameters</strong>

- **paging** `PageInput` — Pagination settings.
- **tokenAddress** `string` — Filter by token address.
- **reserveAddress** `string` — Filter by reserve token address.
- **owner** `string` — Filter by owner address.
- **timeFilter** `TimeFilterInput` — Filter by time range.

<strong>Returns</strong>

- **ResponseListTokenFactories** `object` — An object containing pagination info and a list of token factories.
  - **code** `string` — The status code of the response.
  - **page** `PageInfo` — Pagination information.
  - **tokenFactories** `IndexedTokenFactoryState[]` — An array of token factory state objects.

## Mutation Methods

Mutations are used to send transactions that modify the state of the blockchain.

### sendTx

Broadcasts a pre-signed transaction to the network. This is the fundamental method for all write operations. For creating and signing transactions, see the [High-level API](/en/docs/blockchain-sdk-nodejs/api-reference-transaction-helpers-8cbd10/) and [Transaction Lifecycle](/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/) guides.

<strong>Parameters</strong>

- **tx** `string` *(required)* — The encoded transaction string.
- **wallet** `object` *(required)* — The wallet object used for signing.
- **token** `string` — Authentication token, if required.
- **commit** `boolean` (default: `true`) — If true, waits for the transaction to be committed to a block.
- **extra** `string` — Extra data to be included.

<strong>Returns</strong>

- **ResponseSendTx** `object` — An object containing the response code and the transaction hash.
  - **code** `string` — The status code of the response.
  - **hash** `string` — The hash of the submitted transaction.

<strong>Example</strong>

```javascript
// This example assumes `signedTx` is a properly encoded and signed transaction string.
// See other guides for how to create it.

const signedTx = '...';
const wallet = { ... }; // The wallet that signed the transaction

try {
  const { hash } = await client.sendTx({ tx: signedTx, wallet });
  console.log('Transaction sent successfully! Hash:', hash);
} catch (error) {
  console.error('Failed to send transaction:', error);
}
```

---

## High-level API

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/api-reference-transaction-helpers-8cbd10/

Transaction helpers are high-level functions built into the OCAP Client that abstract away the complexity of creating and signing common transactions. Instead of manually constructing transaction objects, you can use these convenient methods for workflows like creating assets, transferring tokens, staking, and performing atomic swaps. These helpers ensure that the transaction structure is correct and simplify the development process significantly.

For a deeper understanding of the underlying transaction lifecycle, see [Core Concepts: Transaction Lifecycle](/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/).

## Account Management

### migrateAccount

Migrates the ownership of an account to a new key pair. This is useful for key rotation or account recovery.

<strong>Parameters</strong>

- **from** `WalletObject` *(required)* — The wallet object of the account to migrate from.
- **to** `WalletObject` *(required)* — The wallet object of the account to migrate to.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send an AccountMigrateTx**

```javascript
const txHash = await client.migrateAccount({
  from: oldWallet,
  to: newWallet,
});
console.log('Migration transaction hash:', txHash);
```

### delegate

Authorizes another account (the delegatee) to send specific types of transactions on behalf of the delegator. This is a powerful feature for creating secure, sandboxed permissions.

<strong>Parameters</strong>

- **from** `WalletObject` *(required)* — The delegator's wallet, who is granting the privilege.
- **to** `WalletObject` *(required)* — The delegatee's wallet, who is receiving the privilege.
- **privileges** `array` *(required)* — An array of privilege objects specifying the allowed actions.
  - **typeUrl** `string` *(required)* — The type URL of the transaction being permitted (e.g., 'fg:t:transfer_v2').
  - **limit** `object` — Optional limits on the delegation.
    - **tokens** `array` — Limits on specific fungible tokens.
    - **assets** `array` — Limits on specific assets (NFTs).

<strong>Returns</strong>

- **result** `Promise<[string, string]>` — An array containing the transaction hash and the newly created delegate address.

<strong>Example</strong>

**Send a DelegateTx**

```javascript
const [txHash, delegateAddress] = await client.delegate({
  from: userWallet,
  to: appWallet,
  privileges: [
    {
      typeUrl: 'fg:t:transfer_v2',
    },
  ],
});
console.log('Delegation tx hash:', txHash);
console.log('Delegate address:', delegateAddress);
```

### revokeDelegate

Revokes previously granted permissions from a delegatee.

<strong>Parameters</strong>

- **from** `WalletObject` *(required)* — The delegator's wallet.
- **to** `WalletObject` *(required)* — The delegatee's wallet.
- **privileges** `array` *(required)* — An array of privilege objects specifying the permissions to revoke.
  - **typeUrl** `string` *(required)* — The type URL of the transaction to revoke (e.g., 'fg:t:transfer_v2').

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a RevokeDelegateTx**

```javascript
const txHash = await client.revokeDelegate({
  from: userWallet,
  to: appWallet,
  privileges: ['fg:t:transfer_v2'],
});
console.log('Revocation tx hash:', txHash);
```

## Asset (NFT) Management

### createAsset

Creates a new asset (Non-Fungible Token) on the blockchain.

<strong>Parameters</strong>

- **moniker** `string` *(required)* — A short, human-readable name for the asset.
- **data** `object` *(required)* — A JSON object containing the asset's metadata.
- **wallet** `WalletObject` *(required)* — The wallet of the asset's initial owner.
- **parent** `string` — The address of a parent asset, establishing a hierarchical link.
- **ttl** `number` (default: `0`) — Time-to-live in seconds after the first consumption.
- **readonly** `boolean` (default: `false`) — If true, the asset cannot be updated after creation.
- **transferrable** `boolean` (default: `true`) — If true, the asset can be transferred to another account.
- **display** `object` — Object for asset display metadata.
- **endpoint** `object` — Object for asset endpoint metadata.
- **tags** `string[]` — An array of tags for categorization.
- **delegator** `string` — The address of the delegator, if the transaction is sent by a delegatee.

<strong>Returns</strong>

- **result** `Promise<[string, string]>` — An array containing the transaction hash and the address of the newly created asset.

<strong>Example</strong>

**Send a CreateAssetTx**

```javascript
const [txHash, assetAddress] = await client.createAsset({
  moniker: 'My First NFT',
  data: {
    typeUrl: 'json',
    value: { name: 'Digital Collectible', description: 'A unique item.' },
  },
  wallet: userWallet,
});
console.log('Create asset tx hash:', txHash);
console.log('New asset address:', assetAddress);
```

### updateAsset

Updates the `moniker` and `data` fields of an existing, non-readonly asset.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the asset to update.
- **moniker** `string` *(required)* — The new moniker for the asset.
- **data** `object` *(required)* — The new JSON data object for the asset.
- **wallet** `WalletObject` *(required)* — The wallet of the asset's current owner.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send an UpdateAssetTx**

```javascript
const txHash = await client.updateAsset({
  address: 'z3g...',
  moniker: 'Updated NFT Name',
  data: {
    typeUrl: 'json',
    value: { name: 'Updated Collectible', description: 'Now with more features!' },
  },
  wallet: userWallet,
});
console.log('Update asset tx hash:', txHash);
```

### createAssetFactory

Creates an asset factory, which acts as a template for minting multiple new assets with a consistent structure.

<strong>Parameters</strong>

- **factory** `object` *(required)* — An object containing the factory's configuration.
  - **name** `string` *(required)* — Name of the factory.
  - **description** `string` *(required)* — Description of the factory.
  - **limit** `number` (default: `0`) — The maximum number of assets that can be minted (0 for unlimited).
  - **trustedIssuers** `string[]` — A list of wallet addresses allowed to mint from this factory.
  - **input** `object` *(required)* — Defines the inputs required for minting.
  - **output** `object` *(required)* — Defines the structure of the minted asset, often using templates.
- **wallet** `WalletObject` *(required)* — The wallet to own the factory.

<strong>Returns</strong>

- **result** `Promise<[string, string]>` — An array containing the transaction hash and the address of the newly created factory.

<strong>Example</strong>

**Send a CreateFactoryTx**

```javascript
const factoryConfig = {
  name: 'Ticket Factory',
  description: 'Mints event tickets',
  limit: 1000,
  input: { ... },
  output: { ... },
};

const [txHash, factoryAddress] = await client.createAssetFactory({
  factory: factoryConfig,
  wallet: eventCreatorWallet,
});
console.log('Create factory tx hash:', txHash);
console.log('New factory address:', factoryAddress);
```

### acquireAsset

Acquires (mints) a new asset from an existing asset factory. This is typically initiated by the end-user who will own the asset.

<strong>Parameters</strong>

- **itx** `AcquireAssetV2Tx` *(required)* — The inner transaction object, often prepared using a helper like `preMintAsset`.
- **wallet** `WalletObject` *(required)* — The wallet of the user acquiring the asset.
- **delegator** `string` — The address of the delegator, if applicable.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send an AcquireAssetV2Tx**

```javascript
// First, prepare the minting transaction (e.g., on the server)
const itx = await client.preMintAsset({
  factory: factoryAddress,
  owner: userWallet.address,
  wallet: issuerWallet,
});

// Then, the user sends the transaction
const txHash = await client.acquireAsset({ itx, wallet: userWallet });
console.log('Acquire asset tx hash:', txHash);
```

### mintAsset

This is the issuer-side counterpart to `acquireAsset`. It allows a trusted issuer to mint an asset from a factory and assign it to a specified owner.

<strong>Parameters</strong>

- **itx** `MintAssetTx` *(required)* — The inner transaction object, often prepared using `preMintAsset`.
- **wallet** `WalletObject` *(required)* — The wallet of the trusted issuer.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a MintAssetTx**

```javascript
const itx = await client.preMintAsset({
  factory: factoryAddress,
  owner: userWallet.address,
  wallet: issuerWallet,
});

const txHash = await client.mintAsset({ itx, wallet: issuerWallet });
console.log('Mint asset tx hash:', txHash);
```

## Token Management

### createTokenFactory

Creates a new factory for minting and burning a specific fungible token, often based on a bonding curve pricing model.

<strong>Parameters</strong>

- **feeRate** `number` (default: `0`) — The fee rate for minting and burning operations.
- **curve** `object` *(required)* — The bonding curve configuration for pricing.
- **token** `object` *(required)* — The configuration for the token to be created. This includes properties like name, symbol, decimal, and maxTotalSupply.
- **data** `object` — Optional metadata for the token factory.
- **wallet** `WalletObject` *(required)* — The wallet of the factory's owner.

<strong>Returns</strong>

- **result** `Promise<[string, string]>` — An array containing the transaction hash and the address of the newly created token factory.

<strong>Example</strong>

**Send a CreateTokenFactoryTx**

```javascript
const [txHash, factoryAddress] = await client.createTokenFactory({
  feeRate: 100, // 1%
  curve: { fixedPrice: '1' }, // 1 native token per new token
  token: {
    name: 'My Community Token',
    symbol: 'MCT',
    decimal: 18,
    maxTotalSupply: '1000000',
  },
  wallet: creatorWallet,
});
console.log('Create token factory tx hash:', txHash);
console.log('New token factory address:', factoryAddress);
```

### updateTokenFactory

Updates the `feeRate` and `data` for an existing token factory.

<strong>Parameters</strong>

- **address** `string` *(required)* — The address of the token factory to update.
- **feeRate** `number` — The new fee rate for minting and burning.
- **data** `object` — New metadata for the token factory.
- **wallet** `WalletObject` *(required)* — The wallet of the factory's owner.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send an UpdateTokenFactoryTx**

```javascript
const txHash = await client.updateTokenFactory({
  address: 'z2f...',
  feeRate: 50, // 0.5%
  wallet: ownerWallet,
});
console.log('Update token factory tx hash:', txHash);
```

### mintToken

Mints new tokens from a token factory in exchange for the reserve token (usually the native chain token). The cost is determined by the factory's bonding curve.

<strong>Parameters</strong>

- **tokenFactory** `string` *(required)* — The address of the token factory.
- **amount** `number` *(required)* — The amount of new tokens to mint.
- **receiver** `string` *(required)* — The address that will receive the newly minted tokens.
- **maxReserve** `number` *(required)* — The maximum amount of reserve tokens the user is willing to pay. This acts as slippage protection.
- **data** `object` — Optional metadata for the transaction.
- **wallet** `WalletObject` *(required)* — The wallet initiating the mint.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a MintTokenTx**

```javascript
const txHash = await client.mintToken({
  tokenFactory: 'z2f...',
  amount: 100,
  receiver: userWallet.address,
  maxReserve: 105, // Willing to pay up to 105 native tokens
  wallet: userWallet,
});
console.log('Mint token tx hash:', txHash);
```

### burnToken

Burns existing tokens at a factory to receive the underlying reserve token in return. The amount of reserve token received is determined by the factory's bonding curve.

<strong>Parameters</strong>

- **tokenFactory** `string` *(required)* — The address of the token factory.
- **amount** `number` *(required)* — The amount of tokens to burn.
- **receiver** `string` *(required)* — The address that will receive the reserve tokens.
- **minReserve** `number` *(required)* — The minimum amount of reserve tokens the user expects to receive. This acts as slippage protection.
- **data** `object` — Optional metadata for the transaction.
- **wallet** `WalletObject` *(required)* — The wallet initiating the burn.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a BurnTokenTx**

```javascript
const txHash = await client.burnToken({
  tokenFactory: 'z2f...',
  amount: 50,
  receiver: userWallet.address,
  minReserve: 48, // Expecting to receive at least 48 native tokens
  wallet: userWallet,
});
console.log('Burn token tx hash:', txHash);
```

## Transfer & Exchange

### transfer

Transfers native tokens, custom fungible tokens, and/or assets (NFTs) to another account in a single transaction.

<strong>Parameters</strong>

- **to** `string` *(required)* — The address of the recipient.
- **wallet** `WalletObject` *(required)* — The sender's wallet.
- **token** `number` (default: `0`) — The amount of the chain's native token to transfer.
- **assets** `string[]` — An array of asset addresses (NFTs) to transfer.
- **tokens** `object[]` — An array of custom fungible token objects to transfer.
  - **address** `string` *(required)* — The address of the custom token contract.
  - **value** `number` *(required)* — The amount of the custom token to transfer.
- **memo** `string` — An optional note for the transaction.
- **delegator** `string` — The delegator's address, if applicable.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a TransferV2Tx**

```javascript
const txHash = await client.transfer({
  to: 'z1sb...',
  token: 1.5, // 1.5 of the native chain token
  assets: ['z3g...'], // An NFT
  tokens: [{ address: 'z2t...', value: 100 }], // 100 of a custom token
  memo: 'Payment for services',
  wallet: senderWallet,
});
console.log('Transfer tx hash:', txHash);
```

### prepareExchange

Prepares the sender's half of an atomic swap (exchange) transaction. It signs the sender's offer and returns a transaction object that can be passed to the receiver.

<strong>Parameters</strong>

- **receiver** `string` *(required)* — The address of the other party in the exchange.
- **wallet** `WalletObject` *(required)* — The wallet of the user making the offer.
- **offerToken** `number` — Amount of native token offered.
- **offerAssets** `string[]` — Array of asset addresses offered.
- **offerTokens** `object[]` — Array of custom fungible tokens offered.
- **demandToken** `number` — Amount of native token demanded in return.
- **demandAssets** `string[]` — Array of asset addresses demanded in return.
- **demandTokens** `object[]` — Array of custom fungible tokens demanded.
- **memo** `string` — An optional note for the transaction.

<strong>Returns</strong>

- **transactionObject** `Promise<object>` — The partially signed transaction object.

### finalizeExchange

Finalizes the receiver's half of an atomic swap. It takes the partially signed transaction from `prepareExchange`, adds the receiver's signature, and returns the fully signed transaction object.

<strong>Parameters</strong>

- **tx** `object` *(required)* — The transaction object returned from `prepareExchange`.
- **wallet** `WalletObject` *(required)* — The wallet of the user accepting the offer.
- **data** `object` — Extra data in the multi-signature.

<strong>Returns</strong>

- **transactionObject** `Promise<object>` — The fully signed, multi-signature transaction object.

### exchange

Sends the fully signed exchange transaction to the blockchain. This can be called by either party after `finalizeExchange` is complete.

<strong>Parameters</strong>

- **tx** `object` *(required)* — The transaction object returned from `finalizeExchange`.
- **wallet** `WalletObject` *(required)* — The wallet of the user submitting the transaction.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example (Full Exchange Flow)</strong>

**Perform an atomic swap**

```javascript
// 1. Offerer prepares the transaction
const offerTx = await client.prepareExchange({
  receiver: receiverWallet.address,
  offerAssets: ['z3g...'], // Offer an NFT
  demandToken: 10, // Demand 10 native tokens
  wallet: offererWallet,
});

// 2. Receiver finalizes the transaction
const finalTx = await client.finalizeExchange({
  tx: offerTx,
  wallet: receiverWallet,
});

// 3. Either party can send the finalized transaction
const txHash = await client.exchange({ tx: finalTx, wallet: offererWallet });
console.log('Exchange tx hash:', txHash);
```

## Staking

### stake

Stakes tokens and/or assets to a receiver address. Staking locks up resources, often in exchange for rewards or to provide security.

<strong>Parameters</strong>

- **to** `string` *(required)* — The address of the stake receiver.
- **wallet** `WalletObject` *(required)* — The wallet of the staker.
- **assets** `string[]` — An array of asset addresses to stake.
- **tokens** `object[]` — An array of fungible token objects to stake.
- **locked** `boolean` (default: `false`) — Whether the stake is locked upon creation.
- **slashers** `string[]` — A list of addresses that are permitted to slash this stake.
- **message** `string` — An optional note for the stake.

<strong>Returns</strong>

- **result** `Promise<[string, string]>` — An array containing the transaction hash and the address of the newly created stake.

<strong>Example</strong>

**Send a StakeTx**

```javascript
const [txHash, stakeAddress] = await client.stake({
  to: 'z1v...',
  tokens: [{ address: 'z2t...', value: 5000 }],
  message: 'Staking for validator rewards',
  wallet: userWallet,
});
console.log('Stake tx hash:', txHash);
console.log('New stake address:', stakeAddress);
```

### revokeStake

Revokes previously staked tokens and/or assets, initiating the process to return them to the owner. Note that there may be an unbonding period before the assets can be claimed.

<strong>Parameters</strong>

- **from** `string` *(required)* — The address of the stake to revoke from.
- **wallet** `WalletObject` *(required)* — The wallet of the stake owner.
- **assets** `string[]` — An array of asset addresses to revoke.
- **tokens** `object[]` — An array of fungible token objects to revoke.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a RevokeStakeTx**

```javascript
const txHash = await client.revokeStake({
  from: 'z6s...',
  tokens: [{ address: 'z2t...', value: 1000 }],
  wallet: userWallet,
});
console.log('Revoke stake tx hash:', txHash);
```

### claimStake

Claims items from a stake that have been successfully revoked and have passed their unbonding period.

<strong>Parameters</strong>

- **from** `string` *(required)* — The address of the stake to claim from.
- **evidence** `string` *(required)* — The transaction hash of the `revokeStake` transaction.
- **wallet** `WalletObject` *(required)* — The wallet of the stake owner.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a ClaimStakeTx**

```javascript
const revokeTxHash = '0x123...abc';
const txHash = await client.claimStake({
  from: 'z6s...',
  evidence: revokeTxHash,
  wallet: userWallet,
});
console.log('Claim stake tx hash:', txHash);
```

### slashStake

Allows a designated slasher to penalize a stake, typically for misbehavior. The slashed assets are transferred to a designated vault address.

<strong>Parameters</strong>

- **from** `string` *(required)* — The address of the stake to slash.
- **reason** `string` *(required)* — A message explaining the reason for slashing.
- **wallet** `WalletObject` *(required)* — The wallet of the designated slasher.
- **assets** `string[]` — An array of asset addresses to slash.
- **tokens** `object[]` — An array of fungible token objects to slash.

<strong>Returns</strong>

- **transactionHash** `Promise<string>` — The hash of the submitted transaction.

<strong>Example</strong>

**Send a SlashStakeTx**

```javascript
const txHash = await client.slashStake({
  from: 'z6s...',
  reason: 'Validator downtime',
  tokens: [{ address: 'z2t...', value: 500 }],
  wallet: slasherWallet,
});
console.log('Slash stake tx hash:', txHash);
```

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/core-concepts-8cbd10/

This section dives into the fundamental principles and architectural decisions that shape the OCAP Client library. Understanding these core concepts will help you leverage the library's full potential, write more efficient code, and troubleshoot issues more effectively.

While the [How-to Guides](/en/docs/blockchain-sdk-nodejs/how-to-guides-8cbd10/) provide step-by-step instructions for specific tasks, this section explains the "why" behind the "how." We'll explore the client's structure, how transactions are processed from start to finish, how to listen for real-time events, and how to create gasless user experiences.

::::card-group
::link-card{title="Client Architecture" description="Learn about the different client implementations (Node, Browser, Lite) and how to choose the right one for your environment to optimize performance and bundle size." icon="layout" href="/en/docs/blockchain-sdk-nodejs/core-concepts-client-architecture-8cbd10/"}
::link-card{title="Transaction Lifecycle" description="Follow a transaction's journey from a simple JavaScript object to a confirmed block on the chain, covering creation, encoding, signing, and broadcasting." icon="refresh" href="/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/"}
::link-card{title="Event Subscriptions" description="Discover how to use the WebSocket-based subscription feature to listen for real-time on-chain events, enabling dynamic and responsive applications." icon="radio" href="/en/docs/blockchain-sdk-nodejs/core-concepts-event-subscriptions-8cbd10/"}
::link-card{title="Gas Payment" description="Explore the powerful gas payment feature, which allows a designated wallet to sponsor transaction fees for users, creating seamless, gasless experiences." icon="flame" href="/en/docs/blockchain-sdk-nodejs/core-concepts-gas-payment-8cbd10/"}
::::

By grasping these foundational topics, you'll be well-equipped to build robust, scalable, and user-friendly applications using the OCAP Client.

---

## Client Architecture

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/core-concepts-client-architecture-8cbd10/

The OCAP Client is designed with a modular architecture to cater to different JavaScript environments and specific use cases. Instead of a one-size-fits-all library, it offers several client implementations, each optimized for a particular context, such as a Node.js backend or a bundle-size-sensitive web application. This approach allows you to choose the most efficient client for your needs, ensuring better performance and a smaller footprint where necessary.

All client variations are built upon a common base, `GraphQLClientBase`, which provides the core functionality for interacting with the blockchain's GraphQL API.

### Inheritance Diagram

The following diagram illustrates the relationship between the different client implementations:

![Client Architecture](https://media.arcblock.io/lib/5f/5ff3ab4beddf7d79.w1600.webp)

## Client Implementations

Here's a breakdown of each available client and its intended use case.

### GraphQLClientBase (The Core)

This is the foundational, lightweight client that all other clients extend. It provides the essential features for communicating with the blockchain:

- Sending GraphQL queries and mutations.
- Establishing WebSocket connections for real-time event subscriptions.
- Handling gas payment headers for sponsored transactions.
- It is environment-agnostic but requires you to provide compatible implementations for WebSockets and EventEmitters if you use subscriptions.

This client is ideal if you only need basic, read-only functionality and want to minimize dependencies.

### GraphQLClient (The Full Client)

This is the standard, general-purpose client and the one you'll likely use most often. It extends `GraphQLClientBase` and adds a rich set of high-level helper methods that simplify common on-chain operations. These helpers cover tasks like creating assets, transferring tokens, and managing stakes, abstracting away the complexity of raw GraphQL mutations.

By default, it also automatically initializes its context upon instantiation, making it ready to use immediately.

### NativeGraphqlClient (For Node.js)

This client is specifically optimized for the Node.js runtime. It extends the full `GraphQLClient` and configures it to use Node.js's native `events` module for its event handling. This makes it the most performant and reliable choice for any backend application, command-line tool, or script running on a server.

### GraphqlClientLite (For Browsers)

Designed for front-end web applications, the `GraphqlClientLite` extends `GraphQLClientBase` and is optimized for minimal bundle size. It swaps out Node.js-specific dependencies for browser-compatible alternatives like `wolfy87-eventemitter`. If you are building a web application where performance and load times are critical, this client provides the core OCAP functionality without the extra weight of the full helper method suite.

## Which Client Should I Use?

To help you decide, here is a summary of the recommended client for each scenario:

| Environment  | Use Case  | Recommended Client  | Import Path  |
|---|---|---|---|
| Node.js  | Backend services, scripts, CLI tools  | `NativeGraphqlClient`  | `@ocap/client/node`  |
| Browser  | General web applications (e.g., React, Vue)  | `GraphQLClient`  | `@ocap/client`  |
| Browser  | Bundle-size sensitive applications  | `GraphqlClientLite`  | `@ocap/client/lite`  |
| Any  | Read-only, minimal functionality required  | `GraphQLClientBase`  | `@ocap/client/base`  |

### Example Imports

Here’s how you would import each client in your code:

**Node.js Client**

```javascript
const NativeGraphqlClient = require('@ocap/client/node');
const client = new NativeGraphqlClient('https://beta.abtnetwork.io/api');
```

**Full Browser Client**

```javascript
const GraphQLClient = require('@ocap/client');
const client = new GraphQLClient('https://beta.abtnetwork.io/api');
```

**Lite Browser Client**

```javascript
const GraphqlClientLite = require('@ocap/client/lite');
const client = new GraphqlClientLite('https://beta.abtnetwork.io/api');
```

## Summary

Understanding the different client implementations allows you to make an informed choice that best fits your application's environment and requirements. By selecting the appropriate client, you can optimize for performance, bundle size, and ease of use.

Now that you understand the client architecture, you can dive deeper into how transactions are constructed and processed. Learn more in the [Transaction Lifecycle](/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/) guide.

---

## Event Subscriptions

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/core-concepts-event-subscriptions-8cbd10/

The OCAP Client provides a powerful, real-time event subscription system that allows your application to listen for on-chain activities as they happen. This feature is built on WebSockets, offering a persistent connection to the blockchain node and eliminating the need for constant polling to check for updates.

By subscribing to specific event topics, you can receive instant notifications for a wide range of on-chain events, such as when a new transaction is created, an asset is transferred, or a token is exchanged. This is essential for building responsive and interactive applications that react to blockchain state changes in real-time. For a deeper understanding of what triggers these events, you might want to review the [Transaction Lifecycle](/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/).

## How It Works

Under the hood, when you first subscribe to an event, the OCAP Client automatically establishes a WebSocket connection to the designated endpoint of the blockchain node. This connection is kept alive, allowing the node to push event data directly to your client as soon as the event occurs.

The client manages the WebSocket connection lifecycle for you. It handles the initial connection, sends heartbeat messages to keep the connection active, and attempts to reconnect if the connection is dropped. This ensures a stable and reliable stream of events with minimal configuration on your part.

## Subscribing to Events

To start listening for events, you use the `subscribe` method. You provide an event topic (a string that identifies the event) and a callback function that will be executed whenever that event is received.

**OCAP Client**

```javascript
const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');

const handleNewTransaction = (eventData) => {
  console.log('A new transaction was created on-chain:', eventData);
};

// Subscribe to the 'tx.create' topic
client.subscribe('tx.create', handleNewTransaction);
```

### Method Signature

<strong>`subscribe(topic, callback)`</strong>

- **topic** `string` *(required)* — The name of the event topic to subscribe to. For example, 'tx.create'.
- **callback** `Function` *(required)* — The function to execute when an event is received. The event data is passed as the first argument.

### Common Event Topics

Event topics generally follow the pattern `tx.<transaction_type>`. Here are some common examples:

| Topic  | Description  |
|---|---|
| `tx.create`  | Fired when any new transaction is successfully processed and added to a block.  |
| `tx.transfer_v2`  | Fired specifically when a `transferV2` transaction occurs.  |
| `tx.exchange_v2`  | Fired when an `exchangeV2` (atomic swap) transaction is completed.  |
| `tx.create_asset`  | Fired when a new asset (NFT) is created.  |

## Unsubscribing from Events

It's good practice to clean up your subscriptions when they are no longer needed, especially in single-page applications where components mount and unmount. This prevents memory leaks and unnecessary processing. You can remove a subscription using the `unsubscribe` method.

**OCAP Client**

```javascript
// To remove a specific listener, pass the same callback function reference
client.unsubscribe('tx.create', handleNewTransaction);

// To remove all listeners for a specific topic
client.unsubscribe('tx.create');
```

### Method Signature

<strong>`unsubscribe(topic, [callback])`</strong>

- **topic** `string` *(required)* — The name of the event topic to unsubscribe from.
- **callback** `Function` — Optional. The specific callback function to remove. If omitted, all listeners for the given topic will be removed.

## Complete Example

Here is a complete example that demonstrates subscribing to an event, triggering it, and then unsubscribing.

**Event Subscription Lifecycle**

```javascript
import GraphQLClient from '@ocap/client';
import { fromRandom } from '@ocap/wallet';

const main = async () => {
  const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');
  const events = { txCreate: 0, txTransfer: 0 };

  // 1. Subscribe to events
  client.subscribe('tx.create', () => (events.txCreate += 1));
  client.subscribe('tx.transfer_v2', () => (events.txTransfer += 1));

  console.log('Subscribed to tx.create and tx.transfer_v2 events...');

  // Helper to wait for a short period
  const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
  await sleep(100); // Wait a moment for the subscription to register

  // 2. Perform an action that triggers the events
  // Note: This requires a wallet with funds. You can get test tokens from https://faucet.abtnetwork.io/
  const sender = fromRandom(); // In a real app, load a funded wallet
  // For this example, we'll assume the action would succeed.
  console.log('A transfer transaction would trigger the event handlers.');

  // In a real scenario, after a successful transfer:
  // await client.transfer({ to: 'z1...', token: 1, wallet: sender });

  // Let's simulate the event counters being incremented after a successful transaction
  events.txCreate = 1;
  events.txTransfer = 1;

  await sleep(100); // Wait for events to be processed

  // 3. Verify that the event handlers were called
  console.log(`tx.create was called ${events.txCreate} time(s).`);
  console.log(`tx.transfer_v2 was called ${events.txTransfer} time(s).`);

  // 4. Unsubscribe to clean up
  client.unsubscribe('tx.create');
  client.unsubscribe('tx.transfer_v2');
  console.log('Unsubscribed from events.');
};

main().catch(console.error);
```

## Summary

Event subscriptions are a core feature for building dynamic dApps with the OCAP Client. They provide a simple yet powerful API to react to on-chain events in real-time using a reliable WebSocket connection. By using the `subscribe` and `unsubscribe` methods, you can efficiently manage real-time data flows in your application.

For more details on how transactions are constructed and sent, which in turn generate these events, see the [Transaction Lifecycle](/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/) documentation. To explore how to sponsor transaction fees for your users, which can be useful when combined with event listeners, read about [Gas Payment](/en/docs/blockchain-sdk-nodejs/core-concepts-gas-payment-8cbd10/).

---

## Gas Payment

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/core-concepts-gas-payment-8cbd10/

In most blockchain systems, every transaction requires a fee, commonly known as "gas," to be paid by the initiator. This can be a significant hurdle for new users who may not have the native currency to pay these fees. The OCAP Client introduces a Gas Payment feature that allows application developers to sponsor these fees, creating a seamless, "gasless" experience for their users.

This powerful feature enables dApps to abstract away the complexity of gas, improving user onboarding and overall application usability.

## How It Works

The gas payment mechanism is implemented through standard HTTP headers. When you configure a gas payer wallet on your client instance, the client automatically attaches two special headers to every `sendTx` mutation it sends to the blockchain node:

- `x-gas-payer-pk`: The public key of the wallet that will pay the gas fee.
- `x-gas-payer-sig`: A JSON Web Token (JWT) signed by the gas payer's secret key. This token contains the hash of the transaction, acting as a verifiable authorization from the sponsor to pay the fee for that specific transaction.

When the blockchain node receives the transaction, it performs two critical validations:

1. It verifies the user's signature on the transaction itself.
2. It verifies the gas payer's signature in the header against the transaction hash.

If both signatures are valid, the transaction is executed under the user's authority, but the corresponding gas fee is deducted from the gas payer's account balance.

### Workflow Diagram

The following diagram illustrates the entire gas payment flow from transaction initiation to execution:

![Gas Payment](https://media.arcblock.io/lib/01/019f82ba2a44a35e.w1600.webp)

## Usage Example

To enable gasless transactions, you simply need to create a wallet instance for the sponsoring account and set it on the client using the `setGasPayer` method.

**Gas Payer Setup and Usage**

```javascript
import Client from '@ocap/client';
import Wallet, { fromRandom } from '@ocap/wallet';

// 1. Initialize the client to connect to the Beta chain
const client = new Client('https://beta.abtnetwork.io/api');

// 2. Create a wallet for the gas payer (your application's wallet)
// This wallet must have enough native tokens (TBA) to cover transaction fees.
// You can get test tokens from the faucet: https://faucet.abtnetwork.io/
const gasPayerWallet = Wallet.fromJSON({
  sk: '...your_sponsor_secret_key...',
  pk: '...your_sponsor_public_key...',
  address: '...your_sponsor_address...',
});

// 3. Set the gas payer on the client instance
client.setGasPayer(gasPayerWallet);

// 4. Create a wallet for the end-user.
const userWallet = fromRandom();

// 5. Send a transaction using the user's wallet.
// The transaction is signed by the user, but the gas fee is paid by gasPayerWallet.
async function performGaslessTransaction() {
  try {
    // Note: While a new account is created on-chain upon its first incoming transaction,
    // it must exist on-chain before it can *send* transactions.
    // You can initialize it by sending it a small amount of tokens from a faucet.

    const receiverAddress = 'z1...'; // A valid recipient address
    const hash = await client.transfer({
      to: receiverAddress,
      tokens: [{ value: '0.1' }], // Sending 0.1 TBA
      wallet: userWallet,
    });

    console.log('Gasless transaction successful. Hash:', hash);
    console.log(`Review on explorer: https://beta.abtnetwork.io/explorer/txs/${hash}`);
  } catch (error) {
    console.error('Transaction failed:', error);
  }
}

performGaslessTransaction();
```

In this example, `userWallet` can successfully send a transaction even with a zero balance of the native token, because `gasPayerWallet` covers the cost. This creates a frictionless experience, especially for new users joining your application.

To understand the full journey of a transaction, from creation to finalization, see the [Transaction Lifecycle](/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/) documentation.

---

## Transaction Lifecycle

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/core-concepts-transaction-lifecycle-8cbd10/

Every action that modifies the state of the blockchain, such as transferring tokens or creating an asset, is executed through a transaction. Understanding the lifecycle of a transaction is fundamental to building applications with the OCAP Client. This process involves four main stages: Preparation, Encoding, Signing, and Sending.

The OCAP Client provides a flexible set of methods that allow you to either perform these steps individually for maximum control or use high-level helpers that combine them for convenience.

This guide breaks down each stage and illustrates both single-signature and multi-signature workflows.

## Lifecycle Overview

The following diagram illustrates the complete journey of a transaction from preparation to its final submission to the blockchain.

![Transaction Lifecycle](https://media.arcblock.io/lib/70/7009f95e02aa11f6.w1600.webp)

## Stage 1: Preparation (Creating the itx)

Every transaction begins with an `itx` (inner transaction). This is a plain JavaScript object that contains the specific data for the action you want to perform. For example, a transfer `itx` would include the recipient's address and the amount.

**Preparing the itx**

```javascript
// The core data for our transfer transaction
const itx = {
  to: 'z2C8j81aL2oXpA5t42s2h4g9o8p1k6m3n7b', // Recipient's address
  value: await client.fromTokenToUnit(10),   // Amount to send, converted to the chain's base unit
};
```

## Stage 2: Encoding

Encoding transforms the `itx` and other metadata into a standardized, binary format that can be cryptographically signed. The client provides an `encode{TxType}Tx` method for each transaction type (e.g., `encodeTransferV2Tx`).

During this stage, the client automatically adds essential metadata:

- <strong>`from`</strong>: The sender's address, derived from the provided wallet.
- <strong>`chainId`</strong>: The identifier of the target blockchain, fetched automatically.
- <strong>`nonce`</strong>: A unique number to prevent replay attacks, which defaults to the current timestamp (`Date.now()`).
- <strong>`pk`</strong>: The public key of the sender's wallet.

The encoding function returns both the full transaction object and a `Buffer` of the serialized data, which is used for signing.

**Encoding the Transaction**

```javascript
const { object: encodedTx, buffer: txBuffer } = await client.encodeTransferV2Tx({
  tx: { itx },
  wallet: senderWallet,
});

console.log('Encoded TX Object:', encodedTx);
console.log('Buffer to be signed:', txBuffer);
```

## Stage 3: Signing

Signing proves ownership of the account and authorizes the transaction. The process differs for single-signature and multi-signature workflows.

### Single-Signature Workflow

This is the most common scenario, where a single user signs a transaction. The `sign{TxType}Tx` methods take the encoded transaction, sign the binary buffer with the user's private key, and populate the `signature` field.

**Signing with a Single Signature**

```javascript
const signedTx = await client.signTransferV2Tx({
  tx: encodedTx, // The object from the encoding step
  wallet: senderWallet,
});

console.log('Signature:', signedTx.signature);
```

### Multi-Signature Workflow

Multi-signature (multisig) transactions require approval from multiple parties. This is commonly used for atomic swaps or shared accounts. The process is sequential:

::::steps
:::step{title="Preparation"}
The initial transaction is created with a `signaturesList` that defines all required signers.
:::

:::step{title="Sequential Signing"}
The transaction is passed from one signer to the next. Each signer uses the corresponding `multiSign{TxType}Tx` method to add their signature.
:::
::::

Internally, the `multiSign` method ensures that each party signs the exact same transaction digest by temporarily stripping all existing signatures before encoding the transaction for signing.

Here’s an example for an `ExchangeTx`, where two parties swap assets.

**Multi-Signature Signing Example**

```javascript
// Step 1: Alice (the offerer) prepares and signs the exchange transaction.
const txFromAlice = await client.prepareExchange({
  offerToken: 10,
  demandToken: 20,
  receiver: bobWallet.address,
  wallet: aliceWallet,
});

// Step 2: The transaction is sent to Bob.
// Bob (the demander) adds his signature to finalize it.
const txFromBob = await client.finalizeExchange({
  tx: txFromAlice, // Transaction signed by Alice
  wallet: bobWallet,
});

console.log('Alice\'s Signature:', txFromBob.signaturesList[0].signature);
console.log('Bob\'s Signature:', txFromBob.signaturesList[1].signature);
```

## Stage 4: Sending

Once a transaction is fully signed, it can be sent to the blockchain node for processing. The `send{TxType}Tx` methods handle this final step.

For convenience, these methods can also perform the signing step implicitly if you provide a wallet and an unsigned transaction. The method returns a promise that resolves with the transaction hash upon successful submission.

**Sending the Signed Transaction**

```javascript
// Using a pre-signed transaction
const hash = await client.sendTransferV2Tx({ tx: signedTx, wallet: senderWallet });

// Or, letting the send method handle the signing automatically
const hash2 = await client.sendTransferV2Tx({
  tx: { itx }, // Just the inner transaction
  wallet: senderWallet,
});

console.log('Transaction sent! Hash:', hash);
```

You can also include a `commit: true` option to make the client wait until the transaction is fully confirmed and included in a block before resolving the promise.

## Summary

The transaction lifecycle provides a robust and flexible framework for interacting with the blockchain. By breaking the process into distinct stages—Preparation, Encoding, Signing, and Sending—the OCAP Client offers developers granular control over transaction creation while also providing simple, high-level helpers for common use cases.

For more details on how transaction fees are handled, see the [Gas Payment](/en/docs/blockchain-sdk-nodejs/core-concepts-gas-payment-8cbd10/) guide. To understand the different client types available, refer to the [Client Architecture](/en/docs/blockchain-sdk-nodejs/core-concepts-client-architecture-8cbd10/) documentation.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/getting-started-8cbd10/

Welcome! This guide will get you up and running with the OCAP Client in under 30 minutes. You'll learn how to install the client, connect your application to an OCAP-compatible blockchain, and make your first API call to verify your setup.

Follow these simple steps to begin interacting with the network.

::::card-group
::link-card{title="Installation" description="Learn how to add the OCAP Client package to your project using npm or pnpm." icon="download" href="/en/docs/blockchain-sdk-nodejs/getting-started-installation-8cbd10/"}
::link-card{title="Basic Usage" description="Initialize the client, connect to the Beta chain, and make your first API call to verify your setup." icon="play" href="/en/docs/blockchain-sdk-nodejs/getting-started-basic-usage-8cbd10/"}
::::

Once you've completed these initial steps, you'll be ready to explore more advanced features. For practical, task-oriented examples, be sure to check out the [How-to Guides](/en/docs/blockchain-sdk-nodejs/how-to-guides-8cbd10/).

---

## Basic Usage

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/getting-started-basic-usage-8cbd10/

This guide will walk you through the essential steps to get started with the OCAP Client. You'll learn how to initialize the client, connect to the ArcBlock Beta Chain, and perform a basic query to ensure everything is set up correctly.

Following this guide, you should have a working client instance ready to interact with the blockchain in just a few minutes.

## 1. Initialize the Client

First, you need to import the `@ocap/client` package and create an instance of `GraphQLClient`. The constructor takes the GraphQL endpoint of the blockchain node you want to connect to. For this guide, we will use the public endpoint for the ArcBlock Beta Chain.

**Initialize Client**

```javascript
const GraphQLClient = require('@ocap/client');

// Connect to the Beta Chain
const client = new GraphQLClient('https://beta.abtnetwork.io/api');

console.log('OCAP Client initialized!');
```

This creates a client instance that is pre-configured with methods for querying the chain, sending transactions, and more.

## 2. Query the Blockchain

Now that the client is initialized, you can perform a simple read-only operation to verify the connection. The `getChainInfo` method is perfect for this, as it fetches basic information about the connected blockchain and doesn't require any authentication.

**Query Chain Info**

```javascript
(async () => {
  try {
    const { info } = await client.getChainInfo();
    console.log('Chain Info:', info);
  } catch (error) {
    console.error('Failed to get chain info:', error);
  }
})();
```

If the request is successful, the `info` object will be logged to the console, containing details about the chain such as its ID, network, and supported transaction types. This confirms your client is successfully communicating with the blockchain node.

## 3. Prepare an Account

To send transactions (write operations), you need a wallet. You can generate a new wallet locally. This wallet represents your on-chain account identity.

**Create a Wallet**

```javascript
const { fromRandom } = require('@ocap/wallet');

// Create a new random wallet
const wallet = fromRandom();

console.log('New wallet created:');
console.log('Address:', wallet.address);
console.log('PublicKey:', wallet.publicKey);
console.log('SecretKey:', wallet.secretKey);
```

<strong>Important:</strong> A newly generated wallet is just a key pair. It does not exist on the blockchain yet. An account is automatically created on-chain when its address receives its first incoming transaction.

To make your new account active, you need to fund it with some test tokens. You can get free test tokens (`TBA`) for the Beta Chain from the official faucet:

:::action-card{title="ArcBlock Faucet" description="Visit the faucet and send some TBA to your newly generated address to activate it." icon="droplets"}
::action{label="Get Test Tokens" href="https://faucet.abtnetwork.io/" variant="primary"}
:::

## 4. Query Account State

Once you have funded your new account using the faucet, you can query its state to verify the balance.

**Query Account State**

```javascript
(async () => {
  try {
    // Replace with the address you funded from the faucet
    const address = wallet.address;

    const { state } = await client.getAccountState({ address });
    console.log('Account State:', state);
  } catch (error) {
    console.error('Failed to get account state:', error);
  }
})();
```

The `state` object in the response will contain your account's address, balance, nonce (number of transactions sent), and other details. Seeing a non-zero balance confirms that your account has received the tokens from the faucet and is now active on the blockchain.

## Next Steps

You have successfully set up the OCAP Client, connected to the blockchain, and verified your account. You are now ready to explore more advanced operations.

Check out the [How-to Guides](/en/docs/blockchain-sdk-nodejs/how-to-guides-8cbd10/) to learn how to perform common tasks like transferring tokens, managing assets, and more.

---

## Installation

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/getting-started-installation-8cbd10/

The OCAP Client is a JavaScript library that connects your application to an OCAP blockchain. It works in both Node.js and browser environments. This guide will walk you through installing the client using a package manager.

## Prerequisites

Before you begin, ensure you have the following installed:

- [Node.js](https://nodejs.org/) (which includes the npm package manager)
- [pnpm](https://pnpm.io/) (optional, but recommended)

## Install the Package

You can install the `@ocap/client` package from the npm registry using either `npm` or `pnpm`.

### Using npm

Run the following command in your project's terminal:

**npm**

```shell
npm install @ocap/client
```

### Using pnpm

If you prefer using `pnpm`, run this command:

**pnpm**

```shell
pnpm install @ocap/client
```

This command will download the package and add it to your project's dependencies.

## Verify Installation

After the installation is complete, you can verify that the package is correctly installed by importing it into a JavaScript file. Create a file named `test-client.js` and add the following code:

**Verify Installation**

```javascript
const OCapClient = require('@ocap/client');

if (OCapClient) {
  console.log('Successfully installed and imported @ocap/client!');
} else {
  console.error('Failed to import @ocap/client.');
}
```

Run the file from your terminal:

```shell
node test-client.js
```

You should see the success message printed to the console, confirming that the client is ready to use.

## Next Steps

Now that you have the client installed, you're ready to connect to the blockchain and start making requests. Continue to the next section to learn the basics.

- [<strong>Basic Usage</strong>](/en/docs/blockchain-sdk-nodejs/getting-started-basic-usage-8cbd10/): Learn how to initialize the client and make your first query.

---

## How-to Guides

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-8cbd10/

This section provides practical, step-by-step instructions for completing common tasks with the OCAP Client. Each guide is designed as a self-contained recipe to help you accomplish a specific goal, from managing accounts to performing complex atomic swaps.

::::card-group
::link-card{title="Manage Accounts" description="Covers account-related operations such as migrating an account to new keys." icon="user" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-accounts-8cbd10/"}
::link-card{title="Delegate Permissions" description="Shows how to authorize another account to send transactions on your behalf, specifying which actions are permitted." icon="key" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-delegate-permissions-8cbd10/"}
::link-card{title="Transfer Tokens and NFTs" description="Provides a step-by-step guide on transferring fungible tokens and non-fungible tokens (assets) between accounts." icon="refresh" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-transfer-tokens-and-nfts-8cbd10/"}
::link-card{title="Manage Assets (NFTs)" description="Walks through the complete lifecycle of Non-Fungible Tokens, including creation, updating, and acquiring assets from a factory." icon="star" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-assets-8cbd10/"}
::link-card{title="Manage Tokens" description="Explains how to perform fungible token operations like minting and burning tokens from a token factory." icon="wallet" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-tokens-8cbd10/"}
::link-card{title="Stake Tokens and Assets" description="A step-by-step guide on how to stake tokens or assets to a receiver, including revoking and claiming stakes." icon="wallet" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-stake-tokens-and-assets-8cbd10/"}
::link-card{title="Perform Atomic Swaps" description="A guide on how to securely exchange tokens and assets between two parties using a multi-signature transaction." icon="refresh" href="how-to-guides-perform-atomic-swaps-8cbd10"}
::::

---

## Delegate Permissions

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-delegate-permissions-8cbd10/

Delegating permissions is a powerful feature that allows one account (the delegator) to authorize another account (the delegatee) to send specific types of transactions on its behalf. This is particularly useful for applications that need to perform actions for a user without having direct access to the user's primary private key. For example, you could delegate permission to an application-specific key to transfer certain assets or interact with a smart contract, enhancing security by limiting the scope of the key's authority.

This guide will walk you through granting, using, and revoking delegations.

## Granting Delegation

To authorize another account, you use the `delegate` method. You must specify who you are delegating to and which specific transaction types they are allowed to send. Each permission can also have limits, such as which tokens or assets can be involved.

### Parameters

- **from** `WalletObject` *(required)* — The wallet object of the delegator (the account granting permissions).
- **to** `WalletObject` *(required)* — The wallet object of the delegatee (the account receiving permissions).
- **privileges** `Array<object>` *(required)* — An array of permission objects to grant. Each object defines a specific authorization.
  - **typeUrl** `string` *(required)* — The type URL of the transaction being permitted (e.g., fg:t:transfer_v2).
  - **limit** `object` — Optional limits on the permission, such as restricting it to specific tokens or assets.
    - **tokens** `Array<string>` — An array of token addresses that this permission applies to.
    - **assets** `Array<string>` — An array of asset addresses that this permission applies to.

### Returns

- **result** `Promise<[string, string]>` — A promise that resolves to an array containing the transaction hash and the newly created delegate address.

### Example

Here’s how to delegate the `transfer` permission from one account to another.

**Granting transfer permission**

```javascript
import Client from '@ocap/client';
import { fromRandom } from '@ocap/wallet';
import { typeUrls } from '@ocap/proto';

const client = new Client('https://beta.abtnetwork.io/api');

// The account granting permission
const delegatorWallet = fromRandom();

// The account receiving permission
const delegateeWallet = fromRandom();

async function grantPermission() {
  try {
    // First, ensure the delegator account has funds.
    // In a real application, you would transfer funds to delegatorWallet.address
    // from a faucet or another account.
    console.log(`Delegator address: ${delegatorWallet.address}`);
    console.log(`Delegatee address: ${delegateeWallet.address}`);
    console.log('Please fund the delegator account before proceeding.');

    const privileges = [
      {
        typeUrl: typeUrls.TransferV2Tx,
        // No limits specified, allowing transfer of any token/asset
        limit: { tokens: [], assets: [] },
      },
    ];

    const [hash, delegateAddress] = await client.delegate({
      from: delegatorWallet,
      to: delegateeWallet,
      privileges: privileges,
    });

    console.log('Delegation successful!');
    console.log('Transaction Hash:', hash);
    console.log('Delegate Address:', delegateAddress);
  } catch (error) {
    console.error('Error delegating permissions:', error);
  }
}

grantPermission();
```

## Sending a Transaction as a Delegatee

Once delegated, the delegatee wallet can send the authorized transaction by specifying the `delegator`'s address in the transaction parameters. The transaction is signed by the delegatee, but executed on behalf of the delegator, and the transaction fees are paid from the delegator's account.

### Example

**Sending a transfer as a delegatee**

```javascript
// Assuming the grantPermission() function from the previous example was successful

// The recipient of the transfer
const recipientWallet = fromRandom();

async function sendDelegatedTransaction() {
  try {
    const hash = await client.transfer({
      to: recipientWallet.address,
      token: 1, // Transfer 1 of the chain's native token
      wallet: delegateeWallet, // Signed by the delegatee
      delegator: delegatorWallet.address, // Executed on behalf of the delegator
    });

    console.log('Delegated transfer successful!');
    console.log('Transaction Hash:', hash);
    console.log(`Check transaction at: https://beta.abtnetwork.io/explorer/txs/${hash}`);
  } catch (error) {
    console.error('Error sending delegated transaction:', error);
  }
}

// Make sure to call this after the delegation is confirmed on-chain.
// sendDelegatedTransaction();
```

## Revoking Delegation

The delegator can revoke any granted permissions at any time using the `revokeDelegate` method. You need to specify which transaction types to revoke for a given delegatee.

### Parameters

- **from** `WalletObject` *(required)* — The wallet object of the delegator who originally granted the permissions.
- **to** `WalletObject` *(required)* — The wallet object of the delegatee whose permissions are being revoked.
- **privileges** `Array<string>` *(required)* — An array of transaction typeUrl strings to revoke.

### Returns

- **hash** `Promise<string>` — A promise that resolves to the transaction hash for the revocation.

### Example

**Revoking transfer permission**

```javascript
// Assuming the same delegatorWallet and delegateeWallet from previous examples

async function revokePermission() {
  try {
    const hash = await client.revokeDelegate({
      from: delegatorWallet,
      to: delegateeWallet,
      privileges: [typeUrls.TransferV2Tx], // The list of permissions to revoke
    });

    console.log('Revocation successful!');
    console.log('Transaction Hash:', hash);
    console.log(`Check transaction at: https://beta.abtnetwork.io/explorer/txs/${hash}`);
  } catch (error) {
    console.error('Error revoking delegation:', error);
  }
}

// revokePermission();
```

After this transaction is confirmed, the `delegateeWallet` will no longer be able to send `transfer` transactions on behalf of the `delegatorWallet`.

---

## Manage Accounts

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-accounts-8cbd10/

On an OCAP-powered blockchain, an account is fundamentally a state associated with an address, controlled by a pair of cryptographic keys (a public key and a private key). A key concept to understand is that accounts are created implicitly. An account officially exists on-chain as soon as it receives its first incoming transaction, such as a token or asset transfer. There is no explicit `createAccount` transaction.

This guide covers migration from an old account to a different address controlled by a new key pair. The chain records the migration relationship. Fees, asset rules, and application-specific records must be checked separately; migration does not guarantee an unchanged balance or move every associated object.

## Migrate an Account to New Keys

The `migrateAccount` function submits the target wallet’s address and public key, using the original wallet to sign. The target address must differ from the sender and must not already have an account state in the implementation described below. This is useful in several scenarios, such as:

- <strong>Key Compromise</strong>: If you suspect your private key has been exposed, you can migrate the account to a new, secure key pair to replace the exposed key’s control after migration takes effect. Until then, an attacker with that key may also act.
- <strong>Upgrading Security</strong>: You might want to migrate from an older key type to a newer, more secure one.

This operation effectively transfers control of the account while preserving its history and state on the blockchain.

### Parameters

- **from** `WalletObject` *(required)* — The wallet object representing the current account that is being migrated. This wallet must sign the transaction to prove ownership.
- **to** `WalletObject` *(required)* — The new wallet object to which control will be transferred. Its address and matching public key identify the new target account, not a replacement key at the unchanged old address.

### Returns

The `migrateAccount` method returns a Promise that resolves to the transaction hash as a string.

Source correction (September 29, 2026): this address behavior is verified against `@ocap/client` and `@ocap/tx-protocols` 1.20.2 in the [publicly distributed implementation](https://unpkg.com/@ocap/tx-protocols@1.20.2/lib/protocols/account/migrate.js). The earlier wording incorrectly said the address would stay unchanged. The original key is required; this is not recovery after total key loss. See [the migration explanation](/en/articles/account-migration-old-address/) for old-address resolution and historical signatures.

The following is a historical SDK example. Verify package compatibility and supply a working test-network endpoint and explorer for your deployment; availability of the old example services has not been established.

### Example

Here's how to migrate an account from an old wallet to a new one.

**Migrating an Account**

```javascript
import Client from '@ocap/client';
import { fromRandom } from '@ocap/wallet';

const client = new Client('https://beta.abtnetwork.io/api');

// Assume oldWallet is the currently authorized wallet for the account
const oldWallet = fromRandom();

// Create a new wallet with a new set of keys
const newWallet = fromRandom();

async function migrate() {
  try {
    // Before migrating, you would typically fund the oldWallet's address.
    // For this example, we'll assume it has enough funds to pay for the transaction fee.
    // You can get test tokens from https://faucet.abtnetwork.io/
    console.log(`Migrating account from ${oldWallet.address} to target address ${newWallet.address}`);

    const hash = await client.migrateAccount({
      from: oldWallet,
      to: newWallet,
    });

    console.log('Account migration transaction sent successfully!');
    console.log('Transaction Hash:', hash);
    console.log(`View transaction at: https://beta.abtnetwork.io/explorer/txs/${hash}`);

  } catch (err) {
    console.error('Error migrating account:', err);
  }
}

migrate();
```

Now that you know how to secure your account by migrating keys, you might want to learn how to grant limited permissions to other accounts without sharing your primary keys. See the [Delegate Permissions](/en/docs/blockchain-sdk-nodejs/how-to-guides-delegate-permissions-8cbd10/) guide for more details.

---

## Manage Assets (NFTs)

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-assets-8cbd10/

This guide provides a comprehensive walkthrough of managing the entire lifecycle of Non-Fungible Tokens (NFTs), also known as assets, using the OCAP Client. You will learn how to create new assets from scratch, update their properties, establish an asset factory for standardized minting, and acquire new assets from that factory.

## Create a New Asset

You can create a unique, standalone asset on the blockchain using the `createAsset` method. Each asset is assigned a unique on-chain address derived from its initial properties.

```javascript
const { wallet } = getWallet(); // User's wallet object

async function createNewAsset() {
  try {
    const [hash, address] = await client.createAsset({
      moniker: 'My Unique Digital Artwork',
      data: {
        typeUrl: 'json',
        value: {
          description: 'A one-of-a-kind piece created by Artist X.',
          imageUrl: 'https://example.com/path/to/image.png',
        },
      },
      readonly: true,
      transferrable: true,
      wallet: wallet,
    });

    console.log(`Asset creation transaction sent: ${hash}`);
    console.log(`New asset address: ${address}`);
    return address;
  } catch (error) {
    console.error('Error creating asset:', error);
  }
}

createNewAsset();
```

### Parameters

- **moniker** `string` *(required)* — The name of the asset.
- **parent** `string` (default: `''`) — The address of a parent asset, if any.
- **data** `object` *(required)* — The data payload for the asset, which must include a typeUrl and value.
- **readonly** `boolean` (default: `false`) — If true, the asset cannot be updated after creation.
- **transferrable** `boolean` (default: `true`) — If true, the asset can be transferred to another account.
- **ttl** `number` (default: `0`) — Time-to-live in seconds after the asset's first consumption.
- **display** `object` — Object containing display information for the asset.
- **endpoint** `object` — Object containing endpoint details for the asset.
- **tags** `string[]` (default: `[]`) — An array of strings to categorize the asset.
- **wallet** `WalletObject` *(required)* — The wallet object of the asset's initial owner.
- **delegator** `string` (default: `''`) — The address of the account that authorized this transaction via delegation.

### Returns

A `Promise` that resolves to an array containing the transaction hash and the new asset's on-chain address.

- **response** `Promise<[string, string]>` — [transactionHash, assetAddress]

## Update an Existing Asset

If an asset was created with `readonly: false`, you can modify its `moniker` and `data` fields using the `updateAsset` method. The asset is identified by its unique address.

```javascript
const { wallet } = getWallet(); // User's wallet object
const assetAddress = 'z362...'; // Address of the asset to update

async function updateExistingAsset() {
  try {
    const hash = await client.updateAsset({
      address: assetAddress,
      moniker: 'My Updated Digital Artwork',
      data: {
        typeUrl: 'json',
        value: {
          description: 'An updated description for my unique piece.',
          imageUrl: 'https://example.com/path/to/new_image.png',
        },
      },
      wallet: wallet,
    });

    console.log(`Asset update transaction sent: ${hash}`);
  } catch (error) {
    console.error('Error updating asset:', error);
  }
}

updateExistingAsset();
```

### Parameters

- **address** `string` *(required)* — The on-chain address of the asset to update.
- **moniker** `string` *(required)* — The new name for the asset.
- **data** `object` *(required)* — The updated data payload for the asset.
- **wallet** `WalletObject` *(required)* — The wallet object of the current asset owner.

### Returns

A `Promise` that resolves to the transaction hash.

- **response** `Promise<string>` — transactionHash

## Create an Asset Factory

An Asset Factory is a template for creating multiple, similar assets. It defines the structure, rules, and logic for minting new assets, which is more efficient than creating each one individually. This is ideal for use cases like issuing event tickets, certificates, or collectibles.

```javascript
const { wallet } = getWallet(); // Factory owner's wallet

const factoryDefinition = {
  name: 'Conference Ticket Factory',
  description: 'Mints tickets for the 2024 Tech Conference.',
  limit: 1000, // Max 1000 tickets can be minted
  input: {
    // Defines what data is required to mint an asset
    type: 'object',
    properties: {
      attendeeName: { type: 'string' },
      ticketType: { type: 'string', enum: ['General', 'VIP'] },
    },
  },
  output: {
    // Defines the structure of the minted asset
    moniker: 'Ticket for {{attendeeName}}',
    description: '{{ticketType}} admission for the 2024 Tech Conference.',
    transferrable: false, // Tickets are non-transferrable
  },
  hooks: [],
};

async function createFactory() {
  try {
    const [hash, factoryAddress] = await client.createAssetFactory({
      factory: factoryDefinition,
      wallet: wallet,
    });

    console.log(`Factory creation transaction sent: ${hash}`);
    console.log(`New factory address: ${factoryAddress}`);
  } catch (error) {
    console.error('Error creating asset factory:', error);
  }
}

createFactory();
```

### Parameters

- **factory** `object` *(required)* — An object defining the factory's properties and minting logic.
  - **name** `string` *(required)* — Name of the factory.
  - **description** `string` *(required)* — Description of the factory's purpose.
  - **limit** `number` (default: `0`) — The maximum number of assets that can be minted from this factory. 0 means unlimited.
  - **trustedIssuers** `string[]` — A list of account addresses authorized to mint from this factory.
  - **input** `object` *(required)* — Defines the required input data for minting an asset.
  - **output** `object` *(required)* — Defines the structure and properties of the asset that will be minted.
  - **hooks** `object[]` — A list of hooks to execute during the minting process.
  - **data** `object` — Additional arbitrary data to store with the factory.
- **wallet** `WalletObject` *(required)* — The wallet object of the factory's owner.

### Returns

A `Promise` that resolves to an array containing the transaction hash and the new factory's on-chain address.

- **response** `Promise<[string, string]>` — [transactionHash, factoryAddress]

## Acquire an Asset from a Factory

Acquiring an asset from a factory is a two-step process. First, you prepare the minting data, which allows you to preview the asset that will be created. Second, you submit the transaction to the blockchain to officially acquire the asset.

This separation is useful because it allows an application to show a user what they are about to receive before they sign and submit the final transaction.

### Step 1: Prepare the Asset Data

The `preMintAsset` method takes the factory address and user-provided inputs to generate the final asset data. This happens off-chain and does not require a transaction.

```javascript
const factoryAddress = 'z2...'; // Address of the factory created previously
const { wallet: issuerWallet } = getIssuerWallet(); // The factory owner or a trusted issuer
const { wallet: userWallet } = getUserWallet(); // The user who will own the new asset

async function prepareAssetForMinting() {
  try {
    const mintingData = await client.preMintAsset({
      factory: factoryAddress,
      inputs: {
        attendeeName: 'John Doe',
        ticketType: 'VIP',
      },
      owner: userWallet.address,
      wallet: issuerWallet,
    });

    console.log('Prepared asset data for minting:', mintingData);
    return mintingData;
  } catch (error) {
    console.error('Error preparing asset:', error);
  }
}
```

### Step 2: Send the Transaction

Once the minting data is prepared, the user (the future asset owner) signs and sends the `acquireAsset` transaction. The `itx` object from `preMintAsset` is used as the payload.

```javascript
async function acquireNewAsset() {
  // First, get the minting data from Step 1
  const itx = await prepareAssetForMinting();
  if (!itx) return;

  try {
    const hash = await client.acquireAsset({
      itx: itx,
      wallet: userWallet, // The user's wallet signs the transaction
    });

    console.log(`Asset acquisition transaction sent: ${hash}`);
    console.log(`New asset will be available at address: ${itx.address}`);
  } catch (error) {
    console.error('Error acquiring asset:', error);
  }
}

acquireNewAsset();
```

### Parameters for acquireAsset

- **itx** `object` *(required)* — The inner transaction object returned from the `preMintAsset` method.
- **wallet** `WalletObject` *(required)* — The wallet of the user who is acquiring the asset.
- **delegator** `string` (default: `''`) — The address of the account that authorized this transaction via delegation.

### Returns

A `Promise` that resolves to the transaction hash for the `acquireAsset` operation.

- **response** `Promise<string>` — transactionHash

## Mint an Asset from a Factory

In addition to the user-led `acquireAsset` flow, an authorized issuer (such as the factory owner or a trusted issuer) can mint an asset and send it directly to a user's account. This process also uses `preMintAsset` to prepare the data, but the final transaction is `mintAsset`, signed by the issuer.

This flow is useful for scenarios like airdrops, awarding certificates, or any case where the receiving user does not need to initiate the final transaction.

### Step 1: Prepare the Asset Data

This step is identical to the acquisition flow. The issuer calls `preMintAsset` to generate the transaction payload (`itx`) off-chain.

```javascript
const factoryAddress = 'z2...'; // Address of the factory
const { wallet: issuerWallet } = getIssuerWallet(); // The factory owner or a trusted issuer
const userAddress = 'z1...'; // The address of the user who will receive the asset

async function prepareAssetForMinting() {
  try {
    const mintingData = await client.preMintAsset({
      factory: factoryAddress,
      inputs: {
        attendeeName: 'Jane Smith',
        ticketType: 'General',
      },
      owner: userAddress,
      wallet: issuerWallet, // Issuer's wallet is used here
    });

    console.log('Prepared asset data for minting:', mintingData);
    return mintingData;
  } catch (error) {
    console.error('Error preparing asset:', error);
  }
}
```

### Step 2: Send the Mint Transaction

The issuer uses the prepared `itx` object to call `mintAsset`. The transaction is signed with the issuer's wallet, and the newly created asset is assigned to the owner specified in the previous step.

```javascript
async function mintNewAsset() {
  // First, get the minting data from Step 1
  const itx = await prepareAssetForMinting();
  if (!itx) return;

  try {
    // The issuer's wallet signs the transaction
    const hash = await client.mintAsset({
      itx: itx,
      wallet: issuerWallet,
    });

    console.log(`Asset minting transaction sent: ${hash}`);
    console.log(`New asset for ${userAddress} will be available at address: ${itx.address}`);
  } catch (error) {
    console.error('Error minting asset:', error);
  }
}

mintNewAsset();
```

### Parameters for mintAsset

- **itx** `object` *(required)* — The inner transaction object returned from the `preMintAsset` method.
- **wallet** `WalletObject` *(required)* — The wallet of the issuer who is minting the asset.

### Returns

A `Promise` that resolves to the transaction hash for the `mintAsset` operation.

- **response** `Promise<string>` — transactionHash

---

## Manage Tokens

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-tokens-8cbd10/

This guide provides step-by-step instructions for managing fungible tokens using the OCAP Client. You will learn how to set up a token factory, which acts as a blueprint for your token, and then use it to mint (create new tokens) and burn (destroy existing tokens). These operations are fundamental to creating and managing custom economies within your application.

Once you have minted tokens, you can transfer them between accounts. For more details on that process, please see the [Transfer Tokens and NFTs](/en/docs/blockchain-sdk-nodejs/how-to-guides-transfer-tokens-and-nfts-8cbd10/) guide.

## Create a Token Factory

A token factory is a smart contract that defines the properties and rules of a fungible token, such as its name, symbol, and supply mechanics. It also governs the process of minting and burning. Creating a factory is the first step before any new tokens can be brought into circulation.

The `createTokenFactory` method deploys a new token factory to the blockchain.

### Parameters

- **wallet** `WalletObject` *(required)* — The wallet object of the factory owner, used to sign the transaction.
- **token** `object` *(required)* — An object defining the properties of the token to be created.
  - **name** `string` *(required)* — The full name of the token (e.g., 'My Awesome Token').
  - **symbol** `string` *(required)* — The token's ticker symbol (e.g., 'MAT').
  - **decimal** `number` *(required)* — The number of decimal places the token supports.
  - **description** `string` — A brief description of the token.
  - **icon** `string` — URL to an icon for the token.
  - **maxTotalSupply** `number` — The maximum total supply that can ever be minted.
- **curve** `object` — Configuration for a bonding curve, which programmatically controls the token's price. If omitted, minting/burning is not tied to a reserve token.
  - **basePrice** `number` — The base price for the token in the reserve currency.
  - **fixedPrice** `number` — A fixed price for the token, if not using a dynamic curve.
  - **slope** `number` — The slope of the bonding curve, determining its steepness.
- **feeRate** `number` (default: `0`) — The fee rate (in basis points) for minting and burning operations.
- **data** `object` — Optional custom data to attach to the token factory.

### Returns

Returns a promise that resolves to an array containing the transaction hash and the address of the newly created token factory.

- **[0]** `string` — The transaction hash for the factory creation.
- **[1]** `string` — The address of the new token factory.

### Example

**Create a Token Factory**

```javascript
import Client from '@ocap/client';
import Wallet from '@ocap/wallet';

const endpoint = 'https://beta.abtnetwork.io/api';
const client = new Client(endpoint);
const wallet = Wallet.fromRandom();

// First, ensure the wallet has funds. You can get test tokens from a faucet:
// https://faucet.abtnetwork.io/

async function createFactory() {
  try {
    const [hash, factoryAddress] = await client.createTokenFactory({
      wallet,
      token: {
        name: 'My Game Coin',
        symbol: 'MGC',
        decimal: 18,
        description: 'The official currency for My Awesome Game.',
        maxTotalSupply: 1000000,
      },
      feeRate: 100, // 1% fee
    });

    console.log('Token factory created successfully!');
    console.log('Transaction Hash:', hash);
    console.log('Factory Address:', factoryAddress);
    return factoryAddress;
  } catch (error) {
    console.error('Error creating token factory:', error);
  }
}

createFactory();
```

## Mint Tokens

Minting is the process of creating new tokens and adding them to the total supply. This is done through a token factory. If the factory was configured with a bonding curve, minting will require a payment in the reserve token.

The `mintToken` method initiates a transaction to mint a specified amount of tokens from a factory.

### Parameters

- **wallet** `WalletObject` *(required)* — The wallet funding the mint operation and signing the transaction.
- **tokenFactory** `string` *(required)* — The address of the token factory to mint from.
- **amount** `number` *(required)* — The quantity of tokens to mint.
- **receiver** `string` *(required)* — The address that will receive the newly minted tokens.
- **maxReserve** `number` *(required)* — The maximum amount of the reserve token the wallet is willing to spend. This acts as a slippage protection mechanism.
- **data** `object` — Optional custom data to attach to the mint transaction.

### Returns

Returns a promise that resolves to the transaction hash.

- **hash** `string` — The transaction hash for the mint operation.

### Example

**Mint Tokens from a Factory**

```javascript
async function mintNewTokens(factoryAddress) {
  try {
    const hash = await client.mintToken({
      wallet,
      tokenFactory: factoryAddress,
      amount: 5000,
      receiver: wallet.address, // Mint tokens to our own wallet
      maxReserve: 10, // Max reserve token to pay. Adjust based on bonding curve price.
    });

    console.log('Tokens minted successfully!');
    console.log('Transaction Hash:', hash);
  } catch (error) {
    console.error('Error minting tokens:', error);
  }
}

// Assuming `factoryAddress` is available from the createFactory example
// const factoryAddress = '...';
// mintNewTokens(factoryAddress);
```

## Burn Tokens

Burning is the opposite of minting; it permanently removes tokens from circulation. If the token factory uses a bonding curve, burning tokens will return a proportional amount of the reserve currency to the user.

The `burnToken` method initiates this process.

### Parameters

- **wallet** `WalletObject` *(required)* — The wallet that holds the tokens to be burned and will sign the transaction.
- **tokenFactory** `string` *(required)* — The address of the token factory.
- **amount** `number` *(required)* — The quantity of tokens to burn.
- **receiver** `string` *(required)* — The address that will receive the reserve tokens in return.
- **minReserve** `number` *(required)* — The minimum amount of the reserve token the wallet expects to receive. This protects against price slippage.
- **data** `object` — Optional custom data to attach to the burn transaction.

### Returns

Returns a promise that resolves to the transaction hash.

- **hash** `string` — The transaction hash for the burn operation.

### Example

**Burn Tokens**

```javascript
async function burnExistingTokens(factoryAddress) {
  try {
    const hash = await client.burnToken({
      wallet,
      tokenFactory: factoryAddress,
      amount: 1000,
      receiver: wallet.address, // Receive reserve tokens back to our own wallet
      minReserve: 1, // Min reserve token to receive. Adjust based on bonding curve price.
    });

    console.log('Tokens burned successfully!');
    console.log('Transaction Hash:', hash);
  } catch (error) {
    console.error('Error burning tokens:', error);
  }
}

// Assuming `factoryAddress` is available from the createFactory example
// const factoryAddress = '...';
// burnExistingTokens(factoryAddress);
```

## Summary

In this guide, you've learned the complete lifecycle for managing fungible tokens: creating a factory, minting new tokens into existence, and burning them to reduce the supply. These powerful primitives allow you to build sophisticated economic systems on the OCAP platform.

Now that you know how to create tokens, the next logical step is to learn how to move them around. Head over to the [Transfer Tokens and NFTs](/en/docs/blockchain-sdk-nodejs/how-to-guides-transfer-tokens-and-nfts-8cbd10/) guide to see how it's done.

---

## Stake Tokens and Assets

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-stake-tokens-and-assets-8cbd10/

Staking is the process of locking up tokens or assets (NFTs) to a specific receiver, often to secure a network, participate in governance, or earn rewards. This guide provides a step-by-step walkthrough of the entire staking lifecycle using the OCAP Client, including creating a stake, revoking it, claiming the assets back, and slashing a stake for punitive reasons.

This process involves a few key methods:

- `stake()`: To create a new stake.
- `revokeStake()`: To initiate the process of withdrawing your staked items.
- `claimStake()`: To finalize the withdrawal and return the items to your account.
- `slashStake()`: To allow authorized parties to penalize a staker.

## How to Stake

To begin, you use the `stake` method to lock your tokens or assets. This action creates a new, unique stake address on the chain that holds your staked items and the rules governing them.

### Parameters

- **to** `string` *(required)* — The DID address of the account that will receive the stake.
- **assets** `string[]` — An array of asset addresses (NFTs) to be staked.
- **tokens** `object[]` — An array of token objects to be staked.
  - **address** `string` *(required)* — The address of the token contract.
  - **value** `number` *(required)* — The amount of tokens to stake.
- **wallet** `WalletObject` *(required)* — The wallet object of the staker.
- **locked** `boolean` (default: `false`) — A boolean indicating if the stake is locked upon creation.
- **slashers** `string[]` — An array of DID addresses permitted to slash this stake. Defaults to the receiver's address if not provided.
- **message** `string` — An optional note or message for the stake.
- **nonce** `string` — An optional nonce to ensure the stake address is unique.

### Example

**Staking Tokens and an Asset**

```javascript
// Assume 'client' is an initialized GraphQLClient instance
// and 'stakerWallet' is a valid wallet object.
const receiverAddress = 'z29d5852576b8a8b6f3a8b4b74a3f4a3e2e1d'; // The address of the stake receiver

async function createStake() {
  try {
    const [txHash, stakeAddress] = await client.stake({
      to: receiverAddress,
      tokens: [{
        address: 'z35n6aTUTK8h5nAF43h21A1g84g3C3D7B5E', // Address of the token to stake
        value: 100, // Amount of tokens to stake
      }],
      assets: ['zNKtA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6'], // Address of the asset/NFT to stake
      message: 'Staking for validator rewards',
      wallet: stakerWallet,
    });

    console.log('Stake transaction sent:', txHash);
    console.log('New stake address created:', stakeAddress);
    return stakeAddress;
  } catch (error) {
    console.error('Error creating stake:', error);
  }
}
```

### Return Value

The `stake` method returns a tuple containing the transaction hash and the newly created `stakeAddress`. This address is crucial for all future interactions with this specific stake, such as revoking or slashing.

## How to Revoke a Stake

Revoking a stake is the process initiated by the staker to retrieve their locked tokens and assets. This transaction does not immediately return the funds; instead, it marks them as available for claiming, subject to any on-chain lock-up periods.

### Parameters

- **from** `string` *(required)* — The address of the stake to be revoked (obtained from the 'stake' call).
- **assets** `string[]` — An array of asset addresses to revoke from the stake.
- **tokens** `object[]` — An array of token objects to revoke.
  - **address** `string` *(required)* — The address of the token contract.
  - **value** `number` *(required)* — The amount of tokens to revoke.
- **wallet** `WalletObject` *(required)* — The staker's wallet object, which must be the original creator of the stake.

### Example

**Revoking a Stake**

```javascript
// Assume 'stakeAddress' is the address returned from the previous step
// and 'stakerWallet' is the same wallet used to create the stake.

async function revokeExistingStake(stakeAddress) {
  try {
    const revokeTxHash = await client.revokeStake({
      from: stakeAddress,
      tokens: [{
        address: 'z35n6aTUTK8h5nAF43h21A1g84g3C3D7B5E',
        value: 100,
      }],
      assets: ['zNKtA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6'],
      wallet: stakerWallet,
    });

    console.log('Revoke stake transaction sent:', revokeTxHash);
    console.log('IMPORTANT: Save this hash to claim your stake later.');
    return revokeTxHash;
  } catch (error) {
    console.error('Error revoking stake:', error);
  }
}
```

### Return Value

This function returns the transaction hash of the revoke operation. This hash serves as evidence and is <strong>required</strong> for the final step of claiming the stake.

## How to Claim a Revoked Stake

After a stake has been successfully revoked, the staker must send a `claimStake` transaction to move the tokens and assets back into their account. This finalizes the withdrawal process.

### Parameters

- **from** `string` *(required)* — The address of the stake.
- **evidence** `string` *(required)* — The transaction hash from the 'revokeStake' call, which serves as proof of revocation.
- **wallet** `WalletObject` *(required)* — The staker's wallet object.

### Example

**Claiming Staked Items**

```javascript
// Assume 'stakeAddress' and 'revokeTxHash' are from the previous steps,
// and 'stakerWallet' is the staker's wallet.

async function claimRevokedStake(stakeAddress, revokeTxHash) {
  try {
    const claimTxHash = await client.claimStake({
      from: stakeAddress,
      evidence: revokeTxHash,
      wallet: stakerWallet,
    });

    console.log('Claim stake transaction sent:', claimTxHash);
    console.log('Your tokens and assets have been returned to your account.');
  } catch (error) {
    console.error('Error claiming stake:', error);
  }
}
```

### Return Value

The method returns the final transaction hash. Once this transaction is confirmed on the chain, the staked items are returned to the `wallet`'s address.

## How to Slash a Stake

Slashing is a punitive action that can be taken by a designated `slasher` (usually the stake receiver) against a staker. This typically happens if the staker violates certain rules. The slashed tokens or assets are removed from the stake and sent to a designated vault.

### Parameters

- **from** `string` *(required)* — The address of the stake to be slashed.
- **reason** `string` *(required)* — A mandatory message explaining why the slash is occurring.
- **assets** `string[]` — An array of asset addresses to be slashed from the stake.
- **tokens** `object[]` — An array of token objects to be slashed.
  - **address** `string` *(required)* — The address of the token contract.
  - **value** `number` *(required)* — The amount of tokens to slash.
- **wallet** `WalletObject` *(required)* — The wallet object of an authorized slasher.

### Example

**Slashing a Stake**

```javascript
// Assume 'stakeAddress' is the address of the stake to be slashed,
// and 'slasherWallet' is the wallet of an authorized slasher.

async function slashExistingStake(stakeAddress) {
  try {
    const slashTxHash = await client.slashStake({
      from: stakeAddress,
      reason: 'Validator missed signing 10 consecutive blocks.',
      tokens: [{
        address: 'z35n6aTUTK8h5nAF43h21A1g84g3C3D7B5E',
        value: 10, // Slashing 10 tokens as a penalty
      }],
      wallet: slasherWallet,
    });

    console.log('Slash stake transaction sent:', slashTxHash);
  } catch (error) {
    console.error('Error slashing stake:', error);
  }
}
```

### Return Value

This method returns the transaction hash for the slashing operation.

## Summary

You've now learned the complete lifecycle of staking on the OCAP blockchain: creating a stake with `stake`, retrieving funds with `revokeStake` and `claimStake`, and penalizing bad actors with `slashStake`. This powerful mechanism is fundamental to many decentralized applications.

To learn more about the items you can stake, see the [Manage Tokens](/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-tokens-8cbd10/) and [Manage Assets (NFTs)](/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-assets-8cbd10/) guides.

---

## Transfer Tokens and NFTs

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/how-to-guides-transfer-tokens-and-nfts-8cbd10/

This guide provides a step-by-step walkthrough for transferring fungible tokens (both native and custom) and non-fungible tokens (NFTs or assets) between accounts using the OCAP Client. The primary method for all transfers is `client.transfer()`.

One key feature to remember is that a new account is automatically created on-chain when it receives its first incoming transaction. This means you can transfer tokens or assets to a brand new address without any prior setup for the recipient.

## The transfer Method

The `client.transfer()` method is a versatile helper function that simplifies the process of sending assets and tokens. It constructs, signs, and sends the appropriate transaction (`transferV2Tx`) to the blockchain in a single call.

### Parameters

- **to** `string` *(required)* — The recipient's account address. This must be a valid DID address.
- **wallet** `WalletObject` *(required)* — The sender's wallet object used to sign the transaction.
- **token** `number` (default: `0`) — The amount of the chain's native token to transfer. The client handles the conversion to the correct decimal units automatically.
- **assets** `string[]` (default: `[]`) — An array of asset addresses (NFTs) to transfer.
- **tokens** `object[]` (default: `[]`) — An array of custom fungible token objects to transfer.
  - **address** `string` *(required)* — The address of the custom token contract.
  - **value** `number` *(required)* — The amount of the custom token to transfer.
- **memo** `string` — An optional message or note to include with the transaction.
- **delegator** `string` — If the wallet is acting on behalf of another account, this should be the address of the delegating account. See the Delegate Permissions guide for more details.

### Returns

- **Promise<string>** `Promise` — A Promise that resolves to the transaction hash upon successful submission to the blockchain.

## Step-by-Step Examples

### Prerequisites

Before you start, make sure you have:

1. An initialized `GraphQLClient` connected to a chain host like `https://beta.abtnetwork.io`.
2. A sender's wallet object (`senderWallet`) that is funded with enough tokens to cover the transfer and transaction fees.
3. A recipient's wallet object (`recipientWallet`) to get their address. The recipient's account does not need to exist on-chain yet.

**Basic Setup**

```javascript
import GraphQLClient from '@ocap/client';
import { fromRandom } from '@ocap/wallet';

// 1. Initialize the client
const client = new GraphQLClient({ endpoint: 'https://beta.abtnetwork.io/api' });

// 2. Create wallets for sender and recipient
// In a real application, the sender's wallet would be loaded, not created randomly.
const senderWallet = fromRandom(); // Assume this wallet is funded
const recipientWallet = fromRandom();

console.log(`Sender Address: ${senderWallet.address}`);
console.log(`Recipient Address: ${recipientWallet.address}`);

// To fund the sender's wallet for this example, use the faucet:
// https://faucet.abtnetwork.io/
```

### Example 1: Transferring Native Tokens

This example shows how to send 10 native tokens from the sender to the recipient.

**Transfer Native Tokens**

```javascript
async function transferNativeTokens() {
  try {
    const hash = await client.transfer({
      to: recipientWallet.address,
      token: 10, // The amount of native tokens to send
      wallet: senderWallet,
      memo: 'Sending you 10 native tokens!'
    });
    console.log('Native token transfer successful. Tx Hash:', hash);
  } catch (err) {
    console.error('Error transferring tokens:', err);
  }
}

transferNativeTokens();
```

### Example 2: Transferring an NFT (Asset)

To transfer an NFT, you need its unique asset address. First, you would create or acquire an asset (see [Manage Assets (NFTs)](/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-assets-8cbd10/)). For this example, let's assume `senderWallet` already owns an NFT with the address `zNKj...`.

**Transfer an NFT**

```javascript
async function transferNFT() {
  // Assume this is the address of an NFT owned by senderWallet
  const nftAddress = 'zNKjL4wTmxQPk5nN2ADDPCd58286b2de3f3e';

  try {
    const hash = await client.transfer({
      to: recipientWallet.address,
      assets: [nftAddress], // An array of asset addresses
      wallet: senderWallet,
      memo: 'Here is the NFT you wanted.'
    });
    console.log('NFT transfer successful. Tx Hash:', hash);
  } catch (err) {
    console.error('Error transferring NFT:', err);
  }
}

transferNFT();
```

### Example 3: Transferring Custom Tokens

This example demonstrates how to transfer a custom fungible token. You need the token's contract address. See the [Manage Tokens](/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-tokens-8cbd10/) guide for information on creating custom tokens.

**Transfer Custom Tokens**

```javascript
async function transferCustomToken() {
  // Assume this is the address of a custom token owned by senderWallet
  const customTokenAddress = 'z37bA4x...';

  try {
    const hash = await client.transfer({
      to: recipientWallet.address,
      wallet: senderWallet,
      tokens: [
        { address: customTokenAddress, value: 50 } // 50 units of a custom token
      ],
      memo: 'Sending 50 custom tokens.'
    });
    console.log('Custom token transfer successful. Tx Hash:', hash);
  } catch (err) {
    console.error('Error transferring custom token:', err);
  }
}

transferCustomToken();
```

### Example 4: A Combined Transfer

You can send native tokens, custom tokens, and multiple NFTs all in a single, atomic transaction. This is highly efficient.

**Combined Transfer**

```javascript
async function combinedTransfer() {
  // Assume these are addresses of assets and tokens owned by senderWallet
  const nftAddress1 = 'zNKjL4wTmxQPk5nN2ADDPCd58286b2de3f3e';
  const nftAddress2 = 'zNKiabcdeQPk5nN2ADDPCd58286b2defghj';
  const customTokenAddress = 'z37bA4x...'; // Address of a custom fungible token

  try {
    const hash = await client.transfer({
      to: recipientWallet.address,
      wallet: senderWallet,
      token: 5, // 5 native tokens
      assets: [nftAddress1, nftAddress2], // An array of two NFTs
      tokens: [
        { address: customTokenAddress, value: 50 } // 50 units of a custom token
      ],
      memo: 'Sending a mix of tokens and NFTs.'
    });
    console.log('Combined transfer successful. Tx Hash:', hash);
  } catch (err) {
    console.error('Error with combined transfer:', err);
  }
}

combinedTransfer();
```

By following these examples, you can easily implement token and NFT transfers in your application. For more details on creating the items you wish to transfer, please see the related guides.

### Further Reading

- [How to Manage Assets (NFTs)](/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-assets-8cbd10/)
- [How to Manage Tokens](/en/docs/blockchain-sdk-nodejs/how-to-guides-manage-tokens-8cbd10/)
- [High-level API](/en/docs/blockchain-sdk-nodejs/api-reference-transaction-helpers-8cbd10/)

---

## Overview

URL: https://www.arcblock.io/en/docs/blockchain-sdk-nodejs/overview-8cbd10/

The OCAP Client is a powerful and versatile JavaScript library designed to connect your applications to an OCAP-powered blockchain. It provides a streamlined, developer-friendly interface for reading and writing data, managing digital assets, and listening for on-chain events. The client can be used in any Node.js or browser-based environment, offering a single solution for both backend services and frontend applications.

At its core, the client simplifies blockchain interaction by abstracting away the complexities of transaction encoding and signing. It uses a GraphQL API for all communication with the blockchain node over HTTP/S, making it easy to query chain data and submit transactions.

![Overview](https://media.arcblock.io/lib/4c/4c23cadabfce51c5.w1600.webp)

### Key Features

The OCAP Client is organized into several distinct groups of methods to handle different aspects of blockchain communication:

::::card-group
::link-card{title="Queries" description="Read any data from the blockchain, including blocks, transactions, account states, asset details, and general chain information." icon="search"}
::link-card{title="Mutations & Senders" description="Write data to the blockchain. Use high-level helper methods like `transfer` or `createAsset` to easily prepare, sign, and send transactions." icon="send"}
::link-card{title="Subscriptions" description="Listen for real-time on-chain events. Subscribe to topics and receive updates as they happen via a WebSocket connection." icon="radio"}
::link-card{title="Coders & Signers" description="For advanced use cases, you can encode and sign transactions manually, giving you full control over the transaction lifecycle." icon="edit"}
::::

### Important Concepts

- <strong>Automatic Account Creation</strong>: On an OCAP-powered chain, a new account is automatically created on-chain when it receives its first incoming transaction (e.g., receiving tokens). You don't need a separate transaction to initialize an account.
- <strong>Gasless Transactions</strong>: The client supports a gas payment mechanism where a designated "gas payer" wallet can sponsor transaction fees for other users. This enables you to create seamless, gas-free experiences for your application's users.

### Where to Go Next

Ready to start building? Here are some helpful links to get you moving:

::::card-group
::link-card{title="Getting Started" description="Install the client, connect to the Beta chain, and make your first query in under 30 minutes." icon="rocket" href="/en/docs/blockchain-sdk-nodejs/getting-started-8cbd10/"}
::link-card{title="How-to Guides" description="Follow step-by-step tutorials for common tasks like creating NFTs, transferring tokens, and staking." icon="book-open" href="/en/docs/blockchain-sdk-nodejs/how-to-guides-8cbd10/"}
::link-card{title="API Reference" description="Dive into the complete API documentation for detailed information on every method, parameter, and data type." icon="code" href="/en/docs/blockchain-sdk-nodejs/api-reference-8cbd10/"}
::::

---

## Blockchain Utils

URL: https://www.arcblock.io/en/docs/blockchain-utils/

---

## @arcblock/did

URL: https://www.arcblock.io/en/docs/blockchain-utils/did-855cea/

This package provides a JavaScript library for working with ArcBlock's Decentralized Identity (DID) protocol. It allows you to create, manage, and validate DIDs, which are fundamental for building applications on the OCAP platform. This section covers the essential functionalities of the library.

For a deeper understanding of the underlying principles, please see our [Core Concepts](/en/docs/blockchain-utils/did-concepts-855cea/). For a detailed breakdown of all available functions, refer to the [API Reference](/en/docs/blockchain-utils/did-api-reference-855cea/).

## Installation

To get started, install the necessary packages using npm or your preferred package manager.

**Installation**

```bash
npm install @ocap/mcrypto @arcblock/did
```

## Quick Start

You can easily generate a new DID from a secret key. The library handles the cryptographic operations to derive the public key and construct the corresponding DID address based on the specified role and cryptographic types.

**Generate a DID from a Secret Key**

```javascript
const Mcrypto = require('@ocap/mcrypto');
const { fromSecretKey } = require('@arcblock/did');

// Destructure required types from Mcrypto
const { types } = Mcrypto;

// 1. Generate a new Ed25519 key pair
const keyPair = Mcrypto.Signer.Ed25519.genKeyPair();

// 2. Generate a DID from the secret key
// We specify the role, public key type, and hash algorithm
const didAddress = fromSecretKey(keyPair.secretKey, {
  role: types.RoleType.ROLE_APPLICATION,
  pk: types.KeyType.ED25519,
  hash: types.HashType.SHA3,
});

// 3. The full DID string includes the 'abt:did:' prefix
console.log(`Generated DID: abt:did:${didAddress}`);
```

This example demonstrates the basic workflow for creating an application DID. For more advanced use cases, such as creating DIDs from public keys or validating DID ownership, please refer to the detailed guides in the following sections.

## Next Steps

Dive deeper into the specifics of ArcBlock DIDs by exploring the following sections.

::::card-group
::link-card{title="Core Concepts" description="Learn about the fundamental concepts behind ArcBlock DIDs, including types, roles, and address formats." icon="book-open" href="/en/docs/blockchain-utils/did-concepts-855cea/"}
::link-card{title="API Reference" description="Explore the complete API with detailed descriptions and practical code examples for every function." icon="code" href="/en/docs/blockchain-utils/did-api-reference-855cea/"}
::::

---

## API Reference

URL: https://www.arcblock.io/en/docs/blockchain-utils/did-api-reference-855cea/

This section provides a comprehensive API reference for all public functions and types within the `@arcblock/did` library. It includes practical, copy-paste-ready code snippets for common tasks like creating, validating, and inspecting Decentralized Identities (DIDs).

## DID Creation

These functions are used to generate DIDs from various cryptographic inputs like secret keys, public keys, or hashes.

### fromSecretKey

Generates a DID from a secret key and a specified DID type configuration.

<strong>Parameters</strong>

- **sk** `BytesType` *(required)* — The hex-encoded secret key string.
- **type** `DIDTypeArg` — The DID type configuration. Can be a shortcut string (e.g., 'arcblock', 'eth') or a type object. Defaults to the standard ArcBlock DID type.

<strong>Returns</strong>

- **did** `string` — The generated DID string.

<strong>Example</strong>

**Create an Application DID**

```javascript
import { fromSecretKey, types } from '@arcblock/did';

const sk = '0xD67C071B6F51D2B61180B9B1AA9BE0DD0704619F0E30453AB4A592B036EDE644E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';

const appType = {
  role: types.RoleType.ROLE_APPLICATION,
  pk: types.KeyType.ED25519,
  hash: types.HashType.SHA3,
};

const did = fromSecretKey(sk, appType);
console.log(did); // zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr
```

### fromPublicKey

Generates a DID from a public key and a specified DID type configuration.

<strong>Parameters</strong>

- **pk** `BytesType` *(required)* — The hex-encoded public key string.
- **type** `DIDTypeArg` — The DID type configuration. Defaults to the standard ArcBlock DID type.

<strong>Returns</strong>

- **did** `string` — The generated DID string.

<strong>Example</strong>

**Create an Ethereum-style DID**

```javascript
import { fromPublicKey } from '@arcblock/did';

const pk = '0x4bc2a31265153f07e70e0bab08724e6b85e217f8cd628ceb62974247bb493382ce28cab79ad7119ee1ad3ebcdb98a16805211530ecc6cfefa1b88e6dff99232a';

const ethDid = fromPublicKey(pk, 'eth');
console.log(ethDid); // 0x9d8A62f656a8d1615C1294fd71e9CFb3E4855A4F
```

### fromPublicKeyHash

Generates a DID from a public key hash and a specified DID type. The output format (Base58 or Base16) depends on the encoding type specified in the DID type.

<strong>Parameters</strong>

- **buffer** `string` *(required)* — The hex-encoded public key hash.
- **type** `DIDTypeArg` *(required)* — The DID type configuration.

<strong>Returns</strong>

- **did** `string` — The generated DID string.

<strong>Example</strong>

```javascript
import { fromPublicKeyHash, types, DidType } from '@arcblock/did';
import { Hasher } from '@ocap/mcrypto';

const pk = '0xFF47B3022FA503EAA1E9FA4B20FA8B16694EA56096F3A2E9109714062B3486D9';
const pkHash = Hasher.SHA3.hash256(pk);
const nodeType = DidType({ role: types.RoleType.ROLE_NODE });

const did = fromPublicKeyHash(pkHash, nodeType);
console.log(did); // z89nF4GRYvgw5mqk8NqVVC7NeZLWKbcbQY7V
```

### fromHash

Generates a DID from a generic hex-encoded hash and a role type.

<strong>Parameters</strong>

- **hash** `string` *(required)* — The hex-encoded hash.
- **role** `number` (default: `ROLE_ACCOUNT`) — The role type from mcrypto.types.RoleType. Defaults to ROLE_ACCOUNT.

<strong>Returns</strong>

- **did** `string` — The generated DID string.

<strong>Example</strong>

```javascript
import { fromHash, types } from '@arcblock/did';
import { Hasher } from '@ocap/mcrypto';

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const pkHash = Hasher.SHA3.hash256(pk);

const did = fromHash(pkHash, types.RoleType.ROLE_APPLICATION);
console.log(did); // zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr
```

## DID Validation

These functions help verify the integrity of a DID and its relationship to a public key.

### isValid

Checks if a DID string is valid by verifying its format and checksum.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID string to validate.

<strong>Returns</strong>

- **isValid** `boolean` — Returns `true` if the DID is valid, `false` otherwise.

<strong>Example</strong>

```javascript
import { isValid } from '@arcblock/did';

// ArcBlock DIDs (Base58)
console.log(isValid('zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr')); // true
console.log(isValid('did:abt:z1nfCgfPqvSQCaZ2EVZPXbwPjKCkMrqfTUu')); // true

// ArcBlock DIDs (Base16)
console.log(isValid('0x0021e4b8f62674897ed75df0f7356e82c6f9a64a5c13f3cc0cd3')); // true

// Ethereum DIDs
console.log(isValid('0x9d8A62f656a8d1615C1294fd71e9CFb3E4855A4F')); // true

// Invalid DIDs
console.log(isValid('abc')); // false
console.log(isValid('z1muQ3xqHQK2uiACHyChikobsiY5kLqtSha')); // false (bad checksum)
```

### isFromPublicKey

Checks if a given DID was generated from a specific public key.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID string.
- **pk** `BytesType` *(required)* — The hex-encoded public key to check against.

<strong>Returns</strong>

- **isMatch** `boolean` — Returns `true` if the DID corresponds to the public key, `false` otherwise.

<strong>Example</strong>

```javascript
import { isFromPublicKey } from '@arcblock/did';

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';

console.log(isFromPublicKey(did, pk)); // true
console.log(isFromPublicKey('abc', pk)); // false
```

## Type Utilities

Functions for creating, parsing, and converting DID type information.

### DidType

Creates a standardized DID Type object from a shortcut string or a partial type definition. It automatically fills in any missing properties with defaults for an ArcBlock DID.

<strong>Parameters</strong>

- **type** `DIDTypeArg` — A shortcut string ('arcblock', 'eth', 'passkey') or a partial DIDType object.

<strong>Returns</strong>

- **didType** `DIDType` — A complete DIDType object.

<strong>Example</strong>

```javascript
import { DidType, types } from '@arcblock/did';

// Using a shortcut
const ethType = DidType('eth');
console.log(ethType);
// { role: 1, pk: 2, hash: 2, address: 1 }

// Using a partial type object
const nodeType = DidType({ role: types.RoleType.ROLE_NODE });
console.log(nodeType);
// { role: 3, pk: 1, hash: 4, address: 0 }
```

### toTypeInfo

Extracts the DID type information (role, key type, hash algorithm, etc.) from a DID string.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID string.

<strong>Returns</strong>

- **didType** `DIDType` — A DIDType object containing the numeric type codes.

<strong>Example</strong>

```javascript
import { toTypeInfo } from '@arcblock/did';

const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const typeInfo = toTypeInfo(did);

console.log(typeInfo);
// { role: 12, pk: 1, hash: 1, address: 0 }
```

### toTypeInfoStr

Extracts the DID type information from a DID string and returns it in a human-readable string format.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID string.

<strong>Returns</strong>

- **didTypeStr** `DIDTypeStr` — A `DIDTypeStr` object with string representations of the types.

<strong>Example</strong>

```javascript
import { toTypeInfoStr } from '@arcblock/did';

const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const typeInfo = toTypeInfoStr(did);

console.log(typeInfo);
// { role: 'ROLE_APPLICATION', pk: 'ED25519', hash: 'SHA3', address: 'BASE58' }
```

### fromTypeInfo

Converts a DID Type object into its compact 2-byte hex string representation.

<strong>Parameters</strong>

- **type** `DIDTypeArg` *(required)* — A DID Type object or shortcut.

<strong>Returns</strong>

- **hex** `string` — The 4-character hex string representing the type.

<strong>Example</strong>

```javascript
import { fromTypeInfo, types } from '@arcblock/did';

const appType = {
  role: types.RoleType.ROLE_APPLICATION,
  pk: types.KeyType.ED25519,
  hash: types.HashType.SHA3,
  address: types.EncodingType.BASE58,
};

const typeHex = fromTypeInfo(appType);
console.log(typeHex); // 0c01
```

### isEthereumDid

Checks if a string is a valid Ethereum address, including checksum validation.

<strong>Parameters</strong>

- **did** `string` *(required)* — The string to check.

<strong>Returns</strong>

- **isEth** `boolean` — Returns `true` if it's a valid Ethereum DID.

### toChecksumAddress

Converts an Ethereum address to its checksummed format.

<strong>Parameters</strong>

- **address** `string` *(required)* — The Ethereum address.

<strong>Returns</strong>

- **checksummedAddress** `string` — The checksummed address.

## Formatting Utilities

Helper functions to add or remove the standard DID prefix.

### toDid

Ensures a DID string is prefixed with `did:abt:`.

<strong>Parameters</strong>

- **address** `string` *(required)* — A raw DID address.

<strong>Returns</strong>

- **did** `string` — The fully qualified DID string.

<strong>Example</strong>

```javascript
import { toDid } from '@arcblock/did';

const address = 'z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA';
console.log(toDid(address)); // did:abt:z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA
```

### toAddress

Removes the `did:abt:` prefix from a DID string, returning the raw address.

<strong>Parameters</strong>

- **did** `string` *(required)* — A fully qualified DID string.

<strong>Returns</strong>

- **address** `string` — The raw DID address.

<strong>Example</strong>

```javascript
import { toAddress } from '@arcblock/did';

const did = 'did:abt:z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA';
console.log(toAddress(did)); // z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA
```

## Constants

Predefined constants for DID types and prefixes.

| Constant  | Description  |
|---|---|
| `DID_PREFIX`  | The standard string prefix for ArcBlock DIDs: `"did:abt:"`.  |
| `DID_TYPE_ARCBLOCK`  | A `DIDType` object representing the default ArcBlock DID configuration.  |
| `DID_TYPE_ETHEREUM`  | A `DIDType` object for Ethereum-compatible DIDs.  |
| `DID_TYPE_PASSKEY`  | A `DIDType` object for DIDs derived from passkeys.  |

## Types

Key TypeScript type definitions used throughout the library.

- **DIDType** `object` — An object that defines the cryptographic properties of a DID. It includes role, pk (key type), hash (hash algorithm), and address (encoding type).
- **DIDTypeStr** `object` — Similar to DIDType, but the property values are human-readable strings instead of numeric codes.
- **DIDTypeArg** `DIDTypeShortcut | DIDType` — A union type that can be either a shortcut string or a DIDType object, used as an argument in many functions.
- **DIDTypeShortcut** `string` — A literal string type for predefined DID configurations: 'default', 'arcblock', 'eth', 'ethereum', or 'passkey'.
- **BytesType** `string | Buffer` — A type that can be either a hex-encoded string or a Buffer, representing binary data.

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/blockchain-utils/did-concepts-855cea/

This section explains the fundamental concepts behind ArcBlock's Decentralized Identity (DID). A DID in the ArcBlock ecosystem is more than just an identifier; it's a self-contained, self-describing entity that embeds its own cryptographic properties. This design allows for a versatile and interoperable identity system.

## DID Structure

An ArcBlock DID is a string that follows the W3C DID specification format, prefixed with `did:abt:`. The part that follows the prefix is a Base58 encoded string that contains all the necessary information about the identity.

For example: `did:abt:zNKoDmH82m9fW5n444z4T8tWz9t2v7q3m6s`

The core of the DID is a 26-byte buffer that contains:

- <strong>Type Information (2 bytes):</strong> Encodes the cryptographic suite used by the DID.
- <strong>Public Key Hash (20 bytes):</strong> A hash of the public key associated with the DID.
- <strong>Checksum (4 bytes):</strong> Ensures the integrity of the DID string.

This structure makes ArcBlock DIDs self-validating and self-describing, as you can derive the DID's capabilities directly from the DID string itself.

## The DIDType Object

The `DIDType` object is a crucial configuration object that defines the cryptographic characteristics of a DID. It specifies the algorithms used for key pairs, hashing, and address encoding.

- **role** `number` *(required)* — Specifies the purpose or role of the DID. Different roles may have different cryptographic requirements. For example, a ROLE_NODE uses SHA2 for hashing, while a ROLE_ACCOUNT uses SHA3. Common roles include ROLE_ACCOUNT, ROLE_APPLICATION, ROLE_NODE, and ROLE_PASSKEY.
- **pk** `number` *(required)* — Defines the public key cryptography scheme used for signing and verification. Supported types include ED25519, ETHEREUM, and PASSKEY.
- **hash** `number` *(required)* — Specifies the hashing algorithm used to generate the public key hash and the checksum. Supported algorithms include SHA3, SHA2, and KECCAK.
- **address** `number` *(required)* — Determines the encoding format of the final DID address string. The primary formats are BASE58 (for standard ArcBlock DIDs) and BASE16 (for Ethereum-compatible DIDs).

## DID Type Presets

To simplify DID creation, the library provides several string shortcuts that correspond to pre-configured `DIDType` objects for common use cases.

| Shortcut  | Role  | Key Type  | Hash Type  | Encoding  | Use Case  |
|---|---|---|---|---|---|
| `'default'`, `'arcblock'`  | `ROLE_ACCOUNT`  | `ED25519`  | `SHA3`  | `BASE58`  | Standard user and application accounts.  |
| `'eth'`, `'ethereum'`  | `ROLE_ACCOUNT`  | `ETHEREUM`  | `KECCAK`  | `BASE16`  | Ethereum-compatible accounts.  |
| `'passkey'`  | `ROLE_PASSKEY`  | `PASSKEY`  | `SHA2`  | `BASE58`  | DIDs managed by WebAuthn Passkeys.  |

## DID Generation Flow

A DID is generated from a secret key and a `DIDType` object. The following diagram illustrates the process for a standard ArcBlock DID.

![Core Concepts](https://media.arcblock.io/lib/bc/bc2865d2211c5f44.w1600.webp)

## Ethereum-Compatible DIDs

The library provides first-class support for Ethereum-compatible DIDs. These are standard Ethereum addresses, prefixed with `0x`.

Unlike standard ArcBlock DIDs, an Ethereum DID does not encode its type information within the address itself. Instead, its type is inferred by its format. When the library encounters a valid Ethereum address, it automatically applies the `'ethereum'` preset (`ETHEREUM` key type, `KECCAK` hash, `BASE16` encoding). The library also handles EIP-55 checksum validation and generation to ensure interoperability with the broader Ethereum ecosystem.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blockchain-utils/getting-started-855cea/

This guide provides a quick, step-by-step walkthrough to get you up and running with ocap-libs. In just a few minutes, you'll install the necessary packages, create your first Decentralized Identity (DID), generate a compatible crypto wallet, and learn how to use some helpful utilities.

## Step 1: Install the Packages

First, you need to install the core packages. You'll need libraries for DID creation, wallet management, cryptography, and general utilities.

Open your terminal and run the following command:

**Installation Command**

```bash
pnpm install @arcblock/did @ocap/wallet @ocap/mcrypto @ocap/util
```

This command installs four essential packages:

- <strong>`@arcblock/did`</strong>: The main library for creating and managing Decentralized Identities.
- <strong>`@ocap/wallet`</strong>: A utility for creating and using crypto wallets for signing and verification.
- <strong>`@ocap/mcrypto`</strong>: Handles the underlying cryptographic functions, such as key generation.
- <strong>`@ocap/util`</strong>: Provides shared helper functions for data encoding, conversion, and more.

## Step 2: Create a Wallet and DID

Now that the packages are installed, let's create a wallet and its corresponding DID. The wallet holds the cryptographic keys, and the DID is the public identifier derived from those keys.

Create a new JavaScript file (e.g., `create-did.js`) and add the following code:

**Create Wallet and DID**

```javascript
const { fromSecretKey: walletFromSecretKey } = require('@ocap/wallet');
const { fromSecretKey: didFromSecretKey } = require('@arcblock/did');
const Mcrypto = require('@ocap/mcrypto');
const assert = require('assert');

// Destructure required types from Mcrypto
const { types } = Mcrypto;

// 1. Generate a new cryptographic key pair using Ed25519
const keyPair = Mcrypto.Signer.Ed25519.genKeyPair();
console.log('Generated Secret Key (Buffer):', keyPair.secretKey);

// 2. Define the properties for our DID and Wallet
// This ensures they are generated with the same cryptographic settings.
const spec = {
  role: types.RoleType.ROLE_ACCOUNT, // Role type for a standard user account
  pk: types.KeyType.ED25519,          // Public key algorithm
  hash: types.HashType.SHA3,         // Hashing algorithm
};

// 3. Create a wallet instance from the secret key
const wallet = walletFromSecretKey(keyPair.secretKey, spec);
console.log('\nWallet Address:', wallet.address);

// 4. Create a DID from the same secret key and spec
const didAddress = didFromSecretKey(keyPair.secretKey, spec);
const did = `did:abt:${didAddress}`;
console.log('Generated DID:', did);

// 5. Verify that the wallet address and DID address are identical
assert.strictEqual(wallet.address, didAddress, 'Wallet address and DID address should match!');
console.log('\n✅ Success! Wallet address and DID are a match.');
```

Run the script from your terminal:

```bash
node create-did.js
```

You will see the newly generated secret key, wallet address, and DID printed to the console. Notice that the wallet's address is the core component of the full DID string.

## Step 3: Sign and Verify a Message

A primary function of a wallet is to prove ownership of a DID by signing messages. This is crucial for authentication and authorizing actions.

Let's add signing and verification to our script:

**Sign and Verify**

```javascript
// ... (keep the code from Step 2) ...

// 6. Sign a message to prove ownership of the wallet/DID
const message = 'Hello, decentralized world!';
const signature = wallet.sign(message);

console.log('\nOriginal Message:', message);
console.log('Generated Signature:', signature);

// 7. Verify the signature against the original message
const isVerified = wallet.verify(message, signature);
assert.ok(isVerified, 'Signature should be verified successfully.');

console.log(`\nIs the signature valid? ${isVerified}`);
console.log('✅ Success! The signature has been verified.');
```

When you run the updated script, it will first create the wallet and DID, then sign a message and successfully verify that the signature is valid.

## Step 4: Use a Utility Function

The `@ocap/util` package provides many helpful functions. For example, the secret key generated in Step 2 is a Buffer. You can use utilities to convert it into a more readable format like Hex or Base58.

**Using Utilities**

```javascript
// ... (keep the code from Step 3) ...
const { toHex } = require('@ocap/util');

// 8. Convert the secret key buffer to a hex string for display or storage
const secretKeyHex = toHex(keyPair.secretKey);
console.log('\nSecret Key (Hex Format):', secretKeyHex);
console.log('✅ Success! Used a utility to format the secret key.');
```

This simple example shows how utilities can simplify common data manipulation tasks.

## Next Steps

Congratulations! You have successfully created a decentralized identity, generated a wallet, used it to sign and verify a message, and leveraged a utility function. You now have the basic building blocks for integrating DIDs into your applications.

To learn more, dive into the core concepts and detailed API references for each package:

::::card-group
::link-card{title="@arcblock/did" description="Explore DID types, roles, and the full API for creating, resolving, and validating identities." icon="key" href="/en/docs/blockchain-utils/did-855cea/"}
::link-card{title="@ocap/wallet" description="Learn about the Wallet object, different ways to instantiate it, and its cryptographic methods." icon="wallet" href="/en/docs/blockchain-utils/wallet-855cea/"}
::link-card{title="@ocap/util" description="Discover a collection of helper functions for data conversion, encoding, and more." icon="wrench" href="/en/docs/blockchain-utils/util-855cea/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/blockchain-utils/overview-855cea/

Welcome to the official documentation for OCAP Libraries, a comprehensive suite for building applications with decentralized identity. This guide provides everything you need to integrate powerful, self-sovereign identity features into your applications. At the core are three main packages: `@arcblock/did`, `@ocap/wallet`, and `@ocap/util`. Together, they provide a complete toolset for creating, managing, and utilizing DIDs in a decentralized environment.

### @arcblock/did

The `@arcblock/did` library is a JavaScript implementation for working with ArcBlock DIDs, fully compliant with the [ArcBlock DID specification](https://github.com/ArcBlock/abt-did-spec). It provides the essential functions to create and validate DIDs from various inputs like public or private keys.

### @ocap/wallet

The `@ocap/wallet` library provides utility functions to create and manage DID-compatible cryptographic wallets. A wallet holds the cryptographic keys (public and secret) that are the foundation of a decentralized identity. It handles core operations like signing messages and verifying signatures, which are essential for proving ownership and authorizing actions in a decentralized system.

### @ocap/util

The `@ocap/util` library serves as a foundational toolkit, providing shared utility functions used across multiple OCAP libraries. It includes essential helpers for data type conversion, encoding (like Base58 and Hex), and other low-level operations that both `@arcblock/did` and `@ocap/wallet` rely on to function correctly.

## How They Work Together

While these libraries can be used independently, they are designed to work seamlessly together. The typical workflow involves using `@ocap/wallet` to manage the cryptographic keys and then passing those keys to `@arcblock/did` to generate the corresponding DID address. The wallet secures the 'who' (the keys), while the DID library creates the 'what' (the public identifier).

![Overview](https://media.arcblock.io/lib/e6/e6f0cb9a5df1d3b4.w1600.webp)

## What's Next?

Ready to dive in? Here are some starting points:

::::card-group
::link-card{title="Getting Started" description="A step-by-step guide to install the packages and create your first DID and wallet." icon="rocket" href="/en/docs/blockchain-utils/getting-started-855cea/"}
::link-card{title="@arcblock/did" description="Explore the core concepts and API for creating and managing Decentralized Identities." icon="key" href="/en/docs/blockchain-utils/did-855cea/"}
::link-card{title="@ocap/wallet" description="Learn how to generate wallets and use them for cryptographic operations like signing." icon="wallet" href="/en/docs/blockchain-utils/wallet-855cea/"}
::link-card{title="@ocap/util" description="Discover the collection of essential helper functions for data conversion, encoding, and more." icon="tool" href="/en/docs/blockchain-utils/util-855cea/"}
::::

---

## @ocap/util

URL: https://www.arcblock.io/en/docs/blockchain-utils/util-855cea/

The `@ocap/util` package is a foundational library providing a collection of essential helper functions shared across multiple OCAP JS libraries. Designed to be isomorphic, it works seamlessly in both Node.js and browser environments. This module simplifies common tasks such as data type conversion, encoding/decoding, big number arithmetic, and bonding curve calculations, ensuring consistency and reliability in your applications.

## Installation

To get started, install the package using your preferred package manager:

**Installation**

```shell
pnpm install @ocap/util
```

## Key Features

`@ocap/util` provides a wide range of helpers to streamline your development process. Here are some of the core functionalities:

::::card-group
::link-card{title="Data Conversion & Encoding" description="Seamlessly convert between various data formats like Hex, Buffers, and Uint8Arrays. Includes robust support for Base58 and Base64 encoding and decoding." icon="refresh"}
::link-card{title="BigNumber & Token Math" description="Perform precise arithmetic with large integers using the integrated BN.js library. Easily convert between large units and human-readable token amounts." icon="hash"}
::link-card{title="Bonding Curve Calculations" description="A suite of functions for calculating token prices and costs based on different bonding curve models, including constant, linear, and quadratic curves." icon="chart"}
::link-card{title="DID & Address Helpers" description="Simplify Decentralized Identity management with helpers to convert between DID formats and wallet addresses, and to format transaction types." icon="fingerprint"}
::::

## API Reference

For detailed usage and a complete list of all available functions, please refer to the comprehensive API Reference.

:::action-card{title="Explore the API Reference" description="Dive into a comprehensive reference for all utility functions, complete with practical examples for data conversion, big number arithmetic, UUID generation, and bonding curve calculations." icon="code"}
::action{label="View API" href="/en/docs/blockchain-utils/util-api-reference-855cea/" variant="primary"}
:::

---

## API Reference

URL: https://www.arcblock.io/en/docs/blockchain-utils/util-api-reference-855cea/

This is a comprehensive reference for all utility functions available in the `@ocap/util` package. It provides practical examples for data conversion, big number arithmetic, UUID generation, and bonding curve calculations.

## Number & BigNumber Utilities

These functions provide robust ways to handle large numbers and perform conversions between different numerical representations.

### BN

An alias for the `bn.js` library, used for handling arbitrary-precision integers. All functions that work with large numbers either accept or return `BN` instances.

**Bignumber Arithmetic**

```javascript
import { BN } from '@ocap/util';

const a = new BN('1000000000000000000');
const b = new BN('2000000000000000000');
const result = a.add(b);

console.log(result.toString()); // '3000000000000000000'
```

### toBN

Converts various input types into a `BN` instance. It can handle numbers, strings, and hexadecimal strings.

<strong>Parameters</strong>

- **num** `number | string | BN` *(required)* — The value to convert.
- **base** `number | 'hex'` (default: `10`) — The numerical base for conversion, defaults to 10.

<strong>Returns</strong>

- **** `BN` — The BN instance.

<strong>Example</strong>

**Converting to BN**

```javascript
import { toBN } from '@ocap/util';

// From number
console.log(toBN(15).toString(10)); // '15'

// From hex string
console.log(toBN('0xf').toString(10)); // '15'

// From negative number
console.log(toBN(-15).toString(10)); // '-15'

// From large number string
const largeNumber = '115792089237316195423570985008687907853269984665640564039457584007913129639935';
console.log(toBN(largeNumber).toString(10));
```

### isBN

Checks if a given object is a `BN` instance.

<strong>Parameters</strong>

- **object** `any` *(required)* — The object to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the object is a BN instance, otherwise `false`.

### isBigNumber

Checks if a given object is a `BigNumber` instance (from a different library, for compatibility).

<strong>Parameters</strong>

- **object** `any` *(required)* — The object to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the object is a BigNumber instance, otherwise `false`.

### numberToHex

Converts a number, string, or BN instance into a hexadecimal string representation, prefixed with `0x`.

<strong>Parameters</strong>

- **value** `string | number | BN` *(required)* — The value to convert.

<strong>Returns</strong>

- **** `string` — The hexadecimal string.

<strong>Example</strong>

**Number to Hex**

```javascript
import { numberToHex } from '@ocap/util';

console.log(numberToHex(255));      // '0xff'
console.log(numberToHex('15'));     // '0xf'
console.log(numberToHex(-1));       // '-0x1'
```

### hexToNumber

Converts a hexadecimal string into a standard JavaScript `number`.

<strong>Parameters</strong>

- **value** `string | number | BN` *(required)* — The hexadecimal value to convert.

<strong>Returns</strong>

- **** `number` — The number representation.

### isHex / isHexStrict

- `isHex(str)`: Checks if a string is a hexadecimal value. It allows for an optional `0x` prefix.
- `isHexStrict(str)`: Checks if a string is a strict hexadecimal value, requiring a `0x` prefix.

<strong>Parameters</strong>

- **hex** `string` *(required)* — The string to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the string is a valid hex value according to the function's rules, otherwise `false`.

<strong>Example</strong>

**Hex Validation**

```javascript
import { isHex, isHexStrict } from '@ocap/util';

console.log(isHex('0xff'));       // true
console.log(isHex('ff'));         // true
console.log(isHexStrict('0xff')); // true
console.log(isHexStrict('ff'));   // false
```

### isHexPrefixed

Checks if a string starts with '0x'.

<strong>Parameters</strong>

- **str** `string` *(required)* — The string to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the string has a '0x' prefix, otherwise `false`.

### stripHexPrefix

Removes the `0x` prefix from a hexadecimal string if it exists.

<strong>Parameters</strong>

- **str** `string` *(required)* — The string to process.

<strong>Returns</strong>

- **** `string` — The string without the '0x' prefix.

<strong>Example</strong>

**Stripping Hex Prefix**

```javascript
import { stripHexPrefix } from '@ocap/util';

console.log(stripHexPrefix('0xabcdef')); // 'abcdef'
console.log(stripHexPrefix('abcdef'));   // 'abcdef'
```

## Encoding & Decoding

Functions for converting data between different formats like UTF-8, Hex, Base58, and Base64.

### toHex

Automatically converts a value of almost any type (string, number, boolean, object, Buffer) into its hexadecimal representation.

<strong>Parameters</strong>

- **value** `any` *(required)* — The input value to convert.

<strong>Returns</strong>

- **** `string` — The resulting hexadecimal string.

<strong>Example</strong>

**Universal Hex Conversion**

```javascript
import { toHex } from '@ocap/util';

console.log(toHex('myString'));                  // '0x6d79537472696e67'
console.log(toHex(255));                         // '0xff'
console.log(toHex(true));                        // '0x01'
console.log(toHex({ a: 1 }));                    // '0x7b2261223a317d'
console.log(toHex(Buffer.from('hello')));       // '0x68656c6c6f'
```

### utf8ToHex / hexToUtf8

- `utf8ToHex(str)`: Converts a UTF-8 string to its hex representation.
- `hexToUtf8(hex)`: Converts a hex string back to a UTF-8 string.

<strong>Parameters</strong>

- **str or hex** `string` *(required)* — The string to convert.

<strong>Returns</strong>

- **** `string` — The converted string.

<strong>Example</strong>

**UTF-8 and Hex Conversion**

```javascript
import { utf8ToHex, hexToUtf8 } from '@ocap/util';

const originalString = 'Hello World!';
const hexString = utf8ToHex(originalString);
console.log(hexString); // '0x48656c6c6f20576f726c6421'

const decodedString = hexToUtf8(hexString);
console.log(decodedString); // 'Hello World!'
```

### bytesToHex / hexToBytes

- `bytesToHex(bytes)`: Converts a byte array to a hex string.
- `hexToBytes(hex)`: Converts a hex string to a byte array.

<strong>Parameters</strong>

- **bytes or hex** `Array<number> | string` *(required)* — The data to convert.

<strong>Returns</strong>

- **** `string | Array<number>` — The converted data.

### toBase58 / fromBase58

- `toBase58(data)`: Encodes data into a Base58 string with a 'z' prefix.
- `fromBase58(str)`: Decodes a 'z' prefixed Base58 string into a Buffer.

<strong>Parameters</strong>

- **data or str** `any | string` *(required)* — The data to encode or decode.

<strong>Returns</strong>

- **** `string | Buffer` — The encoded string or decoded Buffer.

<strong>Example</strong>

**Base58 Encoding**

```javascript
import { toBase58, fromBase58 } from '@ocap/util';

const hexData = '0x15D0014A9CF581EC068B67500683A2784A15E1F6';
const base58String = toBase58(hexData);
console.log(base58String); // 'z2y82i5n5aD62x28s44j32hA73P41B5o1i411C'

const decodedBuffer = fromBase58(base58String);
console.log(decodedBuffer.toString('hex')); // '15d0014a9cf581ec068b67500683a2784a15e1f6'
```

### isBase58btc

Checks if a string is a valid Base58 encoded value with the 'z' prefix.

<strong>Parameters</strong>

- **data** `any` *(required)* — The value to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the value is a valid Base58 string, otherwise `false`.

### toBase64 / fromBase64

- `toBase64(data)`: Encodes data into a URL-safe Base64 string.
- `fromBase64(str)`: Decodes a URL-safe Base64 string into a Buffer.

<strong>Parameters</strong>

- **data or str** `any | string` *(required)* — The data to encode or decode.

<strong>Returns</strong>

- **** `string | Buffer` — The encoded string or decoded Buffer.

<strong>Example</strong>

**Base64 Encoding**

```javascript
import { toBase64, fromBase64 } from '@ocap/util';

const hexData = '0xeb82b4eab08020eca09cec9dbc20ec9e9820eb8298eab082';
const base64String = toBase64(hexData);
console.log(base64String); // '64K06rCAIOygnOydvCDsnpgg64KY6rCC'

const decodedBuffer = fromBase64(base64String);
console.log('0x' + decodedBuffer.toString('hex')); // '0xeb82b4eab08020eca09cec9dbc20ec9e9820eb8298eab082'
```

## Data Type Conversion

### toUint8Array

Converts various input types (Hex, Base58, Buffer, string) into a `Uint8Array` on a best-effort basis.

<strong>Parameters</strong>

- **v** `any` *(required)* — The value to convert.

<strong>Returns</strong>

- **** `Uint8Array` — The resulting Uint8Array.

### toBuffer

Converts various input types into a Node.js `Buffer`.

<strong>Parameters</strong>

- **v** `any` *(required)* — The value to convert.

<strong>Returns</strong>

- **** `Buffer` — The resulting Buffer.

### isUint8Array

Validates if a value is a `Uint8Array`.

<strong>Parameters</strong>

- **value** `any` *(required)* — The value to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the value is a Uint8Array, otherwise `false`.

## Token Unit Conversion

These functions are essential for converting between the smallest unit of a token (like wei in Ethereum) and its more human-readable representation.

### fromUnitToToken

Converts a value from its smallest unit (e.g., a `BN` instance) to a human-readable decimal string.

<strong>Parameters</strong>

- **input** `string | number | BN` *(required)* — The value in its smallest unit.
- **decimal** `number` (default: `18`) — The number of decimal places the token has.

<strong>Returns</strong>

- **** `string` — The human-readable token amount.

<strong>Example</strong>

**Token Unit Conversion**

```javascript
import { fromUnitToToken } from '@ocap/util';

// 1 Ether (10^18 wei)
console.log(fromUnitToToken('1000000000000000000', 18)); // '1'

// 1.2345 tokens
console.log(fromUnitToToken('1234500000000000000', 18)); // '1.2345'
```

### fromTokenToUnit

Converts a human-readable token amount (as a string or number) into its smallest unit representation as a `BN` instance.

<strong>Parameters</strong>

- **input** `string | number` *(required)* — The human-readable token amount.
- **decimal** `number` (default: `18`) — The number of decimal places the token has.

<strong>Returns</strong>

- **** `BN` — The value in its smallest unit.

<strong>Example</strong>

**Token to Smallest Unit**

```javascript
import { fromTokenToUnit } from '@ocap/util';

// 1 token to its smallest unit
console.log(fromTokenToUnit('1', 18).toString()); // '1000000000000000000'

// 0.5 tokens
console.log(fromTokenToUnit('0.5', 18).toString()); // '500000000000000000'
```

## DID Utilities

Helper functions for working with ArcBlock DIDs and addresses.

### toAddress / toDid

- `toAddress(did)`: Converts a full DID string (e.g., `did:abt:z...`) to its corresponding address by removing the `did:abt:` prefix.
- `toDid(address)`: Converts an address to a full DID string by adding the `did:abt:` prefix.

<strong>Parameters</strong>

- **did or address** `string` *(required)* — The DID or address to convert.

<strong>Returns</strong>

- **** `string` — The converted address or DID.

### isSameDid

Compares two DID strings for equality in a case-insensitive manner after converting them to addresses.

<strong>Parameters</strong>

- **a** `string` *(required)* — The first DID to compare.
- **b** `string` *(required)* — The second DID to compare.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the DIDs are the same, otherwise `false`.

## Transaction Utilities

### formatTxType

Formats a transaction type string into UpperCamelCase.

<strong>Parameters</strong>

- **type** `string` *(required)* — The transaction type string (e.g., 'transfer').

<strong>Returns</strong>

- **** `string` — The formatted string (e.g., 'Transfer').

## UUID Utilities

### UUID

Generates a random Version 4 UUID.

<strong>Parameters</strong>

None.

<strong>Returns</strong>

- **** `string` — A new UUID string.

### isUUID

Checks if a given string is a valid UUID.

<strong>Parameters</strong>

- **str** `string` *(required)* — The string to check.

<strong>Returns</strong>

- **** `boolean` — Returns `true` if the string is a valid UUID, otherwise `false`.

## Bonding Curve Calculations

These functions are used to calculate the price and cost for minting or burning tokens based on different mathematical curves. This is a core component of tokenomics models.

### Direction (Enum)

An enum used in cost calculation functions to specify the direction of the operation.

- `Direction.Mint`: 'mint'
- `Direction.Burn`: 'burn'

### Constant Curve

- `calcConstantPrice({ fixedPrice })`: Calculates the price, which is always the `fixedPrice`.
- `calcConstantCost({ amount, fixedPrice, decimal })`: Calculates the cost, which is `amount * fixedPrice`.

<strong>Parameters for</strong> <strong>`calcConstantPrice`</strong>

- **fixedPrice** `string` *(required)* — The fixed price per token in its smallest unit.

<strong>Parameters for</strong> <strong>`calcConstantCost`</strong>

- **amount** `string` *(required)* — The amount of tokens to mint/burn.
- **fixedPrice** `string` *(required)* — The fixed price per token.
- **decimal** `number` *(required)* — The token's decimal places.

<strong>Returns</strong>

- **** `BN` — The calculated price or cost.

### Linear Curve

- `calcLinearPrice({ basePrice, slope, currentSupply, decimal })`: Calculates price based on the formula `Price = basePrice + slope * currentSupply`.
- `calcLinearCost({ amount, currentSupply, basePrice, slope, decimal, direction })`: Calculates the integral cost of minting or burning tokens along the linear price curve.

<strong>Parameters for</strong> <strong>`calcLinearPrice`</strong>

- **basePrice** `string` *(required)* — The starting price of the token.
- **slope** `string` *(required)* — The rate at which the price increases with supply.
- **currentSupply** `string` *(required)* — The current total supply of the token.
- **decimal** `number` *(required)* — The token's decimal places.

<strong>Parameters for</strong> <strong>`calcLinearCost`</strong>

- **params** `object` *(required)* — An object containing calculation parameters.
  - **amount** `string` *(required)* — The amount of tokens.
  - **currentSupply** `string` *(required)* — The current token supply.
  - **basePrice** `string` *(required)* — The base price.
  - **slope** `string` *(required)* — The price slope.
  - **decimal** `number` *(required)* — The token's decimal places.
  - **direction** `Direction` *(required)* — The operation direction (`Direction.Mint` or `Direction.Burn`).

<strong>Returns</strong>

- **** `BN` — The calculated price or cost.

### Quadratic Curve

- `calcQuadraticPrice({ basePrice, currentSupply, constant, decimal })`: Calculates price based on the formula `Price = basePrice + currentSupply^2 / constant`.
- `calcQuadraticCost({ amount, currentSupply, basePrice, constant, decimal, direction })`: Calculates the integral cost of minting or burning tokens along the quadratic price curve.

<strong>Parameters for</strong> <strong>`calcQuadraticPrice`</strong>

- **basePrice** `string` *(required)* — The starting price.
- **currentSupply** `string` *(required)* — The current token supply.
- **constant** `string` *(required)* — A constant that moderates the price curve.
- **decimal** `number` *(required)* — The token's decimal places.

<strong>Parameters for</strong> <strong>`calcQuadraticCost`</strong>

- **params** `object` *(required)* — An object containing calculation parameters.
  - **amount** `string` *(required)* — The amount of tokens.
  - **currentSupply** `string` *(required)* — The current token supply.
  - **basePrice** `string` *(required)* — The base price.
  - **constant** `string` *(required)* — The curve constant.
  - **decimal** `number` *(required)* — The token's decimal places.
  - **direction** `Direction` *(required)* — The operation direction (`Direction.Mint` or `Direction.Burn`).

<strong>Returns</strong>

- **** `BN` — The calculated price or cost.

### Generic Calculators

- `calcPrice({ currentSupply, decimal, curve })`: A dispatcher function that calculates the current price based on the `curve` object provided. The `curve.type` property (`'constant'`, `'linear'`, or `'quadratic'`) determines which calculation to use.
- `calcCost({ amount, decimal, currentSupply, direction, curve })`: A dispatcher function that calculates the total cost for an operation based on the `curve` object.

<strong>Parameters for</strong> <strong>`calcPrice`</strong>

- **currentSupply** `string` *(required)* — The current token supply.
- **decimal** `number` *(required)* — The token's decimal places.
- **curve** `object` *(required)* — A curve configuration object with `type` and other relevant parameters.

<strong>Parameters for</strong> <strong>`calcCost`</strong>

- **amount** `string` *(required)* — The amount of tokens.
- **decimal** `number` *(required)* — The token's decimal places.
- **currentSupply** `string` *(required)* — The current token supply.
- **direction** `Direction` *(required)* — The operation direction.
- **curve** `object` *(required)* — A curve configuration object.

<strong>Returns</strong>

- **** `BN` — The calculated price or cost as a BN instance.

<strong>Example: Using</strong> <strong>`calcCost`</strong> <strong>dispatcher</strong>

**Generic Cost Calculator**

```javascript
import { calcCost, Direction } from '@ocap/util';

const linearCurve = {
  type: 'linear',
  basePrice: '1000000000000000000', // 1 token
  slope: '100000000000000000', // 0.1
};

const cost = calcCost({
  amount: '10000000000000000000', // 10 tokens
  decimal: 18,
  currentSupply: '0',
  direction: Direction.Mint,
  curve: linearCurve,
});

// Cost should be 10.5 tokens
console.log(cost.toString()); // '10500000000000000000'
```

### calcFee

Calculates the fee based on a reserve amount and a fee rate.

<strong>Parameters</strong>

- **reserveAmount** `string` *(required)* — The total amount from which the fee is calculated.
- **feeRate** `string` *(required)* — The fee rate in basis points (e.g., '500' for 5%).

<strong>Returns</strong>

- **** `BN` — The calculated fee amount.

## Asynchronous Utilities

### withRetry

A higher-order function that wraps an async operation, automatically retrying it upon failure.

<strong>Parameters</strong>

- **handle** `() => Promise<T>` *(required)* — The async function to execute and retry.
- **options** `object` — Configuration for the retry logic.
  - **retryLimit** `number` (default: `30`) — Maximum number of retry attempts.
  - **backoff** `object` — Exponential backoff configuration.
    - **baseDelay** `number` (default: `20`) — The base delay in milliseconds.
    - **maxDelay** `number` (default: `1000`) — The maximum delay in milliseconds.
  - **shouldRetry** `(error: unknown) => boolean` (default: `() => true`) — A function to determine if a retry should be attempted based on the error.
  - **onError** `(error: unknown, attempt: number) => void` — A callback function that executes on each failed attempt.

<strong>Returns</strong>

- **** `Promise<T>` — A promise that resolves with the result of the `handle` function.

<strong>Example</strong>

**Auto-Retry Operation**

```javascript
import { withRetry } from '@ocap/util';

let attempts = 0;
async function flakyFetch() {
  attempts++;
  console.log(`Attempting to fetch, attempt #${attempts}...`);
  if (attempts < 3) {
    throw new Error('Network failed');
  }
  return { data: 'Success!' };
}

async function main() {
  try {
    const result = await withRetry(flakyFetch, {
      retryLimit: 5,
      onError: (err, attempt) => console.log(`Attempt ${attempt} failed: ${err.message}`),
    });
    console.log(result); // { data: 'Success!' }
  } catch (error) {
    console.error('Operation failed permanently:', error.message);
  }
}

main();
```

## Custom Errors

### CustomError / PersistError

Custom error classes that extend the native `Error` object. They include a `code` for programmatic error handling and a `props` object for additional context. `PersistError` is a variant that signals the error should be persisted.

<strong>Constructor Parameters</strong>

- **code** `string` *(required)* — An error code string.
- **message** `string` *(required)* — The error message.
- **props** `object` — Additional properties associated with the error.

## Hashing

### md5

Computes the MD5 hash of a given input.

<strong>Parameters</strong>

- **data** `any` *(required)* — The data to hash.

<strong>Returns</strong>

- **** `string` — The MD5 hash as a hex string.

---

## @ocap/wallet

URL: https://www.arcblock.io/en/docs/blockchain-utils/wallet-855cea/

This package provides utility functions to create and use an OCAP-compatible crypto wallet. The generated wallets are also compatible with ArcBlock's Decentralized Identity (DID) system, enabling you to manage cryptographic keys, sign messages, and verify signatures seamlessly.

This section serves as an entry point for understanding and utilizing the `@ocap/wallet` library. Whether you're creating a new wallet from scratch or working with existing keys, this module offers a straightforward and powerful API.

## Installation

To get started, add the package to your project using npm or your preferred package manager.

**Installation**

```shell
npm install @ocap/wallet
```

## What's Next?

To dive deeper into the functionalities and concepts of the wallet library, explore the following sections:

::::card-group
::link-card{title="Core Concepts" description="Learn about the fundamental concepts behind the Wallet object, its structure, various instantiation methods, and its connection to DIDs." icon="book-open" href="/en/docs/blockchain-utils/wallet-concepts-855cea/"}
::link-card{title="API Reference" description="Explore a comprehensive reference for all wallet-related methods and factory functions, complete with practical examples for signing, verifying, and more." icon="code" href="/en/docs/blockchain-utils/wallet-api-reference-855cea/"}
::::

---

## API Reference

URL: https://www.arcblock.io/en/docs/blockchain-utils/wallet-api-reference-855cea/

This section provides detailed documentation for the `Wallet` object and its factory functions. You'll find descriptions of each function, its parameters, return values, and practical code examples for common operations like creating wallets, signing messages, and verifying signatures.

## Factory Functions

These functions are the primary way to create `Wallet` instances. Each function serves a specific purpose, whether you're creating a new wallet from scratch, from existing keys, or from a DID address.

### fromSecretKey()

Creates a complete wallet instance from a secret key. A wallet created this way can be used for both signing and verification.

<strong>Parameters</strong>

- **sk** `string | Buffer | Uint8Array` *(required)* — The secret key, typically in hex format.
- **_type** `DIDTypeArg` (default: `'default'`) — The DID type configuration. Can be a predefined string like 'default' or 'eth', or a custom type object. See @arcblock/did documentation for more details.

<strong>Returns</strong>

- **wallet** `WalletObject` — A new wallet object capable of signing and verifying.

<strong>Example</strong>

**Signing and Verifying a Message**

```javascript
const assert = require('assert');
const { fromSecretKey } = require('@ocap/wallet');

// A secret key in hex format
const sk = '0xD67C071B6F51D2B61180B9B1AA9BE0DD0704619F0E30453AB4A592B036EDE644E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';

// Create a wallet using the default DID type
const wallet = fromSecretKey(sk);

const message = 'data to sign';
const signature = wallet.sign(message);

console.log('Generated Signature:', signature);

const isValid = wallet.verify(message, signature);
assert.ok(isValid, "Signature should be verified successfully.");
console.log('Verification successful!');
```

### fromPublicKey()

Creates a wallet instance from a public key. This type of wallet can only be used to verify signatures, not to sign messages, as it lacks the secret key.

<strong>Parameters</strong>

- **pk** `string | Buffer | Uint8Array` *(required)* — The public key, typically in hex format.
- **_type** `DIDTypeArg` (default: `'default'`) — The DID type configuration. Determines the hashing and signing algorithms associated with the key.

<strong>Returns</strong>

- **wallet** `WalletObject` — A new wallet object capable of verifying signatures.

<strong>Example</strong>

**Verifying a known signature**

```javascript
const assert = require('assert');
const { fromPublicKey } = require('@ocap/wallet');

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const message = 'data to sign';
const knownSignature = '0x8122c608f61b04f6b574f005dc8e0463d393a7fb50e0426bca587b20778a8a9f6376bab87bc3983b0a5f1c9581f6d94162317c715a3c1c0f086be1e514399109';

const wallet = fromPublicKey(pk);

// This wallet can verify the signature
const isValid = wallet.verify(message, knownSignature);
assert.ok(isValid, "Signature should be verified.");

// This will throw an error because there is no secret key
try {
  wallet.sign(message);
} catch (e) {
  console.error(e.message); // Cannot sign data without a secretKey
}
```

### fromAddress()

Creates a minimal wallet instance from a DID address. Since the public and secret keys are unknown, this wallet cannot be used for signing or verifying. Its primary use is to inspect the DID type information encoded in the address.

<strong>Parameters</strong>

- **address** `string` *(required)* — A valid DID address (e.g., 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr').

<strong>Returns</strong>

- **wallet** `WalletObject` — A new wallet object containing the address and derived type information.

<strong>Example</strong>

**Inspecting a DID Address**

```javascript
const { fromAddress } = require('@ocap/wallet');
const { types } = require('@ocap/mcrypto');

const appId = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const wallet = fromAddress(appId);

console.log('Wallet Address:', wallet.address);
console.log('Role Type:', wallet.type.role); // 2 (ROLE_APPLICATION)
console.log('PK Type:', wallet.type.pk);     // 1 (ED25519)
console.log('Hash Type:', wallet.type.hash);   // 2 (SHA3)
```

### fromRandom()

Generates a new wallet with a randomly created key pair. This is the standard way to create a new identity.

<strong>Parameters</strong>

- **_type** `DIDTypeArg` (default: `'default'`) — The DID type for the new wallet. Use 'eth' to generate an Ethereum-compatible wallet.

<strong>Returns</strong>

- **wallet** `WalletObject` — A new wallet object with a randomly generated key pair.

<strong>Example</strong>

**Creating a new standard and an Ethereum wallet**

```javascript
const { fromRandom } = require('@ocap/wallet');

// Create a standard wallet (base58 address)
const standardWallet = fromRandom();
console.log('Standard DID Address:', standardWallet.address);
console.log('Secret Key:', standardWallet.secretKey);

// Create an Ethereum-compatible wallet (base16 address)
const ethWallet = fromRandom('eth');
console.log('Ethereum Address:', ethWallet.address);
console.log('Secret Key:', ethWallet.secretKey);
```

### fromJSON()

Reconstructs a wallet instance from a serialized JSON object, typically one created by the `wallet.toJSON()` method.

<strong>Parameters</strong>

- **json** `SerializedWallet` *(required)* — A serialized wallet object.
  - **type** `string` *(required)* — The DID type string.
  - **pk** `string` *(required)* — The public key in hex format.
  - **sk** `string` *(required)* — The secret key in hex format.
  - **address** `string` *(required)* — The DID address.

<strong>Returns</strong>

- **wallet** `WalletObject` — A wallet object restored from the JSON data.

<strong>Example</strong>

**Serializing and Deserializing a Wallet**

```javascript
const assert = require('assert');
const { fromRandom, fromJSON } = require('@ocap/wallet');

const originalWallet = fromRandom();

// Serialize the wallet to a JSON object
const walletJSON = originalWallet.toJSON();
console.log('Serialized Wallet:', walletJSON);

// Restore the wallet from the JSON object
const restoredWallet = fromJSON(walletJSON);

assert.equal(originalWallet.address, restoredWallet.address, 'Addresses should match');
assert.equal(originalWallet.secretKey, restoredWallet.secretKey, 'Secret keys should match');

console.log('Wallet restored successfully!');
```

### isValid()

Checks if a given object is a valid `WalletObject`. This is useful for type guarding and ensuring a wallet has the necessary properties and methods.

<strong>Parameters</strong>

- **wallet** `any` *(required)* — The object to check.
- **canSign** `boolean` (default: `true`) — If true, the function will also check for the presence of a secret key and a `sign` method.

<strong>Returns</strong>

- **isValid** `boolean` — Returns `true` if the object is a valid wallet, otherwise `false`.

<strong>Example</strong>

**Validating Wallet Objects**

```javascript
const { fromRandom, fromPublicKey, isValid } = require('@ocap/wallet');

const signingWallet = fromRandom();
const verifyingWallet = fromPublicKey(signingWallet.publicKey);

// A full wallet is valid for signing
console.log('Is signing wallet valid for signing?', isValid(signingWallet)); // true

// A wallet from a public key is not valid for signing
console.log('Is verifying wallet valid for signing?', isValid(verifyingWallet)); // false

// But it is valid if we don't require signing capabilities
console.log('Is verifying wallet valid for verification?', isValid(verifyingWallet, false)); // true

// An empty object is not a valid wallet
console.log('Is empty object a valid wallet?', isValid({})); // false
```

## Wallet Object

The `WalletObject` is the core entity returned by the factory functions. It holds the cryptographic keys, DID address, and methods for performing cryptographic operations.

### Properties

- **address** `string` — The DID address derived from the public key and type information.
- **publicKey** `BytesType` — The public key. The format (e.g., hex string, Buffer) depends on how the wallet was created.
- **secretKey** `BytesType` — The secret key. This is `undefined` for wallets created from a public key or address.
- **type** `DIDType` — An object containing the DID type information (role, pk, hash, address encoding).

### Methods

#### .sign()

Signs a piece of data using the wallet's secret key.

<strong>Parameters</strong>

- **data** `BytesType` *(required)* — The data to be signed.
- **hashBeforeSign** `boolean` (default: `true`) — If `true`, the data is hashed using the wallet's hash algorithm before signing.
- **encoding** `string` (default: `'hex'`) — The output encoding for the signature ('hex', 'base64', 'base58', 'buffer', etc.).

<strong>Returns</strong>

- **signature** `BytesType` — The generated signature in the specified encoding.

#### .verify()

Verifies a signature against a piece of data using the wallet's public key.

<strong>Parameters</strong>

- **data** `BytesType` *(required)* — The original data that was signed.
- **signature** `BytesType` *(required)* — The signature to verify.
- **hashBeforeVerify** `boolean` (default: `true`) — If `true`, the data is hashed before verification to match the signing process.

<strong>Returns</strong>

- **isValid** `Promise<boolean>` — A promise that resolves to `true` if the signature is valid, otherwise `false`.

#### .hash()

Hashes data using the wallet's configured hash algorithm.

<strong>Parameters</strong>

- **data** `BytesType` *(required)* — The data to be hashed.
- **round** `number` (default: `1`) — The number of hashing rounds.
- **encoding** `string` (default: `'hex'`) — The output encoding for the hash.

<strong>Returns</strong>

- **hash** `BytesType` — The resulting hash in the specified encoding.

#### .ethSign()

Signs a message using the Ethereum-specific signing algorithm (`eth_sign` behavior). Only available for wallets with the `'eth'` type.

<strong>Parameters</strong>

- **data** `string` *(required)* — The data to be signed.
- **hashBeforeSign** `boolean` (default: `true`) — If `true`, the data is hashed using the Ethereum-specific `ethHash` method first.

<strong>Returns</strong>

- **signature** `string` — The generated Ethereum signature.

#### .ethVerify()

Recovers the signer's address from an Ethereum signature and compares it to the wallet's address. Only available for wallets with the `'eth'` type.

<strong>Parameters</strong>

- **data** `string` *(required)* — The original data that was signed.
- **signature** `string` *(required)* — The Ethereum signature.
- **hashBeforeVerify** `boolean` (default: `true`) — If `true`, the data is hashed using `ethHash` before verification.

<strong>Returns</strong>

- **isValid** `boolean` — Returns `true` if the recovered address matches the wallet's address, otherwise `false`.

#### .toJSON()

Serializes the wallet's state into a plain JSON object. This is useful for storing or transmitting wallet data.

<strong>Returns</strong>

- **serialized** `SerializedWallet` — A JSON object containing the wallet's type, keys, and address.

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/blockchain-utils/wallet-concepts-855cea/

This section introduces the fundamental concepts behind the `@ocap/wallet` package. You'll learn what a Wallet object is, its structure, the different ways to create one, and its crucial relationship with Decentralized Identities (DIDs).

A Wallet object is more than just a container for a key pair; it's a powerful, self-contained utility for performing all necessary cryptographic operations related to a DID. It encapsulates the keys, the DID type information, and the methods for signing, verifying, and hashing data according to the rules defined by its type.

## The Wallet Object

The `WalletObject` is the central piece of this library. It holds all the information and functionality needed to manage a digital identity. Every wallet is composed of the following key properties:

- **type** `DIDType` *(required)* — An object that defines the cryptographic algorithms and encoding formats for the wallet.
- **secretKey** `string | Buffer` — The private key. This is required for signing operations. Keep it secret, keep it safe.
- **publicKey** `string | Buffer` *(required)* — The public key, derived from the secret key. It's used for verifying signatures.
- **address** `string` *(required)* — The decentralized identifier (DID) string associated with the wallet, derived from the public key.

## Understanding Wallet Types

A wallet's behavior is entirely determined by its `type`, which is a `DIDType` object from the [`@arcblock/did`](/en/docs/blockchain-utils/did-concepts-855cea/) package. This type object specifies which cryptographic algorithms and formats to use.

A `DIDType` is composed of four main parts:

| Property  | Description  |
|---|---|
| <strong>role</strong>  | Defines the purpose of the DID (e.g., Account, Application, Node).  |
| <strong>pk</strong>  | The public key algorithm to use (e.g., ED25519, ETHEREUM).  |
| <strong>hash</strong>  | The hashing algorithm to use (e.g., SHA3, KECCAK).  |
| <strong>address</strong>  | The encoding format for the final DID string (e.g., BASE58, BASE16).  |

The library provides convenient shortcuts for common configurations, such as `'default'` (for ArcBlock DIDs) and `'ethereum'`.

You can also define a custom wallet type for specific use cases, like creating an Application DID:

**Wallet Type Configuration**

```javascript
const { WalletType } = require('@ocap/wallet');
const { types } = require('@ocap/mcrypto');

const appWalletType = WalletType({
  role: types.RoleType.ROLE_APPLICATION,
  pk: types.KeyType.ED25519,
  hash: types.HashType.SHA3,
  address: types.EncodingType.BASE58,
});

// Now you can use this type to create a new wallet
// const wallet = fromRandom(appWalletType);
```

## Creating a Wallet

You can instantiate a wallet in several ways, depending on what information you have available. The following diagram illustrates the general process:

![Core Concepts](https://media.arcblock.io/lib/7d/7d3e91bf293eb44e.w1600.webp)

Here are the primary factory functions:

### fromRandom

This is the simplest way to create a brand new wallet. It generates a new random secret key and derives the corresponding public key and address.

```javascript
const { fromRandom } = require('@ocap/wallet');

// Create a new wallet with the default ArcBlock type
const wallet = fromRandom();

console.log('New Wallet Address:', wallet.address);
console.log('Secret Key:', wallet.secretKey);
```

### fromSecretKey

Use this function to restore a wallet when you already have the secret key. This is the most common way to load an existing identity.

```javascript
const { fromSecretKey } = require('@ocap/wallet');

const sk = '0xD67C071...'; // Your existing secret key
const wallet = fromSecretKey(sk);

console.log('Restored Wallet Address:', wallet.address);
```

### fromPublicKey

If you only have a public key, you can create a "read-only" wallet. This wallet can be used to verify signatures and derive the address, but it cannot be used to sign messages because it lacks the secret key.

```javascript
const { fromPublicKey } = require('@ocap/wallet');

const pk = '0xE4852B7...'; // An existing public key
const wallet = fromPublicKey(pk);

console.log('Address from PK:', wallet.address);
// wallet.sign('message'); // This would throw an error
```

### fromAddress

Creating a wallet from just a DID address is useful for parsing the type information embedded within the address string. This type of wallet is very limited and cannot sign or verify data.

```javascript
const { fromAddress } = require('@ocap/wallet');

const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const wallet = fromAddress(did);

// You can inspect the type information derived from the address
console.log('Wallet Type:', wallet.type);
```

### fromJSON

This function allows you to reconstruct a wallet from a serialized JSON object that was previously created using the `wallet.toJSON()` method. This is ideal for storing and retrieving wallets.

```javascript
const { fromRandom, fromJSON } = require('@ocap/wallet');

// 1. Create a wallet and serialize it
const originalWallet = fromRandom();
const serialized = originalWallet.toJSON();

// 2. Later, restore it from the JSON object
const restoredWallet = fromJSON(serialized);

console.log('Restored successfully:', originalWallet.address === restoredWallet.address);
```

## Relationship with DIDs

The Wallet object and a Decentralized Identity (DID) are intrinsically linked:

- <strong>A Wallet is the controller of a DID.</strong> The secret key within the wallet is the proof of ownership, granting the holder the ability to perform actions on behalf of the DID.
- <strong>The</strong> <strong>`wallet.address`</strong> <em><strong>is</strong></em> <strong>the DID.</strong> It's the public identifier that can be shared with others.
- <strong>The</strong> <strong>`wallet.type`</strong> <strong>defines the DID's properties.</strong> It determines how the DID was constructed and how it should behave cryptographically.

In essence, the `@ocap/wallet` library provides the practical tools to create, manage, and utilize the identities defined by the `@arcblock/did` specification.

With these core concepts in mind, you can now explore the [API Reference](/en/docs/blockchain-utils/wallet-api-reference-855cea/) for detailed information on all available methods and their parameters.

---

## Conceptual Guides

URL: https://www.arcblock.io/en/docs/blockchain/blockchain-conceptual-guides/

- [Understanding DIDs](/en/docs/blockchain/understanding-dids/)

- [Understanding Wallets and Accounts](/en/docs/blockchain/understanding-wallets-and-accounts/)

- [Understanding Transactions](/en/docs/blockchain/understanding-transactions/)

- [Understanding Tokens](/en/docs/blockchain/understanding-tokens/)

- [Understanding NFTs](/en/docs/blockchain/understanding-nfts/)

- [Understanding Verifiable Credentials](/en/docs/blockchain/understanding-verifiable-credentials/)

---

## Frequently Asked Questions

URL: https://www.arcblock.io/en/docs/blockchain/blockchain-frequently-asked-questions/

## How the documentation is organized?

ArcBlock Blockchain has a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things:

- [Getting Started](/en/docs/blockchain/blockchain-getting-started/) take you by the hand through a series of steps to sending your first transaction. Start here if you’re new to ArcBlock Blockchain.
- [Conceptual guides](/en/docs/blockchain/blockchain-conceptual-guides/) discuss key concepts at a fairly high level and provide useful background information and explanation.
- [Reference guides](/en/docs/blockchain/blockchain-reference-guides/) contain technical reference various aspects of ArcBlock Blockchain machinery. They describe how it works and how to use it but assume that you have a basic understanding of key concepts.
- [How-to guides](/en/docs/blockchain/blockchain-how-to-guides/) are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than Getting Started and assume some knowledge of how ArcBlock Blockchain works.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blockchain/blockchain-getting-started/

If you are an intermediate or advanced javascript developer, you can start from [Send first transaction](/en/docs/blockchain/send-first-transaction/).

Otherwise, you should follow following steps to get started:

- [Setup Node.js](/en/docs/blocklet-developer/setup-nodejs/)
- [Send first transaction](/en/docs/blockchain/send-first-transaction/)

---

## How-to Guides

URL: https://www.arcblock.io/en/docs/blockchain/blockchain-how-to-guides/

- [Create Account](/en/docs/blockchain/create-account/)

- [Query Accounts](/en/docs/blockchain/query-accounts/)

- [Query Transactions](/en/docs/blockchain/query-transactions/)

- [Create Token](/en/docs/blockchain/create-token/)

- [Query NFT](/en/docs/blockchain/query-nft/)

---

## Reference Guides

URL: https://www.arcblock.io/en/docs/blockchain/blockchain-reference-guides/

- [Working with DIDs](/en/docs/blockchain/working-with-dids/)

- [Work with Verifiable Credentials](/en/docs/blockchain/work-with-verifiable-credentials/)

- [Transaction Types](/en/docs/blockchain/transaction-types/)

---

## Setup Node.js

URL: https://www.arcblock.io/en/docs/blockchain/blockchain-setup-nodejs/

About why Node.js is required and how to install Node.js please refer to [Blocklet Developer Guide](/en/docs/blocklet-developer/setup-nodejs/)

---

## Create Account

URL: https://www.arcblock.io/en/docs/blockchain/create-account/

An account is a data entry that's stored in the chain ledger, on-chain accounts are controlled by off-chain wallets, see [understanding accounts and wallets](/en/docs/blockchain/understanding-wallets-and-accounts/).

There are several ways to create an account in the ledger.

## Create accounts with DeclareTx

The most intuitive way to create an account is to send a `DeclareTx` to the chain, here are a few examples:

### With account moniker

```javascript
const { fromRandom } = require("@ocap/wallet");
const Client = require("@ocap/client");

const client = new Client("https://beta.abtnetwork.io/api/");
const wallet = fromRandom();

const hash = await client.declare({ moniker: "chain-user", wallet });
```

The `moniker` field will be displayed on the account detail page in [chain explorer](https://beta.abtnetwork.io/explorer/accounts/z1TPn5rYHyxwbyphJ8ZoJECyVhy9tDDyEJU) like this:

![Image](https://media.arcblock.io/lib/3d/3deb8b96812820aadb7c9b5b9f04a8d7.w1600.webp)

### With customized type

Each account can customize the [role type](/en/docs/blockchain/understanding-dids/#did-type), [key-type](/en/docs/blockchain/understanding-dids/#keytype) and [hash-type](/en/docs/blockchain/understanding-dids/#hashtype) for its address:

```javascript
const { types } = require("@ocap/mcrypto");
const { fromRandom } = require("@ocap/wallet");
const Client = require("@ocap/client");

const client = new Client("https://beta.abtnetwork.io/api/");
const wallet = fromRandom({
  role: types.RoleType.ROLE_BOT, // default to ROLE_ACCOUNT
  key: types.KeyType.ED25519, // default to ED25519
  hash: types.HashType.SHA3, // default to SHA3
});

const hash = await client.declare({ moniker: "customized-did", wallet });
```

### With account issuer

You can also set the `issuer` field when creating an account, with this field you can relate multiple accounts in a public way:

- `issuer` must be a valid account address
- `issuer` must refer to an existing account in the ledger

```javascript
const hash = await client.declare({
  moniker: "chain-user",
  issuer: "<issuer-address>",
  wallet,
});
```

### With account data

You can also attach some `data` with the account when creating:

- `data` will be immutable upon creation
- `data` can be retrieved with `getAccountState`
- `data` must be structured in the [transaction data format](/en/docs/blockchain/understanding-transactions/)
- `data` size can not be too large because [transaction size limit](/en/docs/blockchain/understanding-transactions/).

```javascript
const hash = await client.declare({
  moniker: "chain-user",
  data: {
    type: "json",
    value: {
      source: "hello-arcblock-chain",
    },
  },
  wallet,
});
```

## Create accounts implicitly

ArcBlock chain also creates accounts implicitly in the following cases so that the user does not need to send `DeclareTx` ahead:

- Delegate: when the delegation receiver is not in the ledger, it's created
- Transfer: when the receiver is not in the ledger, it's created

But there are some pros for accounts created implicitly:

- `moniker` can not be customized
- `issuer` can not be customized
- `data` is empty

---

## Create Token

URL: https://www.arcblock.io/en/docs/blockchain/create-token/

此文档描述如何从 ArcSwap 界面上创建 Token。

Beta：https://beta.abtnetwork.io/swap

Main：尚未开放

费用：质押 100 TBA（Main链为 ABT），质押的 Token 可在 Token Factory 关闭后取回（即将支持）

从界面点击 「创建Token」，进入创建页面：

![image.png](https://media.arcblock.io/lib/1b/1b07e0ae22f0a452090ac1f1e1063cec.w1600.webp)

### 填写 Token 基本信息

根据表单提示，填写 Token Name、Symbol、Description、Issuer 等基本信息。

上传一张 < 12 kb 的 SVG 头像，如未上传，ArcSwap 会根据 Token Address 自动生成 DID 风格的头像。

填写 Offcial Website，此网站在后续的创建流程中，需要验证所有权，因此需要填写自己的站点，如果没有站点，可以参照下面的指南快速生成一个。

### 快速创建新站点

如果你没有自己的站点，点击 「Launch New Website」，由 Arcblock Launcher 自动为你快速创建和部署一个站点：

![image.png](https://media.arcblock.io/lib/69/69bb9bcc4dbb8387dea87157c6b7440e.w1600.webp)

点击「Pay & Launch Website」，跳转到支付页面进行支付订阅。

当前的定价只做教程演示，实际定价会随着官方的策略动态调整。

![image.png](https://media.arcblock.io/lib/80/804a3478976b1a895ac508ca88e05125.w1600.webp)

支付成功后，等待自动生成站点，成功之后界面上会显示此站点的访问地址，可以点击「Manage Website」进入网站的 Dashboard 进行管理。

![image.png](https://media.arcblock.io/lib/dc/dccd4442c586ee0930c3b6d53c301323.w1600.webp)

后续可以访问 Blocklet Launcher 管理你的应用和订阅：

Main：https://launcher.arcblock.io

Beta：https://launcher.staging.arcblock.io

### 填写联合曲线参数

联合曲线是一种依赖数学曲线自动做市的模型，曲线的参数决定了 Token 的定价模型，随着用户对 Token 的购买或出售，Token 的价格将随着曲线上涨或下跌。

联合曲线模型也保证了所有被购买的 Token，都一定能出售回去，不会因为缺少流动性导致有市无价。

ArcSwap 目前支持 3 种常用模型：

<strong>Constant</strong>： 固定价格曲线，无论供应量如何变化，Token 价格始终保持不变

<strong>Linear</strong>：线性曲线，随着供应量的增加或减少，Token 的价格将会线性增加或减少

<strong>Quadratic</strong>：指数曲线，随着供应量的增加或减少，Token 的价格将会指数增加或减少

你可以调节参数，观察曲线图的变化，找到最适合自己的定价模型。

曲线图的x轴表示 Token 的供应量，Y轴表示 Token 的价格，能直观的看出，当 Token 被 Mint 出多少个时，对应的价格为多少。

![image.png](https://media.arcblock.io/lib/ab/abf5fe5c9a1bcf1d5070a750e4da50f8.w1600.webp)

### 验证 Offical Website 所有权

点击 「Create Token」，打开验证弹窗：

![image.png](https://media.arcblock.io/lib/55/55d89fb40ad6edaad304972ad7d64a14.w1600.webp)

点击「Generate Verification Content」，通过 DID Wallet 进行签名，签名后将显示一串数据，这串数据包含了 Token 的基本信息以及对应的网站，用来验证网站和 Token 的关联。

![image.png](https://media.arcblock.io/lib/34/3426add447b07c939103872ef2c12185.w1600.webp)

如果你的网站是 Blocklet 或者是在该页面「Launch New Website」创建的，那么点击「Connect to verify」，进入授权页面，授权后 ArcSwap 将自动验证网站所有权。

![image.png](https://media.arcblock.io/lib/61/61f7647e4c8a9542aa91a99cb8a560e7.w1600.webp)

如果你的网站不是 Blocklet，那么你需要根据页面上的提示，将签名后得到的数据，复制到你网站的 /.well-known/ocap/tokens.json 路径下:

![image.png](https://media.arcblock.io/lib/93/937b423add198001915970a26e45c339.w1600.webp)

验证成功后，离创建成功就只差一步了。

### 质押和创建 Token

点击 Create Token，将在 DID Wallet 中发起两笔交易：

1. 质押 100 TBA 的交易 (Main 链则为 ABT) ，质押的 Token 可在 Token Factory 关闭后取回（即将支持）
2. 创建 Token

![image.png](https://media.arcblock.io/lib/69/698b64a11b06d4511f08a6cbcb6df32a.w1600.webp)

交易成功后，Token 就创建成功了，回到 ArcSwap 页面，在 Mint Token 的 Symbol 列表里选择你刚刚创建的 Token，就可以进行交易了。

![image.png](https://media.arcblock.io/lib/df/df1efc2295430afc35e441efd213a563.w1600.webp)

---

## Query Accounts

URL: https://www.arcblock.io/en/docs/blockchain/query-accounts/

## Query account by address

Since each account is identified by account address(DID), we can query account state by address with `getAccountState` method:

```javascript
const Client = require("@ocap/client");

const client = new Client("https://beta.abtnetwork.io/api/");
const { state } = await client.getAccountState({
  address: "zNKZ4YXc9tYZN87KP51b7psz857GBzWFMz3N",
});
console.log(state);
```

## Query account tokens

Each account can have multiple [tokens](/en/docs/blockchain/understanding-tokens/), we can query tokens owned by account address with `getAccountTokens` method:

```javascript
const Client = require("@ocap/client");

const client = new Client("https://beta.abtnetwork.io/api/");
const { tokens } = await client.getAccountTokens({
  address: "zNKZ4YXc9tYZN87KP51b7psz857GBzWFMz3N",
});
console.log(tokens);
```

## Query account NFTs

Each account can own multiple [NFTs](/en/docs/blockchain/understanding-nfts/), we can query NFTs owned by account address with `listAssets` method:

```javascript
const Client = require("@ocap/client");

const client = new Client("https://beta.abtnetwork.io/api/");
const { assets } = await client.listAssets({
  ownerAddress: "zNKZ4YXc9tYZN87KP51b7psz857GBzWFMz3N",
});
console.log(assets);
```

## Query accounts by token balance

We can also query accounts by token balance to monitor top token holders with `listTopAccounts` method:

```javascript
const Client = require("@ocap/client");

const client = new Client("https://beta.abtnetwork.io/api/");
const { accounts } = await client.listTopAccounts({
  tokenAddress: "z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG",
});
console.log(accounts);
```

---

## Query NFT

URL: https://www.arcblock.io/en/docs/blockchain/query-nft/

### Query NFT State

The `getAssetState` query allows you to fetch the current state of an asset on the blockchain using its address. This can be useful for retrieving information such as the asset's owner, properties, and other relevant data.

```javascript
const Client = require('@ocap/client');

const endpoint = 'https://main.abtnetwork.io/api';
const client = new Client(endpoint);

async function getAssetInfo(assetAddress) {
  try {
    const { state } = await client.getAssetState({ address: assetAddress });
    console.log('Asset State:', state);
  } catch (error) {
    console.error('Error fetching asset state:', error);
  }
}

// Usage
(async () => {
  // Assume assetAddress is defined earlier in your code
  await getAssetInfo(assetAddress);
})();
```

### Query NFT List

The `listAssets` query allows you to fetch a list of assets on the blockchain based on various criteria such as owner, factory, and time range. This can be useful for retrieving collections of assets or monitoring asset creation and updates.

```javascript
const Client = require('@ocap/client');

const endpoint = 'https://main.abtnetwork.io/api';
const client = new Client(endpoint);

async function listAssets(params) {
  try {
    const result = await client.listAssets(params);
    console.log('Assets:', result.assets);
    console.log('Pagination:', result.page);
  } catch (error) {
    console.error('Error listing assets:', error);
  }
}

// Usage examples
(async () => {
  // List assets by owner
  await listAssets({ ownerAddress: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' });

  // List assets with pagination
  await listAssets({
    paging: { size: 10, cursor: '' }
  });

  // List assets by factory
  await listAssets({ factoryAddress: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' });

  // List assets with time filter
  await listAssets({
    timeFilter: {
      startDateTime: '2023-01-01T00:00:00Z',
      endDateTime: '2023-12-31T23:59:59Z',
      field: 'renaissanceTime',
    }
  });

  // Combine multiple parameters
  await listAssets({
    ownerAddress: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr',
    factoryAddress: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr',
    paging: { size: 20, cursor: '' },
    timeFilter: {
      startDateTime: '2023-01-01T00:00:00Z',
      endDateTime: '2023-12-31T23:59:59Z',
      field: 'genesisTime',
    }
  });
})();
```

---

## Query Transactions

URL: https://www.arcblock.io/en/docs/blockchain/query-transactions/

The `listTransactions` query allows you to fetch a list of transactions on the blockchain based on various criteria. This can be useful for monitoring specific types of transactions, analyzing account activity, or tracking asset-related operations.

```javascript
const Client = require('@ocap/client');

const endpoint = 'https://main.abtnetwork.io/api';
const client = new Client(endpoint);

async function listTransactions(params) {
  try {
    const result = await client.listTransactions(params);
    console.log('Transactions:', result.transactions);
    console.log('Pagination:', result.page);
  } catch (error) {
    console.error('Error listing transactions:', error);
  }
}

// Usage examples
(async () => {
  // List transactions with pagination
  await listTransactions({
    paging: { size: 10, cursor: '' }
  });

  // List transactions by address
  await listTransactions({
    addressFilter: { sender: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' }
  });

  // List transactions by time range
  await listTransactions({
    timeFilter: {
      startDateTime: '2023-01-01T00:00:00Z',
      endDateTime: '2023-12-31T23:59:59Z'
    }
  });

  // List transactions by type
  await listTransactions({
    typeFilter: { types: ['transfer'] }
  });

  // List valid transactions only
  await listTransactions({
    validityFilter: { validity: 'VALID' }
  });

  // List transactions related to a specific token
  await listTransactions({
    tokenFilter: { address: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' }
  });

  // List transactions related to a specific asset
  await listTransactions({
    assetFilter: { address: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' }
  });

  // List transactions with multiple filters
  await listTransactions({
    addressFilter: { sender: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' },
    timeFilter: {
      startDateTime: '2023-01-01T00:00:00Z',
      endDateTime: '2023-12-31T23:59:59Z'
    },
    typeFilter: { types: ['transfer'] },
    validityFilter: { validity: 'VALID' },
    paging: { size: 20, cursor: '' }
  });

  // List staking-related transactions
  await listTransactions({
    stakeFilter: { address: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' }
  });

  // List delegation-related transactions
  await listTransactions({
    delegationFilter: { address: 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr' }
  });
})();
```

---

## Send first transaction

URL: https://www.arcblock.io/en/docs/blockchain/send-first-transaction/

In this tutorial you will learn how to connect to a running chain and send your first transaction.

## Setup Project

Run following commands to setup a project:

```javascript
mkdir -p /tmp/arcblock/chain && cd /tmp/arcblock/chain
npm init -y
npm install @ocap/client @ocap/wallet -S
```

## Connect to Test Chain

Then let's create a `list.js` file under `/tmp/arcblock/chain`:

```javascript
const Client = require("@ocap/client");

// Init client with test chain endpoint
const client = new Client("https://beta.abtnetwork.io/api/");

// Query latest transactions on test chain
client.listTransactions().then((data) => console.log(data.transactions));
```

Then run the script with `node list.js`, output will be similar with following:

```javascript
[
  {
    code: 'OK',
    hash: '088E573D87CD2831D283DBF9BFBC744ED95A6DC953ED867D6F50E43A455C3BD9',
    receiver: 'z1eoWWAhtb2Y2ZLB5D2Pbgb1kEgKyURvtt1',
    sender: 'zNKeLKixvCM32TkVM1zmRDdAU3bvm3dTtAcM',
    time: '2022-09-20T08:46:04.671Z',
    type: 'transfer_v2',
    tx: {
      chainId: 'beta',
      delegator: '',
      from: 'zNKeLKixvCM32TkVM1zmRDdAU3bvm3dTtAcM',
      itxJson: [Object],
      nonce: '1663663564596',
      pk: '6xbpBn_ND9DB8YTgF7AV67Lsy8ZbAutmPQLpXlRJ6K8',
      receiver: null,
      sender: null,
      serviceFee: '0',
      signature: '95U8cKN2TZM-waRaEjA5CwHKv60VHxiDfvJPt4n8_Q2526BoQoI4kkw5272P1LZ-_5o5Qvgs0CN_Zc1A3TMNCQ',
      signatures: []
    }
  },
  ...
]
```

- For more examples on query transactions please checkout [Query Transactions](/en/docs/blockchain/query-transactions/).

## Create Wallet

In order to send transactions to the chain, we need create a wallet first, create a `wallet.js` file under `/tmp/arcblock/chain`:

```javascript
const { fromRandom } = require("@ocap/wallet");

// Create wallet from random key-pair
const wallet = fromRandom();
console.log(wallet);
```

Then run the script with `node wallet.js`, output will be similar with following:

```javascript
{
  type: { role: 0, pk: 0, hash: 1, address: 1 },
  secretKey: '0x18625b160eed695dc4ce0e77b334c0041fcecc9149198ec3791c1f173440607fc----truncated-text----',
  publicKey: '0xcdde351726ef6bf8486a558d90d6588975eb07428a9c04acf55d7e439a4f63c7',
  address: 'z1ivznhRWTgZaZkS2ZhwxgDVaYxV8qadxK9',
  hash: [Function: hash],
  sign: [Function: sign],
  verify: [Function: verify],
  ethHash: [Function: ethHash],
  ethSign: [Function: ethSign],
  ethVerify: [Function: ethVerify],
  toAddress: [Function: toAddress],
  toJSON: [Function: toJSON]
}
```

- For a better understanding of wallets please checkout [Understanding Wallets](/en/docs/blockchain/understanding-wallets-and-accounts/).
- For detailed usage instructions of `@ocap/wallet` please checkout [Working with Wallets](/en/docs/blockchain/working-with-wallets/).

## Send Transaction

Now let's put things together by sending a transaction to the test chain, create a `tx.js` file under `/tmp/arcblock/chain`:

```javascript
const Client = require("@ocap/client");
const { fromRandom } = require("@ocap/wallet");

const wallet = fromRandom();
const client = new Client("https://beta.abtnetwork.io/api/");

(async () => {
  // Create account on the chain that can own token and NFTs
  const hash = await client.declare({ moniker: "hello-chain", wallet });
  const result = await client.getTx({ hash });

  console.log(result);
})();
```

Then run the script with `node tx.js`, upon success you will see following output:

```javascript
{
  code: 'OK',
  info: {
    code: 'OK',
    hash: '8F8732038C397A5B5A0578728298CF1AA629616F6F48376DA98D69386295BAFC',
    height: '0',
    index: 0,
    receiver: '',
    sender: '',
    time: '2022-09-20T08:59:01.281Z',
    receipts: [],
    tags: null,
    tx: {
      chainId: 'beta',
      delegator: '',
      from: 'z1TPn5rYHyxwbyphJ8ZoJECyVhy9tDDyEJU',
      itxJson: [Object],
      nonce: '1663664340951',
      pk: 'ZibFto8AEQHjOCk-EulgeZ6Liue7mxfyUikRrS16pZs',
      receiver: null,
      sender: null,
      serviceFee: '0',
      signature: 'HAcfobpWist6eYrUAJ83N8W-gEktJcWy7YrZ0Mg9jojgl-W0h2ESKDFB2Ii7-U0-fu4A9dkHJX6zuyfjfHkqCg',
      signatures: []
    }
  }
}
```

The `8F8732038C397A5B5A0578728298CF1AA629616F6F48376DA98D69386295BAFC` is the transaction hash returned by the chain.

You can inspect the transaction on [beta chain explorer](https://beta.abtnetwork.io/explorer/txs/8F8732038C397A5B5A0578728298CF1AA629616F6F48376DA98D69386295BAFC)

- For a better understanding of transactions please checkout [Understanding Transactions](/en/docs/blockchain/understanding-transactions/).

---

## Migration Guides

URL: https://www.arcblock.io/en/docs/blockchain/tBSXI18ueOFs1K4osywznwdX/

- [Upgrade from 1.18.x to 1.19.x](/en/docs/blockchain/upgrading-from-18-to-19/)

---

## Transaction Types

URL: https://www.arcblock.io/en/docs/blockchain/transaction-types/

## Account Related

### DeclareTx

```javascript
message DeclareTx {
  string moniker = 1;
  string issuer = 2;

  google.protobuf.Any data = 15;
}
```

### AccountMigrateTx

```javascript
// User can use this to lock a breached sk
// Or upgrade his account to a more secure crypto algorithm
// Or rotate account sk periodically for better security
message AccountMigrateTx {
  bytes pk = 1;                              // new public key
  WalletType type = 2 [ deprecated = true ]; // new wallet type
  string address = 3;                        // new wallet address

  google.protobuf.Any data = 15;
}
```

### DelegateTx

```javascript
// if rules are empty, signature for this type_url is entirely delegated
// otherwise rules are checked one by one, relationship between rules is AND.
// a rule is an expression defined in rule_parser
// (github.com/arcblock/rule-parser) one can setup
message DelegateOp {
  string type_url = 1;
  repeated string rules = 2;
}
message DelegateTx {
  string address = 1; // address of the delegation between sender and receiver
  string to = 2;      // delegatee's address
  repeated DelegateOp ops = 3; // a list of operations permitted, ops will be merged when multiple delegation is done on same address

  google.protobuf.Any data = 15;
}
```

### RevokeDelegateTx

```javascript
message RevokeDelegateTx {
  string address = 1; // address of the delegation between sender and receiver
  string to = 2;      // delegatee's address
  repeated string type_urls = 3;

  google.protobuf.Any data = 15;
}

protobuf
```

## Trade Related

Transactions used to transfer tokens and NFTs.

### ExchangeV2Tx

```javascript
message ExchangeInfoV2 {
  BigUint value = 1;
  repeated string assets = 2;
  repeated TokenInput tokens = 3;
}

// we could support these cases (and vise versa):
// 1. sender fungible token <-> receiver one or more assets
// 2. sender fungible token + asset <-> receiver one or more assets
// 3. sender one or more assets <-> receiver one or more assets
message ExchangeV2Tx {
  string to = 1;
  ExchangeInfoV2 sender = 2;
  ExchangeInfoV2 receiver = 3;
  google.protobuf.Timestamp expired_at = 4;

  google.protobuf.Any data = 15;
}
```

### TransferV2Tx

```javascript
message TokenInput {
  string address = 1;
  string value = 2;
}
message TransferV2Tx {
  string to = 1;
  BigUint value = 2;
  repeated string assets = 3;
  repeated TokenInput tokens = 4;

  google.protobuf.Any data = 15;
}
```

### TransferV3Tx

```javascript
message TransactionInput {
  string owner = 1;
  repeated TokenInput tokens = 2;
  repeated string assets = 3;
}
message TransferV3Tx {
  repeated TransactionInput inputs = 1;
  repeated TransactionInput outputs = 2;

  google.protobuf.Any data = 15;
}
```

## Token Related

Transactions used to create, deposit and withdraw token.

### CreateTokenTx

```javascript
message CreateTokenTx {
  string name = 1;
  string description = 2;
  string symbol = 3;
  string unit = 4;
  int32 decimal = 5;
  string icon = 6;
  string total_supply = 7;
  string address = 8;

  // For tokens that supports rollup, the initial supply should be very small
  // Initial supply should be less than total supply
  string initial_supply = 9;

  // It's recommended that you set this, so your token will possibly have a price in fiat currency.
  // string erc20_contract_address = 15; // deprecated
  ForeignToken foreign_token = 16;

  google.protobuf.Any data = 20;
}
```

### DepositTokenV2Tx

```javascript
message DepositTokenV2Tx {
  // Should be a multi-signed transaction
  // Submited by user, signed by rollup validators
  TokenInput token = 1;           // token address and amount to deposit
  string to = 2;                  // address to deposit token to, should be same as tx.from
  string proposer = 3;            // the rollup validator that pays for this deposit, other validators exists in tx.signatures
  Evidence evidence = 4;          // the evidence of the original transaction
  string rollup = 5;              // the rollup chainId to deposit to

  // Added since v1.13.61
  string actual_fee = 7;       // the actual_fee charged for this tx

  google.protobuf.Any data = 15;
}
```

### WithdrawTokenV2Tx

```javascript
message WithdrawTokenV2Tx {
  TokenInput token = 1;           // token address and amount to withdraw
  string to = 2;                  // foreign address to withdraw token to, should by same as tx.from
  string rollup = 3;              // the rollup chainId to withdraw from

  // Added since v1.13.61
  string proposer = 5;            // the rollup validator that proposed the max-reward
  string max_fee = 6;             // the maximum fee amount that user is willing to pay for this tx to be committed
  string actual_fee = 7;          // the actual_fee charged for this tx

  google.protobuf.Any data = 15;
}
```

## NFT Related

### AcquireAssetV2Tx

```javascript

// --------------------- Asset Related -------------------------------------
message AssetFactoryInput {
  // how much primary token required to mint
  // usually used to set a price for the NFT
  string value = 1;

  // how much secondary tokens required to mint asset from this factory
  // usually used to set a price for the NFT
  repeated TokenInput tokens = 2;

  // which asset(s) required to mint new nft
  // can be either a list of specific assets or factories
  // if specific assets are provided, we should ensure they are not consumed when creating the factory
  // and then mark the input assets as consumed when minting success, in such case, this factory usage is limited
  // if a factory is provided, we should ensure each input assets is not consumed and all minted from that factory on minting
  // in such case, we can pipe factory to build very complex business logic
  // optional, default to empty array
  repeated string assets = 3;

  // variables that will be inserted into the output
  // limitation: all variables should be strings
  repeated VariableInput variables = 4;
}
// Granted issuers can help users to mint new assets with predefined costs
message AcquireAssetV2Tx {
  // the address of the asset factory
  string factory = 1;

  // address of the minted asset
  // must be calculated on client side to make things deterministic
  string address = 2;

  // assets to consume to mint new asset
  // should be a list of specific asset (not factory)
  // each asset will be checked for consumption before minting
  // and marked as consumed when minting success
  repeated string assets = 3;

  // template variables, should all be strings
  // this list should contain all required variables to populate the factory output template
  repeated VariableInput variables = 4;

  // issuer info to mint the asset
  NFTIssuer issuer = 5;

  google.protobuf.Any data = 15;
}
```

### AcquireAssetV3Tx

```javascript
message AcquireAssetV3Tx {
  // the address of the asset factory
  string factory = 1;

  // address of the minted asset
  // must be calculated on client side to make things deterministic
  string address = 2;

  // Who pays for this acquire
  repeated TransactionInput inputs = 3;

  // Who gets the minted asset
  string owner = 4;

  // template variables, should all be strings
  // this list should contain all required variables to populate the factory output template
  repeated VariableInput variables = 5;

  // issuer info to mint the asset
  NFTIssuer issuer = 6;

  google.protobuf.Any data = 15;
}
```

### MintAssetTx

```javascript
// The factory owner can mint new assets without any cost
message MintAssetTx {
  // the address of the asset factory
  string factory = 1;

  // address of the minted asset
  // must be calculated on client side to make things deterministic
  string address = 2;

  // assets to consume to mint new asset
  // should be a list of specific asset (not factory)
  // each asset will be checked for consumption before minting
  // and marked as consumed when minting success
  repeated string assets = 3;

  // template variables
  repeated VariableInput variables = 4;

  // owner of the minted asset
  string owner = 5;

  google.protobuf.Any data = 15;
}
```

### CreateAssetTx

```javascript
message CreateAssetTx {
  string moniker = 1;
  // ocap won't update data into state if app is interested in this tx.
  google.protobuf.Any data = 2;
  bool readonly = 3;
  bool transferrable = 4;
  // ttl for the asset after first consumption. 0 means unlimited.
  uint32 ttl = 5;
  string parent = 6;
  string address = 7;
  string issuer = 8;
  // nft related
  NFTEndpoint endpoint = 9;
  NFTDisplay display = 10;
  repeated string tags = 11;
}
```

### UpdateAssetTx

```javascript
message UpdateAssetTx {
  string address = 1;
  string moniker = 2;

  google.protobuf.Any data = 15;
}
```

### CreateFactoryTx

```javascript
// An asset factory is readonly by default
// Thus any change to the factory result a new factory
message CreateFactoryTx {
  string name = 1;
  string description = 2;

  // If the input requires some tokens, how are they settled?
  // Currently we only support instant settlement
  // In future we may consider periodic settlement
  string settlement = 3;

  // total assets can mint from this factory, set to 0 to allow infinite minting
  uint32 limit = 4;

  // who can mint assets from this factory
  // default to empty, which only the factory owner can mint assets from
  // If set to ["*"], then anyone can mint from this factory
  repeated string trusted_issuers = 5;

  // input params to mint new asset, can be any combination of tokens + assets
  AssetFactoryInput input = 6;

  // the template that asset factory will use to generate the asset
  // the output must be the same structure as `CreateAssetTx`
  // from which we can derive the asset address from
  // the output object can contain template variable placeholders to populate
  CreateAssetTx output = 7;

  // hooks called when new assets minted
  repeated AssetFactoryHook hooks = 8;

  // address for the factory
  string address = 9;

  // how the nft factory will look like
  NFTDisplay display = 10;

  google.protobuf.Any data = 15;
}
```

## Staking Related

### StakeTx

```javascript

// --------------------- Staking Related -------------------------------------
// User can append assets to the same stake
message StakeTx {
  string address = 1;

  // used to create stake address = createDid(tx.sender, itx.to)
  string receiver = 2;

  // Can stake any combination of tokens + assets
  repeated TransactionInput inputs = 3;

  // Lock the stake on creation, does not have any effect when append to existing stake
  bool locked = 4;

  // Human readable messge help to identify the purpose of the stake
  string message = 5;

  // Period to wait before revoked stake can be claimed, in seconds
  uint32 revoke_waiting_period = 6;

  google.protobuf.Any data = 50;
}
```

### RevokeStakeTx

```javascript
// Withdraw assets from the stake
message RevokeStakeTx {
  string address = 1;

  // Can unstake any combination of tokens + assets
  // Can unstake part of it or all of it
  repeated TransactionInput outputs = 2;

  google.protobuf.Any data = 50;
}
```

### ClaimStakeTx

```javascript
// Claim revoked stake
message ClaimStakeTx {
  // Which stake to claim from
  string address = 1;

  // Revoke transaction
  Evidence evidence = 2;

  google.protobuf.Any data = 50;
}
```

## Rollup Related

Transactions used to goverance an ArcBridge instance.

### CreateRollupTx

```javascript
message CreateRollupTx {
  string address = 1;

  // can be token or factory adddress
  string token_address = 2;

  // string erc20_token_address = 3; // deprecated

  string contract_address = 4;

  // Immutable
  repeated RollupValidator seed_validators = 5;

  // Mutable
  string min_stake_amount = 6;
  string max_stake_amount = 7;

  // Mutable
  uint32 min_signer_count = 8; // default to 1
  uint32 max_signer_count = 9;

  // Mutable
  uint32 min_block_size = 10; // default to 1
  uint32 max_block_size = 11; // default to 1000, ideally cost < income

  // Mutable
  uint32 min_block_interval = 12;
  uint32 min_block_confirmation = 13;

  // Immutable
  string foreign_chain_type = 14; // type of the foreign chain, possibly "eth", "bsc", "matic"
  string foreign_chain_id = 15;   // chain id of the chain. Could be testnet or mainnet.

  // Mutable
  uint32 deposit_fee_rate = 16;
  uint32 withdraw_fee_rate = 17;
  uint32 proposer_fee_share = 18;

  // Mutable
  string min_deposit_amount = 19;
  string min_withdraw_amount = 20;

  // Added since v1.13.45
  string max_deposit_amount = 21;
  string max_withdraw_amount = 22;
  string min_deposit_fee = 23;
  string max_deposit_fee = 24;
  string min_withdraw_fee = 25;
  string max_withdraw_fee = 26;
  bool paused = 27;

  // Added since v1.13.53
  uint32 leave_waiting_period = 28;

  // Added since v1.13.57
  uint32 publisher_fee_share = 29;

  // Added since v1.13.61
  uint32 publish_waiting_period = 30;
  uint32 publish_slash_rate = 31;

  google.protobuf.Any data = 50;
}
```

### UpdateRollupTx

```javascript
// Should be a multi-signed transaction
message UpdateRollupTx {
  string min_stake_amount = 1;
  string max_stake_amount = 2;

  uint32 min_signer_count = 3; // default to 1
  uint32 max_signer_count = 4;

  uint32 min_block_size = 5; // default to 1
  uint32 max_block_size = 6; // default to 1000, ideally cost < income

  uint32 min_block_interval = 7;
  uint32 min_block_confirmation = 8;

  uint32 deposit_fee_rate = 9;
  uint32 withdraw_fee_rate = 10;
  uint32 proposer_fee_share = 11;

  string min_deposit_amount = 12;
  string min_withdraw_amount = 13;

  // Added since v1.13.45
  string max_deposit_amount = 14;
  string max_withdraw_amount = 15;
  string min_deposit_fee = 16;
  string max_deposit_fee = 17;
  string min_withdraw_fee = 18;
  string max_withdraw_fee = 19;

  // Added since v1.13.57
  uint32 publisher_fee_share = 20;

  // Added since v1.13.61
  uint32 leave_waiting_period = 21;
  uint32 publish_waiting_period = 22;
  uint32 publish_slash_rate = 23;

  string rollup = 40;
  google.protobuf.Any data = 50;
}
```

### JoinRollupTx

```javascript
message JoinRollupTx {
  // Other nodes must sign for this join: by checking availability of the node endpoint
  // We should carefully design an challenge workflow for the new node
  // Only seed validators can join without multi-sign
  // New node can only join when it meets minimum staking requirements
  string rollup = 1;

  // If the validator endpoint changed, it should leave and join again
  // The node does not have to make any changes to the stake
  string endpoint = 2;

  // The foreign chain tx hash that the node has added itsself from the contract
  // The node must pass a group of challenges before actually join the rollup
  Evidence evidence = 3;

  // Signature from other nodes that verified the evidence
  // The current validator should not be included
  repeated Multisig signatures = 4;

  google.protobuf.Any data = 50;
}
```

### LeaveRollupTx

```javascript
message LeaveRollupTx {
  // The staking can only be revoked when the node is not in the validator list anymore
  string rollup = 1;

  // The foreign chain tx hash that the node has removed itsself from the contract
  Evidence evidence = 2;

  // Signature from other nodes that verified the evidence
  // The current validator should not be included
  repeated Multisig signatures = 3;

  google.protobuf.Any data = 50;
}
```

### CreateRollupBlockTx

```javascript
// Most fields are the same as RollupBlockState
message CreateRollupBlockTx {
  string hash = 1;
  uint64 height = 2;
  string merkle_root = 3;
  string previous_hash = 4;

  string txs_hash = 5;

  repeated string txs = 6;

  string proposer = 7;

  repeated Multisig signatures = 8;

  // Deprecated
  // string checkpoint = 9; // must be valid iso date string

  // the rollup chainId
  string rollup = 10;

  // Added since v1.13.61
  string min_reward = 11;

  google.protobuf.Any data = 50;
}
```

### ClaimBlockRewardTx

```javascript
message ClaimBlockRewardTx {
  // rollup and block hash
  string rollup = 1;
  uint64 block_height = 2;
  string block_hash = 3;

  // The foreign chain tx evidence of block publishing
  Evidence evidence = 4;

  // Who published the block to the contract, can get 70% of the block fee
  // All validators will get 30% of the block fee
  string publisher = 5;

  google.protobuf.Any data = 50;
}
```

### PauseRollupTx

```javascript
message PauseRollupTx {
  string rollup = 1;
  google.protobuf.Any data = 10;
}
```

### ResumeRollupTx

```javascript
message ResumeRollupTx {
  string rollup = 1;
  google.protobuf.Any data = 10;
}
```

### MigrateRollupContractTx

```javascript
message MigrateRollupContractTx {
  string rollup = 1;
  string to = 2;
  google.protobuf.Any data = 10;
}

```

### MigrateRollupTokenTx

```javascript
message MigrateRollupTokenTx {
  string rollup = 1;
  string from = 2;       // from which contract
  string to = 3;         // to which contract, must points to latest contract address
  TokenInput token = 4;           // token address and amount to migrate
  google.protobuf.Any data = 10;
}
```

---

## Understanding DIDs

URL: https://www.arcblock.io/en/docs/blockchain/understanding-dids/

## What is DID?

DID is a unique identity address calculated from a set of credentials, and we extend DID as unique identifiers for everything in ArcBlock Ecosystem, such as:

- [Account](/en/docs/blockchain/understanding-wallets-and-accounts/)
- [Token](/en/docs/blockchain/understanding-tokens/)
- [NFT](/en/docs/blockchain/understanding-nfts/)
- [NFT Factory](/en/docs/blockchain/understanding-nfts/)
- Stake
- Delegation
- [Blocklet](/en/docs/blocklet-developer/blockletyml/#did)
- Server

## How to Create DID?

> [!TIP]
> Please note that sometimes the terms DID and address is used interchangeably in this documentation.

### DID Notation

A typical DID provided by ArcBlock looks like this:

```javascript
did:abt:z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA
  DID            DID String
schema
```

### DID Type

Bitcoin and Ethereum use `secp256k1` for the public key encryption of their wallets, to generate the wallet address, they used fixed hash algorithms. In ArcBlock, we make this process flexible and extensible - developers and users can choose their favorite algorithm combination. For example, by default, we use `ED25519` for public key encryption, `SHA3` for public key hashing, and `base58` for address encoding.

To make sure the address contains the info about the algorithm combination, we pack this algorithm combination as `DID Type` and include them in the DID generating process.

`DID type` is the first 2 bytes of the DID string's binary format. It contains three sections:

1. The first six bits are the `RoleType` of DID, e.g., `account` = 0
2. The following 5 bits denote the `KeyType`, the algorithm to convert the secret key to the public key, e.g., `ED25519` = 0
3. The latter 5 bits represent the `HashType` function to calculate the hash of the public key, e.g., `SHA3` = 1

So DID type bytes `0x0C01` can be interpreted as follows:

```javascript
+-------------+-----------+------------+
| 000011      | 00000     | 00001      |
+-------------+-----------+------------+
| application | ed25519   | sha3       |
+-------------+-----------+------------+
```

See [Appendix](/en/docs/blockchain/understanding-dids/#appendix) for the full list of `RoleType`, `KeyType` and `HashType`.

### DID Generate Algorithm

It's calculated with the following algorithm:

- Step 1: Choose the <em>RoleType</em>, <em>KeyType</em> and <em>Hash</em> from above, let's use `application`, `ed25519` and `sha3` in this example.
- Step 2: Choose a secret key randomly, e.g. ```javascript D67C071B6F51D2B61180B9B1AA9BE0DD0704619F0E30453AB4A592B036EDE644E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7 ```
- Step 3: Generate the public key of this secret key by using the <em>KeyType</em>. So we can get public key ```javascript E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7 ```
- Step 4: Get the <em>Hash</em> of the public key ```javascript EC8E681514753FE5955D3E8B57DAEC9D123E3DB146BDDFC3787163F77F057C27 ```
- Step 5: Take the first 20 bytes of the public key hash ```javascript EC8E681514753FE5955D3E8B57DAEC9D123E3DB1 ```
- Step 6: Add the DID type bytes `0x0C01` in front of the hash of Step 4 ```javascript 0C01EC8E681514753FE5955D3E8B57DAEC9D123E3DB1 ```
- Step 7: Get the hash of the extended hash in Step 6 ```javascript 42CD815145538F8003586C880AF94418341F9C4B8FA0394876553F8A952C7D03 ```
- Step 8: Take the first 4 bytes in step 7 ```javascript 42CD8151 ```
- Step 9: Append the 4 bytes in step 8 to the extended hash in step 6. This is the binary DID string ```javascript 0C01EC8E681514753FE5955D3E8B57DAEC9D123E3DB142CD8151 ```
- Step 10: Encode the binary value by using the Bitcoin Base58 method. Note, we are using IPFS's [multibase](https://github.com/multiformats/multibase) to encode as `base58_btc` type, it will add a `z` in the beginning of the base58 encoded string ```javascript zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr ```
- Step 11: Assemble the parts and get the full DID ```javascript did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr ```

For a detailed explanation of the algorithm, please check out [ArcBlock DID Explained](/en/articles/did-101/)

## Appendix

### RoleType

```javascript
const RoleType = {
  ROLE_ACCOUNT: 0,
  ROLE_NODE: 1,
  ROLE_DEVICE: 2,
  ROLE_APPLICATION: 3,
  ROLE_SMART_CONTRACT: 4,
  ROLE_BOT: 5,
  ROLE_ASSET: 6,
  ROLE_STAKE: 7,
  ROLE_VALIDATOR: 8,
  ROLE_GROUP: 9,
  ROLE_TX: 10,
  ROLE_TETHER: 11,
  ROLE_SWAP: 12,
  ROLE_DELEGATION: 13,
  ROLE_VC: 14,
  ROLE_BLOCKLET: 15,
  ROLE_STORE: 16,
  ROLE_TOKEN: 17,
  ROLE_FACTORY: 18,
  ROLE_ROLLUP: 19,
  ROLE_STORAGE: 20,
  ROLE_ANY: 63,
};
```

### KeyType

```javascript
const KeyType = {
  ED25519: 0,
  SECP256K1: 1,
  ETHEREUM: 2,
};
```

### HashType

```javascript
const HashType = {
  KECCAK: 0,
  SHA3: 1,
  KECCAK_384: 2,
  SHA3_384: 3,
  KECCAK_512: 4,
  SHA3_512: 5,
  SHA2: 6,
};
```

## References

- [W3C DID Core](https://www.w3.org/TR/did-core)

---

## Understanding NFTs

URL: https://www.arcblock.io/en/docs/blockchain/understanding-nfts/

> [!TIP]
> We use the term NFT and Asset interchangeably throughout this documentation because they mean the same thing on the ArcBlock chain.

## What is NFT?

NFTs (Non-fungible tokens) are cryptographic assets on a blockchain with unique identifiers and metadata that distinguish them from each other.

Unlike [tokens](/en/docs/blockchain/understanding-tokens/), they cannot be traded or exchanged at equivalency. This differs from fungible tokens like cryptocurrencies, which are identical to each other and, therefore, can serve as a medium for commercial transactions.

- NFTs can represent real-world items like artwork and real estate. "Tokenizing" these real-world tangible assets makes buying, selling, and trading them more efficient while reducing the probability of fraud.
- NFTs can also function to represent individuals' identities, property rights, passports, and more.

On the ArcBlock chain, <strong>the essence of an NFT is data</strong>, any data that has actual value and needs to be recorded on the chain can be put on the chain in the form of NFTs. Each NFT is identified by a universal unique address, we call it [DID](/en/docs/blockchain/understanding-dids/).

## NFT Use Cases?

The usage scenarios for NFTs are very extensive, when you need to make any records of the data, you can create NFTs and update them through transactions. There are many usage scenarios for NFTs, including but not limited to:

- <strong>Create tickets</strong>: Alice needs to create tickets for her event so that participants can buy tickets to participate in the event. Alice can create ticket NFTs and store them on the chain.
- <strong>Issue certificates</strong>: After the user of the online learning website finishes a course, he can create a course certificate for him, and then ask him to hold a certificate of a course when studying other courses.
- <strong>Membership certificate</strong>: Paid subscription platform users pay for a passport, and check the pass that requires payment to view content.

## NFT Structure

A typical NFT stored on ArcBlock chain has the following structure:

| field  | type  | required  | default  | memo  | updatable  |
|---|---|---|---|---|---|
| address  | string  | Yes  | -  | NFT identifier  | No  |
| owner  | string  | Yes  | -  | NFT owner identifier  | Yes  |
| issuer  | string  | Yes  | -  | NFT issuer identifier  | No  |
| parent  | string  | Yes  | -  | NFT Factory identifier  | No  |
| moniker  | string  | Yes  | -  | Human-readable name  | No  |
| readonly  | boolean  | Yes  | false  | is the NFT immutable  | No  |
| transferrable  | boolean  | Yes  | false  | can NFT be transferred after creation  | No  |
| consumedTime  | Date  | No  | -  | The consume date for the NFT  | Yes  |
| data  | [Any](/en/docs/blockchain/transactions/#any-type) | Yes  | false  | the data that makes the NFT unique  | Yes  |
| display  | object  | No  | null  | the NFT display  | No  |
| endpoint  | object  | No  | null  | the NFT endpoint  | No  |
| tags  | string[]  | No  | []  | List of tags for later filtering  | No  |

## NFT Extendability

NFTs on ArcBlock chain can either be mutable or immutable depending on the use case. To make NFTs more flexible in real-world applications we have another 2 layers that are totally customizable by developers:

- NFT Display: used to define how the NFT will look like
- NFT Endpoint: used to define dynamic attributes and actions of the NFT

Here is an example of how NFT Display and NFT Endpoint are parsed and displayed in [DID Wallet](https://didwallet.io/):

![Image](https://media.arcblock.io/lib/c8/c8a12a9f8a414dcdc49d0f4d5779b0ab.w1600.webp)

### NFT Display

An NFT can have:

- an immutable display, such as NFT from [Blocklet Store](https://main.abtnetwork.io/explorer/assets/zjdwHAZv23SGqyvi1CMEyaWcsFs6RMLBrHnk)
- a mutable display, such as NFT from [Blocklet Launcher](https://main.abtnetwork.io/explorer/assets/zjdo88xSyb3NRMGWLPEE8qxbAbjaCMdy7ikZ)
- no display at all

NFT display is defined with the following structure:

```javascript
type NFTDisplay = {
  // Can be svg|url|uri
  type: string;

  // Varies according to the type
  // For svg type, content should be the svg itself
  // For url type, content should be the url to fetch the display content, this URL will be requested with the NFT or the NFT address for the display
  // For uri type, content should be the uri to resolve the display content, such as base64 encoded image
  content: string;
};
```

Developers can define NFT display in one of following ways:

- Define `display` field in the `CreateAssetTx`
- Define `output.display` field in `CreateFactoryTx`

### NFT Endpoint

NFT endpoint enables developers to extend NFT capabilities off the chain, such as:

- Display NFT status that may change over time
- Display NFT action that may change over time

NFT endpoint is defined in the following structure:

```javascript
type NFTEndpoint = {
  // the url that serve the endpoint, the url is requested with assetId and locale when displaying the NFT
  id: string;

  // can be public|private, private endpoints are requested with DID Connect
  scope: string;
};
```

A live NFT endpoint example form [Blocklet Launcher](https://launcher.arcblock.io/api/nft/status?locale=en&assetId=zjdo88xSyb3NRMGWLPEE8qxbAbjaCMdy7ikZ).

TODO: how to create the response by NFT endpoint should be added

## NFT Factory

Since some NFTs have standard formats, such as tickets sold in cinemas and parks, developers can use NFT factory to create vending machines on the blockchain: users send transactions to the NFT factory to pay and acquire NFTs that are defined by the NFT factory.

Just like a real-world factory that consumes some materials to produce standard products, the following diagram shows how NFT factory works:

![Image](https://media.arcblock.io/lib/aa/aa551730de064ed9637d248b567340ab.w1600.webp)

### NFT Factory Transactions

There are a few transactions related to NFT Factory:

- `CreateFactoryTx`: used by developers to create the factory
- `AcquireAssetV3Tx`: used by users to acquire NFT with payment
- `MintAssetTx`: used by factory owners to mint NFT without payment

### NFT Factory Inputs

Users usually need to pay some tokens or consume some NFT to acquire a new NFT, the cost user paid on acquiring NFTs are called factory input, following is a factory input from [Blocklet Launcher](https://main.abtnetwork.io/explorer/txs/F815571D4091AF59CDEDB14092E72C8015A65DC89BC985A9041B9175D9FEE7AE):

```javascript
{
  "tokens": [
    {
      "address": "z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD",
      "value": "299000000000000000000"
    }
  ],
  "assets": [],
  "variables": [
    {
      "name": "plan",
      "value": "",
      "description": "",
      "required": true
    },
    {
      "name": "tag",
      "value": "",
      "description": "",
      "required": true
    }
  ]
}
```

Factory inputs fall into 3 categories:

- `tokens`: cryptocurrencies required to acquire NFT, a factory can require up to 8 tokens on acquiring, and each token input must specify its token address and price.
- `assets`: NFT to be consumed to acquire NFT, can be NFT address or Factory address, all assets are marked consumed upon successful acquiring
- `variables`: extra info required to acquire NFT, usually collected with a form before the acquiring

### NFT Factory Output

Since all NFTs from a factory share a predefined format, developers define the format as output, a typical factory output is a [mustache](https://mustache.github.io/) template that produces the same structure as `CreateAssetTx` upon rendering(acquiring).

Following is the factory output from [Blocklet Launcher](https://main.abtnetwork.io/explorer/txs/F815571D4091AF59CDEDB14092E72C8015A65DC89BC985A9041B9175D9FEE7AE)

```javascript
{
  "moniker": "BlockletServerOwnershipNFT",
  "data": {
    "type": "json",
    "value": {
      "purchased": {
        "plan": "{{input.plan}}",
        "sku": {
          "name": "{{data.name}}",
          "type": "{{data.type}}",
          "period": "{{data.period}}"
        }
      }
    }
  },
  "readonly": false,
  "transferrable": true,
  "ttl": 0,
  "parent": "{{ctx.factory}}",
  "address": "",
  "issuer": "{{ctx.issuer.id}}",
  "endpoint": {
    "id": "http://1322c65c-znkqyck3vfnye4cyk3yrwfnydgvvkshr9cur.did.abtnet.io/api/nft/status",
    "scope": "public"
  },
  "display": {
    "type": "url",
    "content": "http://1322c65c-znkqyck3vfnye4cyk3yrwfnydgvvkshr9cur.did.abtnet.io/api/nft/display"
  },
  "tags": ["BlockletServerOwnershipNFT", "{{input.tag}}"]
}
```

Data that can be consumed in NFT factory output includes:

- `input.*`: factory input variables, must be set when acquiring/minting
- `data.*`: [factory data object](/en/docs/blockchain/understanding-nfts/#nft-factory-data), immutable since factory creation
- `ctx.*` the context when acquiring/minting from the factory
-
  - `ctx.factory`: the factory address
  - `ctx.id`: the current mint sequence, set to `factory.numMinted + 1` on each mint
  - `ctx.issuer.id`: address for NFT issuer
  - `ctx.issuer.pk`: public key for NFT issuer
  - `ctx.issuer.name`: name for NFT issuer(account moniker)
  - `ctx.owner`: address of NFT owner

### NFT Factory Hooks

Developers can use hooks to add custom logic when a new NFT is acquired from a factory, for example:

- [Blocklet Store](https://store.blocklet.dev/) uses factory hooks to split revenue between the blocklet developer and store when users purchased a paid blocklet.
- NFT minting tool use factory hooks to split revenue between the developer and NFT provider.

Factory hooks are set and immutable when sending `CreateFactoryTx`, [hooks from Blocklet Store](https://main.abtnetwork.io/explorer/txs/8C44A0551752A33B9F9488DA20877F7E15B0ECD9774A405AB046C362A4BD7E48):

```javascript
[
  {
    "name": "mint",
    "type": "contract",
    "hook": "transferToken('z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD','z1gShFYDsiMfGtaerBTh2ydu75768xMYPQU','4662000000000000000');\ntransferToken('z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD','zNKXtdqz6Jbw5mKpojK2nP5gRNiEGJY3mNFF','1998000000000000000')"
  }
]
```

This mint hook uses the <strong>experimental contract</strong> of the chain:

```javascript
transferToken(
  "z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD", // token address
  "z1gShFYDsiMfGtaerBTh2ydu75768xMYPQU", // receiver address
  "4662000000000000000" // token amount in big number
);
```

Token transfers in factory hooks must the following restrictions:

- Revenue split must not exceed the factory input token amount
- Token receivers must exist in the ledger
- Token address must exist in the ledger

### NFT Factory Data

The NFT factory can have data attached to it on creation, the data can be used in NFT output templates upon acquiring/minting.

- NFT factory data is copied from the `CreateFactoryTx`
- NFT factory data should be [Any Type](/en/docs/blockchain/understanding-transactions/#any-type)

## NFT Security

### Privacy considerations

Once the NFT is stored on the chain, anyone with the NFT address can view all the information stored in the NFT state. In theory, any data can be stored in the NFT. As for what kind of data is stored, the developer can choose according to the actual scenario:

- If NFT data is weakly typed, no privacy protection is required: for example, the certificate data can be stored in plain JSON, so that is fully publicly verifiable.
- If NFT data is strongly typed, some privacy protection requirements are required: NFT data can be saved in the serialized format of [Any Type](/en/docs/blockchain/understanding-transactions/#any-type), no one can directly decode the NFT data without the NFT data proto-buffer, but technically it is possible to view some of the fields
- If NFT data is sensitive: such as contracts, pay slips, etc., to protect the security of NFT data, the data should only contain the hash of the original data, the original data should go into an off-chain database

### Prevent counterfeiting

ArcBlock chain has built-in NFT anti-counterfeiting logic, that is, 2 identical NFTs are not allowed. However, during the app development process, the developer may mistake the fake NFT for the correct NFT when the verification logic is not strict enough, one solution to this is attaching the issuer's signature on NFT creation so that it can be easily verified.

## Move NFT Across ArcBridge

> TODO: more about ArcBridge should be added here

---

## Understanding Tokens

URL: https://www.arcblock.io/en/docs/blockchain/understanding-tokens/

## What is token?

A typical blockchain supports at least 1 cryptocurrency natively, cryptocurrencies on the ArcBlock chain are called <strong>tokens</strong>, a token is a digital or virtual currency that is secured by cryptography, which makes it nearly impossible to counterfeit or double-spend.

- The native token on [main chain](https://main.abtnetwork.io/) is [ABT](https://main.abtnetwork.io/explorer/tokens/z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD/txs)
- The native token on [beta chain](https://beta.abtnetwork.io/) is [TBA](https://beta.abtnetwork.io/explorer/tokens/z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG/txs)

Developers can create as many tokens as needed on the ArcBlock chain by sending `CreateTokenTx`.

Users can do more with tokens on ArcBlock chain than other blockchains without any smart contract, such as:

- Transfer tokens to his/her friend
- Pay with tokens to purchase digital properties in NFT format
- Exchange between tokens at some fixed rate

## What is foreign token?

Foreign token is used to correlate a token on ArcBlock chain with a token on EVM compatible chain. The token on both chains has the same symbol, decimal, and supply.

For example: ABT on Arcblock [main chain](https://main.abtnetwork.io/explorer/tokens/z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD/txs) and Ethereum [mainnet](https://etherscan.io/address/0xb98d4c97425d9908e66e53a6fdf673acca0be986) are the same

The `foreignToken` field is defined when sending `CreateTokenTx` and can not be updated after creation:

```javascript
type ForeignToken = {
  type: string;
  contractAddress: string;
  chainType: string;
  chainName: string;
  chainId: number;
};
```

A token with a valid foreign token should set up an ArcBridge to allow users to move their tokens between ArcBlock and Ethereum chain.

## Move Token Across ArcBridge

> TODO: more about ArcBridge should be added here

---

## Understanding Transactions

URL: https://www.arcblock.io/en/docs/blockchain/understanding-transactions/

A transaction must be encoded and signed by the sender's [wallet](/en/docs/blockchain/understanding-wallets-and-accounts/), once sent to the chain, it's decoded and verified, and then executed and appended to the ledger.

- A transaction is identified by `hash` similar to other chains such as Bitcoin and Ethereum.
- A transaction is encoded as binary before being signed and sent to the chain.
- A transaction is decoded and formatted before being displayed on the chain explorer.

## Transaction Structure

To make transactions flexible and extensible, we use a mail-like structure to define a transaction:

- `envelope` = `outer transaction`: contains required fields for all transactions, such as `sender`, `signature`
- `letter` = `inner transaction`: the actual transaction content, such as `DeclareTx`, `DelegateTx`

You can inspect the "Raw Transaction" on [transaction detail](https://beta.abtnetwork.io/explorer/txs/75A57414CE65375A1C4A4BA52F5D1305CD02567F8949718946394AF525DF78CA) from the explorer to get a better understanding of the structure.

### Outer Transaction

The outer transaction structure is defined as follows:

```javascript
type Transaction = {
  from: string; // the transaction sender address
  pk: string; // the transaction sender public key
  nonce: number;
  chainId: string; // must match with the chain
  delegator: string;
  signature: string; // the transaction sender's signature
  signatures: Array<Multisig>; // signatures from other parties, default to empty
  itx: Any;
};
```

### Inner Transaction (itx)

The inner transaction structure varies across different transaction types. Here are some examples:

```javascript
type DeclareTx = {
  moniker: string;
  issuer: string;
  data?: Any;
};

type TransferV2Tx = {
  to: string;
  assets: Array<string>;
  tokens: Array<{
    address: string;
    value: string;
  }>;
  data?: Any;
};
```

> [!NOTE]
> The inner transaction is decoded and notated as itxJson in chain explorer for better readability.

### Any Type

<strong>Any</strong> type is widely used in transactions to encode data that's attached to the same field but has different types and shapes:

```javascript
type Any = {
  type: string;
  value: any;
};
```

Let's look at how `Any` type is used with an example:

```javascript
const tx = {
  from: "zNKnjMDau9aK6kYkxX7fhFkbozQQhvTzGqnX",
  pk: "0848uy6x11gle2SR3hummTMyZpLRNv_ai4RaquxIDyg",
  chainId: "beta",
  nonce: "1663680171202",
  signature: "Sd4ALBExbm5ssWo4S2RITqJm48BPcb8s1c4UmO-l6o5x5WW619ZEK",
  signatures: [],
  delegator: "",
  itx: {
    type: "DeclareTx",
    value: {
      moniker: "blocklet-registry-service",
      issuer: "",
      data: {
        type: "json",
        value: {
          role: "ROLE_APPLICATION",
          pk: "ED25519",
          hash: "SHA3",
          address: "BASE58",
        },
      },
    },
  },
};
```

<strong>Any</strong> is used in 2 places in above transaction:

- `itx` field on the outer transaction to attach the inner transaction, which can be any of the [supported types](/en/docs/blockchain/understanding-transactions/#transaction-types).
- `data` filed on the inner transaction to attach optional data that can be any type, such as `json` and `vc`.

As you can see from the example <strong>Any</strong> types can be nested.

### Transaction Types

The transaction filter from chain explorer lists all supported transaction types supported. Each transaction type defines a structure that can be used in `itx`.

- Account
-
  - DeclareTx
  - AccountMigrateTx
  - DelegateTx
  - RevokeDelegateTx
- NFT
-
  - CreateAssetTx
  - UpdateAssetTx
  - MintAssetTx
  - AcquireAssetV2Tx
  - AcquireAssetV3Tx
  - CreateFactoryTx
- Token
-
  - CreateTokenTx
  - DepositTokenV2Tx
  - WithdrawTokenV2Tx
- Trading
-
  - ExchangeV2Tx: with multiple input support
  - TransferV2Tx: with multiple input support
  - TransferV3Tx: with multiple input and output support
- Staking
-
  - StakeTx
  - RevokeStakeTx
  - ClaimStakeTx
- Rollup
-
  - CreateRollupTx
  - UpdateRollupTx
  - JoinRollupTx
  - PauseRollupTx
  - ResumeRollupTx
  - MigrateRollupContractTx
  - MigrateRollupTokenTx
  - JoinRollupTx
  - LeaveRollupTx
  - CreateRollupBlockTx
  - ClaimBlockRewardTx

### Transaction Data

Each transaction can have a `data` field that is `Any` type, see next section.

## Transaction Size Limit

To protect the chain from abuse, there are hard limits for each transaction size, transactions that exceed the size limit will fail at the verification phase.

The current size limit (measured by byteLength of the encoded transaction buffer) for each transaction type is:

- AccountMigrate: 348
- CreateAsset: 65881
- CreateFactory: 65881
- Declare: 664
- ExchangeV2: 1691
- Transfer: 664
- TransferV2: 664
- TransferV3: 4096
- UpdateAsset: 65881
- AcquireAssetV2: 4096
- AcquireAssetV3: 4096
- MintAsset: 4096
- CreateToken: 664
- DepositTokenV2: 1691
- WithdrawTokenV2: 1691
- Stake: 4096
- RevokeStake: 664
- ClaimStake: 664
- CreateRollup: 1691
- UpdateRollup: 1691
- PauseRollup: 1691
- ResumeRollup: 1691
- JoinRollup: 1691
- LeaveRollup: 1691
- MigrateRollupContract: 1691
- MigrateRollupToken: 1691
- CreateRollupBlock: 4096
- ClaimBlockReward: 1691

## Transaction Fees

The <strong>Transaction Fee</strong> is another mechanism for protecting the chain from attacks. There are 3 types of fees charged when a transaction is successfully executed:

- Service fee: charged when moving tokens with DepositTokenV2Tx and WithdrawTokenV2Tx across ArcBridge, fee rate may vary between bridges.
- Protocol fee: charged when sending `CreateAssetTx`, `CreateFactoryTx`, `CreateTokenTx` and `CreateRollupTx`.
- Gas fee: charged when sending all transaction types, neither the main nor beta chain enabled gas fee.

## Transaction Signature

### Sender signature

Each transaction carries a signature generated using the sender's secret key. The chain and recipient can verify the sender's signature using the sender's public key, which is published on the chain. This helps ensure that the transaction content received is exactly as it was when the sender initiated the transaction.

### Multi-party signature

In most chain implementations, only the transaction sender is required to sign the transaction. With the sender's signature, we would trust that the operation is authorized by the sender. Transactions like `Transfer` is a typical example that the sender would send some tokens / NFTs to the receiver (without the receiver's permission). In the real-world, vast use cases require authorization among all parties in the transaction.

ArcBlock chain has native support for multi-party-signed transactions. Transactions that support multi-party-signature includes:

- TransferV3Tx: if the transaction input is from multiple payers
- AcquireAssetV3Tx: if the transaction input is from multiple payers
- Rollup Related Tx: signatures are required from all rollup validators

---

## Understanding Verifiable Credentials

URL: https://www.arcblock.io/en/docs/blockchain/understanding-verifiable-credentials/

> Learn the basic concept, mental model, use cases and benefits of verified credentials, understand it's difference between NFTs

## What are Verifiable Credentials?

Verifiable Credentials are a digital, cryptographically secured version of both paper and digital credentials that people can present to organizations that need them for verification. Imagine digital and instantly verifiable versions of identity documents, academic achievements, licenses, and more.

The core mental model of verifiable credentials is illustrated and clearly explained in [W3C Verifiable Credential Overview](https://w3c.github.io/vc-data-model/#ecosystem-overview).

## Benefits of Verifiable Credentials

- <strong>Instantly verifiable</strong> anywhere at any time within seconds compared to days, weeks, or months with traditional verification processes
- <strong>Tamper-proof</strong> with cryptography, which enables people to store, protect, and share data securely
- <strong>No need to contact the issuer</strong> (e.g. a university or certifying body) to confirm the authenticity
- <strong>Creates immediate trust</strong> between parties
- <strong>User have full control and ownership of their data</strong>, enabled by decentralized identifiers (globally unique identifiers) and Public key cryptography.
- <strong>Provides user privacy</strong> because they can choose which parts of their identity they want to reveal such as showing their age without showing their full name. Or proving they are above a certain age without disclosing their date of birth.
- <strong>No personal data</strong> is stored on the blockchain
- <strong>Portable</strong> as holders can store Verifiable Credentials in their digital wallet and take them anywhere while still being verifiable.

## Use cases for Verifiable Credentials

Verifiable Credentials can be used in many cases:

- User passports to a system that requires authentication
- Membership proof of online/offline communities
- Academic achievement certificates of online training programs
- KYC certificates, such as email, mobile phone

A lot more use cases can be found from the [W3C Verifiable Credential Spec](https://w3c.github.io/vc-data-model/#use-cases-and-requirements).

## Relationship with NFTs

NFTs are always stored on the blockchain, but verifiable credentials do not need to, because a verifiable credential is cryptographically self-proven and tamp-proof. Sometimes an NFT can include a verifiable credential in its data.

![Image](https://media.arcblock.io/lib/29/29250e0935452107db4d4a6554b2a8a6.w1600.webp)

From the user's perspective, verifiable credentials and NFTs are both publicly verifiable, should have some visual presentation, and can be used to trigger some actions in applications in which the verifiable credential can be used.

To make things consistent, verifiable credentials share the same [display](/en/docs/blockchain/understanding-nfts/#nft-display) and [endpoint](/en/docs/blockchain/understanding-nfts/#nft-endpoint) mechanism as NFTs.

### Verifiable Credential Display

The display of a verifiable credential can be defined in `credentialSubject.display` field with the same data structure as [NFT Display](/en/docs/blockchain/understanding-nfts/#nft-display), and presented the same way as NFT in DID Wallet.

### Verifiable Credential Endpoint

The endpoint of a verifiable credential can be defined in `credentialStatus` field with the same data structure as [NFT Endpoint](/en/docs/blockchain/understanding-nfts/#nft-endpoint), and presented the same way as NFT in DID Wallet.

The endpoint should return the status and action information related to the verifiable credential.

## Working with Verifiable Credentials

- See [working with verifiable credentials](/en/docs/blockchain/work-with-verifiable-credentials/) for how to <strong>issue</strong> and <strong>verify</strong> verifiable credentials with code
- See [did-connect](https://www.didconnect.io/playground/react/?path=/story/connect--request-verifiable-credential) on how to <strong>request</strong> and <strong>verify</strong> verifiable credentials from DID Wallet users.

## References

- [W3C VC Data Model](https://w3c.github.io/vc-data-model)

---

## Understanding Wallets and Accounts

URL: https://www.arcblock.io/en/docs/blockchain/understanding-wallets-and-accounts/

## What is Wallet?

![Image](https://media.arcblock.io/lib/1b/1b9e1b4a780ab384830ba7e6ee1945c2.w1600.webp)

- A wallet usually has a secret key (SK), a public key (PK), and an address ([DID](/en/docs/blockchain/understanding-dids/)).
- A wallet can be used to sign a [transaction](/en/docs/blockchain/understanding-transactions/) or other formats of message.
- A wallet can be used to verify a signed message.

The wallet's secret and public keys are important, because:

- The secret key is used to calculate the public key
- The public key is used to calculate the address

It's important to keep the secret keys safe since knowledge of the secret key allows others to spoof signatures to send unauthorized transactions.

## What is Account?

- An account is a data entry that exists in the chain ledger, each account is identified by a unique address ([DID](/en/docs/blockchain/understanding-dids/)).
- An account can own many tokens.
- An account can own many NFTs.
- An account can be migrated to a new account.
- A user can have as many accounts as they would like, this is usually achieved with [DID Wallet](https://didwallet.io/).
- A user needs at least one account before they can send and receive transactions on the chain.

## Relationship between Wallet and Account

- Most accounts are backed by a wallet (secret key).
- Ownership of the wallet secret key means ownership of funds in the account, if you lose the secret key you lose the funds.

> [!TIP]
> Please note that sometimes the terms account and wallet are used interchangeably in this documentation.

---

## Upgrade from 1.18.x to 1.19.x

URL: https://www.arcblock.io/en/docs/blockchain/upgrading-from-18-to-19/

ArcBlock's blockchain, as of v1.19.x, includes native support for Passkeys, allowing them to have corresponding accounts on the blockchain and to sign and send transactions like other accounts.

Because adding native Passkey support has introduced breaking changes to some underlying library APIs, please consult the upgrade guide below if you need to use the latest version.

## Updating Project Dependencies

You can use any familiar tool to update the following project dependencies to their latest versions:

- @ocap/*
- @arcblock/*
- @blocklet/*

## Make Code Changes

### @ocap/wallet

`wallet.verify` is now an `async` method

```javascript
const { fromSecretKey } = require('@ocap/wallet');

const wallet = fromSecretKey(sk, type);
const message = 'data to sign';
const signature = wallet.sign(message);
expect(await wallet.verify(message, signature)).toEqual(true); // changed
```

Support for new DID types has been added.

```javascript
const { fromPublicKey } = require('@ocap/wallet');
const { fromBase64 } = require('@ocap/util');

const publicKey = fromBase64('pQECAyYgASFYIA3GyM4rSxM_HyV52QTRwGJOdkXurky3cwTLvb_gKSF-Ilggpd0fhMlPdxHBl45_eJxqywCRl-a4IDpeFa4pcfmrxuM');
const wallet = fromPublicKey(publicKey, 'passkey');
expect(wallet.address).toEqual('z3i165rPumFgyQZpZ1W3VLEYBPuV2xSCAjoqo');
```

### @arcblock/vc

The following methods are now `async`.

- Create
- verify
- Verify Presentation

```javascript
const { create, verify, verifyPresentation, createCredentialList, verifyCredentialList } = require('@arcblock/vc');

const issuer = fromRandom();
const owner = fromRandom();
let vc = null;

const subject = {
  id: owner.address,
  key: 'value',
  method: 'SHA3',
};

const issuerInfo = {
  wallet: issuer,
  name: 'DID.KYC.Email',
};

const vc = await create({
  type: 'EmailVerificationCredential',
  issuer: issuerInfo,
  subject,
  tag: 'abcd',
  endpoint: 'https://www.arcblock.io/api/vc/status',
});

expect(await verify({ vc, ownerDid: owner.address, trustedIssuers: issuer.address })).toEqual(true);
```

### @arcblock/jwt

jwt.verify` is now an `async` method

```javascript
const { sign, verify } = require('@arcblock/jwt');

const token = sign(appId, sk, { key: 'value' });
const [, bodyB64] = token.split('.');
const body = JSON.parse(fromBase64(bodyB64).toString());
const result = await verify(token, pk); // changed
```

### @ocap/asset

The `preMintFromFactory` method was changed to be `async`.

### @blocklet/sdk

`wallet.verify` is now an `async` method

```javascript
const getWallet = require('@blocklet/sdk/lib/wallet');

const wallet = getWallet();
const message = 'data to sign';
const signature = wallet.sign(message);
expect(await wallet.verify(message, signature)).toEqual(true); // changed
```

---

## Welcome

URL: https://www.arcblock.io/en/docs/blockchain/welcome-to-arcblock-blockchain/

ArcBlock blockchain is an open, secure, and extensible billing layer for the ArcBlock ecosystem, the blockchain has native [DID](/en/docs/blockchain/understanding-dids/) support, and it's widely used to:

- The public verifiable ledger for [tokens](/en/docs/blockchain/understanding-tokens/) and [NFTs](/en/docs/blockchain/understanding-nfts/) created on the blockchain
- The public verifiable registry for [verifiable credential](/en/docs/blockchain/understanding-verifiable-credentials/) issuers and holders
- The billing infrastructure of the [blocklet platform](https://developer.blocklet.io/) -- a decentralized web3 application platform

## How to get help?

Having trouble? We’d like to help!

- Try the [FAQ](/en/docs/blockchain/blockchain-frequently-asked-questions/) – it’s got answers to many common questions.
- Looking for specific information? Try the search box with your keywords.
- Found something missing? or found a typo? Click "Submit Feedback" on each page footer to create issues on GitHub.

---

## Work with Verifiable Credentials

URL: https://www.arcblock.io/en/docs/blockchain/work-with-verifiable-credentials/

[@arcblock/vc](https://www.npmjs.com/package/@arcblock/vc) includes several utility functions to issue and verify [verifiable credentials](/en/docs/blockchain/understanding-verifiable-credentials/) and [their presentations](https://w3c.github.io/vc-data-model/#presentations).

## Add Library to project

Add `@arcblock/vc` to your project before creating or verifying any verifiable credential.

```javascript
npm install @arcblock/vc -S
# yarn add @arcblock/vc
```

## Issue Verifiable Credential

Create a verifiable credential, the result can be sent and stored in DID Wallet.

Usage: `create(params)`, the param should be like:

| Param  | Type  | Description  |
|---|---|---|
| params.type  | `string` | The type of credential, can be an array  |
| params.subject  | `object` | The content of credential  |
| params.issuer  | `object` | The issuer name and wallet  |
| params.issuanceDate  | `Date` | Default to now  |
| params.expirationDate  | `Date` | Default to null, never expire  |
| params.endpoint  | `String` | Status endpoint url  |
| params.endpointScope  | `String` | Endpoint scope, either be public or private  |

### Basic Credential

Example:

```javascript
const { create } = require("@arcblock/vc");
const { fromRandom, fromSecretKey, fromAddress } = require("@ocap/wallet");

// the verifiable credential issuer,
// in real word applications, you should replace fromRandom with fromSecretKey
// const issuer = fromSecretKey(process.env.VC_ISSUER_SK);
const issuer = fromRandom();

// the verifiable credential holder
// in real word applications, you should replace fromRandom with fromAddress
// const holder = fromAddress(process.env.ENV_HOLDER);
const holder = fromRandom();

const vc = create({
  type: "CourseCertificate",
  issuer: {
    name: "Online Course Platform",
    wallet: issuer,
  },
  subject: {
    // the only required field in subject, the id of the holder
    id: holder.address,
    // other fields can be customized
    completed: {
      course: "Developer Training Program",
    },
  },
});

console.log(vc);
```

Simple Verifiable Credential

### Add Credential Display

```javascript
const vc = create({
  type: "CourseCertificate",
  issuer: {
    name: "Online Course Platform",
    wallet: issuer,
  },
  subject: {
    id: holder.address,
    completed: {
      course: "Developer Training Program",
    },
    display: {
      content: "https://www.example.com/api/vc/display",
      type: "url",
    },
  },
});

console.log(vc);
```

Verifiable Credential With Display

### Add Credential Endpoint

```javascript
const vc = create({
  type: "CourseCertificate",
  issuer: {
    name: "Online Course Platform",
    wallet: issuer,
  },
  subject: {
    id: holder.address,
    completed: {
      course: "Developer Training Program",
    },
  },
  endpoint: "https://www.example.com/api/vc/status",
});

console.log(vc);
```

Verifiable Credential With Endpoint

## Verify Verifiable Credential

Verify that the verifiable credential is valid:

- The credential is signed by a whitelist of issuers
- The credential is owned by the holder
- The credential has valid signature by the issuer
- The credential is not expired

Usage: `verify(vc, ownerDid, trustedIssuers)`

| Param  | Type  | Description  |
|---|---|---|
| vc  | `object` | the verifiable credential object  |
| ownerDid  | `string` | the holder/owner did  |
| trustedIssuers  | `Array` | the list of issuer did  |

Example:

```javascript
const { verify } = require("@arcblock/vc");
const { fromSecretKey, fromAddress } = require("@ocap/wallet");

// the verifiable credential issuer,
const issuer = fromSecretKey(process.env.VC_ISSUER_SK);

// the verifiable credential holder
const holder = fromAddress(process.env.ENV_HOLDER);

// verify the credential just created or received from user
const isValid = verify({
  vc,
  ownerDid: holder.address,
  trustedIssuers: issuer.address,
});
```

## Verify Credential Presentation

When your application [requested and received](https://www.didconnect.io/playground/react/?path=/story/connect--request-verifiable-credential) a verifiable credential from the user, you must verify it before trust and use it.

- The verifiable credential presentation is a special credential signed by the credential holder who claims to own the credential.
- Usually a random challenge is generated and sent to user when requesting the presentation

The basic verification process:

- Ensure the presentation is signed by the verifiable credential holder
- Ensure the presentation contains the challenge
- Ensure the verifiable credential has a valid signature by the issuer
- Ensure the verifiable credential is not expired

Usage: `verifyPresentation(presentation, trustedIssuers, challenge)`

| Param  | Type  | Description  |
|---|---|---|
| presentation  | `object` | the presentation object  |
| trustedIssuers  | `Array` | list of issuer did  |
| challenge  | `string` | Random byte you want  |

Example:

```javascript
const presentation = {
  verifiableCredential: [
    '{"@context":"https://schema.arcblock.io/v0.1/context.jsonld","credentialSubject":{"emailDigest":"rDh76MCmM1tEPS8Qd1xGThFJfskGP2PSO8aNqv58IhQ","id":"z1QUxXyLNRWv18ubUdcuu7iPTQdWzRy294C","method":"SHA3"},"id":"z2iUJs3vdJnE1CkaYDPAm1EEWVbNPpcEm6QhL","issuanceDate":"2020-03-30T09:56:31.175Z","issuer":{"id":"zNKrLtPXN5ur9qMkwKWMYNzGi4D6XjWqTEjQ","name":"ArcBlock.KYC.Email","pk":"zDLTrgAHr33NyKx9eD9PFUqySHjGnXpHL7upNvCySx1s4"},"proof":{"created":"2020-03-30T09:56:31.180Z","jws":"EtT4SMpmPK5AhGBstJNnymJ9lwQVC2cI-1N5O3o3iGT8gVB0lfg9oGlCGpwsuK1Zn1lLiNEYBD7eKFjwcA0rCw","proofPurpose":"assertionMethod","type":"Ed25519Signature"},"type":"EmailVerificationCredential"}',
  ],
  type: "Ed25519Signature",
  proof: {
    type: "Ed25519Signature",
    proofPurpose: "assertionMethod",
    pk: "zJ5bH7Jy27jSDf3AE3ntoRwNBhPRX6RXaSwTUh272jwK5",
    jws: "ua-2kBFcn8rwNcd1BkckETnjQTW8nA5EcJ8PcXWirqB51SV9RaHvUChyFFUz_DLL_T-xlwcaQPaW0_q9Hkx3BQ",
    created: "2020-03-31T11:48:02Z",
  },
  challenge: "257A2EC62ED802304F65624C73A53CAA",
  "@context": ["https://schema.arcblock.io/v0.1/context.jsonld"],
};
const result = verifyPresentation({
  presentation,
  trustedIssuers: ["zNKrLtPXN5ur9qMkwKWMYNzGi4D6XjWqTEjQ"],
  challenge: "257A2EC62ED802304F65624C73A53CAA",
});
console.log(result);
```

---

## Working with DIDs

URL: https://www.arcblock.io/en/docs/blockchain/working-with-dids/

Utility functions to create/inspect did, and do did-based auth, an implementation of abt-did-protocol

- [fromSecretKey(sk, type)](/en/docs/blockchain/working-with-dids/#fromsecretkey(sk%2C-type)-%E2%87%92-string) ⇒ `string`
- [fromPublicKey(pk, type)](/en/docs/blockchain/working-with-dids/#frompublickey(pk%2C-type)-%E2%87%92-string) ⇒ `string`
- [fromHash(hash, role)](/en/docs/blockchain/working-with-dids/#fromhash(hash%2C-role)-%E2%87%92-string) ⇒ `string`
- [isFromPublicKey(did, pk)](/en/docs/blockchain/working-with-dids/#isfrompublickey(did%2C-pk)-%E2%87%92-boolean) ⇒ `boolean`
- [isValid(did)](/en/docs/blockchain/working-with-dids/#isvalid(did)-%E2%87%92-boolean) ⇒ `boolean`

## fromSecretKey(sk, type) ⇒ `string`

Gen DID from private key and type config

Spec: [https://github.com/ArcBlock/ABT-DID-Protocol#create-did](https://github.com/ArcBlock/ABT-DID-Protocol#create-did)

<strong>Kind</strong>: static method
<strong>Returns</strong>: `string` - DID string
<strong>Access</strong>: public

| Param  | Type  | Description  |
|---|---|---|
| sk  | `string` | hex encoded secret key string  |
| type  | `object` | wallet type  |

## fromPublicKey(pk, type) ⇒ `string`

Gen DID from public key and type config

<strong>Kind</strong>: static method
<strong>Returns</strong>: `string` - DID string
<strong>Access</strong>: public

| Param  | Type  | Description  |
|---|---|---|
| pk  | `string` | hex encoded public key  |
| type  | `object` | wallet type  |

## fromHash(hash, role) ⇒ `string`

Gen DID from an hex encoded hash and role type

<strong>Kind</strong>: static method
<strong>Returns</strong>: `string` - DID string
<strong>Access</strong>: public

| Param  | Type  | Description  |
|---|---|---|
| hash  | `string` | hex encoded hash  |
| role  | `enum` | role type  |

## isFromPublicKey(did, pk) ⇒ `boolean`

Check if an DID is generated from a publicKey

<strong>Kind</strong>: static method
<strong>Access</strong>: public

| Param  | Type  | Description  |
|---|---|---|
| did  | `string` | string of the did, usually base58btc format  |
| pk  | `string` | hex encoded publicKey string  |

## isValid(did) ⇒ `boolean`

Check if a DID string is valid

<strong>Kind</strong>: static method
<strong>Access</strong>: public

| Param  | Type  | Description  |
|---|---|---|
| did  | `string` | address string  |

---

## Blocklet CLI

URL: https://www.arcblock.io/en/docs/blocklet-cli/

---

## Advanced Topics

URL: https://www.arcblock.io/en/docs/blocklet-cli/advanced-topics-104903/

Welcome to the advanced topics section. While the core workflows cover day-to-day development and server management, this section dives into more specialized commands for fine-tuning and maintaining your blocklets. These utilities help you manage a blocklet's decentralized identity and perform specific cleanup tasks.

::::card-group
::link-card{title="DID Document Management" description="Learn how to manually update the DID document for a specific blocklet. This is a crucial step to ensure the blocklet's on-chain information is synchronized with its current state on the server." icon="key" href="/en/docs/blocklet-cli/advanced-topics-did-document-104903/"}
::link-card{title="Cleanup Blocklet" description="Perform targeted cleanup operations for a blocklet, such as clearing its dedicated cache or disabling and resetting its auto-backup configuration." icon="trash" href="/en/docs/blocklet-cli/advanced-topics-cleanup-104903/"}
::::

Explore these sections to gain deeper control over your blocklet's lifecycle. For a complete list of all available commands and their options, please refer to the [Command Reference](/en/docs/blocklet-cli/command-reference-104903/).

---

## Cleanup Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-cli/advanced-topics-cleanup-104903/

The `blocklet cleanup` command is a utility for performing maintenance tasks on a specific blocklet installed on your Blocklet Server. It allows you to clear a blocklet's dedicated cache or disable its automatic backup configuration.

This command is particularly useful for troubleshooting or managing a blocklet's storage footprint.

## Command Usage

The basic syntax for the cleanup command is as follows:

```bash
blocklet cleanup <target> --app-did <did>
```

### Arguments and Options

| Argument/Option  | Description  |
|---|---|
| `target`  | <strong>Required</strong>. The cleanup task to perform. Valid values are `cache` or `backup`.  |
| `--app-did <did>`  | <strong>Required</strong>. The DID of the blocklet you want to clean up.  |

## Cleanup Tasks

You can perform two distinct cleanup tasks: clearing the cache and disabling backups.

### Clear Blocklet Cache

This task removes all cached data associated with a specific blocklet. This can be useful if you suspect corrupted cache data or want to free up space.

**Clear cache for a specific blocklet**

```bash
blocklet cleanup cache --app-did z8iZufgv3e2yYAmH4L53s83wbeG7eWz4WADS
```

Upon successful execution, the CLI will confirm that the cache has been cleared and list the removed items:

**Success output**

```bash
Cache for app z8iZufgv3e2yYAmH4L53s83wbeG7eWz4WADS cleared: [items]
```

### Disable Auto-Backup

This task disables the automatic backup feature for a specific blocklet. It does this by clearing the backup endpoint configuration and turning off the auto-backup setting.

**Disable auto-backup for a specific blocklet**

```bash
blocklet cleanup backup --app-did z8iZufgv3e2yYAmH4L53s83wbeG7eWz4WADS
```

After running the command, you will see a confirmation message:

**Success output**

```bash
Blocklet z8iZufgv3e2yYAmH4L53s83wbeG7eWz4WADS auto-backup disabled
```

This command provides a straightforward way to manage the persistent data of your blocklets. For other advanced management tasks, you may also be interested in [DID Document Management](/en/docs/blocklet-cli/advanced-topics-did-document-104903/).

---

## DID Document Management

URL: https://www.arcblock.io/en/docs/blocklet-cli/advanced-topics-did-document-104903/

Every blocklet is identified by a Decentralized Identifier (DID), which is associated with a DID Document. This document contains crucial metadata, such as public keys and service endpoints, allowing other services to discover and interact with your blocklet securely. While Blocklet Server typically manages this document automatically, there are situations where a manual update is necessary.

This section covers how to use the CLI to manage your blocklet's DID document.

## Update DID Document

The `blocklet document update` command allows you to manually refresh and republish the DID document for a specific blocklet. This is useful for ensuring the on-chain information is perfectly synchronized with your blocklet's current configuration.

### Usage

**command**

```bash
blocklet document update <appId>
```

### Arguments

| Argument  | Description  |
|---|---|
| `appId`  | The DID of the blocklet to be updated.  |

### Example

Running the command will trigger the update process, showing a spinner while it communicates with the node.

```bash
blocklet document update z8ia12z3ySA1J5694T1aW3E8a3z3e1X9V3E2
```

Upon successful completion, you will see a confirmation message:

```bash
✔ Updating...
✔ Update did document for z8ia12z3ySA1J5694T1aW3E8a3z3e1X9V3E2 successfully!
```

If the blocklet with the specified `appId` cannot be found, the command will fail with an error:

```bash
✖ Failed to update did document for blocklet z8ia12z3ySA1J5694T1aW3E8a3z3e1X9V3E2, error: Blocklet z8ia12z3ySA1J5694T1aW3E8a3z3e1X9V3E2 not found
```

### Common Use Cases

You might need to use this command in the following scenarios:

- <strong>After Configuration Changes</strong>: If you've manually altered settings that affect the blocklet's public-facing endpoints or metadata, running this command ensures those changes are reflected in the DID document.
- <strong>Troubleshooting</strong>: When encountering issues with DID resolution, authentication, or service discovery, forcing an update can help rule out synchronization problems.
- <strong>State Resynchronization</strong>: To ensure the on-chain DID document is a precise representation of the blocklet's current state after a server migration or restoration from backup.

---

## Blocklet Workflows

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-104903/

The Blocklet CLI provides a comprehensive suite of commands to support the entire lifecycle of a blocklet, from initial project creation to final distribution. These workflows are designed to streamline development, ensuring a smooth and efficient process for building, testing, and deploying your applications.

This section provides an overview of the key stages in a blocklet's lifecycle. Each stage corresponds to a set of CLI commands tailored for specific tasks.

![Blocklet Workflows](https://media.arcblock.io/lib/7b/7bd75409a5579715.w1600.webp)

Explore the different workflows to manage your blocklet effectively:

::::card-group
::link-card{title="Project Setup" description="Commands for bootstrapping and setting up new blocklet projects, whether from a template or from scratch." icon="folder-plus" href="/en/docs/blocklet-cli/blocklet-workflows-project-setup-104903/"}
::link-card{title="Local Development" description="Tools for running, testing, and debugging your blocklet in a local development environment connected to Blocklet Server." icon="monitor" href="/en/docs/blocklet-cli/blocklet-workflows-local-development-104903/"}
::link-card{title="Component Management" description="Manage blocklet components by adding or removing them from your project's configuration." icon="box" href="/en/docs/blocklet-cli/blocklet-workflows-component-management-104903/"}
::link-card{title="Packaging & Versioning" description="Commands for packaging your blocklet into a deployable bundle and managing its version number." icon="package" href="/en/docs/blocklet-cli/blocklet-workflows-packaging-104903/"}
::link-card{title="Distribution" description="Deploy your blocklet to a server or upload it to a blocklet store for others to use." icon="send" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-104903/"}
::::

By following these workflows, you can systematically advance your project from an idea to a production-ready blocklet. Begin by setting up your project, then move on to local development to build and test your features. Once ready, package your blocklet and distribute it for the world to see.

---

## Component Management

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-component-management-104903/

Blocklets can be composed of other blocklets, which are referred to as components. This powerful feature allows you to build complex applications by assembling smaller, reusable parts. The Blocklet CLI provides a set of commands to help you manage these component dependencies within your project's `blocklet.yml` file.

This section covers how to add, remove, and interact with components in your blocklet project.

::::card-group
::link-card{title="Add Component" description="Learn how to add new component dependencies to your blocklet." icon="plus" href="/en/docs/blocklet-cli/blocklet-workflows-component-management-add-104903/"}
::link-card{title="Remove Component" description="Find out how to remove existing component dependencies from your blocklet." icon="trash" href="/en/docs/blocklet-cli/blocklet-workflows-component-management-remove-104903/"}
::link-card{title="Component Studio CLI" description="Interact with the Component Studio for advanced component management tasks." icon="box" href="/en/docs/blocklet-cli/blocklet-workflows-component-management-studio-cli-104903/"}
::::

## Add Component

The `blocklet add` command adds a new blocklet as a component to your current project. It automatically updates the `components` section of your `blocklet.yml` file and checks for circular dependencies.

**Command**

```bash
blocklet add <name>[@<version>] | <url> [options]
```

You can add a component from a configured Blocklet Store by specifying its name and an optional version, or directly from a URL pointing to its metadata.

<strong>Examples:</strong>

- <strong>Add from a store:</strong> **Add from store**  ```bash blocklet add my-component@1.2.3 ```
- <strong>Add from a URL:</strong> **Add from URL**  ```bash blocklet add https://example-store.com/blocklets/z8i.../blocklet.json ```

This command will add a new entry to your `blocklet.yml` like this:

**blocklet.yml**

```yaml
components:
  - name: my-component
    title: My Component
    mountPoint: /my-component
    source:
      store: 'https://store.blocklet.dev'
      name: my-component
      version: 1.2.3
```

For more details, see the [Add Component](/en/docs/blocklet-cli/blocklet-workflows-component-management-add-104903/) documentation.

## Remove Component

The `blocklet remove` command removes a component dependency from your project. It finds the component by name in your `blocklet.yml` and deletes its configuration entry.

**Command**

```bash
blocklet remove <component-name>
```

<strong>Example:</strong>

**Remove a component**

```bash
blocklet remove my-component
```

This will remove the corresponding component object from the `components` array in your `blocklet.yml`.

For more details, see the [Remove Component](/en/docs/blocklet-cli/blocklet-workflows-component-management-remove-104903/) documentation.

## Component Studio CLI

The `blocklet component` command is a convenient wrapper that executes the `@blocklet/component-studio-cli`. This specialized tool provides more advanced functionalities for working with components.

Any arguments you pass to `blocklet component` are forwarded directly to the Component Studio CLI.

**Command**

```bash
blocklet component [args...]
```

<strong>Example:</strong>

If the Component Studio CLI has a command called `list`, you can run it like this:

**Proxy a command**

```bash
blocklet component list
```

This executes `npx -y @blocklet/component-studio-cli list` behind the scenes.

For more details, see the [Component Studio CLI](/en/docs/blocklet-cli/blocklet-workflows-component-management-studio-cli-104903/) documentation.

---

## Add Component

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-component-management-add-104903/

The `blocklet add` command adds a new component as a dependency to your blocklet. It automatically updates the `components` section of your `blocklet.yml` file with the necessary configuration.

This command simplifies dependency management by fetching the component's metadata from a specified blocklet store or a direct URL, ensuring that all required information is correctly added to your project configuration.

## Command Syntax

The basic syntax for the `add` command is as follows:

```bash
blocklet add <component> [options]
```

### Arguments

- **<component>** `string` *(required)* — The identifier for the component you want to add. This can be specified in several formats: - By Name and Version: component-name@1.2.3. If the version is omitted (e.g., component-name), it defaults to latest. - By DID: z8... (The decentralized identifier of the blocklet). - By URL: A direct URL to the component's blocklet.json metadata file (e.g., https://example.com/path/to/blocklet.json).

### Options

The following options are available to customize how the component is added:

- **--store <url>** `string` — Specifies the URL of the blocklet store to search for the component. If not provided, the command uses the store configured in your Blocklet CLI profile, falling back to the default official blocklet store.
- **--title <title>** `string` — Sets a custom title for the component in your blocklet.yml. If omitted, the title from the component's own metadata will be used.
- **--mount-point <path>** `string` — Defines the URL path where the component will be mounted. If not specified, a default mount point is generated based on a URL-friendly version of the component's name (e.g., /component-name).
- **--profile <name>** `string` — Selects a specific configuration profile to use for settings like the default blocklet store.

## Usage Examples

Here are some practical examples of how to use the `blocklet add` command.

### Add a Component from the Default Store

To add the latest version of a component named `did-wallet` from the default blocklet store:

```bash
blocklet add did-wallet
```

To add a specific version of the component:

```bash
blocklet add did-wallet@1.6.0
```

After running the command, your `blocklet.yml` will be updated with a new entry similar to this:

```yaml
# blocklet.yml
components:
  - name: did-wallet
    title: DID Wallet
    mountPoint: /did-wallet
    source:
      store: 'https://store.blocklet.dev'
      name: did-wallet
      version: 1.6.0
```

### Add a Component from a URL

If the component is not in a store, you can add it directly from its metadata URL.

```bash
blocklet add https://github.com/arcblock/did-wallet/releases/download/v1.6.25/blocklet.json
```

This will add an entry to your `blocklet.yml` that points directly to the URL:

```yaml
# blocklet.yml
components:
  - name: did-wallet
    title: DID Wallet
    mountPoint: /did-wallet
    source:
      url: 'https://github.com/arcblock/did-wallet/releases/download/v1.6.25/blocklet.json'
```

### Add a Component with Custom Options

You can override the default title and mount point for the component.

```bash
blocklet add did-wallet --title "My Custom Wallet" --mount-point "/my-wallet"
```

The resulting configuration in `blocklet.yml` will reflect these custom values:

```yaml
# blocklet.yml
components:
  - name: did-wallet
    title: My Custom Wallet
    mountPoint: /my-wallet
    source:
      store: 'https://store.blocklet.dev'
      name: did-wallet
      version: latest
```

## Summary

The `blocklet add` command is a crucial tool for managing dependencies within your blocklet project. It automates the process of updating your `blocklet.yml` file, ensuring consistency and reducing the chance of manual errors. For removing dependencies, you can use the corresponding [`blocklet remove`](/en/docs/blocklet-cli/blocklet-workflows-component-management-remove-104903/) command.

---

## Remove Component

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-component-management-remove-104903/

The `blocklet remove` command provides a straightforward way to remove a component dependency from your blocklet's `blocklet.yml` metadata file. This action updates your project configuration to reflect that the component is no longer a dependency.

## Command Usage

To remove a component, navigate to your blocklet's root directory and run the command with the name of the component you wish to remove.

**Command**

```bash
blocklet remove <component-name>
```

### Arguments

| Argument  | Description  |
|---|---|
| `<component-name>`  | <strong>Required.</strong> The name of the component to be removed from the `components` list in your `blocklet.yml` file.  |

## How It Works

When you execute `blocklet remove`, the CLI performs the following steps:

::::steps
:::step{title="Locates Metadata"}
It finds the `blocklet.yml` file in the current working directory.
:::

:::step{title="Parses Components"}
It reads the file and looks for the `components` array.
:::

:::step{title="Verifies Existence"}
It checks if a component with the specified name exists in the array.
:::

:::step{title="Removes Entry"}
If the component is found, its entry is removed from the `components` array.
:::

:::step{title="Updates File"}
The `blocklet.yml` file is saved with the updated list of components.
:::
::::

If the specified component is not found in `blocklet.yml`, the command will print an error message and exit.

## Example

Imagine your `blocklet.yml` file contains a dependency on a component named `did-connect`:

**blocklet.yml (Before)**

```yaml
name: my-blocklet
version: 1.0.0
# ... other properties
components:
  - name: my-first-component
    did: "z8iZqsENBg6tLZUKi2HABj38Cw1LmHZocbQ"
  - name: did-connect
    did: "z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ"
```

To remove the `did-connect` component, you would run:

```bash
blocklet remove did-connect
```

The command will output a success message:

**Console Output**

```text
Component did-connect was successfully removed
```

After execution, your `blocklet.yml` file will be updated to remove the entry for `did-connect`:

**blocklet.yml (After)**

```yaml
name: my-blocklet
version: 1.0.0
# ... other properties
components:
  - name: my-first-component
    did: "z8iZqsENBg6tLZUKi2HABj38Cw1LmHZocbQ"
```

Next, you might want to add a new component to your project. Learn how by visiting the [Add Component](/en/docs/blocklet-cli/blocklet-workflows-component-management-add-104903/) guide.

---

## Component Studio CLI

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-component-management-studio-cli-104903/

The `blocklet component` command serves as a convenient proxy to execute commands from the `@blocklet/component-studio-cli` package. This allows you to interact with the Component Studio directly from your terminal without needing to install the package globally or manage its version manually.

## Usage

Any command or arguments you provide after `blocklet component` are passed directly to the `@blocklet/component-studio-cli`.

**Command Syntax**

```bash
blocklet component [studio-command] [arguments...]
```

For instance, if the Component Studio CLI has a `list` command to show all available components, you would run it like this:

```bash
blocklet component list
```

## How It Works

Behind the scenes, the Blocklet CLI constructs and executes an `npx` command. The `npx` tool allows you to run Node.js package executables without having to explicitly install them. Using `npx` ensures that you are always running the latest version of the Component Studio CLI, fetching it on-demand if it's not already cached on your system.

The previous example translates to the following command:

**How It Works**

```bash
npx -y @blocklet/component-studio-cli list
```

This approach simplifies your workflow and eliminates the need for manual updates of the studio CLI.

## Troubleshooting

If you encounter any issues while running a `blocklet component` command, the CLI is designed to provide helpful feedback. In case of an error, it will print the underlying `npx` command that it tried to execute. Running this command directly can be useful for debugging permission issues, network problems, or getting more detailed error output from the studio CLI itself.

For example, if `blocklet component list` fails, you can try the direct command for a more verbose output:

```bash
npx -y @blocklet/component-studio-cli list
```

After managing your components, the next step is often to package your blocklet for distribution. Learn more in the [Packaging & Versioning](/en/docs/blocklet-cli/blocklet-workflows-packaging-104903/) section.

---

## Distribution

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-distribution-104903/

Once your blocklet is developed and bundled, the next step is to make it available for others to install and use. The Blocklet CLI provides two primary methods for distribution: deploying directly to a Blocklet Server or uploading to a Blocklet Store for public discovery.

This choice depends on your goal: direct deployment is excellent for testing and private use, while uploading to a store is the standard for public releases.

![Distribution](https://media.arcblock.io/lib/a8/a8674468c2d41220.w1600.webp)

Explore the distribution workflows below to determine the best path for your blocklet.

::::card-group
::link-card{title="Deploy Blocklet" description="Directly push your blocklet from your local machine to a running Blocklet Server instance. This is ideal for rapid development cycles, testing on a staging server, or deploying private blocklets." icon="layers" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-deploy-104903/"}
::link-card{title="Upload to Store" description="Package and upload your blocklet to a public or private Blocklet Store. This makes your blocklet discoverable and easily installable by a wider audience, similar to a traditional app store." icon="upload" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-upload-104903/"}
::link-card{title="Connect to Store" description="Before you can upload a blocklet, you must first authenticate your CLI with the target Blocklet Store. This command securely links your developer account to your local environment." icon="link" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-connect-104903/"}
::::

---

## Connect to Store

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-distribution-connect-104903/

Before you can upload a blocklet to a Blocklet Store, you first need to connect your local CLI to it. The `blocklet connect` command facilitates a one-time setup process that authenticates your machine with a specific store, saving the necessary credentials locally for future commands like `blocklet upload`.

This process involves a secure, browser-based authentication flow to link your developer account to your local environment.

## How It Works

The connection process is an interactive flow between your terminal, your web browser, and the Blocklet Store. When you run the command, the CLI generates a unique, secure URL and opens it in your browser. After you log in and authorize the connection, the store sends back an access token and your developer information, which the CLI saves to your local configuration file.

![Connect to Store](https://media.arcblock.io/lib/a6/a68f8115bf7f3f12.w1600.webp)

## Usage

To initiate the connection, run the command with the URL of the target Blocklet Store.

**Basic Usage**

```bash
blocklet connect <store_url>
```

### Arguments

- **store** `string` *(required)* — The full URL of the Blocklet Store you want to connect to. For example, https://store.blocklet.dev. The URL must be a valid web URI using http or https.

### Options

- **--profile <name>** `string` — Connect using a specific configuration profile. This is useful if you work with multiple Blocklet Stores and want to keep their credentials separate.

## Step-by-Step Guide

1. <strong>Run the Connect Command</strong> Open your terminal and execute the `blocklet connect` command, providing the URL of your store. **Connect to the Official Store**  ```bash blocklet connect https://store.blocklet.dev ```
2. <strong>Authenticate in Browser</strong> The CLI will automatically open a new tab in your default web browser. You will be asked to log in to the Blocklet Store (if you aren't already) and then approve the request to grant the CLI access to your account.
3. <strong>Confirmation</strong> Once you approve the request in the browser, the CLI will receive the necessary credentials (`secretKey`, `developerDid`, `name`, `email`). You'll see a success message in your terminal confirming the connection. **Example Success Message**  ```text Successfully connected, and now you are ready to upload blocklets to https://store.blocklet.dev Tips: Use the following command to view the configuration: blocklet config list ```
4. <strong>Verify the Configuration</strong> As the tip suggests, you can view the saved configuration to confirm that your details have been stored correctly. **View Configuration**  ```bash blocklet config list ```  If you used a profile, remember to add the `--profile` flag: **View Configuration with Profile**  ```bash blocklet config list --profile <your-profile-name> ```

## Overwriting an Existing Connection

If you have already connected to a store and you run `blocklet connect` again with a different store URL, the CLI will prompt you to confirm whether you want to overwrite the existing configuration.

**Overwrite Prompt**

```text
The store url has been set, do you need to overwrite it? (y/N)
```

Press `y` and Enter to proceed with connecting to the new store, or simply press Enter (the default is `N`) to cancel the operation.

## Next Steps

With your CLI successfully connected to the store, you are now ready to publish your blocklets.

:::action-card{title="Upload to Store" description="Learn how to package and upload your bundled blocklet to the store." icon="upload"}
::action{label="Learn More" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-upload-104903/" variant="primary"}
:::

---

## Deploy Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-distribution-deploy-104903/

The `blocklet deploy` command is your direct line for pushing a blocklet from your local development environment to a running Blocklet Server instance. This is essential for testing in a staging environment or deploying directly to production. The command handles bundling, versioning, and uploading your project in one step.

There are two primary ways to deploy: to a local server for development and testing, or to a remote server for staging or production.

## Command Usage

The basic syntax for the deploy command is:

**Basic Usage**

```bash
blocklet deploy <directory> [options]
```

- `<directory>`: The path to your blocklet project's root directory. You can use `.` to specify the current directory.

## Deployment Scenarios

### 1. Deploying to a Local Server

When you're running Blocklet Server on your local machine, deploying is straightforward. The CLI automatically detects the running server, generates a temporary access key for the operation, and handles the deployment without needing manual configuration.

This is the recommended workflow for rapid development and testing.

**Deploying Locally**

```bash
# First, ensure your local Blocklet Server is running
blocklet server start

# Navigate to your blocklet project and deploy
cd /path/to/my-blocklet
blocklet deploy . --app-id <your-local-app-did>
```

The CLI will find the running server, deploy the blocklet, and then revoke the temporary access key it used.

### 2. Deploying to a Remote Server

Deploying to a remote server requires specifying the server's endpoint and providing authentication credentials.

#### Method A: Using Access Key & Secret

If you have an access key and secret, you can provide them directly as command-line options. This method is ideal for CI/CD environments where user interaction is not possible.

**Deploying with Access Keys**

```bash
blocklet deploy . \
  --endpoint https://my-server.arcblock.io \
  --access-key 'your_access_key_id' \
  --access-secret 'your_access_key_secret' \
  --app-id z2qa9sD2tFAP8gM7C1i8iETg3a1T3A3aT3bQ
```

#### Method B: Using DID Connect for Authentication

If you don't provide an access key and secret, the CLI will initiate a secure authentication process using DID Connect. This is a user-friendly method for manual deployments from your development machine.

**Deploying with DID Connect**

```bash
blocklet deploy . \
  --endpoint https://my-server.arcblock.io \
  --app-id z2qa9sD2tFAP8gM7C1i8iETg3a1T3A3aT3bQ
```

When you run this command, the CLI will prompt you to open a web page to generate a new access key. After you authenticate with your DID Wallet, the key is securely sent to the CLI and saved locally for future deployments to the same application.

This flow is illustrated below:

![Deploy Blocklet](https://media.arcblock.io/lib/3e/3ef9dc6af3632eba.w1600.webp)

## Command Options

- **--endpoint <url>** `string` — The URL of the remote Blocklet Server. Required for remote deployments.
- **--access-key <key>** `string` — The access key ID for authenticating with the remote server.
- **--access-secret <secret>** `string` — The access key secret for authentication.
- **--app-id <did>** `string` *(required)* — The DID of the root application where this blocklet will be deployed as a component. The CLI will throw an error if this is not provided. You can also use --app-did.
- **--mount-point <path>** `string` — The URL path where the blocklet will be accessible (e.g., /my-component). If not provided, a default is generated from the blocklet's title or name.
- **--incremental** `boolean` — Enables incremental deployment. The CLI will compare local file hashes with the server and only upload changed files, speeding up the process significantly.

## Deployment Output

During deployment, the CLI provides feedback on the files being processed. If you use the `--incremental` flag, it will show which files are new, changed, or deleted.

**Example Deployment Output**

```bash
ℹ Info: Try to deploy My Blocklet@1.0.0 from /path/to/my-blocklet to My App in server https://my-server.arcblock.io.
ℹ Info: Use default mountPoint: /my-blocklet
ℹ Info: Incremental mode, fetching blocklet diff...
ℹ Info: Name: my-blocklet
ℹ Info: DID: z8iZp329XWHe7iMqtTVmFobb82E9CR4X3sKAU
ℹ Info: Version: 1.0.0
ℹ Info: Added Files: 2
  - new-feature.js
  - assets/icon.png
ℹ Info: Changed Files: 1
  - blocklet.yml
ℹ Info: Deleted Files: 0
⠙ Uploading my-blocklet...
✔ Success: My Blocklet@1.0.0 was successfully deployed to My App in server https://my-server.arcblock.io.
```

After a successful deployment, your blocklet will be running on the target Blocklet Server.

:::action-card{title="Next Step: Upload to Store" description="Once your blocklet is deployed and tested, learn how to upload it to a Blocklet Store to make it available to other users." icon="upload"}
::action{label="Learn More" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-upload-104903/" variant="primary"}
:::

---

## Upload to Store

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-distribution-upload-104903/

After you have successfully bundled your blocklet, the next step in distribution is to upload it to a Blocklet Store. The `blocklet upload` command sends your blocklet bundle to the designated store, making it available for others to discover and install. This is the primary method for public distribution.

Before proceeding, ensure you have already bundled your blocklet and configured your CLI to connect to a store.

::::card-group
::link-card{title="Bundle Blocklet" description="Learn how to package your blocklet into a distributable format." icon="package" href="/en/docs/blocklet-cli/blocklet-workflows-packaging-bundle-104903/"}
::link-card{title="Connect to Store" description="Configure your CLI to authenticate with a specific Blocklet Store." icon="power" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-connect-104903/"}
::::

## Command Usage

The command uploads the blocklet bundle found in the default release directory.

**Basic Usage**

```bash
blocklet upload [metaFile]
```

## Arguments and Options

| Argument/Option  | Description  |
|---|---|
| `metaFile`  | Optional. The path to the `blocklet.json` file of the bundled blocklet. If not specified, it defaults to `./.blocklet/release/blocklet.json`.  |
| `--access-token <token>`  | Optional. The access token for the Blocklet Store. This flag overrides any token set in your configuration profile.  |
| `--profile <name>`  | Optional. Specifies which configuration profile to use. This is useful if you manage multiple store connections (e.g., development, staging, production). Defaults to `default`.  |

## Upload Workflow

The upload process involves the CLI reading your local configuration and the blocklet bundle, then securely transmitting it to the Blocklet Store for validation and storage. The following diagram illustrates this process:

![Upload to Store](https://media.arcblock.io/lib/65/65943cd8981d7891.w1600.webp)

## Examples

### Standard Upload

If you are in the root directory of your project and have configured a default profile, simply run the command without any arguments.

**Upload from Project Root**

```bash
blocklet upload
```

### Uploading a Specific File

To upload a blocklet bundle from a specific location, provide the path to its `blocklet.json` file.

**Upload a specific bundle**

```bash
blocklet upload /path/to/my-blocklet/.blocklet/release/blocklet.json
```

### Using a Different Profile

If you have multiple store configurations, use the `--profile` flag to specify which one to use for the upload.

**Upload using a profile**

```bash
blocklet upload --profile production
```

### Overriding the Access Token

You can provide an access token directly on the command line, which is useful for CI/CD environments.

**Upload with a specific token**

```bash
blocklet upload --access-token bst_xxxxxxxxxxxxxxxxxxxxxx
```

## Successful Upload

Upon a successful upload, you will see a confirmation message. The exact message depends on the store's configuration.

#### Uploaded (Manual Publish Required)

Most commonly, the blocklet is uploaded and awaits manual publishing from the developer dashboard.

**Example Output: Uploaded**

```bash
ℹ Blocklet My Awesome Blocklet 1.0.0 successfully uploaded to https://store.blocklet.dev!
ℹ Tips:  You need to publish the blocklet at https://store.blocklet.dev/developer/blocklets to make it public accessible
```

#### Auto-Published

In some cases, the store may be configured to automatically publish new uploads.

**Example Output: Auto-Published**

```bash
✔ Blocklet My Awesome Blocklet 1.0.0 auto published successfully: https://store.blocklet.dev/blocklets/z8iZ......... !
```

## Troubleshooting

::::card-group
::link-card{title="Invalid Meta File" description="Error: `Invalid meta file: '...'`. This means the command cannot find the `blocklet.json` file. Ensure you have run `blocklet bundle` first and are in the correct directory." icon="file"}
::link-card{title="Missing Store URL" description="Error: `Can not find the store url...`. Your CLI profile is missing the store's address. Run `blocklet config set store [storeUrl]` to fix it." icon="link"}
::link-card{title="Access Token Error" description="Error: `accessToken is required...` or `[NO-ACCESS]`. This indicates an authentication failure. Your access token is either missing, invalid, or expired. You can set it globally with `blocklet config set accessToken [token]` or pass it for a single command with the `--access-token` flag." icon="key"}
::::

---

## Local Development

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-local-development-104903/

Developing and testing your blocklet locally is a crucial part of the workflow. The Blocklet CLI provides a powerful set of tools to run your blocklet in a live-reloading environment connected to your local Blocklet Server, execute one-off scripts, and debug your application with ease. This section covers the essential commands for your local development loop.

::::card-group
::link-card{title="Develop Mode" description="Run your blocklet in a live-reloading development environment. The `blocklet dev` command handles installation, starting, and watching for file changes, providing a seamless development experience." icon="play" href="/en/docs/blocklet-cli/blocklet-workflows-local-development-dev-mode-104903/"}
::link-card{title="Execute Script" description="Execute a script within the context of a running blocklet. Ideal for tasks like database migrations, data seeding, or other one-off administrative jobs." icon="terminal" href="/en/docs/blocklet-cli/blocklet-workflows-local-development-exec-104903/"}
::link-card{title="Debug Blocklet" description="Easily set debug configurations for a specific blocklet. This allows you to enable verbose logging or other debugging features without modifying your code." icon="bug" href="/en/docs/blocklet-cli/blocklet-workflows-local-development-debug-104903/"}
::::

Explore the guides in this section to master each aspect of local blocklet development. To manage the components within your project, see the [Component Management](/en/docs/blocklet-cli/blocklet-workflows-component-management-104903/) documentation.

---

## Debug Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-local-development-debug-104903/

The `blocklet debug` command is a utility for developers to set environment variables on a running blocklet, primarily for enabling detailed logging and other debugging features without needing to rebuild or redeploy.

This command directly interacts with the Blocklet Server to modify a blocklet's configuration on the fly.

## Command Usage

The basic syntax for the command is as follows:

**Basic Syntax**

```bash
blocklet debug <value> --appId <did>
```

### Prerequisites

Before using this command, ensure that your Blocklet Server is running. If the server is not active, the command will fail. You can start the server using:

**Start Server**

```bash
blocklet server start
```

### Arguments and Options

- **value** `string` *(required)* — The value to set for the DEBUG environment variable. It can also be a special command or a URL for advanced actions.
- **--appId <did>** `string` *(required)* — The decentralized identifier (DID) of the specific blocklet you wish to debug.

## How It Works

The primary function of this command is to set a configuration entry with the key `DEBUG` for the specified blocklet. Many Node.js libraries, most notably the [`debug`](https://www.npmjs.com/package/debug) package, use the `DEBUG` environment variable to control which logging messages are sent to the console. By setting this value, you can enable verbose output from your blocklet and its dependencies.

### Examples

<strong>1. Enable All Debug Logs</strong>

To see all debug messages from a blocklet and its dependencies, use the wildcard `*` character.

**Enable all debug logs**

```bash
blocklet debug '*' --appId z2qa...w3k
```

After running this, you can view the blocklet's logs to see the detailed output.

<strong>2. Enable Specific Debug Logs</strong>

To target logs from a specific part of your application, you can provide a more specific namespace.

**Enable logs for API routes**

```bash
blocklet debug 'api:*' --appId z2qa...w3k
```

<strong>3. Disable Debug Logs</strong>

To turn off the debug logs, simply provide an empty string as the value.

**Disable all debug logs**

```bash
blocklet debug '' --appId z2qa...w3k
```

## Advanced Actions

The `value` argument also accepts special commands to perform specific actions on the blocklet, which can be useful during a debugging session.

::::card-group
::link-card{title="Stop the Blocklet" description="To temporarily stop a running blocklet, use the `$stopBlocklet` value. This is useful if you need to attach a debugger or make changes that require a restart." icon="pause"}
::link-card{title="Set a Custom Store URL" description="If you need the blocklet to resolve components from a different blocklet store (e.g., a local development store), you can provide a URL as the value." icon="shopping-bag"}
::::

### Stop Blocklet Example

**Stop a running blocklet**

```bash
blocklet debug '$stopBlocklet' --appId z2qa...w3k
```

### Set Custom Store Example

**Point blocklet to a local store**

```bash
blocklet debug http://localhost:3030 --appId z2qa...w3k
```

After setting a custom store, the blocklet will fetch components from that URL, allowing you to test interactions with unpublished or development-stage components.

Once you have configured debugging, you may want to execute a specific script within the blocklet's context. To learn how, proceed to the [Execute Script](/en/docs/blocklet-cli/blocklet-workflows-local-development-exec-104903/) documentation.

---

## Develop Mode

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-local-development-dev-mode-104903/

The `blocklet dev` command is a crucial tool for local development. It runs your blocklet in a live-reloading development mode, connecting it to a running Blocklet Server instance. This allows for rapid iteration by automatically handling the installation, starting, and log streaming of your blocklet as a temporary component.

When you run this command, it performs several key actions:

::::steps
:::step{title="Connects to Server"}
It first ensures that a local Blocklet Server is running and establishes a connection.
:::

:::step{title="Installs as Component"}
It installs the blocklet from your current working directory into the Blocklet Server as a component in "development" mode. If a parent application is specified, it's installed within that application; otherwise, a new container application is created.
:::

:::step{title="Starts Blocklet"}
It starts the blocklet and any necessary services.
:::

:::step{title="Streams Logs"}
It pipes the blocklet's logs directly to your terminal for real-time feedback.
:::

:::step{title="Provides Access URL"}
It outputs the URL where you can access your running blocklet.
:::

:::step{title="Automatic Cleanup"}
When you terminate the command (e.g., with `Ctrl+C`), it automatically removes the development component and cleans up the environment.
:::
::::

This integrated process streamlines the development cycle, letting you focus on coding while the CLI manages the runtime environment.

![Develop Mode](https://media.arcblock.io/lib/c3/c33b5ff026b6a2e2.w1600.webp)

## Command Usage

The primary command for entering development mode is `blocklet dev`.

```bash
blocklet dev
```

This command installs and starts the blocklet from the current directory.

### Subcommands

The `dev` command also includes several subcommands to manage the development lifecycle without starting a full development session.

| Command  | Description  |
|---|---|
| `blocklet dev install`  | Installs the blocklet in development mode but does not start it. Useful for pre-configuring an environment.  |
| `blocklet dev remove`  | Removes a blocklet that was previously installed in development mode.  |
| `blocklet dev reset`  | Resets the data for the blocklet, clearing its state without a full re-installation.  |
| `blocklet dev faucet`  | Claims tokens from a configured testnet faucet for the blocklet's wallet.  |
| `blocklet dev studio`  | Opens the Component Studio in your browser for the specified blocklet.  |

### Options

You can customize the behavior of the `dev` command with the following options:

- **--app-did** `string` — Specify the DID of an existing parent application to install the blocklet into. If omitted, a new application container is created for the blocklet.
- **--mount-point** `string` — Define the URL path where the blocklet component will be mounted (e.g., /my-blocklet). Required when using --app-did.
- **--open** `boolean` — Automatically open the blocklet's access URL in your default web browser after it starts.
- **--store-url** `string` — Specify a component store URL to resolve component dependencies. Overrides the default store URL.
- **--start-all-components** `boolean` — When developing a component within a larger application, this flag will start all other components in that application, not just the one being developed.
- **--host** `string` — Specifies the faucet host URL when using the `faucet` subcommand.
- **--token** `string` — Specifies the token address or symbol to request from the faucet when using the `faucet` subcommand.

## Prerequisites

Before using `blocklet dev`, you must have a Blocklet Server instance running locally. If the server is not running, the command will fail.

You can start the server with the following command:

```bash
blocklet server start
```

For more details, please refer to the [Start Server](/en/docs/blocklet-cli/server-management-start-104903/) documentation.

## Examples

### Basic Development

To start developing a blocklet located in your current directory, simply run:

```bash
blocklet dev --open
```

The CLI will install and start the blocklet, stream its logs to your console, and open its URL in your browser.

### Developing a Component for an Existing Application

If you are developing a blocklet that is intended to be a component of a larger application, you can specify the parent application's DID and a mount point.

```bash
blocklet dev --app-did zNKe4B62j5e9i6rWzM9adcee19s323j4s2pG --mount-point /my-component
```

This command will:

1. Find the application with the specified DID (`zNKe...`).
2. Install your local blocklet as a component within that application.
3. Make it accessible at the `/my-component` path relative to the application's main URL.

### Resetting Blocklet Data

If you need to clear all data and state associated with your development blocklet to test a clean installation flow, use the `reset` subcommand.

```bash
blocklet dev reset
```

This is much faster than removing and re-installing the blocklet.

## Summary

The `blocklet dev` command is the cornerstone of local blocklet development, providing a seamless and efficient workflow. It bridges the gap between your local source code and a live Blocklet Server environment.

After iterating locally, the next steps are to package your blocklet for distribution. For more information, see the documentation on [packaging and versioning](/en/docs/blocklet-cli/blocklet-workflows-packaging-104903/).

---

## Execute Script

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-local-development-exec-104903/

The `blocklet exec` command is a powerful utility for running a script within the live context of an installed blocklet. This is invaluable for tasks like database migrations, data seeding, or any one-off script that needs access to your blocklet's runtime environment variables.

It ensures that your script runs with the same configuration and secrets as your running application, making administrative and debugging tasks much simpler and more reliable.

## How It Works

When you run `blocklet exec`, the CLI connects to your running Blocklet Server, retrieves the environment variables for the specified blocklet instance, and then executes your script in a new process with those variables injected. This allows your script to connect to the same databases, services, and APIs as your blocklet. The following diagram illustrates this process:

![Execute Script](https://media.arcblock.io/lib/84/84c45ed9057ab461.w1600.webp)

## Usage

To execute a script, you must provide the path to the script and the DID of the target blocklet instance.

**Command Syntax**

```bash
blocklet exec <path-to-script> [options]
```

### Prerequisites

::::steps
:::step{title="Blocklet Server Must Be Running"}
The command needs to communicate with the server to fetch the environment. If it's not running, start it with `blocklet server start`.
:::

:::step{title="Blocklet Must Be Installed"}
The blocklet identified by `--app-id` must already be installed on the server.
:::
::::

### Parameters & Options

- **path-to-script** `string` *(required)* — The relative path to the Node.js script you want to execute.
- **--app-id** `string` *(required)* — The DID of the blocklet instance where the script should run. If not provided, the CLI will look for the BLOCKLET_DEV_APP_DID environment variable.
- **--timeout** `number` (default: `1800`) — The maximum execution time for the script, in seconds. Defaults to 30 minutes (1800s).

## Example

Let's say you have a script to check some key environment variables for your running blocklet.

First, create the script file:

**scripts/check-env.js**

```javascript
// This script will run inside the blocklet's context
// and have access to all its environment variables.

console.log('--- Executing Script in Blocklet Context ---');

const appName = process.env.BLOCKLET_APP_NAME;
const appPort = process.env.BLOCKLET_PORT;

if (appName && appPort) {
  console.log(`Successfully accessed environment variables:`);
  console.log(`- Blocklet Name: ${appName}`);
  console.log(`- Blocklet Port: ${appPort}`);
} else {
  console.error('Could not access blocklet environment variables.');
  process.exit(1);
}

console.log('--- Script Finished ---');
process.exit(0);
```

Now, run the script using the `blocklet exec` command. Make sure to replace `z2qa...` with your actual blocklet instance DID.

**Execute the script**

```bash
blocklet exec scripts/check-env.js --app-id z2qaR7iY52Nv9m36m883s9yqjM3aW5tV6c7g8
```

You should see output similar to this, confirming that the script accessed the blocklet's environment:

**Expected Output**

```text
info Try to run script for blocklet(z2qaR7iY52Nv9m36m883s9yqjM3aW5tV6c7g8) (timeout: 1800000ms)
--- Executing Script in Blocklet Context ---
Successfully accessed environment variables:
- Blocklet Name: My Awesome App
- Blocklet Port: 3030
--- Script Finished ---
success Done!
```

## Executing Scripts for Components

If your current working directory contains a `blocklet.yml` file for a component that is part of a larger blocklet, `blocklet exec` will intelligently detect this. It will automatically run the script within the component's specific environment context, which includes variables from both the parent blocklet and the component itself.

## Common Use Cases

::::card-group
::link-card{title="Database Migrations" description="Run scripts to update your database schema or apply migrations in a production-like environment." icon="database"}
::link-card{title="Data Seeding" description="Populate your database with initial or test data using a script that has access to the database connection details." icon="feather"}
::link-card{title="Administrative Tasks" description="Perform one-off administrative tasks, such as resetting a user's password or cleaning up old records." icon="wrench"}
::link-card{title="Debugging" description="Execute a debug script to inspect the state or environment of a running blocklet without stopping it." icon="bug"}
::::

---

## Packaging & Versioning

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-packaging-104903/

Once you've finished developing and testing your blocklet, the next step is to prepare it for distribution. This involves two critical processes: versioning, to assign a unique identifier to your release, and bundling, to package all your code and assets into a single, deployable artifact. The Blocklet CLI provides dedicated commands to streamline this workflow.

This section provides an overview of the commands used to package and version your blocklet. For detailed instructions, please refer to the specific sub-pages.

::::card-group
::link-card{title="Bundle Blocklet" description="Learn how to use the `blocklet bundle` command to package your project. The CLI intelligently selects the best bundling mode (zip, simple, or compact) based on your blocklet's configuration, ensuring an optimized package for deployment." icon="package" href="/en/docs/blocklet-cli/blocklet-workflows-packaging-bundle-104903/"}
::link-card{title="Manage Version" description="Discover how the `blocklet version` command helps you manage your project's version number following semantic versioning (semver) standards. Properly versioning your blocklet is essential for release management and dependency tracking." icon="tag" href="/en/docs/blocklet-cli/blocklet-workflows-packaging-version-104903/"}
::::

## Typical Workflow

The packaging and versioning process is a straightforward part of the development lifecycle, typically occurring after development and before distribution.

![Packaging & Versioning](https://media.arcblock.io/lib/24/2460f73d5684ea98.w1600.webp)

After successfully bundling your blocklet with an updated version, you are ready to share it with the world.

Proceed to the [Distribution](/en/docs/blocklet-cli/blocklet-workflows-distribution-104903/) section to learn how to deploy your blocklet to a server or upload it to a blocklet store.

---

## Bundle Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-packaging-bundle-104903/

The `blocklet bundle` command is a crucial step in the development lifecycle. It packages your blocklet's source code, assets, and metadata into a standardized `.blocklet` directory, making it ready for deployment or distribution.

This process intelligently gathers all necessary files specified in your `blocklet.yml`, includes lifecycle scripts, and prepares a clean, optimized package.

## Basic Usage

To bundle your blocklet, simply navigate to your project's root directory and run the command:

**Terminal**

```bash
blocklet bundle
```

This command will create a `.blocklet` folder in your project directory containing the bundled application.

## Bundling Process Overview

The bundling process involves several key steps to ensure a complete and valid package is created. The following diagram illustrates the interaction between the developer, the Blocklet CLI, and the project files to produce the final bundle output.

![Bundle Blocklet](https://media.arcblock.io/lib/eb/ebdfed564b6c4f62.w1600.webp)

## Bundling Modes

The CLI automatically selects the best bundling mode based on your blocklet's configuration (e.g., `group: 'static'`). You can also override this behavior by explicitly setting a mode.

::::card-group
::link-card{title="Simple Mode" description="The default mode for most Node.js blocklets (e.g., `group: 'dapp'` or `'gateway'`). It copies the necessary files into the `.blocklet` directory without significant transformation. Use `--simple` to force this mode." icon="box"}
::link-card{title="Zip Mode" description="The default for static blocklets (`group: 'static'`). It bundles the main application code into a `blocklet.zip` archive within the `.blocklet` directory. This is efficient for distributing front-end assets. Use `--zip` to force this mode." icon="archive"}
::link-card{title="Compact Mode" description="An advanced mode that bundles the blocklet and its dependencies into a minimal set of files. This mode is ideal for optimizing performance and package size by creating a more self-contained build. Use `--compact` to force this mode." icon="minimize-2"}
::::

## Command Options

You can customize the bundling process with the following options:

| Option  | Description  |
|---|---|
| `--zip`  | Forces the bundler to use <strong>zip</strong> mode.  |
| `--simple`  | Forces the bundler to use <strong>simple</strong> mode.  |
| `--compact`  | Forces the bundler to use <strong>compact</strong> mode for a minimal build.  |
| `--create-release`  | After bundling, creates a distributable `.tgz` release tarball from the `.blocklet` directory.  |
| `--create-archive`  | When used with `--create-release`, it also generates a `.zip` archive of the bundle.  |
| `--changelog <boolean>`  | Toggles the inclusion of changelog information in the bundle. Defaults to `true`.  |
| `--monorepo`  | Specifies that the blocklet is part of a monorepo, adjusting file resolution accordingly.  |
| `--source-map`  | (<strong>Compact mode only</strong>) Generates source maps for the bundled code.  |
| `--nosources-source-map`  | (<strong>Compact mode only</strong>) Generates source maps without embedding the original source code.  |
| `--minify <boolean>`  | (<strong>Compact mode only</strong>) Toggles minification of the output code. Defaults to `true`.  |
| `--external <dependency>`  | Excludes a specified dependency from the bundle. The dependency is expected to be provided by the runtime environment. Can be used multiple times.  |
| `--external-manager <manager>`  | Specifies the package manager (e.g., `npm`, `yarn`) to use for handling external dependencies. Defaults to `npm`.  |
| `--dependencies-depth <number>`  | (<strong>Compact mode only</strong>) Sets the depth to scan for dependencies when parsing external modules. Defaults to `9`.  |

## Advanced Topics

### Handling External Dependencies

In `compact` mode, the bundler attempts to include all necessary dependencies. However, some packages (like `@blocklet/sdk` or `express`) are provided by the Blocklet Server runtime. To prevent them from being included in your bundle and reduce its size, use the `--external` flag.

**Terminal**

```bash
# Exclude a single dependency
blocklet bundle --compact --external react

# Exclude multiple dependencies by using the flag again
blocklet bundle --compact --external react --external react-dom

# Exclude multiple dependencies with a comma-separated list
blocklet bundle --compact --external react,react-dom
```

### Including Additional Files

The bundler automatically includes files beyond your main source code based on your configuration:

- <strong>`files`</strong> <strong>in</strong> <strong>`blocklet.yml`</strong>: Any files or glob patterns listed in the `files` array of your `blocklet.yml` will be included.
- <strong>Lifecycle Scripts</strong>: JavaScript files referenced in your `scripts` hooks (e.g., `pre-start`, `post-stop`) are automatically detected and bundled.
- <strong>Migration Scripts</strong>: All scripts within the `migration/` directory (e.g., `migration/*.js`) are included to support database migrations.

After successfully bundling your blocklet, the next step is to version it and prepare for distribution. Continue to the next sections to learn more.

::::card-group
::link-card{title="Manage Version" description="Learn how to bump your blocklet's version number according to semantic versioning." icon="tag" href="/en/docs/blocklet-cli/blocklet-workflows-packaging-version-104903/"}
::link-card{title="Deploy Blocklet" description="Find out how to deploy your bundled blocklet directly to a Blocklet Server instance." icon="send" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-deploy-104903/"}
::::

---

## Manage Version

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-packaging-version-104903/

The `blocklet version` command is a convenient utility for updating your blocklet's version number in the `blocklet.yml` file. It follows the rules of semantic versioning (semver) to ensure consistent and predictable version increments. This is a critical step to perform before you package and distribute a new release of your blocklet.

## Usage

The command is run from the root of your blocklet project directory.

**Basic Usage**

```bash
blocklet version [<newversion> | patch | minor | major | prepatch | preminor | premajor | prerelease] [options]
```

## How It Works

The command performs the following actions:

1. Reads the `blocklet.yml` file in the current directory.
2. Parses the `version` field to determine the current version.
3. Calculates the next version based on the argument provided (defaults to `patch`).
4. Updates the `version` field in `blocklet.yml` to the new version.
5. Updates the `specVersion` to the latest version supported by the CLI.

## Version Argument

The command accepts one optional argument to specify the next version. If you omit this argument, it defaults to `patch`.

| Argument  | Description  | Example (from 1.2.3)  |
|---|---|---|
| (none) / `patch`  | Increments the patch version (e.g., for bug fixes).  | `1.2.4`  |
| `minor`  | Increments the minor version (e.g., for new features).  | `1.3.0`  |
| `major`  | Increments the major version (e.g., for breaking changes).  | `2.0.0`  |
| `prepatch`  | Increments the patch version for a pre-release.  | `1.2.4-0`  |
| `prerelease`  | Increments the pre-release identifier.  | from `1.2.4-alpha.0` to `1.2.4-alpha.1`  |
| `<version>`  | Sets a specific, valid version number.  | `3.0.0`  |

## Options

You can modify the command's behavior with the following options:

| Option  | Description  |
|---|---|
| `--gitCommit`  | Automatically adds `blocklet.yml` to Git staging and creates a commit with the message `blocklet version <new_version>`.  |
| `--force`  | Forces the version update even if it results in downgrading the `specVersion`. This is generally not recommended unless you are certain about the change.  |

## Examples

### Increment the Patch Version

If your current version is `1.0.0`, running the command without arguments will bump it to `1.0.1`.

**Basic Patch Update**

```bash
blocklet version

# Output:
# ✔ Blocklet version bumped to 1.0.1
```

### Bump to a New Minor Version

To release a new feature, you can bump the minor version.

**Minor Version Bump**

```bash
blocklet version minor

# Output:
# ✔ Blocklet version bumped to 1.1.0
```

### Set a Specific Version and Commit

You can also set an explicit version number and have the CLI commit the change for you.

**Set Version and Commit**

```bash
blocklet version 2.0.0 --gitCommit

# Output:
# ✔ Blocklet version bumped to 2.0.0
# (Also runs 'git add blocklet.yml' and 'git commit ...')
```

## Versioning in Your Workflow

The `version` command fits into the packaging and distribution workflow after you've completed your code changes and before you create a distributable bundle.

![Manage Version](https://media.arcblock.io/lib/8e/8ee2653f62b15e6e.w1600.webp)

After successfully updating your blocklet's version, you are ready for the next steps in the distribution process.

::::card-group
::link-card{title="Bundle Blocklet" description="Package your blocklet and its assets into a deployable bundle." icon="package" href="/en/docs/blocklet-cli/blocklet-workflows-packaging-bundle-104903/"}
::link-card{title="Deploy Blocklet" description="Deploy a blocklet from your local machine directly to a Blocklet Server instance." icon="send" href="/en/docs/blocklet-cli/blocklet-workflows-distribution-deploy-104903/"}
::::

---

## Project Setup

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-project-setup-104903/

Getting a new blocklet project off the ground is straightforward. The Blocklet CLI provides two primary commands to bootstrap your development environment, depending on whether you're starting from scratch or converting an existing project. These commands help you generate the necessary metadata files, such as `blocklet.yml`, and set up a standard project structure.

Choosing the right command depends on your starting point, as illustrated in the following diagram:

![Project Setup](https://media.arcblock.io/lib/7b/7b93c8faf1c748f9.w1600.webp)

::::card-group
::link-card{title="Create Project" description="Use the `create` command to bootstrap a new project from an official starter template. This is the fastest and recommended way to get a functional blocklet running." icon="package" href="/en/docs/blocklet-cli/blocklet-workflows-project-setup-create-104903/"}
::link-card{title="Initialize Project" description="Use the `init` command to add blocklet metadata to an existing directory, turning it into a valid blocklet project. This is ideal if you already have code you want to package as a blocklet." icon="folder" href="/en/docs/blocklet-cli/blocklet-workflows-project-setup-init-104903/"}
::::

Once your project is set up, you're ready to start building. The next step is to run your blocklet in a local development environment.

Continue to the [Local Development](/en/docs/blocklet-cli/blocklet-workflows-local-development-104903/) section to learn how to run, test, and debug your blocklet.

---

## Create Project

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-project-setup-create-104903/

The `blocklet create` command is the fastest way to start a new Blocklet project. It uses `create-blocklet`, an interactive scaffolding tool that lets you choose from various official starter templates. This command is the recommended method for bootstrapping a new application.

## Usage

The command serves as a convenient wrapper for `npx create-blocklet@latest`.

**Command**

```bash
blocklet create [name] [options]
```

### Arguments

- **[name]** `string` — The name for your new blocklet project. If you omit the name, the interactive setup process will prompt you for one.

## How It Works

Running `blocklet create` initiates an interactive command-line interface that guides you through the setup process. You will be prompted to:

1. Enter a name for your blocklet (if not provided as an argument).
2. Choose a starter template (e.g., React, Vue, Static, etc.).

The tool will then create a new directory with the specified name, download the template, and install the necessary dependencies.

### Examples

To start an interactive session, simply run the command without any arguments:

**Interactive Mode**

```bash
blocklet create
```

If you already have a name in mind, you can provide it directly:

**Direct Mode**

```bash
blocklet create my-awesome-blocklet
```

## Options

- **--did <did>** `string` — Pre-assigns a specific Decentralized Identifier (DID) to the blocklet during creation.
- **--did-only** `boolean` — A special utility mode. This flag does not create a project. Instead, it connects to your DID Wallet to generate and display a new DID suitable for a blocklet. This is useful for creating a DID in advance.

### Generating a Blocklet DID Only

If you only need to create a DID for a future blocklet without starting a new project, use the `--did-only` flag.

**Generate DID**

```bash
blocklet create --did-only
```

This command will connect to your wallet, generate a new DID with the moniker 'blocklet', and print the result to your console.

**Example Output**

```text
Created Blocklet DID: z2...A9
```

## Troubleshooting

Occasionally, issues related to `npx` (the Node.js package runner), such as outdated caches, can cause the `create` command to fail. If you encounter an error, here are a couple of workarounds.

#### 1. Run create-blocklet Directly

You can bypass the `blocklet create` wrapper and execute `create-blocklet` directly using `npx`:

**Direct npx Execution**

```bash
npx create-blocklet@latest my-new-blocklet
```

#### 2. Install Globally

Alternatively, you can install `create-blocklet` globally on your system and then run it.

**Global Installation**

```bash
# Step 1: Install globally
npm install -g create-blocklet

# Step 2: Run the command
create-blocklet my-new-blocklet
```

After creating your project, the next step is to run it in a local development environment. For more information, proceed to the [Develop Mode](/en/docs/blocklet-cli/blocklet-workflows-local-development-dev-mode-104903/) guide.

---

## Initialize Project

URL: https://www.arcblock.io/en/docs/blocklet-cli/blocklet-workflows-project-setup-init-104903/

The `blocklet init` command is an interactive utility that helps you create the fundamental structure for a new blocklet within an existing directory. It generates the core `blocklet.yml` metadata file and other essential boilerplate, turning your current folder into a functional blocklet project.

This command is ideal when you want to start a blocklet from scratch or convert an existing project (e.g., one that already has a `package.json`) into a blocklet. If you prefer to start from a pre-built template, see the [`blocklet create`](/en/docs/blocklet-cli/blocklet-workflows-project-setup-create-104903/) command.

## Interactive Walkthrough

When you run `blocklet init` in your project directory, the CLI will guide you through a series of questions to configure your blocklet's metadata.

**Terminal**

```bash
blocklet init
```

The process looks like this:

```text
This utility will walk you through create such files and folders(if not exists):
- blocklet.yml
- blocklet.md
- screenshots/

It only covers common items, if you want to check all items, please visit:
https://github.com/ArcBlock/blocklets#keyinfo-blockletjson

Press ^C to quit.
? blocklet title: (my-blocklet) my-first-blocklet
? Please write concise description: A new Blocklet project.
? What's the group of the blocklet? dapp
? What's the entry point of the blocklet? (index.js)

Is this OK: (Y/n) Y

Meta file .../my-blocklet/blocklet.yml was created
Doc file .../my-blocklet/blocklet.md was created
Screenshots dir .../my-blocklet/screenshots/ was created
.../my-blocklet/logo.png was created
.../my-blocklet/index.js was created
```

### Prompts Explained

| Prompt  | Description  |
|---|---|
| `title`  | The human-readable name of your blocklet. This is used for display purposes. Defaults to the current directory's name.  |
| `description`  | A brief, one-sentence summary of what your blocklet does.  |
| `group`  | The type or category of the blocklet. The available options are `dapp`, `static`, `api`, and `gateway`.  |
| `main`  | The entry point for your blocklet's code. For `dapp` blocklets, this is typically a script like `index.js`. For `static` blocklets, it's the directory containing your static assets (e.g., `.`).  |

## The Initialization Process

The command performs several key steps to set up your project, including generating a unique Decentralized ID (DID) for your blocklet by connecting to a DID wallet.

![Initialize Project](https://media.arcblock.io/lib/88/88c2dc0df083a3bf.w1600.webp)

## Generated Files

After a successful initialization, you will find the following files and directories in your project:

- <strong>`blocklet.yml`</strong>: The most important file. It contains all the metadata for your blocklet, such as its name (which is its DID), title, description, and version. **blocklet.yml**  ```yaml name: 'z8iZz5de8e9a6f8f2b3c1d9e2f7g2h1i8j3k4l5m' version: '0.1.0' title: 'my-first-blocklet' description: 'A new Blocklet project.' group: 'dapp' main: 'index.js' author: 'Your Name <your.email@example.com>' specVersion: '1.16.0' did: 'z8iZz5de8e9a6f8f2b3c1d9e2f7g2h1i8j3k4l5m' logo: 'logo.png' scripts:   dev: 'node index.js' ```
- <strong>`blocklet.md`</strong>: A placeholder Markdown file for your blocklet's detailed documentation and description, which will be displayed in the Blocklet Store.
- <strong>`screenshots/`</strong>: An empty directory where you can place screenshots of your blocklet for display in a blocklet store.
- <strong>`logo.png`</strong>: A default logo image for your blocklet. ![Default Blocklet Logo](https://media.arcblock.io/lib/a3/a3422f38fcb4d477.w1600.webp)
- <strong>Entry Point File</strong>: Depending on the `group` you selected:
-
  - For `dapp`, an `index.js` is created with a simple Node.js HTTP server. **index.js**  ```javascript const http = require('http');  const server = http.createServer((req, res) => {   res.statusCode = 200;   res.setHeader('Content-Type', 'text/plain');   res.end('Hello Blocklet\n'); });  const port = process.env.BLOCKLET_PORT || 3000;  server.listen(port, () => {   // eslint-disable-next-line no-console   console.log(`Server running at http://127.0.0.1:${3000}/`); }); ```
  - For `static`, an `index.html` is created. **index.html**  ```html <!DOCTYPE html> <html> <head>     <title>Hello Blocklet</title> </head> <body>     <h1>Hello Blocklet</h1> </body> </html> ```
- <strong>`.gitignore`</strong>: A basic `.gitignore` file is added to prevent common build artifacts and dependencies from being committed to version control.

## Command Options

You can modify the behavior of `blocklet init` with the following flags.

| Option  | Alias  | Description  |
|---|---|---|
| `--yes`  | `-y`  | Skips the interactive prompt and accepts all default values. This is useful for scripting.  |
| `--force`  | `-f`  | An alias for `--yes`.  |
| `--did <did>`  |  | Provide a specific Blocklet DID to use, skipping the automatic generation step.  |

### Example: Non-interactive Initialization

To quickly initialize a project without answering prompts, use the `-y` flag. The command will use defaults derived from your `package.json` (if it exists) or the directory name.

**Terminal**

```bash
blocklet init -y
```

Once your project is initialized, you're ready to start building. The next step is to run your blocklet in a local development environment.

:::action-card{title="Next: Develop Mode" description="Learn how to run your blocklet in a live-reloading development server." icon="arrow-right"}
::action{label="Learn More" href="/en/docs/blocklet-cli/blocklet-workflows-local-development-dev-mode-104903/" variant="primary"}
:::

---

## Command Reference

URL: https://www.arcblock.io/en/docs/blocklet-cli/command-reference-104903/

The Blocklet CLI provides a comprehensive set of commands to manage both your Blocklet Server instances and individual blocklet projects. This reference is divided into two main categories, helping you quickly find the commands you need for your specific task.

::::card-group
:::action-card{title="blocklet server" description="Commands for installing, starting, stopping, and managing the lifecycle of your Blocklet Server instance." icon="server"}
::action{label="View Server Commands" href="/en/docs/blocklet-cli/command-reference-server-104903/" variant="primary"}
:::
:::action-card{title="blocklet" description="Commands for creating, developing, bundling, and deploying individual blocklet applications and components." icon="box"}
::action{label="View Blocklet Commands" href="/en/docs/blocklet-cli/command-reference-blocklet-104903/" variant="primary"}
:::
::::

## Global Options

Some options can be applied globally to most `blocklet` commands.

| Option  | Alias  | Description  |
|---|---|---|
| `--yes`  | `-y`  | Automatically answers "yes" to any confirmation prompts, allowing for non-interactive script execution.  |
| `--version`  | `-V`  | Displays the currently installed version of the Blocklet CLI.  |
| `--help`  | `-h`  | Displays help information for a specific command or for the CLI in general.  |

Now, dive into the specific command sets to find detailed usage, arguments, and options for your task.

---

## blocklet

URL: https://www.arcblock.io/en/docs/blocklet-cli/command-reference-blocklet-104903/

The `blocklet` command is the primary interface for managing the entire lifecycle of a Blocklet project. It provides a comprehensive suite of subcommands for initializing, developing, bundling, deploying, and managing blocklets and their components.

## Global Options

- **-y, --yes** `boolean` (default: `false`) — Automatically answer yes to any interactive prompts. This is useful for scripting and automation.

## Project Setup

Commands to bootstrap and initialize new Blocklet projects.

### blocklet create

Bootstrap a new Blocklet project from various starter templates.

<strong>Usage</strong>

```bash
blocklet create [name] [options]
```

<strong>Arguments</strong>

- **[name]** `string` — The name for the new blocklet project. If omitted, you will be prompted to enter one.

<strong>Options</strong>

- **--did <did>** `string` — Specify a pre-existing DID for the new blocklet.
- **--did-only** `boolean` — Only create a blocklet DID without creating a project.

### blocklet init

Initialize an empty Blocklet project in the current directory. This command creates the `blocklet.yml` file and essential project structure.

<strong>Usage</strong>

```bash
blocklet init [options]
```

<strong>Options</strong>

- **--did [did]** `string` — Specify a pre-existing DID for the blocklet.
- **-f, --force** `boolean` (default: `false`) — Initialize the project without any interactive prompts.
- **--monikers <monikers>** `string` — Custom moniker for DID creation. Use commas to separate multiple values.
- **--connectUrl <connectUrl>** `string` — A connect URL to assist in DID generation.

## Local Development

Commands for running, testing, and debugging your blocklet in a local environment.

### blocklet dev

Run the blocklet in development mode from the current directory, connecting it to the local Blocklet Server.

<strong>Usage</strong>

```bash
blocklet dev [subcommand] [options]
```

<strong>Options</strong>

- **--open** `boolean` (default: `false`) — Open the browser after the blocklet has started.
- **--app-id <did>** `string` — Develop the blocklet as a component and mount it to the specified application DID.
- **--mount-point <mountPoint>** `string` — Specify the mount point within the parent application.
- **--store-url <storeUrl>** `string` — Default store URL to use when a component's source store is not declared.
- **--start-all-components** `boolean` (default: `false`) — Automatically start all components within the blocklet.

<strong>Subcommands</strong>

| Command  | Description  |
|---|---|
| `install`  | Install the development mode blocklet.  |
| `start`  | Start the development blocklet after it has been installed. Supports `--e2e` option.  |
| `remove`  | Remove the development mode blocklet.  |
| `studio`  | Start the Blocklet Studio.  |
| `reset`  | Reset the blocklet's data. Alias: `clear`.  |
| `faucet`  | Fund your app with test tokens from a faucet. Supports `--host` and `--token` options.  |

### blocklet test

Set up and manage a test environment for your blocklet.

<strong>Usage</strong>

```bash
blocklet test [subcommand] [options]
```

<strong>Subcommands</strong>

| Command  | Description  |
|---|---|
| `init`  | Initialize a new blocklet for testing. Supports `--app-sk`, `--owner-sk`, `--app-name` options.  |
| `start`  | Start the test blocklet. Supports `--app-sk` option.  |
| `remove`  | Completely delete the test blocklet. Supports `--app-sk` option.  |
| `reset`  | Reset the state of the test blocklet. Supports `--app-sk` option.  |

### blocklet exec

Execute a script within the running context of a blocklet.

<strong>Usage</strong>

```bash
blocklet exec <script> [options]
```

<strong>Arguments</strong>

- **<script>** `string` *(required)* — The path to the script to execute.

<strong>Options</strong>

- **--app-id <did>** `string` — Execute the script within the context of the specified running application.
- **--timeout <timeout>** `number` — Maximum time in seconds for the script to run.

### blocklet debug

Set the `DEBUG` environment variable for a blocklet.

<strong>Usage</strong>

```bash
blocklet debug <value> [options]
```

<strong>Arguments</strong>

- **<value>** `string` *(required)* — The debug string to set (e.g., `*`, `my-app:*`).

<strong>Options</strong>

- **--app-id <did>** `string` — Set the debug configuration for the specified application.

## Component Management

Commands for managing component dependencies within your blocklet.

### blocklet add

Add a component as a dependency to your `blocklet.yml` file.

<strong>Usage</strong>

```bash
blocklet add <component> [options]
```

<strong>Arguments</strong>

- **<component>** `string` *(required)* — The component to add (e.g., `component-name@1.0.0` or a URL).

<strong>Options</strong>

- **--profile <profile>** `string` (default: `default`) — The configuration profile to use.
- **--store <store>** `string` — Specify the store from which to fetch the component.
- **--title <title>** `string` — Custom title for the component.
- **--mount-point <mountPoint>** `string` — The mount point for the component.

### blocklet remove

Remove a component dependency from your `blocklet.yml` file.

<strong>Usage</strong>

```bash
blocklet remove <component>
```

<strong>Arguments</strong>

- **<component>** `string` *(required)* — The name of the component to remove.

### blocklet component

Execute commands from the Component Studio CLI.

<strong>Usage</strong>

```bash
blocklet component [command...]
```

This command acts as a proxy, passing all subsequent arguments to the `@blocklet/component-studio-cli`.

## Packaging & Versioning

Commands to prepare your blocklet for distribution.

### blocklet bundle

Package your blocklet and its assets into a deployable bundle.

<strong>Usage</strong>

```bash
blocklet bundle [options]
```

<strong>Options</strong>

- **--zip** `boolean` (default: `true`) — Bundle using zip mode (default).
- **--simple** `boolean` (default: `false`) — Bundle using simple mode.
- **--compact** `boolean` (default: `false`) — Bundle using compact mode, including all dependencies.
- **--dependencies-depth <number>** `number` (default: `9`) — The depth of dependencies to include in the bundle.
- **--source-map** `boolean` (default: `false`) — Create a source map (compact mode only).
- **--nosources-source-map <boolean>** `boolean` (default: `false`) — Create a source map without including sources content (compact mode only).
- **--minify / --no-minify** `boolean` (default: `true`) — Enable or disable minification in compact mode.
- **--external <items>** `string` — Comma-separated list of external dependencies to exclude from the bundle.
- **--create-release** `boolean` (default: `false`) — Create a release tarball and metadata for the bundled blocklet.
- **--create-archive** `boolean` (default: `false`) — Create an archive *.zip file for the bundled blocklet.
- **--monorepo** `boolean` (default: `false`) — Bundle a blocklet that is part of a monorepo.
- **--changelog / --no-changelog** `boolean` (default: `true`) — Include or exclude CHANGELOG.md in the bundle.
- **--store-url <storeUrl>** `string` — Default store URL to use when a component's source store is not declared.

### blocklet version

Bump the blocklet's version in `blocklet.yml`.

<strong>Usage</strong>

```bash
blocklet version [newVersion] [options]
```

<strong>Arguments</strong>

- **[newVersion]** `string` (default: `patch`) — The new version or the type of increment (e.g., `1.2.3`, `major`, `minor`, `patch`).

<strong>Options</strong>

- **--git-commit** `boolean` — Create a git commit after bumping the version.
- **-f, --force** `boolean` — Force the version bump, even if it's a downgrade.

## Distribution

Commands for deploying your blocklet to a server or uploading it to a store.

### blocklet deploy

Deploy a blocklet from a local directory to a Blocklet Server instance.

<strong>Usage</strong>

```bash
blocklet deploy <folder> [options]
```

<strong>Arguments</strong>

- **<folder>** `string` *(required)* — The directory containing the bundled blocklet.

<strong>Options</strong>

- **--endpoint <host>** `string` — The endpoint of the remote Blocklet Server dashboard (e.g., `http://127.0.0.1/admin`).
- **--access-key <key>** `string` — Access key for the remote Blocklet Server.
- **--access-secret <secret>** `string` — Access secret for the remote Blocklet Server.
- **--app-id <did>** `string` — The application DID to which the component will be mounted.
- **--mount-point <mountPoint>** `string` — The mount point within the application.
- **--incremental** `boolean` (default: `false`) — Deploy only the files that have changed since the previous version.

### blocklet upload

Upload a bundled blocklet to a Blocklet Store.

<strong>Usage</strong>

```bash
blocklet upload [metafile] [options]
```

<strong>Arguments</strong>

- **[metafile]** `string` — Path to the blocklet's release metadata file (e.g., `.blocklet/release/blocklet.json`).

<strong>Options</strong>

- **--profile <profile>** `string` (default: `default`) — The configuration profile to use.
- **--access-token <accessToken>** `string` — Access token for the Blocklet Store.

### blocklet connect

Connect and authenticate the CLI with a Blocklet Store.

<strong>Usage</strong>

```bash
blocklet connect <store-url> [options]
```

<strong>Arguments</strong>

- **<store-url>** `string` *(required)* — The URL of the Blocklet Store.

<strong>Options</strong>

- **--profile <profile>** `string` (default: `default`) — The configuration profile to use for storing the connection details.

## Utilities

Helper commands for managing configurations and metadata.

### blocklet config

Manage the local configuration for the Blocklet CLI.

<strong>Usage</strong>

```bash
blocklet config [subcommand] [key] [value]
```

<strong>Subcommands</strong>

| Command  | Description  |
|---|---|
| `set [key] [value]`  | Set a configuration value.  |
| `get [key]`  | Get a configuration value.  |
| `delete [key]`  | Delete a configuration value.  |
| `list`  | List all configuration values. Alias: `ls`.  |

### blocklet meta

Parse and print the `blocklet.yml` metadata from the current directory.

<strong>Usage</strong>

```bash
blocklet meta
```

### blocklet document

Manage the DID document for a blocklet.

<strong>Usage</strong>

```bash
blocklet document update <app-id>
```

<strong>Subcommands</strong>

| Command  | Description  |
|---|---|
| `update <app-id>`  | Update the DID document for the specified blocklet.  |

### blocklet cleanup

Perform cleanup tasks for a specific blocklet.

<strong>Usage</strong>

```bash
blocklet cleanup [options]
```

<strong>Options</strong>

- **--target <target>** `string` — The target to clean up. Available options: `cache`, `backup`.
- **--app-did <did>** `string` — The DID of the blocklet to clean up.

---

## blocklet server

URL: https://www.arcblock.io/en/docs/blocklet-cli/command-reference-server-104903/

The `blocklet server` command is the primary tool for managing the lifecycle and configuration of your Blocklet Server instance. It allows you to initialize, start, stop, and monitor the server and all the blocklets running on it. These commands are essential for server administrators and developers who are self-hosting Blocklet Server.

For managing individual blocklets (e.g., creating, developing, deploying), see the [`blocklet` command reference](/en/docs/blocklet-cli/command-reference-blocklet-104903/).

## Usage

**Basic Usage**

```bash
blocklet server <command> [options]
```

## Global Options

These options can be used with any `blocklet server` subcommand.

- **-c, --config [node-config]** `string` — Specifies the path to the Blocklet Server configuration file.
- **-y, --yes** `boolean` (default: `false`) — Automatically answers 'yes' to any prompts, useful for scripting.

## Commands

### init

Initializes a new Blocklet Server configuration in the current directory. This command creates the necessary files and folders, including the main `config.yml` file.

#### Usage

```bash
blocklet server init [options]
```

#### Options

- **-f, --force** `boolean` (default: `false`) — Initialize a Blocklet Server instance without asking any questions, accepting all default values.
- **-i, --interactive** `boolean` (default: `false`) — Run in interactive mode to customize the configuration. This is ignored if `--force` is used.
- **--mode <mode>** `string` (default: `production`) — Sets the initial server mode. Allowed values are `production` and `debug`.
- **--https** `boolean` (default: `true`) — Enable default HTTPS support for the dashboard and blocklets.
- **--no-https** `boolean` — Disable default HTTPS support.
- **--sk <custom-sk>** `string` — Provide a custom secret key for the Blocklet Server.
- **--web-wallet-url <url>** `string` — Specify a custom web wallet URL.
- **--http-port <httpPort>** `number` (default: `80`) — Set the HTTP port for the service gateway.
- **--https-port <httpsPort>** `number` (default: `443`) — Set the HTTPS port for the service gateway.
- **--owner-nft-holder <ownerNftHolderDid>** `string` — The DID of the account that holds the ownership NFT.
- **--owner-nft-issuer <ownerNftIssuerDid>** `string` — The DID of the account that issued the ownership NFT.
- **--trusted-passport-issuer <passportIssuerDid>** `string` — The DID of a passport issuer that is trusted by this node.
- **--disable-passport-issuance** `boolean` (default: `false`) — Disable the issuance of passports by this node.

### start

Starts the Blocklet Server as a background daemon process based on the configuration in the current directory.

#### Usage

```bash
blocklet server start [options]
```

#### Options

- **-u, --update-db** `boolean` — Update the Blocklet Server database with the latest settings from the config file.
- **--update-blocklet-env** `boolean` (default: `false`) — Update the environments for all installed blocklets.
- **-k, --keep-alive** `boolean` (default: `false`) — Keep the command running without exiting after the server starts successfully.
- **-a, --auto-init** `boolean` (default: `false`) — If a configuration directory does not exist, initialize it automatically before starting.
- **-m, --force-mode <forceMode>** `string` — Force the server to start in a specified mode (e.g., `production`, `debug`, `maintenance`).
- **--force-intranet** `boolean` (default: `false`) — Force the server to run in intranet mode, ignoring any external IP addresses.

### stop

Stops the running Blocklet Server and all associated blocklet processes gracefully.

#### Usage

```bash
blocklet server stop [options]
```

#### Options

- **-f, --force** `boolean` (default: `false`) — Forcefully stop all Blocklet Server related processes immediately.

### status

Checks and displays the current status of the Blocklet Server, including its mode, data directory, and the status of all installed blocklets.

#### Usage

```bash
blocklet server status [options]
```

#### Options

- **--force-intranet** `boolean` (default: `false`) — Force status check to use intranet mode, ignoring any external IP addresses.

### logs

Shows the file paths for Blocklet Server and individual blocklet log files for easy access and debugging.

#### Usage

```bash
blocklet server logs
```

### upgrade

Upgrades the Blocklet Server CLI to the latest available version from the npm registry.

#### Usage

```bash
blocklet server upgrade
```

### info

Gathers and displays environment information useful for debugging and reporting issues. This includes OS, binaries (Node, npm), server configuration, and network details.

#### Usage

```bash
blocklet server info [options]
```

#### Options

- **-C, --clipboard** `boolean` (default: `false`) — Automatically copy the environment information to the clipboard.

### cleanup

Performs various server-level cleanup tasks.

#### Usage

```bash
blocklet server cleanup [options]
```

#### Options

- **--target <target>** `string` *(required)* — Specifies the cleanup target. Available options are: cache, maintenance-status, blacklist, blacklist-expired.

### migrate

Migrates the Blocklet Server database from one system to another. Currently supports migration from SQLite to PostgreSQL.

#### Usage

```bash
blocklet server migrate [options]
```

#### Options

- **--dialect <dialect>** `string` *(required)* — The database dialect to migrate to. Available options are sqlite and postgres.

### nginx

Configures Nginx as a reverse proxy for Blocklet Server. This is useful for production environments where Nginx can handle tasks like SSL termination and load balancing.

#### Usage

```bash
blocklet server nginx [options]
```

#### Options

- **--setup** `boolean` — Set up the Nginx environment for Blocklet Server. This typically requires sudo privileges.

---

## Configuration

URL: https://www.arcblock.io/en/docs/blocklet-cli/configuration-104903/

Proper configuration is essential for both running a Blocklet Server instance and for interacting with it and other services using the Blocklet CLI. This guide focuses on the local CLI settings that you, as a developer, will use to connect to Blocklet Stores and manage your development environment. These settings are managed using the `blocklet config` command.

For details on the server's primary configuration file, `config.yml`, please see the [Initialize Server](/en/docs/blocklet-cli/server-management-init-104903/) documentation.

## Managing CLI Settings with blocklet config

The `blocklet config` command set allows you to view, set, and remove configuration values stored in a local INI file. This is particularly useful for setting up your connection to a Blocklet Store for deploying and uploading blocklets.

### View Current Configuration

To see all your current configuration settings, you can run `blocklet config` without any arguments, or use the `list` subcommand.

**list configuration**

```bash
blocklet config list
```

This will output all the key-value pairs for the current profile.

<strong>Example Output:</strong>

**Example Output**

```ini
store="https://store.blocklet.dev/"
developerDid="z123..."
name="John Doe"
email="john.doe@example.com"
```

### Set a Configuration Value

Use the `set` subcommand to add or update a configuration key.

**set configuration**

```bash
blocklet config set <key> <value>
```

<strong>Example:</strong>

**Set store URL**

```bash
blocklet config set store https://store.blocklet.dev
```

### Get a Specific Value

If you only need to retrieve the value for a single key, use the `get` subcommand.

**get configuration**

```bash
blocklet config get <key>
```

<strong>Example:</strong>

**Get store URL**

```bash
blocklet config get store
```

### Remove a Configuration Value

To delete a key from your configuration, use `unset`, `del`, or `delete`.

**unset configuration**

```bash
blocklet config unset <key>
```

<strong>Example:</strong>

**Unset developer email**

```bash
blocklet config unset email
```

## Available Configuration Keys

The following keys can be managed via the `blocklet config` command:

| Key  | Description  |
|---|---|
| `store`  | The base URL of the Blocklet Store you want to interact with for uploading or deploying blocklets. Must be a valid HTTPS or HTTP URL.  |
| `registry`  | An alias for `store`.  |
| `accessToken`  | The secret key used to authenticate your CLI with the Blocklet Store. You typically get this by running `blocklet connect`.  |
| `developerDid`  | Your unique Decentralized Identifier (DID) as a developer.  |
| `name`  | Your developer name associated with your DID.  |
| `email`  | Your developer email associated with your DID.  |

## Using Profiles

Profiles allow you to manage multiple, separate sets of configurations. This is useful for switching between different environments, such as a development store and a production store. By default, all configurations are saved to the `default` profile.

To use a specific profile, add the `--profile <profile-name>` flag to any `blocklet config` command.

<strong>Example: Setting a value for a 'staging' profile</strong>

```bash
blocklet config set store https://staging.store.example.com --profile staging
```

<strong>Example: Listing values for the 'staging' profile</strong>

```bash
blocklet config list --profile staging
```

## Configuration File Location

The CLI settings are stored in an INI-formatted file. The CLI searches for a `.abtnode/conf/config.ini` file starting from the current directory and moving up through its ancestors.

You can override this behavior and specify an exact file path by setting the `ABT_NODE_CONFIG_FILE` environment variable.

While you can manage these settings manually, the recommended way to configure your connection to a store is by using the [`blocklet connect`](/en/docs/blocklet-cli/blocklet-workflows-distribution-connect-104903/) command, which handles the authentication flow and saves the necessary credentials for you.

---

## Environment Variables

URL: https://www.arcblock.io/en/docs/blocklet-cli/environment-variables-104903/

Environment variables provide a powerful way to configure Blocklet Server and the blocklets it runs. They override default settings and values from configuration files, making them ideal for tailoring your setup across different environments like development, staging, and production.

### Configuration Priority

Blocklet Server applies settings in a specific order of precedence, with later sources overriding earlier ones:

::::steps
:::step{title="Default Values"}
The built-in default settings for the server.
:::

:::step{title="Configuration File"}
Settings defined in your `config.yml` file.
:::

:::step{title="Environment Variables"}
The highest priority. Any `ABT_NODE_*` variable you set will take precedence over the other sources.
:::
::::

## Blocklet-Specific Environments

Individual blocklets can define their own required environment variables in their `blocklet.yml` manifest. When you run a blocklet in development mode (e.g., using `blocklet dev`), you can provide these variables by creating a `.env` file in the blocklet's root directory.

Blocklet Server uses `dotenv-flow` to load these files, which means you can use a cascade of files like `.env`, `.env.development`, and `.env.local` to manage environment-specific configurations. If any required variables are missing when you start the blocklet, the CLI will prompt you to enter them.

## Blocklet Server Environment Variables

All environment variables that control the core Blocklet Server daemon are prefixed with `ABT_NODE_`. The following sections provide a comprehensive reference for these variables, grouped by category.

### Network and Ports

These variables configure the network interfaces and ports that Blocklet Server and its components use.

| Variable  | Purpose  | Default  |
|---|---|---|
| `ABT_NODE_PORT`  | Main port where the Blocklet Server daemon listens.  | `8089`  |
| `ABT_NODE_SERVICE_PORT`  | Port for internal service communication.  | `40404`  |
| `ABT_NODE_BLOCKLET_PORT`  | Starting port for blocklet applications.  | `8090`  |
| `ABT_NODE_HTTP_PORT`  | HTTP port for the gateway/router.  | `80`  |
| `ABT_NODE_HTTPS_PORT`  | HTTPS port for the gateway/router.  | `443`  |
| `ABT_NODE_ROUTER_HTTP_PORT`  | HTTP port specifically for the router provider.  | Same as `ABT_NODE_HTTP_PORT`  |
| `ABT_NODE_ROUTER_HTTPS_PORT`  | HTTPS port specifically for the router provider.  | Same as `ABT_NODE_HTTPS_PORT`  |
| `ABT_NODE_UPDATER_PORT`  | Port for the updater service.  | `40405`  |
| `ABT_NODE_EVENT_PORT`  | Port for event hub communication.  | `40407`  |
| `ABT_NODE_HOST`  | Host address for the server to bind to.  | `0.0.0.0`  |

### Authentication and Security

Manage access control, sessions, DIDs, and security policies.

| Variable  | Purpose  | Default / Notes  |
|---|---|---|
| `ABT_NODE_DID`  | Decentralized Identifier for the server instance.  | System-generated  |
| `ABT_NODE_PK`  | Public key for the server's DID.  | System-generated  |
| `ABT_NODE_SK`  | Secret key for the server's DID.  | System-generated (keep secure)  |
| `ABT_NODE_SESSION_SECRET`  | Secret key for session encryption.  | System-generated  |
| `ABT_NODE_TOKEN_SECRET`  | Secret key for JWT token signing.  | System-generated  |
| `ABT_NODE_SESSION_TTL`  | Session time-to-live in seconds.  | `3600` (1 hour)  |
| `ABT_NODE_SESSION_CACHE_TTL`  | Session cache time-to-live in seconds.  | `300` (5 minutes)  |
| `ABT_NODE_ADMIN_PATH`  | Path prefix for the admin dashboard.  | `/.well-known/service/admin`  |
| `ABT_NODE_IP_WHITELIST`  | Comma-separated list of IP addresses allowed to access admin.  | None (all IPs allowed)  |
| `ABT_NODE_DOMAIN_WHITELIST`  | Comma-separated list of domains allowed for CORS.  | None  |
| `ABT_NODE_DOMAIN_BLACKLIST`  | Comma-separated list of domains to block.  | None  |
| `ABT_NODE_DOMAIN_WHITELIST_HEADERS`  | Additional headers to include in CORS whitelist responses.  | None  |
| `ABT_NODE_NO_PASSKEY_USER_VERIFY`  | Disable passkey user verification. Set to `1` to disable.  | `0` (enabled)  |

### Database and Storage

Configure database connections and caching mechanisms.

| Variable  | Purpose  | Default / Notes  |
|---|---|---|
| `ABT_NODE_POSTGRES_URL`  | PostgreSQL connection URL.  | Uses SQLite if not specified.  |
| `ABT_NODE_CACHE_SQLITE_PATH`  | Path to SQLite cache database file.  | `{DATA_DIR}/core/db-cache.db`  |
| `ABT_NODE_CACHE_REDIS_URL`  | Redis connection URL for caching.  | None (uses in-memory cache)  |
| `ABT_NODE_SQLITE_LARGE_CACHE`  | Enable large cache for SQLite. Set to `1` to enable.  | `0` (disabled)  |
| `ABT_NODE_NO_CACHE`  | Disable caching entirely. Set to `1` to disable.  | `0` (enabled)  |
| `ABT_NODE_IGNORE_USE_POSTGRES`  | Force use of SQLite even if PostgreSQL is configured. Set to `1`.  | `0`  |
| `ABT_NODE_IGNORE_RESTART_POSTGRES`  | Skip restarting PostgreSQL during startup. Set to `1`.  | `0`  |

### Docker Configuration

Customize the behavior of blocklets that run in Docker containers.

| Variable  | Purpose  | Default  |
|---|---|---|
| `ABT_NODE_NOT_ALLOW_DOCKER`  | Disable Docker support entirely. Set to `1` to disable.  | `0` (enabled)  |
| `ABT_NODE_DOCKER_MEMORY`  | Default memory limit for Docker containers.  | `512m`  |
| `ABT_NODE_DOCKER_CPUS`  | Default CPU limit for Docker containers.  | `1`  |
| `ABT_NODE_DOCKER_DISK_SIZE`  | Default disk size limit for Docker containers.  | `10g`  |
| `ABT_NODE_SKIP_DOCKER_CHOWN`  | Skip chown operations in Docker containers. Set to `1` to skip.  | `0`  |
| `ABT_NODE_TEST_DOCKER`  | Enable Docker testing mode. Set to `1` to enable.  | `0`  |

### Logging and Debugging

Control logging levels, locations, and enable debugging modes.

| Variable  | Purpose  | Default / Values  |
|---|---|---|
| `ABT_NODE_LOG_DIR`  | Directory for log files.  | `{DATA_DIR}/logs/_abtnode`  |
| `ABT_NODE_LOG_NAME`  | Name of the log file.  | `daemon`  |
| `ABT_NODE_LOG_LEVEL`  | Logging level.  | `info` (Values: `error`, `warn`, `info`, `debug`)  |
| `ABT_NODE_DEBUG_AS_SERVERLESS`  | Enable serverless debugging mode. Set to `1` to enable.  | `0`  |
| `ABT_NODE_DEV_MODE`  | Enable development mode with additional debugging. Set to `1` to enable.  | `0`  |

### Performance and Limits

Tune performance parameters and set operational limits.

| Variable  | Purpose  | Default  |
|---|---|---|
| `ABT_NODE_MAX_CLUSTER_SIZE`  | Maximum number of cluster instances.  | `4`  |
| `ABT_NODE_JOB_BACKOFF_SECONDS`  | Backoff time for job scheduling in seconds.  | `600` (10 minutes)  |
| `ABT_NODE_BLACKLIST_REFRESH_INTERVAL`  | Interval for refreshing blacklist in minutes.  | `2`  |
| `ABT_NODE_EMAIL_RATE_LIMIT`  | Rate limit for email operations per minute.  | `10`  |
| `ABT_NODE_EMAIL_VERIFY_RATE_LIMIT`  | Rate limit for email verification per minute.  | `5`  |
| `ABT_NODE_ENSURE_RUNNING_CHECK_INTERVAL`  | Interval for checking running blocklets in milliseconds.  | `30000` (30 seconds)  |
| `ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_CPU`  | CPU threshold (%) for high load detection.  | `80`  |
| `ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_MEMORY`  | Memory threshold (%) for high load detection.  | `80`  |
| `ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_DISK`  | Disk threshold (%) for high load detection.  | `90`  |
| `ABT_NODE_ENABLE_ENSURE_BLOCKLET_RUNNING`  | Enable automatic blocklet running assurance. Set `0` to disable.  | `1`  |

### Domain and Routing

Configure how Blocklet Server handles domains, certificates, and routing.

| Variable  | Purpose  | Default / Values  |
|---|---|---|
| `ABT_NODE_DID_DOMAIN`  | Domain for DID-based routing.  | Auto-detected  |
| `ABT_NODE_SLP_DOMAIN`  | Domain for SLP (Service Location Protocol).  | Auto-detected  |
| `ABT_NODE_DASHBOARD_DOMAIN`  | Domain for the admin dashboard.  | Auto-detected  |
| `ABT_NODE_WILDCARD_CERT_HOST`  | Host for downloading wildcard certificates.  | `https://releases.arcblock.io/certs`  |
| `ABT_NODE_ENABLE_SLP_DOMAIN`  | Enable SLP domain support. Set to `1` to enable.  | `0`  |
| `ABT_NODE_ENABLE_IPV6`  | Enable IPv6 support. Set to `1` to enable.  | `0`  |
| `ABT_NODE_FORCE_INTRANET`  | Force intranet mode. Set to `1` to enable.  | `0`  |
| `ABT_NODE_ROUTER_PROVIDER`  | Router provider implementation.  | `nginx` (Values: `nginx`, `nodejs`)  |
| `ABT_NODE_ROUTER_CONFIG`  | Path to an additional router configuration file.  | None  |

### External Services

Configure endpoints for external services that Blocklet Server interacts with.

| Variable  | Purpose  | Default  |
|---|---|---|
| `ABT_NODE_WEB_WALLET_URL`  | URL for the web wallet service.  | `https://web.abtnetwork.io`  |
| `ABT_NODE_DID_REGISTRY`  | DID registry endpoint.  | `https://registry.arcblock.io`  |
| `ABT_NODE_LAUNCHER_DID`  | DID of the launcher service.  | Auto-configured  |
| `ABT_NODE_BLOCKLET_LAUNCHER_URL`  | Address for node registration.  | Auto-detected  |
| `ABT_NODE_EVENT_HOSTNAME`  | Hostname for the event hub.  | `localhost`  |

### Development and Testing

Variables primarily used for development, testing, and debugging purposes.

| Variable  | Purpose  | Default / Notes  |
|---|---|---|
| `ABT_NODE_SKIP_VERSION_CHECK`  | Skip version compatibility checks. Set to `1` to skip.  | `0`  |
| `ABT_NODE_TEST_DNS_SERVER`  | DNS server for testing.  | None  |
| `ABT_NODE_TEST_MIN_CONSECUTIVE_TIME`  | Minimum consecutive time for test runs in milliseconds.  | `1000`  |
| `ABT_NODE_MOCK_DID_NAMES`  | Mock DID names for testing (comma-separated).  | None  |
| `ABT_NODE_FAKE_DISK_INFO`  | Use fake disk information for testing. Set to `1` to enable.  | `0`  |

### System-Generated Variables

These variables are set automatically by the system at runtime. You should not configure them manually as their values are derived from the system's state and context.

| Variable  | Purpose  |
|---|---|
| `ABT_NODE_BINARY_NAME`  | Name of the CLI binary.  |
| `ABT_NODE_COMMAND_NAME`  | Name of the CLI command being executed.  |
| `ABT_NODE_PACKAGE_NAME`  | NPM package name for the server.  |
| `ABT_NODE_VERSION`  | Version of the Blocklet Server.  |
| `ABT_NODE_RESTART_RUNNING_COMPONENT`  | Flag indicating component restart status.  |
| `ABT_NODE_OWNER_NFT_HOLDER`  | NFT holder information for ownership.  |
| `ABT_NODE_OWNER_NFT_ISSUER`  | NFT issuer information for ownership.  |
| `ABT_NODE_BLOCKLET_MODE`  | Current blocklet mode.  |
| `ABT_NODE_KERNEL_MODE`  | Current kernel mode.  |

## Security Considerations

When configuring your Blocklet Server, keep the following security best practices in mind:

- <strong>Secure Secrets</strong>: Always use strong, randomly generated values for secret keys like `ABT_NODE_SESSION_SECRET` and `ABT_NODE_SK`.
- <strong>Limit Access</strong>: Restrict file system access to the data directory and any configuration files to authorized users only.
- <strong>Use Management Tools</strong>: For production deployments, consider using a dedicated tool for managing environment variables to avoid exposing secrets in shell history or plain text files.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-cli/getting-started-104903/

This guide will walk you through the essential steps to get your first Blocklet Server instance up and running. In just a few minutes, you'll go from installation to a fully functional server.

## Prerequisites

Before you begin, ensure you have Node.js installed on your system. Blocklet Server requires a specific version of Node.js to function correctly. Please refer to the `engines` field in the project's `package.json` for the exact version requirement.

## Step 1: Install the Blocklet CLI

The first step is to install the Blocklet Command Line Interface (CLI) globally using npm. This tool provides all the necessary commands to manage your server and blocklets.

Open your terminal and run the following command:

**Install Blocklet CLI**

```bash
npm install -g @blocklet/cli
```

Once the installation is complete, you can verify it by checking the version:

**Verify Installation**

```bash
blocklet --version
```

## Step 2: Initialize Your Server

Now that the CLI is installed, you need to create a configuration for your Blocklet Server. This is done using the `server init` command.

1. Create a new directory for your server and navigate into it: **Create Server Directory**  ```bash mkdir my-blocklet-server cd my-blocklet-server ```
2. Run the initialization command: **Initialize Server**  ```bash blocklet server init ```

This command will launch an interactive setup wizard that guides you through the configuration process. You'll be asked for basic information such as the server's name, description, and port.

**Interactive Setup Example**

```text
? Naming the server? my-node
? Description of the server? My first Blocklet Server instance
? Which port do you want your server to listen on? 3030
? Choose routing engine (Use arrow keys)
❯ nginx
  caddy
  none
...
```

Upon completion, a new `.blocklet-server` directory will be created, containing your `config.yml` file and other necessary server data.

## Step 3: Start the Server

With the configuration in place, you can now start the server. The `server start` command launches all necessary background processes, including the main daemon and services.

**Start the Server**

```bash
blocklet server start
```

After a few moments, the server will be running. The console will display the access URLs for your server's dashboard, which you can use to manage your server from a web browser.

**Successful Start Output**

```text
...✅ Blocklet Server daemon started successfully!

ℹ Your Blocklet Server is running at the following URLs:
  - http://192.168.1.100/admin/
  - http://127.0.0.1/admin/
```

### All-in-One Command

For a faster setup, you can combine initialization and startup into a single command using the `--auto-init` flag. This is perfect for development or testing environments as it initializes the server with default settings and starts it immediately.

**Auto-Initialize and Start**

```bash
# Make sure you are in an empty directory
blocklet server start --auto-init
```

This command will automatically create the configuration with sensible defaults and proceed to start the server, printing the access URLs once it's ready.

Congratulations! Your Blocklet Server is now installed and running. You can now proceed to the [Server Management](/en/docs/blocklet-cli/server-management-104903/) section to learn how to stop, check the status, and further manage your instance.

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-cli/overview-104903/

The Blocklet CLI is your primary tool for managing Blocklet Server and developing blocklets. It provides a comprehensive set of commands to handle everything from local development and testing to packaging and deploying your applications.

Its commands are organized into two main categories, providing a clear separation of concerns between managing the server environment and working on individual blocklet projects.

![Overview](https://media.arcblock.io/lib/32/32c4baf73ad63fe3.w1600.webp)

### Command Structure

- <strong>`blocklet server <subcommand>`</strong>: This group of commands is dedicated to managing the Blocklet Server daemon. You'll use these to initialize, start, stop, and monitor the server process itself.
- <strong>`blocklet <command>`</strong>: These commands are used for the entire lifecycle of an individual blocklet. This includes scaffolding new projects, running a local development environment, managing dependencies, bundling for production, and deploying to a server.

### Key Capabilities

::::card-group
::link-card{title="Server Management" description="Control the Blocklet Server lifecycle. Start, stop, check status, view logs, and manage server configurations." icon="server"}
::link-card{title="Project Scaffolding" description="Quickly create new blocklet projects from official starter templates or initialize an empty project structure." icon="package"}
::link-card{title="Local Development" description="Run your blocklet in a live-reloading development mode, execute scripts, and manage a local test environment." icon="monitor"}
::link-card{title="Packaging & Distribution" description="Bundle your blocklet and its dependencies into a distributable package, deploy it to a server, or upload it to a Blocklet Store." icon="box"}
::::

### First Run Experience

Upon your first use of the CLI after a fresh installation, you'll be greeted with a welcome message. This is a one-time display to confirm that the CLI is installed correctly and ready to use.

**First-run welcome message**

```text
Powered By
   _            _                      _
  / \   _ __ | | __ _ | |__    ___  _ __ | | __
 / _ \ | '__|| |/ /` || '_ \  / _ \| '__|| |/ /
/ ___ \| |   |   < | || |_) ||  __/| |   |   <
/_/   \_\_|   |_|\_\_||_.__/  \___||_|   |_|\_\

        Blocklet CLI vX.Y.Z
```

### Getting Help

You can get help for any command by appending `--help` to it. To see a list of all available commands, simply run `blocklet` with no arguments.

**Getting help for a command**

```bash
# Get help for the 'deploy' command
blocklet deploy --help

# List all top-level commands
blocklet --help
```

### Next Steps

Now that you have a high-level understanding of what the Blocklet CLI can do, let's get it installed and running.

:::action-card{title="Getting Started" description="Follow a step-by-step guide to install the CLI and run your first Blocklet Server instance." icon="arrow-right"}
::action{label="Install the CLI" href="/en/docs/blocklet-cli/getting-started-104903/" variant="primary"}
:::

---

## Server Management

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-104903/

The `blocklet server` command is your primary tool for managing the lifecycle of a Blocklet Server instance. It allows you to initialize configurations, start and stop the server daemon, check its status, and perform various maintenance tasks. This suite of commands ensures you have full control over your server environment directly from the command line.

Each command is designed for a specific stage of server management. Explore the cards below to learn more about each function.

::::card-group
::link-card{title="Initialize Server" description="Set up a new configuration directory and generate the `config.yml` file required to run a Blocklet Server." icon="plus" href="/en/docs/blocklet-cli/server-management-init-104903/"}
::link-card{title="Start Server" description="Launch the Blocklet Server daemon process in the background based on an existing configuration." icon="play" href="/en/docs/blocklet-cli/server-management-start-104903/"}
::link-card{title="Stop Server" description="Gracefully shut down the running Blocklet Server and all associated blocklet processes." icon="pause" href="/en/docs/blocklet-cli/server-management-stop-104903/"}
::link-card{title="Check Status" description="View the current operational status of the Blocklet Server and all installed blocklets." icon="activity" href="/en/docs/blocklet-cli/server-management-status-104903/"}
::link-card{title="View Logs" description="Quickly access the file paths for Blocklet Server and individual blocklet logs for troubleshooting." icon="file-text" href="/en/docs/blocklet-cli/server-management-logs-104903/"}
::link-card{title="Upgrade Server" description="Update the Blocklet Server CLI to the latest available version to get new features and fixes." icon="arrow-up" href="/en/docs/blocklet-cli/server-management-upgrade-104903/"}
::link-card{title="Migrate Database" description="Migrate your server's database from SQLite to a different system like PostgreSQL." icon="database" href="/en/docs/blocklet-cli/server-management-migrate-104903/"}
::link-card{title="Get Server Info" description="Collect and display essential environment information for debugging and reporting issues." icon="info" href="/en/docs/blocklet-cli/server-management-info-104903/"}
::link-card{title="Cleanup Server" description="Perform cleanup tasks like clearing the cache, blacklist, or resetting the server's maintenance status." icon="trash" href="/en/docs/blocklet-cli/server-management-cleanup-104903/"}
::::

Mastering these commands is key to effectively managing your Blocklet Server. Once your server is up and running, you can proceed to manage individual blocklets with the commands detailed in the [Blocklet Workflows](/en/docs/blocklet-cli/blocklet-workflows-104903/) section.

---

## Cleanup Server

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-cleanup-104903/

The `blocklet server cleanup` command is a utility tool for performing various server-level maintenance tasks. It helps you resolve issues by clearing caches, resetting states, or managing network configurations without needing to stop the entire server.

## Usage

The basic syntax for the command is:

**Basic Syntax**

```bash
blocklet server cleanup <target>
```

Where `<target>` is the specific cleanup task you want to perform.

## Available Targets

Here is a summary of the available cleanup targets:

| Target  | Description  |
|---|---|
| `cache`  | Clears the server's application cache.  |
| `maintenance-status`  | Resets the server from a maintenance mode, often after a failed upgrade.  |
| `blacklist`  | Clears all entries from the router blocklist.  |
| `blacklist-expired`  | Clears only the expired entries from the router blocklist.  |

### Clear Server Cache

This target clears the server's application cache. This can be useful if you suspect outdated or corrupted data is causing issues with your server's operation.

**Clear Cache Command**

```bash
blocklet server cleanup cache
```

Upon successful execution, you will see a confirmation message:

**Success Output**

```bash
Cache for server cleared: [list of cleared cache keys]
```

### Reset Maintenance Status

If your server gets stuck in a maintenance mode (e.g., after a failed or interrupted upgrade), this command will reset its status. It clears the `upgradeSessionId` and restores the server's previous operational mode, allowing it to function normally again.

**Reset Status Command**

```bash
blocklet server cleanup maintenance-status
```

Upon success, the following message will be displayed:

**Success Output**

```bash
Server maintenance status reset
```

### Clear Router Blocklist

This command completely clears the server's router blocklist, which is used to temporarily block problematic routes or IPs. After clearing the list, the server's routing rules are immediately re-evaluated.

**Clear Blocklist Command**

```bash
blocklet server cleanup blacklist
```

Successful execution will produce this output:

**Success Output**

```bash
All router blocklist cleared
```

### Clear Expired Router Blocklist

Unlike clearing the entire blocklist, this target specifically removes only the entries that have passed their expiration time. This is a less disruptive way to clean up the blocklist while keeping active blocks in place.

**Clear Expired Blocklist Command**

```bash
blocklet server cleanup blacklist-expired
```

You will see the following confirmation on success:

**Success Output**

```bash
Expired router blocklist cleared
```

---

## Get Server Info

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-info-104903/

The `blocklet server info` command is a vital diagnostic tool designed to collect and display a comprehensive summary of your Blocklet Server's environment. It gathers everything from hardware and OS details to software versions and server configuration, making it invaluable for debugging or providing system information for support.

## Usage

To get the environment summary, run the following command in your server's root directory:

**Basic Usage**

```bash
blocklet server info
```

### Options

| Option  | Description  |
|---|---|
| `--clipboard`  | Copies the full environment report to your system's clipboard, making it easy to paste into issue trackers or support channels.  |

## Information Displayed

The command outputs a detailed report organized into several key areas:

- <strong>Server Configuration</strong>: Shows essential settings from your `config.yml`, including the server's binary path, configuration file location, routing provider, and configured HTTP/HTTPS ports.
- <strong>Host System</strong>: Provides details about the host machine's hardware, such as CPU core count, memory usage (used vs. total), and both local and public IP addresses.
- <strong>Live Status Checks</strong>: Performs real-time diagnostics on critical components:
-
  - <strong>Domain Status</strong>: Verifies if the server's DNS IP mapping correctly corresponds to its DID.
  - <strong>File System Isolation</strong>: Reports whether this security feature is enabled and available on the host system's Node.js version.
  - <strong>Docker Status</strong>: Checks if the Docker daemon is installed and running.
- <strong>Software Environment</strong>: Leverages the `envinfo` utility to generate a thorough report on the development environment, including:
-
  - <strong>System</strong>: OS, CPU architecture, and default Shell.
  - <strong>Binaries</strong>: Versions of crucial tools like Node.js, npm, Yarn, and pm2.
  - <strong>Virtualization</strong>: Detected virtualization software (e.g., Docker).
  - <strong>npm Packages</strong>: Versions of installed `@abtnode/*` and `@arcblock/*` packages in the current project.

## Example Output

Running `blocklet server info` will produce a report similar to this:

**Example Report**

```text
ℹ Server binary from: /home/user/.nvm/versions/node/v18.17.1/bin/blocklet
ℹ Server config from: /home/user/my-blocklet-server/.abtnode/abtnode.yml
ℹ Server router provider: ip
ℹ Server http port: 8080
ℹ Server https port: 8443
ℹ Server host cpu: 8 / 16
ℹ Server host memory: 12.5 GiB / 31.2 GiB
ℹ Server host IP: {"local":"192.168.1.101","public":"203.0.113.55"}
ℹ Server file system isolation status: on(available)
ℹ Docker is installed and running
ℹ Server domain status: correct

  System:
    OS: Linux 5.15 Ubuntu 22.04.3 LTS
    CPU: (16) x64 AMD Ryzen 7 5800X
    Shell: 5.1.16 - /bin/bash
  Binaries:
    Node: 18.17.1 - /usr/bin/node
    npm: 9.6.7 - /usr/bin/npm
    Yarn: 1.22.19 - /usr/bin/yarn
    pm2: 5.3.0 - /usr/bin/pm2
  Virtualization:
    Docker: 24.0.5 - /usr/bin/docker
  npmPackages:
    @abtnode/cli: ^1.18.0 => 1.18.0
```

This command centralizes all necessary diagnostic information, giving you a complete and accurate snapshot of your server's setup for efficient troubleshooting.

---

## Initialize Server

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-init-104903/

The `blocklet server init` command initializes a new Blocklet Server instance by creating a dedicated configuration directory, `.blocklet-server`, in the current working directory. This directory contains the `config.yml` file and other necessary assets to run the server. The process can be executed interactively through a guided setup or non-interactively using command-line flags.

## Usage

To initialize a new server configuration, navigate to the desired directory and execute the following command:

**Basic Initialization Command**

```bash
blocklet server init
```

Executing this command without any flags will launch an interactive setup wizard to guide you through the configuration process.

## Interactive Configuration

When running in interactive mode, the CLI will prompt you for the necessary configuration details. The table below outlines each question, its description, and the default value provided.

| Prompt  | Description  | Default Value  |
|---|---|---|
| Naming the server?  | A human-readable name for your Blocklet Server instance.  | A randomly generated name (e.g., `purple-shape-7133`)  |
| Description of the server?  | A brief description outlining the server's purpose.  | `My Blocklet Server`  |
| Which port do you want your server to listen on?  | The internal port for the Blocklet Server daemon process.  | `3030`  |
| Choose routing engine  | The routing provider to manage incoming traffic (e.g., Nginx).  | Automatically detects existing providers like `nginx`.  |
| Where do you want to mount your admin dashboard?  | The URL path for accessing the server's administrative interface.  | `/admin`  |
| Which web wallet do you want to use?  | The URL of the web wallet to be integrated with the server.  | Varies by environment.  |
| Do you want to enable https support...  | Enables or disables SSL/TLS for the dashboard and blocklets.  | `true`  |
| What's ip wildcard domain?  | The domain for accessing blocklets via the server's IP address.  | `ip.abtnet.io`  |
| Where to download the wildcard certificate?  | The URL for fetching wildcard certificates for HTTPS support.  | `https://releases.arcblock.io/certs/`  |
| Max Upload File Size allowed by the server (MB)?  | The maximum file size permitted for uploads.  | `16` MB  |
| Which http port do you want your service gateway to listen on?  | The public-facing HTTP port for the routing engine.  | `80`  |
| Which https port do you want your service gateway to listen on?  | The public-facing HTTPS port for the routing engine.  | `443`  |
| What is the max memory limit of Blocklet Server (GB)?  | The maximum RAM allocated to the Blocklet Server daemon.  | `4` GB  |
| What is the max memory limit of each Blocklet (GB)?  | The maximum RAM allocated to each individual blocklet.  | `1` GB  |

## Command Options

The initialization process can be customized or automated using the following command-line options.

| Option  | Description  |
|---|---|
| `-y`, `--yes`  | Initializes the server non-interactively, accepting all default values. This is useful for automated scripts.  |
| `--force`  | An alias for `-y` and `--yes`.  |
| `--mode <mode>`  | Sets the server's operational mode. Valid options are `production` (default) and `debug`.  |
| `--no-https`  | Disables HTTPS support for the server. HTTPS is enabled by default.  |
| `--http-port <port>`  | Specifies the public-facing HTTP port for the service gateway, overriding the interactive prompt.  |
| `--https-port <port>`  | Specifies the public-facing HTTPS port for the service gateway, overriding the interactive prompt.  |
| `--sk <secret_key>`  | Provides a custom secret key to generate the server's wallet instead of creating a new random one.  |
| `--interactive`  | Forces the command to run in interactive mode, even if other non-interactive flags are present.  |

### Non-Interactive Example

To initialize a server without any prompts, use the `-y` flag. This command is ideal for scripting and automation.

**Non-Interactive Initialization**

```bash
blocklet server init -y --mode production --http-port 8080
```

## Generated Files

Upon successful initialization, the following files and directories are created in the current working directory:

- <strong>`.blocklet-server/`</strong>: The primary configuration directory for the Blocklet Server instance.
- <strong>`.blocklet-server/config.yml`</strong>: The main configuration file in YAML format. It stores all the settings provided during setup, such as the server name, ports, routing information, and wallet details.
- <strong>`.blocklet-server/.sock`</strong>: A file containing the encryption key used to secure the server wallet's secret key within `config.yml`. This file is critical for wallet recovery and must be backed up securely.

## Next Steps

With the server configuration in place, the next step is to start the server. Proceed to the next section to learn how to start the Blocklet Server daemon.

:::action-card{title="Start Server" description="Learn how to start the Blocklet Server daemon process based on the configuration you just created." icon="play"}
::action{label="Start the Server" href="/en/docs/blocklet-cli/server-management-start-104903/" variant="primary"}
:::

---

## View Logs

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-logs-104903/

The `blocklet server logs` command is an essential utility for troubleshooting and monitoring. It doesn't display the log content directly but instead provides the exact file paths for all logs related to the Blocklet Server daemon and any installed blocklets. This allows you to easily locate and inspect logs using standard command-line tools like `cat`, `tail`, or `less`.

## Usage

To display the log file paths, simply run the command from within your Blocklet Server project directory:

**blocklet server logs**

```bash
blocklet server logs
```

## Output Description

The command's output is organized into two main sections: server-level logs and blocklet-specific logs.

### Server Logs

This section provides paths to the core Blocklet Server daemon logs. It will always show the main directory for daemon logs and point to the most recent business log file.

The server maintains several types of logs, which are rotated daily:

| Filename Pattern  | Description  |
|---|---|
| `access-<date>.log`  | Standard access logs, useful for tracking incoming HTTP requests.  |
| `daemon-<date>.log`  | The main business logs, containing operational information from the server.  |
| `daemon-error-<date>.log`  | Error logs, capturing any exceptions or critical errors thrown by the server.  |
| `service.log`  | Logs related to the underlying Blocklet Server service manager (abtnode).  |
| `stderr.log`  | Raw standard error output from the server process.  |
| `stdout.log`  | Raw standard output from the server process.  |

### Blocklet Logs

If your Blocklet Server is running and you have blocklets installed, the command will also list the log files for each one. This is incredibly helpful for debugging individual blocklets in isolation.

For each installed blocklet, you will see two log file paths:

- <strong>Output</strong>: The path to `output.log`, which contains the standard output (`stdout`) from the blocklet's process.
- <strong>Error</strong>: The path to `error.log`, which contains the standard error (`stderr`) from the blocklet's process.

## Example Output

Here is an example of what you might see when running the command on a server with two blocklets installed:

**Example Output**

```bash
$ blocklet server logs

Blocklet Server Logs
- Latest logs: /path/to/your/data/daemon/logs/daemon-2023-10-27.log
- Daemon Logs Directory: /path/to/your/data/daemon/logs

  Daemon Logs
  - access-<date>.log: access logs rotated by day
  - daemon-<date>.log: business logs rotated by day
  - daemon-error-<date>.log: error logs rotated by day
  - service.log: abtnode service logs
  - stderr.log: stderr logs
  - stdout.log: stdout logs

my-first-blocklet@1.2.0
- Output: /path/to/your/data/logs/my-first-blocklet/output.log
- Error: /path/to/your/data/logs/my-first-blocklet/error.log

another-blocklet@2.0.1
- Output: /path/to/your/data/logs/another-blocklet/output.log
- Error: /path/to/your/data/logs/another-blocklet/error.log
```

## Common Scenarios

- <strong>Server Not Running</strong>: If the Blocklet Server is not running, the command cannot access blocklet-specific logs and will display a warning: `Unable to get blocklet logs because Blocklet Server is not running`.
- <strong>No Blocklets Installed</strong>: If the server is running but no blocklets have been installed yet, you will see the message: `No blocklets installed yet.`

---

## Migrate Database

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-migrate-104903/

The `blocklet server migrate` command is a crucial utility for scaling your Blocklet Server instance. It facilitates the migration of your server's underlying database from the default SQLite—perfect for development and simple setups—to a more robust and scalable system like PostgreSQL for production environments.

## Command Usage

To initiate the migration, use the `migrate` command and specify the target database system.

**Migrate Command**

```bash
blocklet server migrate --dialect <dialect>
```

### Options

| Option  | Description  | Required  | Allowed Values  |
|---|---|---|---|
| `--dialect`  | The target database system to migrate to.  | Yes  | `postgres`, `sqlite`  |

The command supports migrating your database between SQLite and PostgreSQL. While the primary use case is upgrading from SQLite to PostgreSQL for production, it can also be used to migrate from PostgreSQL back to SQLite, which might be useful for creating a portable snapshot for development or debugging.

## How It Works

The migration process is designed to be straightforward. The command first reads the list of installed blocklets and other essential configuration from your existing SQLite database. Then, using the connection details you provide, it connects to the new PostgreSQL database, runs all necessary schema migrations to create the required tables, and populates them with your data.

![Migrate Database](https://media.arcblock.io/lib/7a/7a36209d3e1a33a5.w1600.webp)

## Step-by-Step Guide: Migrating to PostgreSQL

Follow these steps to move your Blocklet Server data from SQLite to PostgreSQL.

### Prerequisites

Before you start, ensure the following conditions are met:

::::steps
:::step{title="Server has been started at least once"}
This is necessary because the initial `blocklet server start` command creates the SQLite database and tables that the migration tool needs to read from.
:::

:::step{title="Target Database is Ready"}
Your PostgreSQL server must be installed, running, and accessible from the machine where you are running the CLI.
:::

:::step{title="PostgreSQL Connection URL"}
You must have the full connection string for your PostgreSQL database.
:::
::::

### Step 1: Configure the Target Database

The CLI needs to know how to connect to your PostgreSQL database. This is done by setting the `ABT_NODE_POSTGRES_URL` environment variable.

**Set Environment Variable**

```bash
export ABT_NODE_POSTGRES_URL="postgres://user:password@host:port/database"
```

Make sure to replace `user`, `password`, `host`, `port`, and `database` with your actual PostgreSQL credentials.

### Step 2: Run the Migration Command

With the environment variable set, execute the migration command. The process will show its progress, starting with messages like `Getting blocklets...`.

**Run Migration**

```bash
blocklet server migrate --dialect postgres
```

### Step 3: Start the Server

Once the command finishes with a `Migration postgres completed` message, the process is done. The final step is to start your Blocklet Server. As long as the `ABT_NODE_POSTGRES_URL` environment variable is present, the server will automatically connect to and use your new PostgreSQL database.

**Start Server**

```bash
blocklet server start
```

Your server is now running on PostgreSQL, ready for production workloads.

## Troubleshooting

### Error: SQLITE_ERROR: no such table

If you encounter an error message similar to `Failed to get blocklets: SQLITE_ERROR: no such table: blocklets` or `dose not exist`, it almost always means the initial SQLite database was never created.

<strong>Solution</strong>: You must run the server at least once to initialize the database. Run `blocklet server start`, wait for it to fully start up, then stop it with `blocklet server stop`. After that, you can attempt the migration process again.

---

## Start Server

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-start-104903/

The `blocklet server start` command is the primary method for launching your Blocklet Server instance. It initializes and runs all necessary components as background daemon processes, making your server and its blocklets accessible.

## Basic Usage

To start the server from its configuration directory, simply run:

**Basic Start Command**

```bash
blocklet server start
```

Upon a successful start, the command will output the access URLs for your server's dashboard.

## The Startup Process

When you execute `blocklet server start`, the CLI performs a sequence of critical tasks to ensure the server starts correctly and in a consistent state. Understanding this process can help with configuration and troubleshooting.

![Start Server](https://media.arcblock.io/lib/34/34e2ae89d8a76048.w1600.webp)

::::steps
:::step{title="Version Check"}
The CLI first verifies that its version is compatible with the version specified in the server's `config.yml` file to prevent potential conflicts.
:::

:::step{title="Database Migrations"}
If a version upgrade is detected, the CLI automatically runs any necessary database schema and data migrations to ensure the database is up-to-date.
:::

:::step{title="Configuration Sync"}
It compares the settings in `config.yml` with the configuration stored in the database. If differences are found, it will issue a warning.
:::

:::step{title="Dependency Checks"}
The server ensures required services like Redis or PostgreSQL are available, attempting to start them if configured to do so (e.g., via Docker).
:::

:::step{title="Process Launch"}
Using PM2, the CLI starts the core background processes: the main <strong>Daemon</strong> (handles web requests and routing), the <strong>Blocklet Service</strong> (manages blocklet lifecycle and services), and the <strong>Event Hub</strong> (facilitates inter-process communication).
:::

:::step{title="Blocklet Resumption"}
Any blocklets that were in a `running` state before the server was last stopped are automatically restarted.
:::

:::step{title="Output URLs"}
Once all processes are confirmed to be healthy and running, the CLI prints the access URLs for the server dashboard.
:::
::::

## Command Options

You can modify the startup behavior using the following flags:

| Option  | Description  |
|---|---|
| `--update-db`  | Forces the server to update its database configuration from the values in `config.yml`. This is useful if you've manually edited the config file and want the changes to take effect.  |
| `--auto-init`  | If a Blocklet Server instance is not found in the current directory, this flag will automatically initialize one before starting it. This is a convenient way to set up and run a new server with a single command.  |
| `--force-intranet`  | Restricts the server to run in intranet mode, ignoring any external IP addresses and only providing local network access URLs.  |
| `--mode <mode>`  | Starts the server in a specific operational mode. For example, using `--mode maintenance` will start the server in maintenance mode.  |

### Example: Updating Configuration

If you've changed a setting in your `config.yml`, such as the server port, you must use the `--update-db` flag for the change to be applied.

**Applying Configuration Changes**

```bash
# 1. Stop the server if it's running
blocklet server stop

# 2. Restart the server with the flag to apply config changes
blocklet server start --update-db
```

### Example: Auto-Initialization

To quickly spin up a new server instance in an empty directory:

**Quick Setup with Auto-Init**

```bash
# This will create a .blocklet-server directory and then start the server
blocklet server start --auto-init
```

## Troubleshooting

If the server fails to start, the CLI will provide immediate feedback:

- <strong>Error Logs</strong>: The last 15 lines of the daemon's error log (`daemon.stderr.log`) will be printed directly to your console. For more detailed information, you should inspect the full log file mentioned in the output.
- <strong>Router Issues</strong>: Sometimes, startup failures are related to the routing engine. Running `blocklet server start` again can often resolve these issues.
- <strong>Forced Stop</strong>: If the server becomes unresponsive, you can ensure a clean shutdown by running `blocklet server stop --force` before attempting to start it again.

Once your server is running, you'll want to check on its health and manage your blocklets. Learn how to [Check Status](/en/docs/blocklet-cli/server-management-status-104903/) or [Stop the Server](/en/docs/blocklet-cli/server-management-stop-104903/).

---

## Check Status

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-status-104903/

The `blocklet server status` command is a vital tool for monitoring the health of your Blocklet Server instance and all the blocklets running within it. It provides a quick, comprehensive snapshot of your entire system, from the core server process to individual blocklet states.

## Usage

To check the status, run the following command in your terminal. It's typically run from within the Blocklet Server's data directory, but it can be run from any directory as it locates the running server process.

**blocklet server status**

```bash
blocklet server status
```

## Example Output

A typical output will look like this, providing detailed information about the server and installed blocklets:

**Output**

```bash
Blocklet Server status: Running (2 hours 15 minutes)
Blocklet Server mode: Production
Blocklet Server Data Directory: /home/user/.blocklet-server
Blocklet Server Router Engine: @blocklet/router-nginx
Blocklet Server Database: @blocklet/db-sqlite

Blocklets Status:
┌──────────────────────────────┬───────────────┬────────────────────────────────────────────────────────────────────┐
│ Name                         │ Status        │ URL                                                                │
├──────────────────────────────┼───────────────┼────────────────────────────────────────────────────────────────────┤
│ My Awesome App               │ running       │ https://z2qa7g7b1f6d8e...did.abtnet.io                              │
├──────────────────────────────┼───────────────┼────────────────────────────────────────────────────────────────────┤
│ Data Analytics Tool          │ stopped       │ https://z8t9b3c2d1e0f...did.abtnet.io                              │
├──────────────────────────────┼───────────────┼────────────────────────────────────────────────────────────────────┤
│ Internal Dashboard           │ errored       │ https://z5m4n3o2p1q0r...did.abtnet.io                              │
└──────────────────────────────┴───────────────┴────────────────────────────────────────────────────────────────────┘

You can access your blocklet server with either of the following URLs:
- http://192.168.1.100
- http://localhost
```

## Understanding the Output

### Server Information

This section gives you an overview of the core server process:

- <strong>Blocklet Server status</strong>: Shows the current state of the server daemon. Common statuses include `Running`, `Stopped`, `Starting`, `Stopping`, and `Errored`. If running, it also displays the uptime.
- <strong>Blocklet Server mode</strong>: Indicates if the server is running in `Production` or `Development` mode.
- <strong>Blocklet Server Data Directory</strong>: The absolute path to the server's data directory where configuration, blocklets, and data are stored.
- <strong>Router Engine & Database</strong>: Displays the currently configured providers for routing (e.g., `nginx`) and the database (e.g., `sqlite`).

### Blocklets Status

This table lists all blocklets installed on the server:

- <strong>Name</strong>: The human-readable title of the blocklet, as defined in its `blocklet.yml`.
- <strong>Status</strong>: The current runtime state of the individual blocklet (e.g., `running`, `stopped`, `errored`).
- <strong>URL</strong>: The unique, decentralized URL to access the blocklet's web interface.

### Access URLs

When the server is running, this section provides the local network and/or localhost URLs to access the Blocklet Server's main dashboard in your web browser.

## Options

- **--force-intranet** `boolean` — By default, the command may show public URLs if available. Use this flag to ensure that only local network (intranet) IP addresses are displayed in the 'Access URLs' section. This is useful when you are on a local network and want to ensure you are connecting directly.

```bash
blocklet server status --force-intranet
```

## Special Cases

- <strong>If the server is not started</strong>, the command will simply output: ```bash Blocklet Server is not started ```
- <strong>If no blocklets are installed</strong>, you will see a warning message instead of a table: ```bash No blocklets installed yet. ```

After checking the status, you might want to inspect the server logs for more detailed information or manage the server state.

::::card-group
::link-card{title="Start Server" description="Learn how to start the Blocklet Server daemon if it's currently stopped." icon="play" href="/en/docs/blocklet-cli/server-management-start-104903/"}
::link-card{title="View Logs" description="Learn how to tail logs for the server and individual blocklets to debug issues." icon="file-text" href="/en/docs/blocklet-cli/server-management-logs-104903/"}
::link-card{title="Stop Server" description="Find out how to safely shut down the Blocklet Server and all running blocklets." icon="power" href="/en/docs/blocklet-cli/server-management-stop-104903/"}
::::

---

## Stop Server

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-stop-104903/

The `blocklet server stop` command gracefully shuts down the running Blocklet Server instance. This process includes stopping all running blocklets, the routing engine, core server processes, and any associated Docker containers.

## Usage

**Basic Usage**

```bash
blocklet server stop [options]
```

## Graceful Shutdown Process

By default, running `blocklet server stop` initiates a sequential shutdown process to ensure all services terminate cleanly and prevent data corruption. The server has a 5-minute timeout for this process to complete.

Here’s a diagram illustrating the flow:

![Stop Server](https://media.arcblock.io/lib/30/30d72638724dd0d5.w1600.webp)

The key steps in a graceful shutdown are:

::::steps
:::step{title="Check for Development Blocklets"}
The server first checks if any blocklets are running in development mode. If so, the stop command will fail, and you must manually stop the development process first.
:::

:::step{title="Notify Clients"}
A `NODE_STOPPED` event is broadcast to notify any connected web dashboard users about the impending shutdown.
:::

:::step{title="Stop Routing Engine"}
The server's routing engine is stopped.
:::

:::step{title="Stop Blocklets"}
Each running blocklet is stopped individually.
:::

:::step{title="Stop Core Processes"}
The main Blocklet Server processes managed by PM2 (`daemon`, `service`, `event-hub`) are terminated.
:::

:::step{title="Stop Docker Containers"}
Any Docker containers managed by Blocklet Server are stopped.
:::

:::step{title="Update Status"}
The server's status is updated to `STOPPED`.
:::
::::

## Options

| Option  | Description  |
|---|---|
| `--force`  | Forcibly stops all Blocklet Server-related processes. This option bypasses the graceful shutdown sequence and should be used if the server fails to stop normally.  |

### Force Stop

Using the `--force` flag initiates a more aggressive shutdown with a 20-second timeout. This process will:

- Immediately clear all router configurations and caches.
- Directly kill all PM2 processes associated with Blocklet Server and any blocklets.
- Kill the main PM2 daemon itself.
- Stop any managed Docker containers.

This is the recommended solution when the server becomes unresponsive and the graceful stop command times out.

## Examples

### Standard Graceful Stop

To perform a standard, graceful shutdown of the server:

**Basic Stop Command**

```bash
blocklet server stop
```

You will see output indicating the successful shutdown of each component:

**Expected Output**

```text
Sending shutdown notification to web dashboard users ✔
Routing engine is stopped successfully ✔
Blocklet My-Blocklet is stopped successfully ✔
...
daemon is stopped successfully ✔
service is stopped successfully ✔
event-hub is stopped successfully ✔
Docker containers managed by blocklet server are stopped ✔
Done! ✔
```

### Forcing the Server to Stop

If the server is unresponsive or the graceful stop fails, use the `--force` flag.

**Force Stop Command**

```bash
blocklet server stop --force
```

This command will attempt to stop all related processes directly.

**Expected Output for Force Stop**

```text
nginx router is stopped successfully ✔
All blocklet processes stopped successfully ✔
Docker containers managed by blocklet server are stopped ✔
```

## Troubleshooting

#### Blocklets in Development Mode

If you have a blocklet running in development mode (using `blocklet dev`), the `blocklet server stop` command will fail with a message similar to this:

**Error Message for Dev Mode**

```text
Unable to stop Blocklet Server, please stop the development by pressing Ctrl + C in the terminal of my-dev-blocklet
```

You must navigate to the terminal where the development process is running and press `Ctrl + C` to stop it before you can stop the main server.

#### Server Fails to Stop

If the graceful shutdown process takes too long (the default timeout is 5 minutes), you will see an error message. In this case, you should use the force stop command:

**Timeout Error Message**

```text
Blocklet Server failed to stop within 5 minutes
You can stop blocklet server with blocklet stop --force
```

---

## Upgrade Server

URL: https://www.arcblock.io/en/docs/blocklet-cli/server-management-upgrade-104903/

This document provides instructions for upgrading the Blocklet Server Command Line Interface (CLI) to the most recent version available.

## Command Usage

The `upgrade` command automates the process of fetching and installing the latest version of the Blocklet Server CLI.

```bash
blocklet server upgrade
```

## Upgrade Process

The command executes a series of steps to ensure a safe and successful upgrade. The process is as follows:

::::steps
:::step{title="Version Check"}
The command first retrieves the latest available version number from the npm registry and compares it against the currently installed version. If the current version is already the latest, the process terminates.
:::

:::step{title="Permission Verification"}
It verifies if the current user has the necessary write permissions for the directory where the CLI tool is installed. If permissions are insufficient, the command will fail and suggest re-running with `sudo`.
:::

:::step{title="Server Shutdown"}
If a Blocklet Server instance is currently running, the upgrade command will automatically stop the server to prevent any conflicts during the update. The original running state and data directory are saved.
:::

:::step{title="Installation"}
The command proceeds to download and install the latest version of the CLI package using the system's detected package manager (e.g., npm, yarn).
:::

:::step{title="Server Restart"}
If the server was running before the upgrade, the command will automatically restart it from its original data directory, ensuring service continuity.
:::

:::step{title="Confirmation"}
Upon successful completion, a confirmation message is displayed, showing the new, upgraded version number.
:::
::::

The following diagram illustrates the workflow of the upgrade command.

![Upgrade Server](https://media.arcblock.io/lib/7e/7e2a1ea316bdeb39.w1600.webp)

## Execution Example

When you run the command, it will display the progress of the upgrade.

```bash
$ blocklet server upgrade

ℹ Using blocklet server from /home/user/.nvm/versions/node/v16.20.2/bin/blocklet
ℹ Checking permissions...
ℹ Current version is 1.8.0, found latest version 1.8.1
ℹ Begin upgrade
ℹ Stopping Blocklet Server ...
ℹ Installing Blocklet Server by npm install -g @blocklet/cli@latest ...

+ @blocklet/cli@1.8.1
added 1 package from 1 contributor, updated 1 package and audited 931 packages in 10.2s

ℹ Restarting Blocklet Server ...
✔ Blocklet Server started
✔ Blocklet Server upgrade success, current version is 1.8.1
```

### Insufficient Permissions

If you lack the necessary permissions to modify the installation directory, the command will output an error and provide guidance.

```bash
$ blocklet server upgrade

ℹ Using blocklet server from /usr/local/bin/blocklet
ℹ Checking permissions...
✖ Seems you do not have permission to upgrade Blocklet Server version
ℹ Maybe you can try run sudo blocklet server upgrade
```

In this case, you should run the command with `sudo` as suggested:

```bash
sudo blocklet server upgrade
```

### Already Up to Date

If your Blocklet Server CLI is already at the latest version, the command will inform you that no action is needed.

```bash
$ blocklet server upgrade

ℹ Using blocklet server from /home/user/.nvm/versions/node/v16.20.2/bin/blocklet
ℹ Checking permissions...
ℹ The current version 1.8.1 is the latest version, no need to upgrade
```

---

## Blocklet Platform

URL: https://www.arcblock.io/en/docs/blocklet-developer/

---

## Request Entity too Large

URL: https://www.arcblock.io/en/docs/blocklet-developer/07ns0Nj6haMOsyrsTdyAjlps/

Blocklet Server limits file size on uploading within a certain range for efficiency considerations, since larger file uploads will consume more resources in the server host.

The default upload size limit is 500M, if the uploaded file is larger than that size, Blocklet Server will throw "Request Entity too large".

If you want to increase the upload size limit of your Blocklet Server, you need to update `routing.maxUploadFileSize` in your server config file, and then start your server with `-u` flag.

![Screenshot 2024-07-12 at 06.04.53.png](https://media.arcblock.io/lib/1e/1e00443a06e24ecac6a8db1c7fd5c9e2.w1600.webp)

---

## Manage Blocklet Versions

URL: https://www.arcblock.io/en/docs/blocklet-developer/3HWWvUOi0Mhqy_yag3CXeJUA/

This documentation provides guidelines on managing the versioning of Blocklets, ensuring consistency and clarity across releases.

### Semantic Versioning

Blocklet versions follow [Semantic Versioning](https://semver.org/) (SemVer) principles. SemVer consists of three numbers separated by dots: `MAJOR.MINOR.PATCH`.

- <strong>MAJOR</strong>: Increments when there are incompatible changes or major feature enhancements.
- <strong>MINOR</strong>: Increments when new functionality is added in a backward-compatible manner.
- <strong>PATCH</strong>: Increments with backward-compatible bug fixes.

### Incrementing Blocklet Version

The version of a Blocklet should be incremented according to the type of change introduced.

#### Manual Versioning

To manually update the version:

```javascript
bashCopy codeblocklet version major    # Increment MAJOR version
blocklet version minor    # Increment MINOR version
blocklet version patch    # Increment PATCH version
```

#### Automated Versioning

Automated tools or scripts can also be used to manage version increments, ensuring consistency and reducing manual errors, which is enforced in blockles created using [Create Blocklet](/en/docs/createblocklet/quick-start/).

### Best Practices

- <strong>Version on Release</strong>: Always update the Blocklet version before a new release to reflect changes accurately.
- <strong>Changelog</strong>: Maintain a changelog to document each version's changes, helping users understand what's new or fixed.

---

## Blocklet SDK (Browser)

URL: https://www.arcblock.io/en/docs/blocklet-developer/5z27x8H1fDFgdL3k6ZKNBvjp/

The Blocklet JS SDK is the official frontend library provided to assist in the development of blocklets.

It mainly includes the following functions:

1. Provide fetch and axios creation functions that can automatically update tokens.
2. Provide user profile related interface requests

### Initialize the instance

```typescript
import { BlockletSDK } from '@blocklet/js-sdk';
const sdk = new BlockletSDK();
```

### User Information Example

<strong>user.getUserPublicInfo</strong>

Get user's public information.

```typescript
type UserPublicInfo = {
  avatar: string;
  did: string;
  fullName: string;
};
const publicInfo: UserPublicInfo = await sdk.user.getUserPublicInfo(userDid: string);
```

<strong>user.getProfileUrl</strong>

Get user personal center address

```typescript
const profileUrl = await sdk.user.getProfileUrl({did: string; locale: string});
```

<strong>user.logout</strong>

Log out

```javascript
await sdk.user.logout();
```

### Create an axios instance

<strong>createAxios</strong>

This example will manage the update of sessionToken and refreshToken.

```typescript
import { createAxios } from '@blocklet/js-sdk';
import type { AxiosRequestConfig, AxiosInstance } from 'axios';

type RequestParams = {
  lazy?: boolean; // 是否需要将请求延迟响应
  lazyTime?: number; // 延迟响应的时间，默认 300 ms
};

const api = createAxios(config?: AxiosRequestConfig, requestParams?:RequestParams)
```

<strong>createFetch</strong>

This instance will manage the updating of sessionToken and refreshToken.

```javascript
import { createFetch } from '@blocklet/js-sdk';

type RequestParams = {
  lazy?: boolean; // 是否需要将请求延迟响应
  lazyTime?: number; // 延迟响应的时间，默认 300 ms
};

const api = createFetch(options?: RequestInit, requestParams?:RequestParams)
```

---

## Test a Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/7CKdPI2ZzVD6YGbPOiKO-nLR/

After creating the application, we can directly install the Blocklet locally to test if it meets expectations.

Open Blocklet Studio, select the created Blocklet, and click to view the details of the latest version:

![image.png](https://media.arcblock.io/lib/01/010c15dd983f0e84e0415c3a1db0a2d3.w1600.webp)

In the details page, you can click "Installation" or "Copy Installation URL" to install and test it:

![image.png](https://media.arcblock.io/lib/9f/9f99c13cec739c0777fab7ffaaf914b6.w1600.webp)

Further reading:

[How to install a resource by URL after creating it](/en/docs/blocklet-developer/R3weqCy7WPI8ggudt0C2alWv/)

---

## Adding a component

URL: https://www.arcblock.io/en/docs/blocklet-developer/7zbw0GQXgcD6sCcjVfwqqT2s/

This document explains how to install <strong>Blocklets</strong> on your website and details the characteristics, use cases, and important considerations for each installation method.

There are three ways to install a Blocklet:

::::steps
:::step{title="Install Through the App Store"}
:::

:::step{title="Install from a URL"}
:::

:::step{title="Install from Local File"}
:::
::::

![image.png](https://media.arcblock.io/lib/73/73e57e848c339407dd90f95950861caf.w1600.webp)

![image.png](https://media.arcblock.io/lib/ff/ff3119ef6a1d8d5dca4a68746f4edd65.w1600.webp)

## 1. Install Through the App Store

This method is the easiest and recommended for new users or those who want to quickly install officially recommended Blocklets.

<strong>Procedure:</strong>

1. Click <strong>Add Blocklet</strong>.
2. The official <strong>Blocklet Store</strong> will open in a new window.
3. Search for the required Blocklet in the Blocklet Store, such as `Static Demo` and `Pages Kit`.
4. Click "Next" to continue the installation.

![image.png](https://media.arcblock.io/lib/e1/e1eafe5f5066ec00bee96882cfef13af.w1600.webp)

---

## 2. Install from a URL

If you already have a valid <strong>`blocklet.json` URL</strong>, you can install it directly.

- <strong>Supported Address Types</strong>:
-
  - <strong>Remote address</strong>: For example, [`https://example.com/blocklet.json`](https://example.com/blocklet.json)
  - <strong>Local Address</strong>: e.g., `file:///Users/xxx/blocklet/blocklet.json`

<strong>Steps:</strong>

1. Select "<strong>Add Blocklet from URL</strong>".
2. Enter a valid `blocklet.json` URL. Alternatively, you can copy the installation URL of a Blocklet from the official Blocklet Store.
3. After the system verification is successful, click "Next" to continue the installation. The remaining steps are identical to those for a store installation.
4. Blocklets installed from a URL will have that URL saved and displayed in a dropdown menu, allowing for quick reinstallation and updates.

![image.png](https://media.arcblock.io/lib/d7/d72c98c8f964200ff344be452c67c515.w1600.webp)

⚠️ <strong>Note</strong>:

- Ensure the address is accessible.
- The provided `blocklet.json` file must adhere to the Blocklet specification; otherwise, installation will fail.

---

## 3. Installing from a Local Upload

This method allows you to directly upload local files, which is suitable for testing Blocklets or using Blocklets that haven't yet been published to the Blocklet Store.

- <strong>Supported File Types</strong>:
-
  - Static files:`html`, `htm`
  - Archive format:`zip`, `tgz`
- <strong>Upload Requirements</strong>：
-
  - Static deployments must include either `index.html` or `index.htm` as the entry point.
  - The compressed package can contain either static files or a pre-built Blocklet. The system automatically detects the project type during upload.

The installation process will begin automatically after the upload is complete.

![image.png](https://media.arcblock.io/lib/8a/8afbed95c3e0abcfe5d930fb61e9479a.w1600.webp)

---

## Mount Points and Override Rules

After installation, you need to configure a <strong>mount point</strong> for the Blocklet:

- <strong>Mount Point Definition</strong>: The Blocklet's access path within a site, for example:
-
  - Access via [`https://your-site.com/blog`](https://your-site.com/blog) or `/blog`
  - Access the forum via [`https://your-site.com/forum`](https://your-site.com/forum)
- <strong>Overriding Rules</strong>:
-
  - If a newly installed Blocklet uses the same mount point as an existing Blocklet, the new content will <strong>replace</strong> the old content.
  - Identical mount points will only overwrite blocklets installed by uploading. If the mount point is the same as one used by a blocklet installed through other methods, a default mount point will be generated, preventing overwriting.
  - It's recommended to select a unique mount point during installation to prevent conflicts with existing services.
  - Upgrading an installed Blocklet can be done by overwriting its mount point, eliminating the need for uninstallation and reinstallation.

![image.png](https://media.arcblock.io/lib/46/46186da0652b57b7fdf30681094b9ccd.w1600.webp)

---

## Access Control

URL: https://www.arcblock.io/en/docs/blocklet-developer/access-control/

Blocklet Service 为 Blocklet 提供的访问控制基于 [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control)(Role-based access control)

Blocklet Service 将角色包装为 Passport(通行证), Passport 本质是 VC(可验证的凭据)

Passport 使得用户角色不必存储在 Server 端，并且用户可以使用其他 Blocklet 颁发的 Passport

## Passport 和 Role 的关系

![](https://media.arcblock.io/docs/access-control/passport.svg)

---

## Access Key

URL: https://www.arcblock.io/en/docs/blocklet-developer/access-key/

## What Are Access Keys?

<strong>Access Key</strong> is a permanent credential provided by the Blocklet platform, composed of an <strong>AccessKey ID</strong> and <strong>AccessKey Secret</strong> key pair.  This key pair is used to authenticate and authorize your requests, enabling you to access and interact with Blocklet data.

<strong>Access Key Structure and Purpose:</strong>

- <strong>AccessKey ID:</strong> A unique string that identifies the user. It tells the Blocklet platform which user made the request.
- <strong>AccessKey Secret:</strong> This is the <strong>secret key used to verify ownership of this AccessKey ID.</strong>  It is a highly confidential string used to generate cryptographic signatures for your requests, confirming your identity as the AccessKey ID holder.

<strong>Note:</strong> Access Keys are <strong>not used for logging into the console</strong>. They are specifically designed for <strong>programmatic access</strong> to Blocklet data, such as via development tools like <strong>APIs, command-line interfaces (CLIs), and software development kits (SDKs)</strong>. When you make a request using these tools, the request includes the Access Key ID and Secret, which are used to generate a signature that encrypts the request content. This signature is then used for authentication and to verify the request's legitimacy.

## Access Key Best Practices

Access keys offer powerful programmatic access, but their compromise or misuse can seriously threaten all Blocklet resources associated with your account. Adhering to the following best practices is essential for maintaining a secure Blocklet environment:

- <strong>Minimize the creation of permanent access keys:</strong>  Avoid creating perpetually valid access keys. Instead, <strong>set expiration dates for access keys</strong> to mitigate the potential damage from compromised credentials.
- <strong>Safeguard Your Credentials:</strong> Treat your <strong>AccessKey ID and AccessKey Secret as highly confidential passwords</strong>. <strong>Never</strong> share them with others or store them in public documents, unprotected version control systems, or any insecure files.
- <strong>Avoid Hardcoding:</strong> <strong>Never embed Access Key information directly into your code.</strong> This practice is extremely risky; if the code is accessed or shared, the keys will be exposed. Always use secure credential management methods, such as environment variables, key management services, or configuration files stored outside of public code repositories.
- <strong>Delete Unused Access Keys Promptly:</strong> When an access key is no longer needed,<strong>delete it immediately.</strong> Unused keys represent a potential security risk.
- <strong>Regularly Rotate Access Keys:</strong> Implement a policy of regularly rotating access keys. This involves generating new keys and deactivating old ones. Regular rotation minimizes the impact of a compromised key by limiting its validity period.
- <strong>Grant Least Privilege:</strong> Always adhere to the <strong>principle of least privilege</strong>, granting each Access Key only the <strong>minimum necessary permissions</strong> to perform its designated tasks.  Avoid granting broad permissions such as "administrator" or "full access" unless absolutely required.  Fine-grained permission control minimizes potential damage should a key be compromised.

## Create an Access Key

- <strong>Access the Admin Console:</strong> First, log in to your Blocklet Admin Console as a user administrator.
- <strong>Navigate to integration settings:</strong> Open the dashboard, then select `integrations` and click `access keys`.
- <strong>To create a key:</strong> Click the "Create access-key" button.
-
  - <strong>Access Key Name:</strong> A descriptive name that helps you identify this key's purpose (e.g., "CI/CD Deployment Key," "Data Analysis Service Key").
  - <strong>Access Key Permissions:</strong> Critically, grant only the <strong>minimum necessary permissions</strong> required for the key's intended use. This adheres to the principle of least privilege.
  - <strong>Access Key Types:</strong> Blocklets offer two levels of access key security:
  -
    - <strong>Signature Security:</strong> Employs enterprise-grade security standards and encryption technologies.  Integration with the Blocklet SDK (`@abtnode/client`) is required, making it ideal for scenarios demanding high security and involving the transfer of sensitive data.
    - <strong>Simple Security:</strong> This lightweight token mechanism, similar to an OpenAPI Key, <strong>supports RESTful API calls and third-party service integrations.</strong>  Integration is quick and code-free via HTTP headers, making it <strong>ideal for</strong> rapid development and prototyping.
  - <strong>Access Key Expiration Date:</strong> While Access Keys can be set to "permanent" by default, we strongly recommend setting a specific expiration date for enhanced security.

![image.png](https://media.arcblock.io/lib/03/032862e8eb7ed202b2e8fabc5252544b.w1600.webp)

## Working with Access Keys

How you use an Access Key depends on the type you select:

#### 1. Signature Access Key (for SDK integration)

![image.png](https://media.arcblock.io/lib/d0/d00c2a36eb7238894f1370028661884b.w1600.webp)

High-security access keys are generally used in conjunction with the Blocklet SDK to provide robust encryption and authentication.

```javascript
const Client = require('@abtnode/client');

const client = new Client(fullEndpoint);
client.setAuthAccessKey({
  accessKeyId: "z1nDbbdm5egHTJz3KZkaairGt6izf9eMoZV",
  accessKeySecret: "z66V1N8fmn7WtvuHg1PSZWfTshi1pxexGPBfrTDTGLJZ34jkVaTM3yyMcxSAfDhoLPG62TzzBjWdPDig9kCcDm2ZD",
});

const result = await client.getBlocklet( { input: { did: rootDid, attachRuntimeInfo: false } }, { headers: { 'x-access-blocklet': rootDid } }
```

You can also deploy Blocklets to a specific application using this method.

```javascript
blocklet deploy --endpoint https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io --access-key z1nDbbdm5egHTJz3KZkaairGt6izf9eMoZV --access-secret z66V1N8fmn7WtvuHg1PSZWfTshi1pxexGPBfrTDTGLJZ34jkVaTM3yyMcxSAfDhoLPG62TzzBjWdPDig9kCcDm2ZD {blockletPath}/.blocklet/bundle;
```

#### 2. Simple Access Key  (RESTful API Calls)

![image.png](https://media.arcblock.io/lib/8b/8b685011d0d4376491829786524526eb.w1600.webp)

A General Access Key functions similarly to a traditional API key and is well-suited for quick integration with RESTful APIs.

```javascript
curl -H "Authorization: Bearer blocklet-z1ohw91Z6SzKcC2Hs7CwhV2ubCRMoN4zdhhM8NszuDj6" "https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/api/did/session"
```

---

## Application vs Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/application-vs-blocklet/

Before we start developing Blocklets, let’s first understand what an application is and what a Blocklet is.

## Application and Site

Applications are applications installed in Blocklet Server. You can also treat applications in Blocklet Server as sites, such as:

- [https://developer.blocklet.io](https://developer.blocklet.io)
- [www.arcblock.io](https://www.arcblock.io)
- [https://community.arcblock.io](https://community.arcblock.io)
- [www.aistro.io](https://www.aistro.io)

They are all applications running in Blocklet Server

## Blocklet and component

In Blocklet Server, an application is composed of one or more components, and Blocklets are the components that make up the application. Each blocklet in the application is a separate service. They use unified configuration and UI to make you feel like you are using a complete application.

For example, the [developer.blocklet.io](https://developer.blocklet.io/)  site consists of four components, namely:

- [Pages Kit](https://store.blocklet.dev/blocklets/z8iZiDFg3vkkrPwsiba1TLXy3H9XHzFERsP8o) : for creating and displaying pages
- [Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu): Used for producing and displaying documents. This document is officially produced with Discuss Kit.
- [Image Bin](https://) : Provides the ability to upload and download general media files (pictures, videos, etc.)
- [Meilisearch](https://test.store.blocklet.dev/blocklets/z8iZorY6mvb5tZrxXTqhBmwu89xjEEazrgT3t) : a lightweight search engine

## Blocklet application features

After understanding the construction form of the application, we also saw the two major characteristics of Blocklet-based applications

- The application is decentralized and you have complete control over your site.
- The application is componentized, so you can focus only on your own business components and quickly build powerful sites by combining other common components. You can also develop common components and put them in the Blocklet Store for others to use, while bringing you profits.

Let’s start learning Blocklet development!

---

## How to bind a domain to Blocklet and generate SSL/TLS certificate

URL: https://www.arcblock.io/en/docs/blocklet-developer/bind-a-domain/

## Overview

Why do Blocklets need to be bound to a domain name?

Even though we provide a built-in `DID Domain` by default, we strongly recommend NFT projects to bind their own domain names.

The reasons are as follows:

1. The application will appear more formal.
2. Short domain names will make it easier for everyone to remember.

Blocklet supports binding <strong>DID Domain</strong> names and domain names purchased from third-party platforms; however, the binding methods are not completely the same.

## Bind DID Domain

DID Domain is naming services provided by ArcBlock, using DID, NFT, and VC to simplify domain publishing, authorization, and management.

Any application running on the Blocklet Server, whether self-hosted or hosted by ArcBlock, can attach any number of DID Domain names.

<strong>We recommend that you prioritize DID Domain</strong>, as it can save you the trouble of manually configuring DNS resolution and changing resolution; you can refer to this document to bind DID Domain:
[Use DID Domain](/en/docs/did-domain/use-did-domain/)


## Bind a third-party domain

Binding a third-party domain requires manual configuration of DNS resolution. This document takes Cloudflare as an example.

1. Enter the `Dashboard -> Overview` page of the Blocklet
2. Copy the DID Domain to prepare for adding DNS later.

![image.png](https://media.arcblock.io/lib/fd/fd09929a871ef52226c05c0523908535.w1600.webp)

1. Access the Cloudflare domain DNS configuration page and click the "Add Record" button.

![image.png](https://media.arcblock.io/lib/6c/6c56cb095c807546d3e42e3b516d6d0a.w1600.webp)

1. Add a CNAME record with the value being the DID copied in step 2 (It is recommended to temporarily disable the proxy in Cloudflare).

![image.png](https://media.arcblock.io/lib/61/61fdb7571ef4505596a594e35e3ce0e8.w1600.webp)

1. DNS records take time to propagate, which can range from a few minutes to several minutes. You can use [Google Admin Tools](https://toolbox.googleapps.com/apps/dig/#CNAME/) to check if it has already taken effect.

![image.png](https://media.arcblock.io/lib/07/0722a43f237a78974a837f55a69dfde3.w1600.webp)

1. After DNS takes effect, enter the Blocklet's `Dashboard -> Overview` page again and add the domain name.

![image.png](https://media.arcblock.io/lib/d9/d9c1f249c4f65b9e100ed42ed52ab2b3.w1600.webp)

![image.png](https://media.arcblock.io/lib/6d/6dc6852b417d344c9d78a6e35bdbda6f.w1600.webp)

1. After adding a domain name, the Blocklet Server will automatically generate an HTTPS certificate for that domain. Wait for the certificate to be successfully generated. If the domain is successfully created, there will be a "lock" icon next to it.

![image.png](https://media.arcblock.io/lib/bf/bfdb0a0bf1335dd12542eea194b07bd3.w1600.webp)

::::steps
:::step{title="Optional"}
If the automatic generation of the certificate was not successful for some reason, you can click the "Generate Let's Encrypt Certificate" button to retry.
:::
::::

![image.png](https://media.arcblock.io/lib/0a/0a8ecc3994938e43b06584990f1ff956.w1600.webp)

---

## Blocklet GitHub Actions

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-actions/

If you are using GitHub Actions to manage the process of packaging, publishing, and deploying Blocklet applications, then you will more efficient Blocklet application deployment guide in this article.

## What is action workflow?

[action-workflow](https://github.com/blocklet/action-workflow) is a quick release process that we have learned from our extensive Blocklet application development practice.

With action-workflow, we can quickly configure the flow in CI for each Blocklet application, saving development time and debugging time cost in CI.

## How to use action workflow?

First your project needs to create a `.github` folder to enable the [GitHub Actions](https://docs.github.com/en/actions) feature

Then create a `workflows/main.yml` file in `.github` and configure some necessary initialization processes. Such as `git checkout`, `dependencies install`, etc.

Once everything is in place, add the following to access the Blocklet action-workflow functionality.

```javascript
- name: Deploy Blocklet Site
  uses: blocklet/action-workflow@v1
  with:
    skip-deps: false
    skip-bundle: false
    skip-upload: false
    skip-deploy: false
    skip-release: false
    skip-readme: false
    deps-server-version: beta
    deps-npm-client: pnpm
    working-directory: . /
    bundle-command: npm run bundle
    store-endpoint: ${{ secrets.STORE_ENDPOINT }}
    store-access-token: ${{ secrets.STORE_ACCESS_TOKEN }}
    store-developer-did: ${{ secrets.STORE_DEVELOPER_DID }}
    server-endpoint: ${{ secrets.XMARK_NODE_ENDPOINT }}
    server-access-key: ${{ secrets.XMARK_NODE_ACCESS_KEY }}
    server-access-secret: ${{ secrets.XMARK_NODE_ACCESS_SECRET }}
    deploy-app-did: xxxxxx
    deploy-mount-point: xxxxxx
    slack-webhook: xxxxxx
    github-token: xxxxx
```

- `skip-deps`: Whether to skip the blocklet-server environment preparation step, the default is ``false`''
- `skip-bundle`: Whether to skip the bundle step, the default is ``false`''
- `skip-upload`: Whether to skip uploading Blocklet applications to Blocklet Store, the default is `true`.
- `skip-deploy`: Whether to skip the step of deploying the Blocklet application to the specified Blocklet Server, the default is `true`.
- `skip-release`: Whether to skip the release Github Release step, the default is `false`
- `skip-readme`: Whether to skip the step of updating the `README.md` file, default is `false`
- `deps-server-version`: Custom `@blocklet/cli` version, default is `latest`, find more version tags at: [https://www.npmjs.com/package/@blocklet/cli?activeTab=versions](https://www.npmjs.com/package/@blocklet/cli?activeTab=versions)
- `deps-npm-client` Which node package manager do you want to use `@blocklet/cli`, the default is `yarn`
- `working-directory`: The directory where the Blocklet action-workflow is executed, often used in monorepo, where multiple Blocklet applications need to be packaged, uploaded, and released at the same time, default is `. /`
- `bundle-command`: The command to package Blocklet applications, usually `npm run bundle`, if `skip-bundle` is not `true`, then this item is required
- `store-endpoint`: The URL of the Blocklet Store, you can freely configure which Blocklet Store you need to upload the application to, if `skip-upload` is not `true`, then this item is required
- `store-access-token`: The key applied in Blocklet Store, you need to register as the developer of the corresponding Blocklet Store first, then apply for an upload key, if `skip-upload` is not `true`, then this item is required. For more details, please refer to: [Blocklet Store](https://arcblock.io/docs/blocklet-store/en)
- `store-developer-did`: The developer ID of the developer in the corresponding Blocklet Store, this item is required when you need to upload a paid Blocklet. For more details, please refer to: [Blocklet Store](https://arcblock.io/docs/blocklet-store/en)
- `server-endpoint`: The address of the Blocklet Server to be deployed. (if `skip-deploy` is not empty). For more details, please refer to: [Blocklet Deploy](/en/docs/blocklet-developer/blocklet-cli/)
- `server-access-key`: Access Key created in Blocklet Server. (if `skip-deploy` is not empty). For more details, please refer to: [Blocklet Deploy](/en/docs/blocklet-developer/blocklet-cli/)
- `server-access-secret`: The Access Secret created in Blocklet Server. (if `skip-deploy`  is not empty). For more details, please refer to: [Blocklet Deploy](/en/docs/blocklet-developer/blocklet-cli/)
- `deploy-app-did`: Under which Blocklet application the current application will be deployed (become its sub-component), if you need to deploy the application as a sub-component, you need to fill in this item. For more details, please refer to: [Blocklet Deploy](/en/docs/blocklet-developer/blocklet-cli/)
- `deploy-mount-point`: The path where the application is mounted when it is deployed as a subcomponent, if you need to deploy the application as a subcomponent, you need to fill in this item. For more details, please refer to: [Blocklet Deploy](/en/docs/blocklet-developer/blocklet-cli/)
- `slack-webhook`: Configure a Slack webhook to send a Slack notification when the Blocklet application is successfully deployed.
- `github-token`: Configure a `token` with `write` permissions that will be used to update the project's `README.md` file in CI

---

## Blocklet CLI

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-cli/

Blocklet CLI provides `blocklet` command-line tool for controlling and administering Blocklets. Use the following syntax to run `blocklet` commands from your terminal:

```javascript
$ blocklet [options] [command]
```

You can use the `-h` or `--help` to determine the full list of supported commands.

## Version

Shows the current Blocklet CLI version.

```javascript
$ blocklet -V
1.4.4
```

## Create Blocklet Project

Bootstraps an Blocklet project. The command use [create-blocklet](https://www.arcblock.io/docs/createblocklet/en) to generate a project.

```javascript
$ blocklet create
```

## Development a blocklet

### Develop

Develop blocklet from current directory

```javascript
$ blocklet dev

ℹ Try to dev blocklet from xxxxxxxx

ℹ Node DID from config xxxxxx
ℹ Node config from xxxxxx
✔ Installing blocklet-developer-docs@0.1.0... Done in 0.31s
✔ Blocklet blocklet-developer-docs@0.1.0 was successfully installed

...

✔ Blocklet blocklet-developer-docs@0.1.0 was successfully started

ℹ You can access with the following URL

- http://xxxxxx-xxxxxxxxxxxxxxxxxxxx.did.abtnet.io
```

Open the browser after blocklet had been started

```javascript
$ blocklet dev --open
```

Develop blocklet as a component

```javascript
$ blocklet dev --app-id <blocklet-app-id> --mount-point /xxx
```

- `blocklet-app-id` can be viewed in the blocklet details page
- `mount-point` the mount point of the component

### Exec script

Execute script in blocklet running context

```javascript
$ blocklet exec <script>
```

## Meta

This is an informational command which prints meta information for a Blocklet.

```javascript
$ blocklet meta
```

## Manage components in blocklet.yml

### Add

Add component to blocklet.yml

```javascript
$ blocklet add <name> --store <store> --title <title> --mount-point <mount-point>
```

- `name`: the id of the component in the store
- `--store`: which store the component is in
- `--title`: you can customize different names for components
- `--mount-point`: the mount point of the component. If you fill in '/my-prefix', then all requests prefixed with it will be forwarded to the configured component

You can see the command to add a component in the component details page of any store. For example, if you want to add DID Comments, you can go to its [details page](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu) Find the command `blocklet add did-comments --store=https://store.blocklet.dev`

### Remove

Remove component from blocklet.yml

```javascript
$ blocklet remove <name>
```

## Config Blocklet CLI

### Config

Manage the configuration for Blocklet CLI

```javascript
$ blocklet config set [key] [value]    # Set config value
$ blocklet config get [key]            # Get config value
$ blocklet config delete [key]         # Delete config value
$ blocklet config list              # List config value
```

你可为配置项设置不同的 profile

```javascript
$ blocklet config set key value # set key in default profile
$ blocklet config set key value1  --profile profile1 # set key in profile1
$ blocklet config set key value2  --profile profile2 # set key in profile2

$ blocklet config get key # get key in default prifle
$ blocklet config get key --profile profile1 # get key in default prifle1
$ blocklet config get key --profile profile2 # get key in default prifle2
```

### Connect

Connect to blocklet store. This command will set store configuration by `blocklet config`

```javascript
$ blocklet connect <store-url>
```

Set store configuration to specific profile

```javascript
$ blocklet connect <store-url> --profile <profile>
```

After executing the command, the component information will be removed from `blocklet.yml`.

## Build and Publish your blocklet

### Update Version

Bumps up the Blocklet version for next changes.

```javascript
$ blocklet version  1.1.0
✔ Blocklet version bumped to 1.1.0
```

### Bundle

Packages the Blocklet. See the detail in [Blocklet Bundle](/en/docs/blocklet-developer/bundle-your-blocklet/)

```javascript
$ blocklet bundle

ℹ Bundling in webpack mode for blocklet b1...

✔ Creating blocklet bundle in .blocklet/bundle... Done in 0.013s
✔ Blocklet b1@1.0.0 was successfully bundled!
```

### Deploy

<strong>Deploys a blocklet from the local folder to remote Blocklet Server.</strong>

```javascript
$ blocklet deploy <blocklet-bundle-folder> --endpoint xxxxxx --access-key xxxxxx --access-secret xxxxxx
```

blocklet-bundle-folder: The directory built using [blocklet bundle](/en/docs/blocklet-developer/bundle-your-blocklet/)  If you are currently in the project root directory, it is `./blocklet/bundle`.

- `--endpoint`: The address of the server, ending with /admin. For example, the address of your local Blocklet Server is [`http://127.0.0.1/admin`](http://127.0.0.1/admin)
- `--access-key`: Access Key created in Blocklet Server
- `--access-secret`: Access Secret created in Blocklet Server

<strong>Deploys a blocklet from the local folder to local Blocklet Server.</strong>

```javascript
$ blocklet deploy <blocklet-bundle-folder>
```

<strong>Deploys a component from the local folder to Blocklet Server.</strong>

```javascript
$ blocklet deploy <blocklet-bundle-folder> --endpoint xxxxxx --access-key xxxxxx --access-secret xxxxxx --app-id <blocklet-app-id> --mount-point /xxx`
```

- `--app-id`: 应用的 AppID, 可在 blocklet 详情页中查看
- `--mount-point`: 组件的挂载点

<strong>Add component to navigation when component is deployed</strong>

Components are not automatically added to the navigation when they are deployed via `blocklet deploy`. You can add the `--navigation` parameter to add component to the navigation.

```javascript
$ blocklet deploy <blocklet-bundle-folder> --app-id xxx --navigation
```

### Upload to Store

Upload the blocklet release to store. See the detail in [Publish Blocklet](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/)

```javascript
$ blocklet upload [options] [metafile]
```

## Help

The help command is useful to determine information for a particular command. Optionally you can also pass the `-h` option to the sub-command for the same purpose.

```javascript
$ blocklet help meta
Usage: blocklet meta [options]

Print blocklet meta from a directory

Options:
  -h, --help  display help for command
```

---

## Blocklet Composition

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-composition/

Imagine you're playing with Lego bricks. Each brick is unique, with its own color, shape, and function. Now, picture being able to snap these bricks together to create complex structures like houses, cars, or even entire cities. This is essentially what blocklet composition is all about in the world of blockchain and decentralized applications.

## What is a Blocklet?

A blocklet is like a single Lego brick in our analogy. It's a self-contained piece of software that performs a specific function. Just as Lego bricks can be windows, doors, or wheels, blocklets can be comment systems, search engines, or payment processors.

## Blocklet Composition: Putting the Pieces Together

Blocklet composition is the process of combining these individual blocklets to create more complex and feature-rich applications. It's similar to how we combine Lego bricks to build larger structures. This approach allows developers to create powerful applications without reinventing the wheel for every component.

## Real-World Analogies

To better understand blocklet composition, let's look at some similar concepts in other technologies:

::::steps
:::step{title="Docker Containers"}
Think of blocklets as Docker containers. Each container is a standalone unit that includes everything needed to run a piece of software. Just as you can orchestrate multiple Docker containers to create a full-stack application, you can compose blocklets to build complex decentralized apps.
:::

:::step{title="Kubernetes Pods"}
In Kubernetes, pods are groups of one or more containers deployed together. Similarly, when you compose blocklets, you're essentially creating a "pod" of different functionalities that work together seamlessly.
:::

:::step{title="npm Packages"}
If you're familiar with JavaScript development, think of blocklets as npm packages. Just as you can import various npm packages to add functionality to your JavaScript project, you can add blocklets to enhance your decentralized application.
:::
::::

## Benefits of Blocklet Composition

::::steps
:::step{title="Modularity"}
Like Lego bricks, blocklets can be easily added, removed, or replaced without affecting the entire structure.
:::

:::step{title="Reusability"}
Once a blocklet is created, it can be used in multiple projects, saving development time and effort.
:::

:::step{title="Scalability"}
Need more functionality? Simply add another blocklet, just like adding more Lego bricks to expand your creation.
:::

:::step{title="Maintenance"}
Updates and improvements can be made to individual blocklets without overhauling the entire application.
:::
::::

## Conclusion

Blocklet composition is revolutionizing the way we build decentralized applications. By allowing developers to mix and match pre-built components, it's making the creation of complex systems as simple and fun as building with Lego bricks. Whether you're a seasoned blockchain developer or just starting out, understanding blocklet composition is key to creating efficient, scalable, and innovative decentralized applications.

So, the next time you're planning your blockchain project, remember: you're not just coding, you're playing with digital Lego bricks. Happy building!

---

## Blocklet Lifecycle

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-lifecycle/

> This doc is a draft and needs to be updated

| 钩子名称  | 运行时机  | 抛错的影响  | 使用场景  |
|---|---|---|---|
| preInstall  | 全新安装或者升级时，下载完成之后  | 终止安装  | 检查依赖的环境  |
| preFlight | 启动、升级之前 | 终止升级、无法启动 | 变更数据库 Schema 等 |
| preStart  | 启动之前  | 无法启动，报启动失败  | 检查配置、注册账户、初始化数据库等  |
| postStart  | 启动之后  | 无影响  | 生成一些配置、更新索引、状态上报  |
| preStop  | 停止之前  | 无影响  | 做一些清理工作  |
| preConfig  | 修改并保存配置之前  | 配置保存失败  | 校验配置是否有效  |
| migration  | 新版安装完启动之前  | 无法启动，报启动失败  | 迁移数据  |

---

## Blocklet SDK (Node.js)

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-sdk/

Blocklet SDK for blocklet developer

## Install

```javascript
yarn add @blocklet/sdk
```

or

```javascript
npm install @blocklet/sdk
```

## Wallet

```javascript
const { getWallet } = require('@blocklet/sdk');

// wallet is an instance of @ocap/wallet
const wallet = getWallet();
const { address, secretKey, publicKey } = wallet;
```

## Auth

### Get Client

```javascript
const { AuthService } = require('@blocklet/sdk');

const client = new AuthService();
```

### getUser

`client.getUser(did)`

Get user by user did

- <em>@param</em> <strong>did</strong> `string`
- <em>@return</em> `{ code, user }`

### getOwner

`client.getOwner()`

Get the owner of the app

- <em>@param</em> <strong>did</strong> `string`
- <em>@return</em> `{ code, user }`

### getUsers

Get users of the app

#### By Default

```js
client.getUsers();
client.getUsers({ paging: { page: 2 } });
client.getUsers({ query: { role: 'admin' } });
client.getUsers({ query: { approved: true } });
client.getUsers({ query: { search: 'Bob' } });
client.getUsers({ sort: { updatedAt: -1 } });
```

- <em>@param</em> <strong>paging</strong> `Object`
- <strong>paging.pageSize</strong>  The value of pageSize cannot exceed 100
- <strong>paging.page</strong>
- <em>@param</em> <strong>query</strong> `Object`
- <strong>query.role</strong> `String` Match users by role name
-
  - `$none`: Match users who do not have a role
- <strong>query.approved</strong> `Boolean` Match users by approved
- <strong>query.search</strong> `String` Match users by did or name
-
  - Search results by name are fuzzy matches
  - Search results by did are exact matches
- <em>@param</em> <strong>sort</strong> `Object` `-1`: The latest time is at first. `1`: The latest time is at last. Default sort is `{ createdAt: -1 }`
-
  - <strong>sort.createdAt</strong> `Number`
  - <strong>sort.updatedAt</strong> `Number`
  - <strong>sort.lastLoginAt</strong> `Number`
- <em>@return</em> `{ code, users, paging }`

```javascript
Paging {
  total: number of users
  pageSize: number of users per page
  pageCount: number of page
  page: current page number
}
```

#### By User DID

```javascript
client.getUsers({ dids: ['did1', 'did2', ...] });
client.getUsers({ dids: ['did1', 'did2', ...], query: { approved: true } });
```

- <em>@param</em> <strong>Array<string></strong> `dids` The user did list
- > The length of dids cannot exceed 100
- <em>@param</em> <strong>query</strong> `Object`
- <strong>query.approved</strong> `Boolean` Match users by approved
- <em>@return</em> `{ code, users }`

Tips:

- If you don't pass the `dids` parameter, the API will run by default
- If you pass in a non-existing DID, the API <strong>will not</strong> report an error

### updateUserApproval

Enable or disable a user by DID. A disabled user will not login to the blocklet again.

- <em>@param</em> <strong>did</strong> `string`
- <em>@param</em> <strong>approved</strong> `boolean`
- <em>@return</em> `{ code, user }`

```js
client.updateUserApproval(did, true); // enable the user
client.updateUserApproval(did, false); // disable the user
```

### getPermissionsByRole

`client.getPermissionsByRole(role)`

Get all permissions of a role

- <em>@param</em> <strong>role</strong> `string`
- <em>@return</em> `{ code, permissions }`

### getRoles

`client.getRoles()`

Get all roles of the app

- <em>@return</em> `{ code, roles }`

### createRole

`client.createRole({ name, title, description, extra })`

- <em>@param</em> <strong>name</strong> `string` the key of the role, should be unique
- <em>@param</em> <strong>title</strong> `string`
- <em>@param</em> <strong>description</strong> `string`
- @param <strong>extra</strong> `string`, a json stringified extra object, may contain `display` and `types` key
- <em>@return</em> `{ code, role }`

### updateRole

`client.updateRole(name, { title, description })`

- <em>@param</em> <strong>name</strong> `string` the key of the role
- <em>@param</em> <strong>title</strong> `string`
- <em>@param</em> <strong>description</strong> `string`
- <em>@return</em> `{ code, role }`

### deleteRole

`client.deleteRole(name, { title, description })`

- <em>@param</em> <strong>name</strong> `string` the key of the role
- <em>@return</em> `{ code }`

### issuePassportToUser

`client.issuePassportToUser({ userDid, role })`

- <em>@param</em> <strong>userDid</strong> `string`
- <em>@param</em> <strong>role</strong> `string` the key of the role. e.g. `owner`, `admin`, `member`
- @param <strong>display</strong> `object`  standard nft display object `{ type: string, content: string }`
- @param <strong>notify</strong> `bool`  should we send notification to wallet
- <em>@return</em> `{ code, user }`

### enableUserPassport

`client.enableUserPassport({ userDid, passportId })`

set passport status to `valid`

- <em>@param</em> <strong>userDid</strong> `string`
- <em>@param</em> <strong>passportId</strong> `string` passportId (get from user.passports)
- <em>@return</em> `{ code, user }`

### revokeUserPassport

`client.revokeUserPassport({ userDid, passportId })`

set passport status to `revoked`

- <em>@param</em> <strong>userDid</strong> `string`
- <em>@param</em> <strong>passportId</strong> `string` passportId (get from user.passports)
- <em>@return</em> `{ code, user }`

### grantPermissionForRole

`client.grantPermissionForRole(role, permission)`

- <em>@param</em> <strong>role</strong> `string` the name of the role
- <em>@param</em> <strong>permission</strong> `string` the name of the permission
- <em>@return</em> `{ code }`

### revokePermissionFromRole

`client.revokePermissionFromRole(role, permission)`

- <em>@param</em> <strong>role</strong> `string` the name of the role
- <em>@param</em> <strong>permission</strong> `string` the name of the permission
- <em>@return</em> `{ code }`

### updatePermissionsForRole

`client.updatePermissionsForRole(role, permissions)`

Full update permissions of a role

- <em>@param</em> <strong>role</strong> `string` the name of the role
- <em>@param</em> <strong>permissions</strong> `array<string>` name of the permissions
- <em>@return</em> `{ code, role }`

### hasPermission

`client.hasPermission(role, permission)`

- <em>@param</em> <strong>role</strong> `string` the name of the role
- <em>@param</em> <strong>permission</strong> `string` the name of the permission
- <em>@return</em> `{ code, result }`
- <strong>result</strong> `boolean`

### getPermissions

`client.getPermissions()`

Get all permissions of the app

- <em>@return</em> `{ code, permissions }`

### createPermission

`client.createPermission({ name, title, description })`

- <em>@param</em> <strong>name</strong> `Permission` the key of the permission, should be unique
- format: `<action>_<resource>`. e.g. `query_article`, `mutate_user`
- <em>@param</em> <strong>description</strong> `string`
- <em>@return</em> `{ code, role }`

### updatePermission

`client.updatePermission(name, { title, description })`

- <em>@param</em> <strong>name</strong> `string` the key of the role
- <em>@param</em> <strong>title</strong> `string`
- <em>@param</em> <strong>description</strong> `string`
- <em>@return</em> `{ code }`

### deletePermission

`client.deletePermission(name, { title, description })`

- <em>@param</em> <strong>name</strong> `string` the key of the permission
- <em>@return</em> `{ code }`

### login

`client.login({ provider, did, pk, avatar, email, fullName, id, locale })`

- <em>@return</em> `{ user, token, refreshToken }`

### refreshSession

`client.refreshSession({ refreshToken })`

- <em>@param</em> <strong>refreshToken</strong> `string` the refresh token
- <em>@return</em> `{ user, token, refreshToken }`

## Notification

```javascript
const { Notification } = require('@blocklet/sdk');
```

### sendToUser

`Notification.sendToUser(receiver, notification)`

Send notification to an account

```javascript
const userDid = 'xxxxxxxx';

const notification = {
  title: 'xxx',
  body: 'xxx',
  attachments: [
    {
      type: 'asset',
      data: {
        did: 'xxx',
        chainHost: 'https://chainhost',
      },
    },
  ],
  actions: [
    {
      name: 'xxx',
      title: 'Go To Website',
      link: 'https://arcblock.io',
    },
  ],
};

const content = { message: 'this is a message' };
const actions = [];

await Notification.sendToUser(userDid, notification);

await Notification.sendToUser(userDid, [notification, anotherNotification]);
await Notification.sendToUser([userDid, anotherUserDid], notification);
await Notification.sendToUser([userDid, anotherUserDid], [notification, anotherNotification]);
```

- <strong>notification</strong> [Notification](#notification-type)
- <strong>receiver</strong> `string | array<string>` required

### broadcast

`Notification.broadcast(notification, options)`

Broadcast notification to a channel

```javascript
const notification = {
  title: 'xxx',
  body: 'xxx',
};

await Notification.broadcast(notification);
await Notification.broadcast(notification, { socketDid: 'did' });
```

- <strong>notification</strong> [Notification](#notification-type)
- <strong>options</strong>
- <strong>socketDid</strong>: `String` send notification to a specific socket by socketDid
- <strong>socketId</strong>: `String` send notification to a specific socket by socketId
- <strong>channel</strong>: `String` send notification to which channel (Default: app public channel)
- <strong>event</strong>: `String` send notification to which event (Default: 'message')

### Notification Type

- <strong>notification</strong> `object | array<object>` required
- <strong>notification.title</strong> `string`
- <strong>notification.body</strong> `string`
- <strong>notification.attachments</strong> `array<object>`
-
  - <strong>attachment.type</strong> `enum` 'asset', 'vc', 'token' required
  - <strong>attachment.data</strong> `object`
  - <em>type: text</em>
  -
    - <strong>type</strong> `string`
    - <strong>message</strong> `string`
  - <em>type: asset</em>
  -
    - <strong>did</strong> `string`
    - <strong>chainHost</strong> `string` uri
  - <em>type: vc</em>
  -
    - <strong>credential</strong> `object`
    - <strong>tag</strong> `string`
  - <em>type: token</em>
  -
    - <strong>address</strong> `string` did
    - <strong>amount</strong> `string`
    - <strong>symbol</strong> `string`
    - <strong>senderDid</strong> `string`
    - <strong>chainHost</strong> `string`
    - <strong>decimal</strong> `integer`
- <strong>notification.actions</strong> `array<object>`
-
  - <strong>name</strong> `string` required
  - <strong>title</strong> `string`
  - <strong>color</strong> `string`
  - <strong>bgColor</strong> `string`
  - <strong>link</strong> `string` uri

### on

`Notification.on()`

Listen for system notification

```javascript
Notification.on('hi', () => {});
```

### off

`Notification.off()`

Cancel listening for system messages

```javascript
const handler = () => {};

Notification.on('hi', handler);
Notification.off('hi', handler);
```

### System Events

#### 'hi'

When the client joins the app public channel

```js
Notification.on('hi', ({ sender: { socketId, did } }) => {});
```

- <strong>sender</strong> `object`
- <strong>sender.socketId</strong> `string`
- <strong>sender.did</strong> `string`

## DID Connect

```javascript
import AuthStorage from '@arcblock/did-auth-storage-nedb';
import { WalletAuthenticator, WalletHandlers } from '@blocklet/sdk';

const authenticator = new WalletAuthenticator();

const handlers = new WalletHandlers({
  authenticator,
  tokenGenerator: () => Date.now().toString(),
  tokenStorage: new AuthStorage({
    dbPath: path.join(process.env.BLOCKLET_DATA_DIR, 'auth.db'),
    onload: (err) => {
      if (err) {
        // eslint-disable-next-line no-console
        console.error(`Failed to load database from ${path.join(process.env.BLOCKLET_DATA_DIR, 'auth.db')}`, err);
      }
    },
  }),
});
```

## Database

A database library for develop blocklet, it's a wrapper of [nedb](https://www.github.com/Arcblock/nedb).
Supply a simpler way to use nedb. Just use `new Database([dbName])`, or you can pass a object option as second parameter to create a database as origin nedb way `new Database([dbName], [options])`

Supply full-promise and typescript support.

```javascript
import { Database } from '@blocklet/sdk';

// Getting Started
(async () => {
  const db = new Database('demo.db');
  const inserted = await db.insert({ key: 'value' });
  const docs = await db.find({});
  const paginated = await db.cursor({}).skip(1).limit(10).exec();
})();

// Extend with class
(async () => {
  class MyDatabase extends Database {
    async extraFn() {
      return 'extra';
    }
  }
  const db = new MyDatabase('demo.db');
  const inserted = await db.insert({ key: 'value' });
  const docs = await db.find({});
  const paginated = await db.cursor({}).skip(1).limit(10).exec();
  const extra = await db.extraFn();
})();
```

## Environment

```javascript
import { env } from '@blocklet/sdk';

const {
  appId, // the did of the app
  appPid, // the permenant did of the app
  appIds, // all did's that the application has previously used
  appName, // the title of the app, used to display to user
  appDescription, // the description of the app
  appUrl, // the web url of the app
  appStorageEndpoint // the endpoint of the DID Spaces of the app
  componentDid, // the did of the blocklet
  dataDir, // the data dir of the blocklet
  cacheDir, // the cache dir of the blocklet
  mode, // in which mode the blocklet is running
  serverVersion: // the version of the server where the app is running
  preferences, // blocklet preferences. default: {}
} = env;
```

Please reference [Blocklet Preferences](/how-to/preferences) for how to change the structure and value in `env.preferences`.

### mode

In which mode the blocklet is running

```js
env.mode === 'development'; // The blocklet is running in the development mode
env.mode === 'production'; // The blocklet is running in the production mode
```

## Config

Unlike Environment, the information in Config will be updated in real time, the application does not need to be restarted, and events will be thrown when updating

```javascript
import { env, components, events, Events } from '@blocklet/sdk/lib/config'
```

- `env` same as env in Environment
- `appId` the did of the app
- `appPid` the permenant did of the app
- `appIds` all did's that the application has previously used
- `appName` the title of the app, used to display to user
- `appDescription` the description of the app
- `appUrl` the web url of the app
- `appStorageEndpoint` the endpoint of the DID Spaces of the app
- `componentDid` 组件 DID
- `dataDir` the data dir of the blocklet
- `cacheDir` the cache dir of the blocklet
- `mode` in which mode the blocklet is running
- `serverVersion` the version of the server where the app is running
- `preferences` blocklet preferences. default: {}
- `components` <strong>Array\<object\></strong>
- `title` component title
- `did` component did
- `name` component name
- `version` component version
- `mountPoint` e.g. '/', '/blog'
- `status` <strong>import(@blocklet/constant).BlockletStatus</strong>
- `port` e.g. 5678
- `webEndpoint` e.g. [http://127.0.0.1:5678](http://127.0.0.1:5678)
- `resources` <strong>Array<string></strong> component resource path

```typescript
events.on(Events.componentAdded, (components) => {});
events.on(Events.componentRemoved, (components) => {});
events.on(Events.componentStarted, (components) => {});
events.on(Events.componentStopped, (components) => {});
events.on(Events.componentUpdated, (components) => {});

events.on(Events.envUpdate, (envs: {key: string; value: string}[]) => {});
```

## Component

```javascript
import { Component } from '@blocklet/sdk';
```

### getComponentWebEndpoint

`Component.getComponentWebEndpoint(name)`

Get endpoint of component of app

- <em>@param</em> <strong>name</strong> `string` the name or title or did of the <strong>component bundle</strong>

If the blocklet.yml of component is

```javascript
did: did1
name: demo-blocklet
title: Demo Blocklet
```

the blocklet should use like this:

```javascript
Component.getComponentWebEndpoint('did1')
Component.getComponentWebEndpoint('demo-blocklet')
Component.getComponentWebEndpoint('Demo Blocklet')
```

- <em>@return</em> endpoint of the first-level component. e.g. [`http://127.0.0.1:5678`](http://127.0.0.1:5678)

### getComponentMountPoint

`Component.getComponentMountPoint(name)`

Get mount point of component of app

- <em>@param</em> <strong>name</strong> `string` the name or title or did of the <strong>component bundle</strong>

If the blocklet.yml of component is

```javascript
did: did1
name: demo-blocklet
title: Demo Blocklet
```

the blocklet should use like this:

```javascript
Component.getComponentMountPoint('did1')
Component.getComponentMountPoint('demo-blocklet')
Component.getComponentMountPoint('Demo Blocklet')
```

- <em>@return</em> mount point of the first-level component. e.g. `/abc`

### call

Communicate with component component safely

`Component.call({ name, path, data })`

- <em>@param</em> <strong>name</strong> `string` the name or title or did of the <strong>component bundle</strong>
- <em>@param</em> <strong>path</strong> `string` the http api. e.g. `/api/xxx`
- <em>@param</em> <strong>data</strong> `object` the payload
- <em>@param</em> <strong>method</strong> `object` http method
- <em>@param</em> <strong>responseType</strong> `undefined | 'stream'` response type
- <em>@return</em> `object` the response of axios [https://github.com/axios/axios#response-schema](https://github.com/axios/axios#response-schema)

e.g.

component-1:

```js
import { Component, middlewares } from '@blocklet/sdk';

const app = express();

app.post(
  '/api/component-2',

  // You should use verifySig middleware to prevent unknown request
  middlewares.component.verifySig,

  (req, res) => {
    // req.body is { msg: "ping from component-2" } if the request is from component-2

    res.json({ msg: 'pong from component-1' });
  }
);

// data: { msg: 'pong from component-2' }
const { data } = await Component.call({
  name: 'component-1',
  path: '/api/component-2',
  data: { msg: 'ping from component-1' },
});
```

component-2:

```js
const app = express();

app.post(
  '/api/component-2',

  // You should use verifySig middleware to prevent unknown request
  middlewares.component.verifySig,

  (req, res) => {
    // req.body is { msg: "ping from component-1" } if the request is from component-1

    res.json({ msg: 'pong from component-2' });
  }
);

// data: { msg: 'pong from component-1' }
const { data } = await Component.call({
  path: '/api/component-1',
  data: 'ping from component-2',
});
```

## Middlewares

### Session

```javascript
import express from 'express';
import { middlewares } from '@blocklet/sdk';

const app = express();

/* Once user is verified, req.user will be like
export type SessionUser = {
  did: string;
  role: string | undefined; // will be `component` when authenticated with componentCall or signedToken
  provider: string;
  fullName: string;
  walletOS: string; // will be `embed` when authenticated with componentCall or signedToken
  emailVerified: boolean; // will always be false when authenticated with componentCall or signedToken
  phoneVerified: boolean; // will always be false when authenticated with componentCall or signedToken
  kyc?: number;
  method: 'loginToken' | 'componentCall' | 'signedToken';
  [key: string]: any;
}; */

app.use(middlewares.session({ loginToken: true })); // only decode user from loginToken
app.use(middlewares.session({ componentCall: true }); // decode user from loginToken and componentCall
app.use(middlewares.session({ signedToken: true }); // decode user for short lived and signed jwt token
app.use(middlewares.session({ accessKey: true }); // decode user from accessKey

app.use(middlewares.session({ loginToken: true, strictMode: true })); // will throw when loginToken invalid
```

### Access

```javascript
import express from 'express';
import { middlewares } from '@blocklet/sdk';

const app = express();

app.get('/auth1', middlewares.auth(), (req, res) => {
  // will return 401 if user is not connected
});

app.get('/auth2', middlewares.auth({ roles: ['admin', 'owner'] }), (req, res) => {
  // will return 401 if user is not connected
  // will return 403 if user role is neither owner nor admin
});

app.get('/auth3', middlewares.auth({ permissions: ['mutate_data', 'query_data'] }), (req, res) => {
  // will return 401 if user is not connected
  // will return 403 if neither 'mutate_data' nor 'query data' in user permissions
});

app.get(
  '/auth4',
  middlewares.auth({ roles: ['admin', 'owner'], permissions: ['mutate_data', 'query_data'] }),
  (req, res) => {
    // will return 401 if user is not connected
    // will return 403 if user role is neither owner nor admin
    // will return 403 if neither 'mutate_data' nor 'query data' in user permissions
  }
);

app.get('/auth5', middlewares.auth({ kyc: ['email'] }), (req, res) => {
  // will return 401 if user email is not verified
});

app.get('/auth6', middlewares.auth({ methods: ['componentCall'] }), (req, res) => {
  // will return 401 if user is not authenticated with componentCall
});
```

### User(deprecated)

```javascript
import express from 'express';
import { middlewares } from '@blocklet/sdk';

const app = express();

app.get('/', middlewares.user(), (req, res) => {
  const { did, fullName, role } = req.user;
});
```

### Secure communication between components

```javascript
import express from 'express';
import { middlewares } from '@blocklet/sdk';

const app = express();

app.post('/component-private-api', middlewares.component.verifySig, (req, res) => {
  // will return 400 if sig not found in req
  // will return 401 if verify sig failed
});
```

## Security

When blocklet needs to encrypt and decrypt sensitive information, the security module comes to help:

```javascript
const assert = require('assert');
const { Security } = require('@blocklet/sdk');

const message = 'some sensitive info';
const encrypted = Security.encrypt(message);
const decrypted = Security.decrypt(encrypted);
assert.notEqual(encrypted, message);
assert.notEqual(encrypted, decrypted);
assert.equal(decrypted, message);
```

> [!NOTE]
> The security module uses AES encryption internally, all encryption params are derived from blocklet server secret key using a deterministic algorithm.

---

## Blocklet Server Architecture

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-server-architecture/

> [!NOTE]
> this page is a draft and need to be updated

![](https://media.arcblock.io/docs/blocklet-server-architecture/images/blocklet-server.w1600.webp)

---

## Blocklet Server CLI

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-server-cli/

Blocklet Server CLI provides `blocklet server` command-line tool for controlling and administering Blocklet Server in local machine. Use the following syntax to run `blocklet server` commands from your terminal:

```javascript
blocklet server [options] [command]
```

You can use the `-h` or `--help` to determine the full list of supported commands.

## Version

```javascript
$ blocklet -V
x.x.x
```

## Init

Init a Blocklet Server

```javascript
$ blocklet server init

blocklet server vx.x.x
? Are you sure to initialize a Blocklet Server instance in the current directory(/path/to/xxx) (y/N)

✔ Blocklet Server configuration is successfully generated /path/to/xxx/.blocklet-server/config.yml
ℹ blocklet server start
```

## Start

Start a Blocklet Server

```javascript
$ cd <your blocklet server folder>
$ blocklet server start
```

## Stop

Stop Blocklet Server and blocklets

```javascript
$ cd <your blocklet server folder>
$ blocklet server stop
```

## Status

Show Blocklet Server and blocklet status

```javascript
$ cd <your blocklet server folder>
$ blocklet server status
```

## Logs

Show Blocklet Server and blocklet log files

```javascript
$ cd <your blocklet server folder>
$ blocklet server logs
```

## Info

Get environment information for debugging and issue reporting

```javascript
$ cd <your blocklet server folder>
$ blocklet server info
```

Copy info to clipboard

```javascript
$ cd <your blocklet server folder>
$ blocklet server info --clipboard
```

## Upgrade

Self-Upgrade Blocklet Server

```javascript
$ blocklet server upgrade
```

---

## Blocklet Server Routing

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-server-routing/

TBD: Blocklet server routing pipeline

---

## Blocklet Server Troubleshooting Checklist for Self-inspection

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-server-troubleshooting-self-checklist/

## Introduction

When the Blocklet Server is started and running, it may encounter some common issues. It could be that the application cannot be accessed due to developer environment proxy, or it could be a domain resolution error caused by the Blocklet Server update mechanism.

After the network switch, the Blocklet Server did not restart, resulting in the domain name resolution records not being updated in time, which in turn caused the application to be inaccessible and so on.

To help developers troubleshoot these common issues, a self-checklist is specially written to help developers quickly pinpoint and solve some common problems.

## Reading object.

This article is aimed at developers with certain development experience.

## Scope of application

This checklist is for reference on how to self-diagnose and resolve when the Server cannot start normally and the application cannot be accessed after
[安装 Blocklet CLI](/zh/docs/blocklet-developer/install-blocklet-cli/)
.

## Checklist

- [ ] Make sure the server is completely shut down: If the local server cannot start, before executing  `blocklet server start`, please execute  `blocklet server stop -f`, and then check if the issue is resolved
- [ ] Check network proxy: The Blocklet Server and Blocklet are both running locally. When accessing the Server and Blocklet on the local machine, the global proxy should not be enabled. You can try disabling the global proxy, and then check if the issue is resolved.
- [ ] Check domain resolution: Both the Blocklet Server and Blocklet run locally, so should their DNS be resolved to the local machine IP? Please use commands like dig to check if the DNS resolution is correct. If incorrect, you need to see if your router has any special configurations.
- [ ] Check network changes: Given the previous two, if the local network has been switched, it is necessary to perform `blocklet server start`, and after restarting, the problem will most likely disappear.
- [ ] Check Blocklet Server version: If the server is not the latest beta version, use `npm install -g @blocklet/cli@beta` to upgrade, then restart the server. Does the issue disappear?
- [ ] Check the Node.js installation method: If Node.js is installed using fnm, it is recommended to try installing Node.js using nvm.
- [ ] Check Node.js version: In particular, there may be issues under v22.5.x, and it is recommended to use versions 21.6.0~22.4.x. Have the issues been resolved after switching Node.js?
- [ ] Check the package manager of blocklet cli: If @blocklet/cli is not installed using npm, it is recommended to uninstall @blocklet/cli, install it globally using npm, then restart the server and see if the issue is resolved?

## Get help.

If the above solution still cannot solve your problem, please go to our social forum [https://community.arcblock.io/](https://community.arcblock.io/) for help.

---

## Blocklet Service

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-service/

Blocklet Service provides some out-of-the-box services for Blocklets.

After the blocklet is installed, it can be accessed through `{blocklet domain}/{following path}`

e.g. https://developer.blocklet.io/.well-known/service/health

## Web page

- `/.well-known/service/lost-passport` Retrieve the passport
- `/.well-known/service/login` Access the login page
- `/.well-known/service/admin` Access the management background
- `/.well-known/service/blocklet/logo` Get the app logo
- `/favicon.ico` Get the app favicon

## API

- `/.well-known/service/health` Returns 200 when the blocklet is running, 503 otherwise
- `/.well-known/service/api/did/session` Get the current login user information

---

## Blocklet Storage

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-storage/

## Using local database

### Local Storage

你可以使用 Blocklet SDK 获取 blocklet 的存储目录

```js
const fs = require('fs');
const { env } = require('@blocklet/sdk');

fs.writeFileSync(path.join(env.dataDir, 'data.txt'), 'blocklet data');
```

### File Database

Blocklet SDK 为 blocklet 提供一个基于文件的数据库

见 [Blocklet SDK: Database](/en/docs/blocklet-developer/blocklet-sdk/)

> [!NOTE]
> TODO: ## Using browser database

> [!NOTE]
> TODO: ## Using Remote database

> [!NOTE]
> TODO: ## Using decentralized data store

## Using ORM

### <del>Prisma + SQLite</del>(deprecreated)

#### Prerequisites

You need Node.js `v14.17.0` or higher for this guide (learn more about [system requirements](https://www.prisma.io/docs/reference/system-requirements)).

#### 1. Initialization prisma

The first step is to install the `prisma` dependency in your project:

```javascript
yarn add prisma -D
```

Execute the following command to initialise `prisma` and use SQLite as your database:

```javascript
npx prisma init --datasource-provider sqlite
```

At this point, a new `prisma` directory and `.env` file will be created in the project root, and SQLite will be configured as your database。

#### 2. Database modelling

We now need the database to be modelled in order to describe the data we store.

Add the user model to the file `prisma/schema.prisma` with the following content:

```typescript
// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
  // Note, please do not customise the output parameters of the generator, there is currently a bug, see: https://github.com/prisma/prisma/issues/13233
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

// 添加用户模型
model User {
  id    String  @id @default(uuid())
  email String  @unique
  name  String?
}
```

If you are using vscode as your development tool, you can install the [prisma plugin](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) to get a better coding experience when modelling.

You can use the `npx prisma format` command to help you format the `schema.prisma` file and verify where the error occurred.

> [!WARNING]
> Note, please do not customize the generator's output parameter, it is currently buggy, see: https://github.com/prisma/prisma/issues/13233

#### 3. Creating databases and data tables

At this point, you already have a model of the database, but you have not yet created the data and data tables. You will need to run the following command to create the database and data tables:

```javascript
npx prisma migrate dev --name init // Execution in local environment only
```

This order does two things:

1. it creates a new SQL migration file `prisma/migrations` in the directory for this migration. 2. it runs the SQL migration file against the database.
2. It runs the SQL migration file against the database.

Since the SQLite database file did not exist before, the command also created it in the `prisma` directory with the name `dev.db` defined by the environment variable in the `.env` file.

Congratulations, you have now created your database and data tables. Now let's start learning how to manipulate the data using the `Prisma Client`.

#### 4. Adding, deleting and checking data using Prisma Client

To manipulate the database you can import `@prisma/client` to do this, create the `test.js` file and add the following code to it:

```typescript
const { PrismaClient } = require("@prisma/client");
const prismaClient = new PrismaClient();

async function main() {
  // Delete records
  const batchPayload = await prismaClient.user.deleteMany();
  console.log("delete", batchPayload.count);

  // Create a record
  const user = await prismaClient.user.create({
    data: {
      email: "2565978507@qq.com",
      name: "skypesky",
    },
  });
  console.log("create", user);

  // Update records
  const updatedUser = await prismaClient.user.update({
    where: {
      email: "2565978507@qq.com",
    },
    data: {
      name: "skypesky666",
    },
  });
  console.log("update", updatedUser);

  // Query records
  const users = await prismaClient.user.findMany();
  console.log("find", users);
}

main();
```

Then, execute the script using the following command:

```javascript
node test.js
```

You can see the following output in the terminal:

```javascript
delete 0
create {
  id: '1736c1c1-7560-4d7d-9b04-dcc6dd1dd1fb',
  email: '2565978507@qq.com',
  name: 'skypesky'
}
update {
  id: '1736c1c1-7560-4d7d-9b04-dcc6dd1dd1fb',
  email: '2565978507@qq.com',
  name: 'skypesky666'
}
find [
  {
    id: '1736c1c1-7560-4d7d-9b04-dcc6dd1dd1fb',
    email: '2565978507@qq.com',
    name: 'skypesky666'
  }
]
```

If you want to know more about the usage of `CRUD`, please refer to: [https://www.prisma.io/docs/concepts/components/prisma-client/crud](https://www.prisma.io/docs/concepts/components/prisma-client/crud)

#### 5. Visualisation of data in Prisma

Prisma comes with a built-in GUI for viewing and editing data in the database. You can open it using the following command:

```javascript
npx prisma studio
```

At this point, the terminal will output the address of prisma studio:

```javascript
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma
Prisma Studio is up on http://localhost:5556
```

Use your browser to access `prisma studio` and you should be able to see all the records in the `user` data table:

![](https://media.arcblock.io/docs/blocklet-storage/images/view-user-model.prisma-studio.w1600.webp)

#### 6. Deployment to the official environment

First we need to generate the Prisma Client using the following command:

```javascript
npx prisma generate // Generate @prisma/client client, recommended under pre-install hook
```

Next, we need to execute the following command in the terminal to complete the migration of the generated environment database:

```javascript
npx prisma migrate deploy // All migration scripts will be applied in the official environment and it is recommended that this is done under the pre-install hook
```

The code for the `pre-install.js` file can be found in the following example:

```typescript
require('dotenv-flow').config();
const { name } = require('../../package.json');
const urljoin = require('url-join');
const exec = require('shelljs.exec');
const { logger } = require('../../libs/logger');
const env = require('@blocklet/sdk/lib/env');

async function createSqliteDatabase() {
  const schemaUrl = urljoin(process.cwd(), 'prisma/schema.prisma');
  // Note: npx may run an unexpected cached version of prisma,
  // so it is recommended to use "latest" or a specified version for prisma here.
  exec(`npx prisma@latest generate --schema ${schemaUrl}`);

  if (process.env.DATABASE_URL) {
    return;
  }

  process.env.DATABASE_URL = `file:${urljoin(env.dataDir, 'db/prd.db')}`;

  // @see: https://www.prisma.io/docs/concepts/components/prisma-migrate/db-push#can-i-use-prisma-migrate-and-db-push-together
  exec(`npx prisma@latest migrate deploy --schema ${schemaUrl}`);
}

(async () => {
  try {
    await createSqliteDatabase();
  } catch (err) {
    logger.error(`${name} pre-start error`, err.message);
    process.exit(1);
  }
})();
```

This completes the deployment of prisma and SQLite in the official environment!

## FAQ

- Error when using prisma `Prisma only supports Node.js >= 14.7` and `Error: ENOENT: no such file or directory, open 'xxx/schema.prisma'`

> [!TIP]
> This is because the node.js version is too low, just upgrade the node.js version to 14.17 or higher and restart the blocklet server to fix the problem.

---

## Blocklet Studio

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-studio/

### What is Blocklet Studio?

Blocklet Studio is a visual building tool for Blocklets, allowing users to leverage the combinable and customizable features of Blocklets to create and publish new Blocklet instances to the Blocklet Store.

For instance, the ArcBlock.io website was constructed by combining and configuring multiple official Blocklets, transforming the entire site into a brand-new Blocklet. When users need to publish their customized Blocklets and list them on the application market for others to use, they can do so conveniently through Blocklet Studio.

### Why do we need Blocklet Studio?

The primary function of Blocklet Studio is to simplify the entire process of creating and publishing Blocklets, allowing for operation without the need for programming. Users can directly publish their valuable Blocklets resources, configurations, and combination plans, forming one or multiple new Blocklets, thereby providing value to other users and earning revenue.

### How to access Blocklet Studio?

If you are an administrator (Admin) or owner (Owner) of a Blocklet instance, you can use Blocklet Studio by accessing the Blocklet Dashboard page and opening the Studio tab, as shown below:

![image.png](https://media.arcblock.io/lib/68/68b64fb5999608f15d9e8b59f69cfae3.w1600.webp)

### How do I use Blocklet Studio?

[Create a Blocklet](/en/docs/blocklet-developer/blocklet-studio-create-blocklet/)

[Test a Blocklet](/en/docs/blocklet-developer/7CKdPI2ZzVD6YGbPOiKO-nLR/)

[Publishing a Blocklet](/en/docs/blocklet-developer/publish-blocklet/)

[Delete a Blocklet](/en/docs/blocklet-developer/blocklet-studio-delete-blocklet/)

---

## Create a Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-studio-create-blocklet/

Before Create a Blocklet, you need to become a developer of the Blocklet Store. Please refer to:

[Get your developer passport](/en/docs/blocklet-store/get-your-developer-passport/)

### Create a Blocklet

We enter the Blocklet Studio page and click the "New Blocklet" button:

![image.png](https://media.arcblock.io/lib/68/68b64fb5999608f15d9e8b59f69cfae3.w1600.webp)

### Fill in Blocklet information

We need to provide some information for the new Blocklet:

![image.png](https://media.arcblock.io/lib/9a/9ad0bc075272a028d544fdd25e2fb493.w1600.webp)

Next, I will explain the meanings of several key fields:

Blocklet DID: The Blocklet DID is the unique ID of the Blocklet. When created, it will prompt us to bind a specific wallet. All future ownership and earnings of this Blocklet will belong to that wallet.

![image.png](https://media.arcblock.io/lib/46/466dcfce24f7b9e64abcdff43ab152bd.w1600.webp)

![image.png](https://media.arcblock.io/lib/0a/0a2039d0beb1578fbd915694265c0824.w1600.webp)

Resources: This indicates the need to reuse certain resources from the current instance for the newly created Blocklet. After selecting the resources to be reused, clicking save will back up the resources at that moment for the current Blocklet.

![image.png](https://media.arcblock.io/lib/4f/4fbf84ad33af82d3b6f9746b651293f3.w1600.webp)

Blocklets: This specifies which Blocklets the current Blocklet needs to be associated with. Associated Blocklets will be installed and run simultaneously with the Blocklet. If it is a strongly dependent blocklet, it will ensure that the blocklet runs simultaneously with this Blocklet. When we associate a blocklet, all configurations of the blocklet will also be reused for the Blocklets of this Blocklet.

When we associate a blocklet, all configurations of the blocklet will also be reused in the blocklet of this Blocklet.

![image.png](https://media.arcblock.io/lib/e7/e752f345167d5bc95948c0570352355f.w1600.webp)

### Publish a new release

After filling in all the details, click the "Create release" button at the top right to create a new Blocklet:

![image.png](https://media.arcblock.io/lib/88/884496aad75642cc077de215a2a300f1.w1600.webp)

Return to the homepage of Blocklet Studio, where we can see the application we just created:

![image.png](https://media.arcblock.io/lib/38/38f0e9fe203e48f8669b3fa8dec2a39d.w1600.webp)

---

## Delete a Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-studio-delete-blocklet/

In the Blocklet Studio list, you can click the delete button of a specific Blocklet to remove it:

![image.png](https://media.arcblock.io/lib/5a/5a31d78dd203f6b60f5417fef60967c4.w1600.webp)
Upon clicking, a prompt message will appear. Please read it carefully as it outlines the risks associated with deleting a Blocklet:

- Once a Blocklet is deleted, it cannot be recovered.
- You will be unable to publish new versions for the deleted Blocklet, meaning it will no longer receive updates in the Blocklet Store.
- Deleting a Blocklet will not affect published versions in the Blocklet Store.

![image.png](https://media.arcblock.io/lib/48/48150fdb2a3486790f832b5829afabbf.w1600.webp)

Next, verification of ownership of the Blocklet is required. Please use the wallet used to create this Blocklet for verification:

![image.png](https://media.arcblock.io/lib/d0/d09874f3126113f9a229b6341646ee35.w1600.webp)

Upon successful verification, your Blocklet will be successfully deleted:

![image.png](https://media.arcblock.io/lib/68/68b64fb5999608f15d9e8b59f69cfae3.w1600.webp)

---

## Upload static resources

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-studio-upload-static/

If you have a project with static resources, you can directly use Blocklet Studio to create a Blocklet.

Here is a video tutorial on creating a static Blocklet in Blocklet Studio through upload:

<video src="https://media.arcblock.io/lib/84/84d7b76c788add4b830a52e6e200be00.mp4" controls></video>

---

## Blocklet UI

URL: https://www.arcblock.io/en/docs/blocklet-developer/blocklet-ui/

Blocklet UI 是一个用于快速构建 Blocklet 的前端组件库。区别于一般的 UI 组件库，Blocklet UI 提供的组件通常需要工作在 Blocklet 环境中，在页面渲染时，Blocklet UI 会读取 Blocklet 运行时信息 (称为 Blocklet Meta), 比如 Blocklet Logo，应用名称，导航菜单 等信息，然后基于这些信息来渲染用户界面。

Blocklet UI 有 2 个核心目的:

1. 根据 Blocklet 运行时信息自动渲染用户界面，以快速、便捷地开发 Blocklet 应用。
2. 在组合式 Blocklet 的场景中，为各个 Blocklet 组件 (父/子 Blocklet) 提供更一致的用户界面。

Blocklet UI 目前主要提供了 Header, Footer 和 Dashboard 三个组件，Header 和 Footer 是应用中不可缺少的元素，而 Dashboard 主要用于构建管理端用户界面，本文后续会有专门的章节来讲述如何使用这些组件。

## Blocklet UI 与 Blocklet Meta

前面提到了 Blocklet UI 组件的渲染依赖于 Blocklet 运行时信息，即 Blocklet Meta，那么 Blocklet Meta 的来源是什么 ？答案是 blocklet.yml。blocklet.yml 配置对于 Blocklet 来说是必不可少的，它用来描述 Blocklet 的元数据，甚至可以影响 Blocklet 的运行行为。当一个 Blocklet 被部署到 Blocklet Server 上时，后者会解析前者的 blocklet.yml 配置，并将该信息 (Blocklet Meta) 存储到某个地方，当我们访问这个 Blocklet 时，Blocklet Server 会将 Blocklet Meta 嵌入到 Blocklet 应用中，因此，在 Blocklet 程序中可以访问 Blocklet Meta。

Blocklet Meta 中包含的数据非常多，Blocklet UI 只关心其中与用户界面相关的数据，比如：

- appId Blocklet 的唯一标识，一个 DID 地址
- appName Blocklet 应用的名称
- appLogo Blocklet 应用的 Logo (URL)
- navigation 导航菜单数据，可以用于配置 Header、Footer 以及 Dashboard 中的导航菜单

进一步了解 Blocklet Meta 请参考[这里](/en/docs/blocklet-developer/blockletyml/)。

## 安装

> 目前 Blocklet UI 只提供了 react 版本 - `@blocklet/ui-react`。

```javascript
npm install @blocklet/ui-react
# or yarn
yarn add @blocklet/ui-react
```

## Header 组件

Header 是网页中必不可少的重要元素，它出现在网页的顶部区域，一般用于显示品牌信息，提供应用导航。

### 使用

```javascript
import Header from '@blocklet/ui-react/lib/Header';

function App() {
  return (
    <div className="page">
      <Header />
      ...
    </div>
  );
}
```

在 Blocklet 应用中使用 `<Header />` 可以为页面渲染一个标准化的 Header 元素 (下图)。它包含的元素有:

- 应用 Logo
- 应用名称
- 应用 DID
- 导航菜单
- 语言选择器
- 会话管理器 (Session Manager)

![](https://media.arcblock.io/docs/blocklet-ui/images/header.w1600.webp)

### 配置导航菜单

Blocklet UI Header 在运行时会读取 blocklet.yml 中的 navigation 配置并渲染一个导航菜单。上图 (Fig.1) 中的导航菜单就是 Header 基于下面的 navigation 配置渲染而成。
navigation 配置由 1 个或多个条目组成，在这里一个条目代表一个菜单项，菜单项的主要属性有：

- title: 菜单项的标题文本，支持多语言
- link: 菜单项的链接, 支持多语言
- icon: 菜单项的图标, 支持 2 种形式的值
- iconify: `<prefix>:<icon-name>`
- image url
- section: 菜单项所出现的位置，可以配置多个值 (数组形式), 目前支持以下几种 section:
- header: Header 区域的导航菜单
- footer: Footer 区域的导航菜单
- social: Footer 社交媒体图标相关的链接
- bottom: Footer 底部区域相关链接，比如法律法规、隐私政策 等链接
- dashboard: 管理控制台中侧边栏中的导航菜单
- sessionManager: Session Manager 中的菜单
- role: 允许菜单项被访问的用户角色，可以配置 1 个或多个值，每个值应该与 Blocklet Server Passport 对应，Blocklet Server 内置的 Passport 有 owner、admin、member 和 guest，进一步了解请参考 [User and Passport](/en/docs/blocklet-developer/user-and-passport/)
- items: 子菜单 (支持嵌套)

```javascript
# blocklet.yml
navigation:
  - title:
      en: Home
      zh: 首页
    link: '/'
    icon: mdi:home
    section: header # This menu item will be displayed in Header Navigation
  - title:
      en: Discuss
      zh: 讨论
    link: '/discussion/'
    icon: mdi:chat-processing
    section: header
  - title: Profile
    link:
      en: '/profile/en'
      zh: '/profile/zh'
    icon: mdi:text-box
    section: header
  - title: Test
    icon: mdi:alpha-t-box
    section: header
    items: # Sub navigation menu
      - title: Sub1
        link: https://store.blocklet.dev
      - title: Sub2
        link: https://dev.store.blocklet.dev
      - title: Sub3
        link: '/profile/'
```

### 定制 Session Manager 菜单

Blocklet UI Header 组件在渲染时会检测上下文中是否存在 Session Context, 如果存在, 会在 Header 的 Addons 区域 (Header 最右侧的区域) 渲染一个 Session Manager。Session Manager 主要提供用户登录、用户注销、切换 profile、切换 passport 等功能，参考下图。

![](https://media.arcblock.io/docs/blocklet-ui/images/session-manager.w1600.webp)

如果需要定制 Session Manager 的菜单, 比如添加一个 "管理控制台" 菜单项，我们可以在 blocklet.yml navigation 中添加如下配置:

```javascript
# blocklet.yml
navigation:
  - title:
    en: Manage
    zh: 管理
  icon: ion:settings-outline
  link: /admin/blocklets?from=sm
  section:
    - sessionManager
  role:
    - admin
    - owner
```

注意这里的 role 配置，表示仅在当前用户是 admin 或 owner 角色时才会将该菜单项渲染到 Session Manager 中，配置后的 Session Manager 渲染结果如下图:

![](https://media.arcblock.io/docs/blocklet-ui/images/session-manager-with-custom-menu.w1600.webp)

## Footer 组件

Footer 是指网页最底部的内容部分。它通常包含品牌介绍、应用导航、版权声明、隐私政策链接、社交媒体图标 等信息。

### 使用

```javascript
import Footer from '@blocklet/ui-react/lib/Footer';

function App() {
  return (
    <div className="page">
      ...
      <Footer />
    </div>
  );
}
```

### 布局

Blocklet UI 目前支持 标准布局 和 简单布局，并根据 Blocklet 运行时数据自动选择一种合适的布局。

![](https://media.arcblock.io/docs/blocklet-ui/images/footer-standard-layout.w1600.webp)

![](https://media.arcblock.io/docs/blocklet-ui/images/footer-plain-layout.w1600.webp)

标准布局中包含的重要元素有：

- 应用 Logo
- 导航
- 社交媒体图标
- 版权声明
- 底部链接 (法律法规、隐私政策等链接)

其中导航、社交媒体图标、底部链接 都可以通过 navigation 进行配置，为导航条目指定相应的 section 就可以将其渲染到合适的位置，下面的配置将产生上图 (Fig.2) 中的效果:

```javascript
# blocklet.yml
# Navigation links in footer
navigation:
  - title:
      en: PRODUCT
      zh: 产品
    icon: mdi:home
    section:
      - footer
    items:
      - title: Overview
        link: https://www.arcblock.io/en/platform
        icon: mdi:home
    # ...
  # Social media icons in footer
  - icon: mdi:twitter
    link: https://github.com
    section: social
  - icon: mdi:telegram
    link: https://github.com
    section: social
  - icon: mdi:github
    link: https://github.com
    section: social
  - icon: mdi:wechat
    link: https://github.com
    section: social
  # Utility links in footer
  - title: Terms of Service
    link: https://www.arcblock.io/en/termsofuse
    section: bottom
  - title: Privacy
    link: https://www.arcblock.io/en/privacy
    section: bottom
  - title: Service Level
    link: https://www.arcblock.io/en/sla
    section: bottom
  - title: Site Map
    link: https://www.arcblock.io/sitemap.xml
    section: bottom
```

## Dashboard 组件

Dashboard 组件用于搭建管理控制台页面，主要包含 Header、Footer、Side Nav、Main Content 几个部分，其中前 3 个部分由 Blocklet UI Dashboard 组件根据 Blocklet 运行时数据自动渲染，应用的业务功能页面会显示在 main content (主内容区) 区域。

### 使用

```javascript
import Dashboard from '@blocklet/ui-react/lib/Dashboard';

function App() {
  return (
    <Dashboard>
      <div className="content">...</div>
    </Dashboard>
  );
}
```

渲染结果如下:

![](https://media.arcblock.io/docs/blocklet-ui/images/dashboard.w1600.webp)

### 配置导航菜单

Dashboard 导航菜单的配置方式与 Header 组件相似，不同之处是导航条目的 section 属性需要设置为 "dashboard"，下面的配置将产生上图 (Fig.3) 中的效果:

```javascript
# blocklet.yml
# Navigation menu items in Dashboard Side Nav
navigation:
  - title: Profile
    link: '/profile'
    icon: charm:person
    section: dashboard # This menu item will be displayed in Dashboard Side Nav
  - title: Account
    link: '/account'
    icon: material-symbols:settings-outline
    section: dashboard
  - title: Appearance
    link: '/appearance'
    icon: la:paint-brush
    section: dashboard
    role: owner # Only owner can access this menu item
  - title: Notification
    link: '/notification'
    icon: ri:notification-2-line
    section: dashboard
  - title: Access
    icon: fluent:accessibility-16-regular
    items: # Grouped menu items
      - title: Billing and plans
        link: '/billing-and-plans'
        icon: ant-design:credit-card-outlined
      - title: Emails
        link: '/emails'
        icon: ic:outline-email
      - title: Authentication
        link: '/authentication'
        icon: ri:shield-keyhole-line
      - title: SSH and GPG keys
        link: '/ssh-and-gpg-keys'
        icon: ph:key-bold
    section: dashboard
  - title: Code
    icon: material-symbols:code
    items:
      - title: Branches
        link: '/branches'
        icon: charm:git-branch
      - title: Tags
        link: '/tags'
        icon: uil:tag-alt
      - title: Repositories
        link: '/repositories'
        icon: octicon:repo-16
      - title: Packages
        link: '/packages'
        icon: octicon:package-24
      - title: Pages
        link: '/pages'
        icon: icon-park-outline:web-page
    section: dashboard
    role:
      - developer
      - owner
  - title: Archives
    icon: mdi:archive-outline
    items:
      - title: Security log
        link: '/security-log'
        icon: ph:scroll
        role:
          - owner
      - title: Sponsorship log
        link: '/sponsorship-log'
        icon: ph:scroll
        role: # User with developer or owner roles can access this menu item
          - developer
          - owner
    section: dashboard
```

### 定制 Session Manager 菜单

与 Header 组件一样，Dashboard 组件会在 Header 区域自动渲染一个 Session Manager，Session Manager 的菜单也可以通过 blocklet.yml navigation 进行配置，配置方式参考上面 Header 章节。

## Header 内置 Addons

Blocklet UI Header (包括 Dashboard 中的 Header) 右侧部分是 Addons 区域，用于放置常用的功能按钮，因为语言选择器 (LocaleSelector) 和会话管理器 (SessionManager) 使用频率很高，所以 Blocklet UI Header 将它们作为内置 addons 进行渲染，默认情况下，Blocklet UI Header 只要检测到 Locale Context (或 Session Context)，就会自动在 addons 区域渲染 LocaleSelector (或 SessionManager)。

因此，如果你的 Blocklet 应用依赖于多语言和用户体系，需要在应用入口处提供 LocaleProvider 和 SessionProvider，在真实的 Blocklet 应用中通常会使用下面的代码片段:

```javascript
import { LocaleProvider, useLocaleContext } from '@arcblock/ux/lib/Locale/context';
import { createAuthServiceSessionContext } from '@arcblock/did-connect/lib/Session';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

const { SessionProvider } = createAuthServiceSessionContext();

function App() {
  return (
    <LocaleProvider translations={...}>
      <SessionProvider serviceHost={...}>
        <div className="page">
          <Header />
          ...
          <Footer />
        </div>
      </SessionProvider>
    </LocaleProvider>
  );
}
```

## Storybook 参考

- [Header](https://arcblock.github.io/ux/?path=/story/blocklet-ui-react-header--basic)
- [Footer](https://arcblock.github.io/ux/?path=/story/blocklet-ui-react-footer--footer)
- [Dashboard](https://arcblock.github.io/ux/?path=/story/blocklet-ui-react-dashboard--basic)

---

## blocklet.js

URL: https://www.arcblock.io/en/docs/blocklet-developer/blockletjs/

## What is blocklet.js?

- `blocklet.js` is used to <strong>load blocklet info</strong> that can be used in browser environment
- `blocklet.js` is an endpoint <strong>served by blocklet server</strong>
- `blocklet.js` is <strong>available from any path</strong>, you get the same response with following requests:
- https://developer.blocklet.io/<strong>blocklet</strong>.js
- https://arcblock.io/docs/blocklet-developer/<strong>blocklet</strong>.js
- `blocklet.js` can return info in <strong>javascript or json format</strong>
- When requested as javascript, which is the default mode, you can use `window.blocklet`
- When requested as json, you must explicitly specify `type=json` in the query string
- `blocklet.js` is <strong>adaptive</strong> to any blocklet composition, both static and dynamic composition
- `blocklet.js` <strong>content may change</strong> with blocklet composition updates

## How is blocklet.js composed?

The following diagram describes how `blocklet.js` is created in blocklet server.

![](https://media.arcblock.io/docs/blockletjs/images/blocklet-js.w1600.webp)

## How to use blocklet.js?

To use `blocklet.js`, you must include the following `script` tag in your html file <strong>before any other script tags</strong>:

```html
<script src="__blocklet__.js"></script>
```

Please <strong className="color-red">do not</strong> add a beginning slash to the script `src` attribute, since `blocklet.js` can be loaded form any endpoint.

Then you can access `window.blocklet` in your javascript code:

The response from [`https://developer.blocklet.io/__blocklet__.js`](https://developer.blocklet.io/__blocklet__.js) is like following:

```javascript
window.blocklet = {
  // basic app info, appName, appDescription, appUrl, appLogo can be configured in blocklet server
  appId: 'zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1',
  appName: 'Blocklet Developer',
  appDescription: 'Blocklet Developer portal and documentation',
  appUrl: 'https://developer.blocklet.io',
  appLogo: '/.well-known/service/blocklet/logo/',

  // whether current blocklet is a component, differs when requesting from different path
  isComponent: false,

  // the blocklet app version === the version of the root blocklet
  version: '0.1.77',
  did: 'z8iZrq2YrLLWUz6X77bfFL4wBfZuEfXuj1R2m',

  // the blocklet group mountPoint
  prefix: '/',
  groupPrefix: '/',

  webWalletUrl: 'https://web.abtwallet.io',

  // the navigation of the composed service
  // it's parsed and merged from all components
  navigation: [
    { title: { en: 'Guides', zh: '指南' }, link: { en: '/docs/en/', zh: '/docs/zh/' } },
    {
      title: { en: 'ToolKit', zh: '工具箱' },
      link: '',
      items: [
        {
          title: 'Blocklet SDK',
          link: { en: '/docs/en/reference/blocklet-sdk/', zh: '/docs/zh/reference/blocklet-sdk/' },
        },
      ],
    },
  ],

  // component blocklet mounted in this app
  componentMountPoints: [
    {
      title: 'Meilisearch',
      name: 'meilisearch',
      did: 'z8iZorY6mvb5tZrxXTqhBmwu89xjEEazrgT3t', // the component blocklet did
      mountPoint: '/meilisearch', // the component path
    },
    {
      title: 'Blocklet Developer Docs',
      name: 'blocklet-developer-docs',
      did: 'z8iZwU5C5Y5SfSqC7LqKAbY9NiqFNjUjcJfPK',
      mountPoint: 'docs',
    },
  ],

  preferences: {
    key1: 'value',
    key2: 'value2',
  },
};
```

Please reference [Blocklet Preferences](/en/docs/blocklet-developer/using-blocklet-preferences/) for how to change the structure and value in `window.blocklet.preferences`.

---

## blocklet.yml

URL: https://www.arcblock.io/en/docs/blocklet-developer/blockletyml/

## DID

Bloklet DID represents the Bundle ID after the Blocklet is packaged, specified by `name` and `did`.

```javascript
name: example
did: z8iZrkWYbi3JU3AP9NHJQbBUdrgiRbeorauqf
```

`name` is a human readable ID, `did` is derived from `name`. Unique `name` derives unique `did`.

<strong>In general,</strong> <strong>`did`</strong> <strong>should not be modified manually,</strong> <strong>`name`</strong> <strong>and</strong> <strong>`did`</strong> <strong>should be automatically generated when the project is initialized via</strong> <strong>`create-blocklet`</strong><strong>.</strong>

The same DID represents the same Bloklet when uploaded to the Blocklet Store.

When installing a Blocklet to the Blocklet Server, the same DID represents the same Bloklet.

<em>Define Blocklet name please use title, do not use name</em>

`name` follows the NPM Package Name specification

- blocklet name length should be greater than zero
- all the characters in the blocklet name must be lowercase i.e., no uppercase or mixed case names are allowed
- blocklet name can consist of hyphens
- blocklet name must not contain any non-url-safe characters (since name ends up being part of a URL)
- blocklet name should not start with . or \_
- blocklet name should not contain any spaces
- blocklet name should not contain any of the following characters: ~)('!\*
- blocklet name length cannot exceed 214

## Version

`version` follows the [semver version](https://semver.org/) specification

```javascript
version: 1.0.0
```

## Infomation

```javascript
title: Example Demo
description: Demo blocklet that shows how to configure Blocklet Meta`
author:
  name: Bob
  email: bob@gmail.com
  url: 'https://bob.me'
contributors:
  - name: Alice
    email: alice@gmail.com
    url: 'https://alice.me'
maintainers:
  - name: Zhangsan
    email: zhangsan@gmail.com
    url: 'https://zhangsan.me'
community: 'https://github.com/orgs/blocklet/discussions'
documentation: 'https://arcblock.io/docs/blocklet-developer'
homepage: 'https://www.blocklet.io'
license: MIT
keywords:
  - demo
  - example
  - blocklet
repository:
  type: git
  url: 'git+https://github.com/blocklet/blocklet-site.git'
support: support@arcblock.io
```

## Logo

App logo file

```javascript
logo: logo.png
```

## Screenshots

The screenshots will be displayed on the introduction page of the store

```javascript
screenshots:
  - 0.png
  - 1.png
  - 2.png
```

## Videos

The link to the video introduction will be displayed on the store's introduction page, supporting up to three links. Supported websites: [Youtube](https://www.youtube.com/), [Vimeo](https://vimeo.com/)

```javascript
videos:
  - https://www.youtube.com/watch?v=K-J7qU1CNSo
  - https://vimeo.com/919738412
```

## Price

Blocklet price

- `price`: Specify the token address and quantity
- `shared`: How the revenue is shared. Usually you don't need to define it yourself, the system will by default distribute Blocklet revenue to developer and store according to 7:3

```javascript
payment:
  price: # Only 1 token can be specified
    - address: z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG # token address
      value: 8 # price
  share: # Usually you don't need to define it yourself
    - name: Bob # account alias
      address: z1QUDFzp6wKhLFjV4sG1ACY3J3ePcknrviy # Account DID
      value: 0.7 # split ratio
    - name: Store # Account alias
      address: zNKr4EeqcMk4W4TpBYD7MzGj6UEua53vJFx1 # Account DID
      value: 0.3 # split ratio
```

#### Component price

Component Price refers to the selling price of the Blocklet when it is combined

- `type`:
- Fixed price: `fixed`
- Divide proportionally: `percentage`
- `value`
- When type is fixed, it refers to the selling price
- When type is percentage, it refers to the percentage
- `parentPriceRange` the price range of the parent component

```javascript
payment:
  componentPrice:
    - parentPriceRange: # The price range of the parent component
        - 0
        - 10
      type: fixed
      value: 2 # fixed price
    - parentPriceRange:
        - 10
        - 20
      type: percentage
      value: 0.2 # divide proportionally
    # When parentPriceRange is not specified, it indicates the default division method
    - type: fixed
      value: 4
```

## Files

Which files need to be packaged into the bundle

```javascript
files:
  - logo.png
  - screenshots
  - hooks
```

## Interfaces

Blocklet access interface (most of the following configurations do not need to be concerned, just focus on the auth configuration)

```javascript
interfaces:
  - type: web # access interface type
    services:
      - name: auth # Auth service for this access interface
        config:
          whoCanAccess: all # Who can access (Can be modified dynamically after app installed)
          blockUnauthenticated: false # Whether to automatically intercept unauthenticated requests and jump to the login page (default: false)
          blockUnauthorized: false # Whether to automatically intercept unauthorized requests (default: false)
          allowSwitchProfile: true # Whether to support switching profiles (default: true)
          profileFields: # Information to provide when logging in
            - fullName
            - email
            - avatar
          ignoreUrls: # Which urls allow public access
            - /public/** # every urls unser /public allow public access
            - /api/xxx # /api/xxx allows access
    protocol: http # access interface type
    name: publicUrl # usually does not need to be modified
    port: BLOCKLET_PORT # Environment variable for receiving port (port number is generated by Blocklet Server)
    path: / # Default prefix when Bloclet receives requests
    prefix: '*' # Blocklet is mounted prefix
```

## Environment

Blocklet runtime environment variables are defined with `environments`:

```javascript
environments:
  - name: key # variable name
    description: xxxx # variable description
    default: '' # default value
    required: false # Is it required
    secure: false # Whether it is sensitive information
    shared: true # Is it public. Defaults to true, shared must be false when secure is true
```

Following rules applies to environments:

- They can have default values
- They can be changed in blocklet dashboard and during blocklet launch process.
- Shared environment variables are merged in [blocklet composition](/conceptual/composition)
- Variable names can not start with `ABT_NODE_` or `BLOCKLET_` except a few exceptions:
- `BLOCKLET_PASSPORT_COLOR` blocklet passport color, can be any valid hex encoded color string
- `BLOCKLET_WALLET_TYPE` can be `eth` or `default`, if your blocklet works on ethereum, should set this to `eth`
- `BLOCKLET_APP_LOGO` URL or path to the running blocklet instance logo, defaults to blocklet logo

## Scripts

Configuring Blocklet Hook Directives

```javascript
scripts:
  dev: npm run start # The command actually executed when `blocklet dev` is executed
  preInstall: node hooks/pre-install.js # hooks before installation
  postInstall: node hooks/post-install.js # hook after installation
  preStart: node hooks/pre-start.js # hook before startup
  preStop: node hooks/pre-stop.js # hook before stop
  preUninstall: node hooks/pre-uninstall.js # Hook before deletion
  postStart: node hooks/post-start.js # 启动后的 hook
  preConfig: node/hooks/pre-config.js # 配置前的 hook
```

![blocklet lifecycle](https://media.arcblock.io/docs/blockletyml/images/blocklet-lifecycle-hooks.w1600.webp)

Blocklet Server provides hook functionality to do something during the execution life cycle. Currently includes: `pre-install, post-install, pre-start, post-start, pre-stop, pre-uninstall, pre-config` These Hooks.

For example, a blocklet has hardware requirements for the machine to run on: the memory cannot be less than 1G, and the available disk capacity cannot be less than 500 MB. At this time, you can use the pre-install hook to detect whether the target machine has met the requirements, if so, install it normally, otherwise throw an error message and terminate the installation.

Hooks are actually some shell scripts, and these scripts may refer to files in Blocklets. During the process of packaging Blocklets, the Blocklet Server packaging tool (Blocklet Server CLI) will package the files used by hooks separately. Therefore, developers need to Declare in `hookFiles` which files are referenced by hooks.

## Requirements

Configure required resources and operating environment constraints

```javascript
requirements:
  server: '>=1.8.0' # server version constraints
  os: '*'
  cpu: '*'
  nodejs: '*'
  fuels: # Fuel needed before starting (token)
    endpoint: xxx # The address of the chain
    address: xxx # token address
    value: xxx # price
    reason: xxx # The reason for the need (for example, because the NFT Factory needs to be created before the first boot)
```

#### Specify the fuel needed before starting (token)

```javascript
requirements:
  fuels:
    endpoint: xxx # The address of the chain
    adress: xxx # token address
    value: xxx # price
    reason: xxx # The reason for the need (for example, because the NFT Factory needs to be created before the first boot)
```

#### Specify the minimum Blocklet Server version number

```javascript
requirements:
  server: '>=1.8.0' # server version must be greater than or equal to 1.8.0
```

#### Specify the minimum Nodejs version number

```javascript
requirements:
  nodejs: '>=18.0.0' # Nodejs version must be greater than or equal to 18.0.0
```

## Capabilities

```javascript
capabilities:
  clusterMode: false # Can blocklet be started in cluster mode
  component: true # Can blocklet become a component and be composed by other blocklets
  didSpace: "optional" # This option is optional and indicates whether the data needs to be stored in the did space or not, the range is: ["optional", "required"]. To learn more, please refer to: https://github.com/ArcBlock/did-spaces/blob/master/docs/blocklet-integration-did-spaces.md
  navigation: true # Can blocklet inject menu into navigation
  serverless: boolean optional, # Whether the blocklet can be installed in the “On-Demand Space” of the Launcher. Optional.
  sitemap: boolean # Whether the blocklet supports composable sitemap. Optional
```

## Components

Demo: [Component Demo](https://github.com/blocklet/component-demo/blob/main/blocklet.yml)

```javascript
components: # Usually no manual maintenance is required, it can be maintained through `blocklet add/remove`
  - name: xxx # Human readable ID (required)
    source: # installation source
      # install via url
      url: xxx
      # install via store
      store: xxx # store address
      name: xxx # Blocklet ID
      version: xxx # Blocklet version
    mountPoint: /path/to # mount point
    title: xxx # name
    description: xxx # description
```

#### Config Source

```javascript
components:
  - name: c1
    mountPoint: /c1

    # source has two types

    # 1. url: equivalent to the previous resolved, can be any bundle url, no need to serve in the store, such as
    # can serve in a github release, or in a local disk
    source:
      url:
- https://store.blocklet.dev/api/blocklets/z8ia4e5vAeDsQEE2P26bQqz9oWR1Lxg9qUMaV/blocklet.json
- file:///Users/wangshijun/Develop/arcblock/nft-store/.blocklet/release/blocklet.json
  - name: c2
    mountPoint: /c2
    # 2. The bundle served in the store can control the version: you can specify the latest version (default) or a fixed version. Later, if necessary, it can support more forms `^x.x.x`, `~x.x.x`, etc.
    # Because the store is decentralized, you need to specify the store
    source:
      store: https://store.blocklet.dev
      name: static-demo # bundle name
      version: latest # latest, 1.3.0
  - name: c3
    mountPoint: /c3
    # url can be set to one or more, when the first url is abnormal, it can be downgraded to the following url
    source:
      url:
        - <primary url>
        - <redundant url>
  - name: c4
    mountPoint: /c4
    # Store can be set to multiple, when the first store is abnormal, it can be downgraded to the following store
    source:
      store:
        - https://store.blocklet.dev
        - https://another-store.blocklet.dev
      name: static-demo
      version: latest
```

## Navigation

```javascript
navigation: # navigation information (app map)
  - id: xxx # navigation id, must be unique, use javascript varable named rules: https://www.npmjs.com/package/is-var-name
    title: xxx name
    # link to a url
    link: xxx
    # link to component
    component: xxx # component name or did
    section: # where I want to show
      - header
      - footer
    icon: mdi:home # icon
```

### i18n

```javascript
id: xxx
title: xxx
link: xxx
```

or

```javascript
id: xxx
title:

zh: xxx

en: xxx
link:

zh: xxx

en: xxx
```

### Header and Footer

```javascript
navigation:
  - id: a
    title: a # appears in the header (default)
  - id: c
    title: c
    section: footer # only in footer
  - id: d
    title: d
    section: # both in header and footer
      - header
      - footer
  - id: e
    title: e
    section: social # in footer's social media
  - id: f
    title: f
    section: bottom # at the bottom of the footer
```

### Icon

```javascript
navigation:
  - id: a
    title: a
    icon: mdi:home # iconify style
  - id: aa
    title: a
    icon: 'https://xxx' # url
  - id: b
    title: b
    icon: '/path/to/xxx' # icon serve in app
```

> [!NOTE]
> To display iconify style icons, the front end needs to import @iconify/iconify

## Theme

```javascript
theme: # theme
  background: '#f5f5f5' # background color
```

### Background

```javascript
background: xxx
```

or

```javascript
background:
  header: xxx
  footer: xxx
  default: xxx
```

## Copyright

```javascript
copyright: # Copyright information
  owner: xxx # owner
  year: 2022 # If not written, take the current year
```

## Types

Specify the Blocklet type through `group`, and specify the Blocklet startup entry through `main`

There are three types of Blocklets

### Type: Static

Contains only static resources. At startup, the purely static Blocklet will be hosted by the static resource service built into the Blocklet Server

```javascript
group: static
main: www # path of static resources, you need to ensure that dist/index.html exists
```

### Type: Dapp

This type of Blocklet itself contains back-end services (it can also contain static resources at the same time). At startup, the DAPP-type Blocklet will start the service at the port number assigned by the Blocklet Server.

> [!NOTE]
> Blocklets of DAPP type need to specify the blocklet development environment startup entry through scripts.dev

```javascript
group: dapps
main: index.js # startup file
scripts:
  dev: npm run dev
```

### Type: Gateway

This type of Blocklet itself will not contain any code and services, it will only compose other Blocklets together

```javascript
group: gateway
```

## Others

```javascript
timeout:
  start: 60 # Start timeout. Unit: second. Default time: 1 minute.
```

## Config Services

The service configuration of Parent blocklet and Component blocklet are independent, not unified.

> For the specific configuration method of services, see [https://github.com/blocklet/blocklet-specification/blob/main/docs/meta.md](https://github.com/blocklet/blocklet-specification/blob/main/docs/meta.md)

### Parent blocklet services

- Parent blocklet services are configured in `interface.services` in parent blocklet.yml

### Component blocklet services

- Component blocklet services are configured in `interface.services` in component blocklet.yml
- When `components[].services` is configured in parent blocklet.yml, it will be merged with component blocklet.yml `interface.services`

Examples of merger strategies:

parent blocklet.yml:

```javascript
name: parent-blocklet
interfaces:
  - name: publicUrl
    type: web
components:
  - name: component-blocklet
    mountPooint: /path/to/xx
    services:
      name: s1
      name: s2
```

component blocklet.yml:

```javascript
name: component-blocklet
interfaces:
  - name: publicUrl
    type: web
    services:
      - name: s2
      - name: s3
```

Then the services of component blocklet are:

- s1 (from parent `components[].services`)
- s2 (from parent `components[].services`)
- s3 (from component `interface.services`)

---

## Build blocklet for profit [deprecated]

URL: https://www.arcblock.io/en/docs/blocklet-developer/build-blocklet-for-profit/

## 设置价格

在 `blocklet.yml:payment.price` 中为 blocklet 设置价格。

见 [blocklet.yml: price](/en/docs/blocklet-developer/blockletyml/)

## 价格分成

blocklet 售卖所得收入默认会按照 7:3 的比例分给商店和开发者。

你也可以在 `blocklet.yml:payment.share` 中自定义 blocklet 分成方式（商店分成比例不能小于商店要求的最小分成比例）

见 [blocklet.yml: price](/en/docs/blocklet-developer/blockletyml/)

## 付费 Blocklet 发布过程

如果你为 blocklet 设置了费用并上传到某个商店, 当你在商店发布 blocklet 时，你需要为 blocklet 创建一个 NFTFactory.

![flow chart](https://media.arcblock.io/docs/build-blocklet-for-profit/flow-chart.svg)

## 设置组件价格

在 `blocklet.yml:payment.componentPrice` 设置组件销售价格。

组件销售价格可设置为 "固定价格" 和 "按比例分成"。

组件可根据应用的价格区间分别设置不同的价格。比如 “当应用售价小于 10 ABT 时，价格为 2 ABT，当应用售价大于 10 ABT 时，价格为 20%”

见 [blocklet.yml: component price](/en/docs/blocklet-developer/blockletyml/)

## 为组合 Blocklet 设置价格

当 blocklet 组合了付费组件时，blocklet 价格不的小于依赖的付费组件的价格之和。组件价格可在组件详情页中查看。

#### 举例

<strong>组合 Blocklet 结构为</strong>

```javascript
App
 |_ Com1
 |   |_ Com2
 |_ Com2
```

<strong>各组件价格</strong>

- App 售价：20 ABT
- Com1 售价：4 ABT
- Com2 售价
- 父组件价格小于 10 时: 2 ABT
- 父组件价格大于 10 时：20%
- Store 分成比例：30%

<strong>App 售卖后各组件分成</strong>

- Store 获得 20 * 30% = 6 ABT
- App 开发者获得 (20 - 4 - 20 * 20%) * 70% = 8.4 ABT
- Com1 开发者获得 (4 - 2) * 70% = 1.4 ABT
- Com2 开发者获得 (20 * 20% + 2) * 70% = 4.2 ABT

---

## Bundle your blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/bundle-your-blocklet/

## Introduction

We only need to know where the program's startup entry is to start this `blocklet`.

> [!NOTE]
> Please remember to increment your blocklet version before bundling if you intend to create a new release.

### 1. What is bundle

The essence of packaging is to transform an existing project structure into another project structure.
After the blocklet is packaged successfully, the system will generate a `.blocklet` directory under the project root directory. The directory structure is as follows:

```md
.blocklet
├── bundle
│   ├── LICENSE
│   ├── README.md
│   ├── api
│   ├── blocklet.js
│   ├── blocklet.md
│   ├── blocklet.yml
│   ├── blocklet.zip
│   ├── dist
│   ├── logo.png
│   ├── media
│   ├── package.json
│   └── screenshots
└── release
    ├── blocklet.json
    └── demo1-0.1.0.tgz
```

### 2. Why do we need bundle

You need to package your blocklet (just like Apple developers package Apple apps), to publish blocklets to the `blocklet store` (just like publishing Apple apps to the app store) and to deploy to the `blocklet server` (just like Apple Apps are installed on Apple phones).

## Preparation

### 1. Program entry (required)

#### 1. Define the entry file of the program

You need to define the `main` field in the `blocklet.yml` file to declare the entry point of the program, for example:

```javascript
main: api/index.js
```

#### 2. Define the files required for the program to run

You need to define the `files` field in the `blocklet.yml` file to declare the files required for the program to run, for example:

```javascript
files: -dist
```

The above configuration means that when bundling, the dist directory will simply be copied to the `.blocklet/bundle` directory.

You can also define the following pattern to include only a subset of files.

```javascript
files:
  - migration/*.js
```

The bundle result will include all files in the `migration` directory.

You can also define the following negation pattern to exclude some files.

```javascript
files:
  - "!server/ignored.js"
```

Following files are always included in the blocklet bundle:

- blocklet.yml
- blocklet.md or README.md
- CHANGELOG.md
- LICENSE

Files that are ignored by default when bundling is the same as: [https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files)

### 2. Logo (required)

A well-designed logo can improve the recognition of the application, and for each blocklet that is `bundled`, the logo file is also necessary.

#### prerequisites

- The width and height of the logo must be the same
- The pixel of the logo cannot be smaller than 256px \* 256px (except for svg files)
- The file size of the logo must not exceed 100KB
- The format of the logo must be a mainstream image format (support svg, jpg, png, etc.)

#### Define the logo field

You can define the path where the logo file is stored in the `blocklet.yml` file.

```javascript
logo: logo.png
```

### 3. Use documentation (required)

#### prerequisites

Each blocklet should have its own documentation, and an easy-to-use documentation can attract users to use it.
Like markdown, we can place [text](https://test.store.blocklet.dev/blocklets/z8iZwyBfqwNcGbLCiUnFAQLEzT8sJd2TSjbM2), [image](https://test.store.blocklet.dev/blocklets/ z8iZwyBfqwNcGbLCiUnFAQLEzT8sJd2TSjbM2), videos, etc.

#### Write usage documentation

Now, you only need to use markdown syntax to create a `blocklet.md` file in the project root directory, no need to declare this file in `blocklet.yml`, the system will automatically recognize this file when packaging.

```markdown
#My Blocklet

Welcome to my blocklet
```

In addition, if there is no `blocklet.md` file in the project root directory, the system will continue to match `blocklet.en.md`, `README.md` files in the project root directory in an orderly manner.
If the system finally fails to find it, it will throw an error during packaging and interrupt the current packaging behavior.

### 4. Screenshot (optional)

Text may not be enough when introducing blocklets to users.
In order to better show the effect of the product running, you can also use screenshots to show users your blocklet at this time.

#### Define the screenshots field

You can define screenshots field in `blocklet.yml` file:

```javascript
screenshots:
  - screenshot-0.png
  - screenshot-1.png
  - screenshot-2.png
  - screenshot-3.png
```

After packaging and publishing to the `blocklet store`, you can see your screenshot on the blocklet details page ([view example](https://test.store.blocklet.dev/blocklets/z8iZqkCjLP6TZpR12tT3jESWxB8SGzNsx8nZa)), the default is to follow the file The lexicographical order of the names is in ascending order, displayed in the form of a carousel.

### 5. Change log (optional)

Every time a blocklet is updated, we may need to log changes.
For developers, usually by updating the `CHANGELOG.md` file to record the changes of the project, the display effect in the `blocklet store` is shown in the following figure:

![changelog preview](https://media.arcblock.io/docs/bundle-your-blocklet/images/changelog-preview.w1600.webp)

#### Writing `CHANGELOG.md`

You can create a `CHANGELOG.md` file in the project root directory, for example:

```md
# 0.7.10 (October 18, 2022)

- chore: update deps to latest

# 0.7.9 (October 17, 2022)

- chore: update @nft-store/react lib and change the primary-color / logo
```

After packaging and publishing to `blocklet store`, you can see your change record on the blocklet details page ([view example](https://test.store.blocklet.dev/blocklets/z8iZqkCjLP6TZpR12tT3jESWxB8SGzNsx8nZa?tab=version)).

## Package the application

> [!NOTE]
> @see: https://github.com/blocklet/blocklet-site/pull/60#issuecomment-1281723839

### Default packaging mode

If the blocklet is created via `blocklet create` or `create-blocklet`, then the built-in packaging command can be executed in the terminal:

```javascript
yarn bundle
```

After the packaging command is executed successfully, you should be able to see the generated `.blocklet/bundle` directory in the project root directory.

### Package a single application (custom)

#### 1. Based on compact packaging (recommended)

Packing through the compact mode will analyze the dependencies of the program from the program entry and package the dependencies into a single file `blocklet-compact.js`.

```javascript
blocklet bundle --compact --create-release
```

The above command mainly does 2 things:

1. When using compact mode for packaging, it compiles the entire project. Therefore, it's important to note: dynamic path `require` statements should be avoided. Please use static path `require` or `import` statements instead.
2. Package the blocklet in webpack mode, and generate a `.blocklet/bundle` directory under the project root directory
3. Put the packaged files in the `.blocklet/release` directory under the project root directory

If our application has dependencies on binary packages, we can specify them using the `--external <items>` flag. These packages will be installed during the application installation process, according to the corresponding platform. For example:

```javascript
blocklet bundle --compact --external sqlite3,sharp --create-release
```

Unnecessary use of `--external` can slow down the installation of your application. To ensure a good user experience, please make sure `--external` only includes packages with binary dependencies.

Create source map for bundled blocklet, only available for compact mode:

```javascript
blocklet bundle --compact --source-map --external sqlite3,sharp --create-release
```

To prevent source code leakage in the production environment, we can use source maps that only retain line numbers.

Create a source map without including sources content, only available for compact mode:

```javascript
blocklet bundle --compact --nosources-source-map --external sqlite3,sharp --create-release
```

#### 2. Based on zip packaging (recommended)

Different from the packaging method of webpack, the zip packaging mode does not package the project into a single file, but analyzes the dependencies of the program from the program entry, and compresses all dependencies into a zip file according to the original project interface.

```javascript
blocklet bundle --zip --create-release
```

The above command mainly does 2 things:

1. Package the blocklet in zip mode, generate a `.blocklet/bundle` directory under the project root directory, and generate a `blocklet.zip` file
2. Put the packaged files in the `.blocklet/release` directory under the project root directory

####

### Package monorepo application (custom)

```javascript
blocklet bundle --create-release --monorepo
```

The above command mainly does 2 things:

1. Package the blocklet in monorepo mode, and generate a `.blocklet/bundle` directory under the project root directory
2. Put the packaged files in the `.blocklet/release` directory under the project root directory

So far, we have successfully packaged our blocklet.
Next, you can [publish](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/) the packaged blocklet to `blocklet store` or [deploy](/en/docs/blocklet-developer/deploy-blocklet-directly-to-the-server/) to `blocklet server`.

### Dynamically set the Source Store of the component when packaging

Before your blocklet is officially released, you can publish the blocklet to the test store first, and then publish it to the official store after the test is completed.

If you want the blocklet in the test store to depend on the components in the test store, and the blocklet in the official store to depend on the components in the official store, you can leave the source store in blocklet.yml and pass it in dynamically when packaging.

```javascript
components:
  - name: component-a
    mountPoint: /component-a
    source:
      name: component-a
      version: latest
  - name: component-b
    mountPoint: /component-b
    source:
      store: https://store.blocklet.dev # After the source store is declared, it will not be overwritten when packaging
      name: component-b
      version: latest
```

Execute `blocklet bundle --store-url "https://your-test-store.com"`, the packaged blocklet.yml is

```javascript
components:
  - name: component-a
    mountPoint: /component-a
    source:
      store: https://your-test-store.com
      name: component-a
      version: latest
  - name: component-b
    mountPoint: /component-b
    source:
      store: https://store.blocklet.dev
      name: component-b
      version: latest
```

Execute `blocklet bundle --store-url "https://your-prod-store.com"`, the packaged blocklet.yml is

```javascript
components:
  - name: component-a
    mountPoint: /component-a
    source:
      store: https://your-prod-store.com
      name: component-a
      version: latest
  - name: component-b
    mountPoint: /component-b
    source:
      store: https://store.blocklet.dev
      name: component-b
      version: latest
```

You can also set source store via environment variable: `COMPONENT_STORE_URL=https://your-prod-store.com blocklet bundle`

---

## Communicate with DID Wallet

URL: https://www.arcblock.io/en/docs/blocklet-developer/communicate-with-did-wallet/

## Establish connection with DID Wallet

Before the Blocklet communicates with the wallet, a Websocket connection needs to be established. There are two ways for Blocklet to establish a Websocket connection with the DID Wallet:

<strong>Method 1</strong>: After the DID Wallet logs in to the Blocklet through the [Auth service](/en/docs/blocklet-developer/user-and-passport/) provided by the Blocklet Service, it automatically establishes a Weboscket connection with the Blocklet.

<strong>Method 2</strong>: After DID Wallet connects to Blocklet through Blocklet using the DID Connect service implemented by [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/), it automatically establishes a Weboscket connection with Blocklet.

You can learn the implementation through [https://github.com/blocklet/notification-demo](https://github.com/blocklet/notification-demo).

## Send message to DID Wallet

After Blocklet and DID Wallet establish a Websocket connection, notifications can be sent to DID Wallet through Blocklet SDK.

### Send message to specified user

<strong>Method 1</strong>: Send a 1-to-1 message to the user. If the user is not online, the message will be temporarily stored for a week, and the user will receive the message when he is online.

`Notification.sendToUser(userDid, )`

<strong>Method 2</strong>: Send messages to specified users through public channels. If the user is not online, messages are not staged.

`Notification.broadcast(notification, { socketDid })`

For details, see [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/)

### Broadcast message to all online users

`Notification.broadcast(notification, { socketDid })`

Broadcast time to all online users, if the user is not online, the message will not be temporarily stored.

For details, see [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/)

### Message Format

Message are in a similar format to emails, including text, attachments, and actions.

#### Text: Contains title and body text

You can also send just the body, which is a simple text message.

```javascript
// Send Text

await Notification.sendToUser(userDid, {
  title: "I'm the message title",
  body: 'I am the message content, the message content can be short text, long text, etc',
});
```

The wallet can receive notifications on the message page

![Send Text](https://media.arcblock.io/docs/communicate-with-did-wallet/images/send-text.w1600.webp)

#### Attachment: Send different types of attachments

The types include Asset(NFT), VC, and Token

```javascript
// Send Token

await Notification.sendToUser(userDid, {
  title: 'I am the title that sent the Token',
  body: 'I will send TBA to the user, and the user can check whether it is received in the balance part',
  attachments: [
    {
      type: 'token',
      data: {
        address: 'z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG',
        amount: '1000000000000000000',
        symbol: 'TBA',
        senderDid: senderDid,
        chainHost: chainHost,
        decimal: 18,
      },
    },
  ],
});
```

The wallet can receive notifications on the message page

![Send Token](https://media.arcblock.io/docs/communicate-with-did-wallet/images/send-token.w1600.webp)

```javascript
// Send NFT

await Notification.sendToUser(userDid, {
  title: 'I am sending the title of the NFT',
  body: 'The application will send two NFT to the user. The user can check whether the corresponding NFT is received in the asset list',
  attachments: [
    {
      type,
      data: {
        did: asset.address,
        chainHost: env.chainHost,
      },
    },
    {
      type,
      data: {
        did: asset2.address,
        chainHost: env.chainHost,
      },
    },
  ],
});
```

The wallet can receive notifications on the message page

![Send Asset](https://media.arcblock.io/docs/communicate-with-did-wallet/images/send-asset.w1600.webp)

```javascript
// Send VC

const { create } = require('@arcblock/vc');

const vc = create({
  type: 'EmailVerificationCredential',
  issuer: {
    wallet: w,
    name: 'ArcBlock.KYC.Email',
  },
  subject: {
    id: userDid,
    emailDigest: toBase64(emailDigest),
    method: 'SHA3',
  },
});

await Notification.sendToUser(userDid, {
  title: 'I am sending the title of the VC',
  body: 'The application will send two vc to the user. The user can check whether the corresponding vc is received in the asset list',
  attachments: [
    {
      type,
      data: {
        credential: vc,
        tag: vt.email,
      },
    },
    {
      type,
      data: {
        credential: vc,
        tag: passport.title,
      },
    },
  ],
});
```

The wallet can receive notifications on the message page

![Send Vc](https://media.arcblock.io/docs/communicate-with-did-wallet/images/send-vc.w1600.webp)

#### Operation: Send operation

You can attach actions to a message (such as clicking to jump to a connection) that will be displayed as buttons in the wallet.

```javascript
// Send with operations

await Notification.sendToUser(userDid, {
  title: "I'm the message title",
  body: 'You can receive a lot of notification actions, which can be links or buttons that can be manipulated',
  actions={[
    { name: 'launch', title: 'Launch', link: 'https://arcblock.io' },
    { name: 'Set', title: 'ABT', link: 'https://arcblock.io' },
    { name: 'Do What', title: 'Node', link: 'https://arcblock.io' },
    { name: 'More', title: 'More Action', link: 'https://arcblock.io' },
  ]}
});
```

The wallet can receive notifications on the message page

![Send With Action](https://media.arcblock.io/docs/communicate-with-did-wallet/images/send-with-action.w1600.webp)

For details, see [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/)

## Receive messages from DID Wallet

Each time a connection is established with the DID Wallet, Blocklet will receive a 'hi' message from the wallet, which can be received by Blocklet through the Blocklet SDK.

After receiving this message, the Blocklet can send a separate message to the user.

For details, see [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/)

---

## Conceptual Guides

URL: https://www.arcblock.io/en/docs/blocklet-developer/conceptual-guides/

- [Platform Overview](/en/docs/blocklet-developer/platform-overview/)

- [Understanding Blocklet](/en/docs/blocklet-developer/understanding-blocklet/)

- [Blocklet Lifecycle](/en/docs/blocklet-developer/blocklet-lifecycle/)

- [Blocklet Composition](/en/docs/blocklet-developer/blocklet-composition/)

- [Understanding Blocklet Payment](/en/docs/blocklet-developer/understanding-blocklet-payment/)

- [Blocklet Server Architecture](/en/docs/blocklet-developer/blocklet-server-architecture/)

- [Blocklet Server Routing](/en/docs/blocklet-developer/blocklet-server-routing/)

- [Access Control](/en/docs/blocklet-developer/access-control/)

---

## Developer Best Practices.

URL: https://www.arcblock.io/en/docs/blocklet-developer/cRaH7u7b7Rj31i0ymIlSOv6r/

- [Developing Blocklet in Docker](/en/docs/blocklet-developer/develop-blocklet-with-docker/)

---

## Create Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/create-blocklet/

Before proceeding, please ensure you have followed the steps outlined here:
[Getting Started](/en/docs/blocklet-developer/getting-started/)


## Create Blocklet from Scratch

If you want to start a new blocklet from scratch, please start with our prebuilt templates: [https://www.arcblock.io/docs/createblocklet/en/quick-start](/en/docs/createblocklet/quick-start/)

## Create Blocklet from Existing Project

If you need to migrate existing project to the blocklet platform, refer to following steps (these steps should work for most javascript apps).

### Generate `blocklet.yml` file

Go to the project directory, execute the `blocklet init` command in the terminal, and enter the project name, project description, and so on

![Step 1](https://media.arcblock.io/docs/create-blocklet/images/add-step-1.w1600.webp)

For blocklet group, select according to your project setup:

- "static": if your project is a simple webapp that ships just HTML/CSS/JS and runs only in browser, such as a simple vue/react webapp
- "dapp": if your project need Node.js as runtime when shipped to production, such as express/next.js apps.

![Step 2](https://media.arcblock.io/docs/create-blocklet/images/add-step-2.w1600.webp)

For blocklet entry point, input according to your project setup (this setup tells blocklet cli to include files in the final blocklet bundle):

- For "static" blocklets: just input the directory name after your webapp is built, such as "dist"
- For "dapp" blocklets: just input the entry point of your backend.

### Config Blocklet Scripts

In the above steps, we have a `blocklet.yml` file that can be consumed by Blocklet Server.

Next, we configure some script commands to make it faster to develop and deploy your blocklet with Blocklet Server.

::::steps
:::step{title="Configure the development commands in"}
<strong>`blocklet.yml`</strong>
:::
::::

Starting a Blocklet  development environment requires the `blocklet dev` command, which relies on the configuration in `blocklet.yml`.

The following configuration needs to be added to `blocklet.yml`.

```plain
scripts:

dev: npm run start
```

To invoke development commands in a more familiar way, you can also add the command `"dev": "blocklet dev"` to `scripts` in the `package.json` file, and then you can use `npm run dev` to enter the Blocklet application development environment.

For more information on `blocklet dev`, see [blocklet dev](/en/docs/blocklet-developer/blocklet-cli/)

::::steps
:::step{title="Configure bundle command"}
:::
::::

We can use the `blocklet bundle` command to package the Blocklet application, but we need to use the project's original command to package it once before executing the command.

Assuming the project's original package command is `npm run build`, we can add `"bundle": "npm run build && blocklet bundle --create-release"` to the `scripts` in the `package.json` file, and then we can use the ` npm run bundle` to quickly package Blocklet applications

For more information about `blocklet bundle`, please refer to [blocklet bundle](/en/docs/blocklet-developer/blocklet-cli/#bundle)

::::steps
:::step{title="Configure deploy commands"}
:::
::::

Add `"deploy": "npm run bundle && blocklet deploy"` to `scripts` in `package.json` file, then you can use `npm run deploy` command to package and deploy with one click.

For more information about `blocklet deploy`, you can refer to [blocklet deploy](/en/docs/blocklet-developer/blocklet-cli/#deploy)

::::steps
:::step{title="Configure the upload command"}
:::
::::

Add a `"upload": "npm run bundle && blocklet upload"` to `scripts` in `package.json` file, then you can use `npm run upload` command to package and publish with one click.

For more information about `blocklet upload`, see [blocklet upload](/en/docs/blocklet-developer/blocklet-cli/)

### Get Better Developing Experience

You can use following library to enhance your blocklet developing experience

[vite-plugin-blocklet](https://www.npmjs.com/package/vite-plugin-blocklet)

### Customize Blocklet Branding

- Update blocklet branding such as logo and screenshot:   [How to fix logo and screenshot ratio?](/en/docs/blocklet-store/LMo49mG9oAyDYRZT8aNsIS3h/#building-with-blocklet-cli%EF%BC%9F)
- Update blocklet title/description, just edit `blocklet.yml`

### Advanced Topics

- [Using Blocklet Preferences](/en/docs/blocklet-developer/using-blocklet-preferences/)  to make your blocklet customizable
- Using  [Blocklet SDK (Node.js)](/en/docs/blocklet-developer/blocklet-sdk/)  to manage users/passports for your blocklet
- Using vite-plugin-blocklet to make your blocklet work on dynamic mountpoint
- Using  [blocklet.js](/en/docs/blocklet-developer/blockletjs/)  to load blocklet runtime environments in the browser
- Using  [Image Service](/en/docs/blocklet-developer/6IG0TQzEKLPc0nXuxg017wGe/)  to serve images dynamically with resize/crop/convert support
- Using  [Blocklet Lifecycle](/en/docs/blocklet-developer/blocklet-lifecycle/)  scripts to do things when run your blocklet

### When something went wrong?

Please contact us at: [https://community.arcblock.io/](https://community.arcblock.io/), we are always here to help.

---

## Compose Blocklets

URL: https://www.arcblock.io/en/docs/blocklet-developer/create-composite-blocklet/

## What is Blocklet Composition?

To understad what is blocklet composition, please check out:
[Blocklet Composition](/en/docs/blocklet-developer/blocklet-composition/)


## Compose in blocklet.yml

The `blocklet.yml` file allows you to define and compose multiple blocklets within your main blocklet. This feature enables you to create modular and reusable applications by incorporating other blocklets as components.

The `components` section in your `blocklet.yml` file is where you define the blocklets you want to include in your main blocklet. Here's the structure:

```javascript
components:
  - name: did-comments
    mountPoint: /did-comments
    required: false
    source:
      store: https://store.blocklet.dev
      name: did-comments
      version: latest
  - name: meilisearch
    required: true
    mountPoint: /meilisearch
    source:
      store: https://dev.store.blocklet.dev
      name: meilisearch
      version: latest
  - name: payment-kit
    required: true
    source:
      store: https://store.blocklet.dev
      name: z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk
      version: latest
```

Fields Explanation:

- `name`: required, The identifier for the component within your blocklet, should be DID for most cases
- `mountPoint`: optional, The path where the component will be accessible in your blocklet.
- `required`: optional, Boolean indicating whether the component is essential for your blocklet to function.
- `source`: required: Specifies where to obtain the component blocklet.
-
  - `store`: URL of the blocklet store containing the component.
  - `name`: Name or DID of the blocklet in the store.
  - `version`: Version of the blocklet to use (e.g., "latest" or a specific version number).
  - `url`: if your blocklet is not hosted in any store, you can provide its bundle URL

<strong>To make blocklet composition much easier to accomplish, here are the steps:</strong>

- Go to [https://store.blocklet.dev/](https://store.blocklet.dev/) and find the blocklet you want to include as a dependency
- Open the blocklet detail, such as [https://test.store.blocklet.dev/blocklets/z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9](https://test.store.blocklet.dev/blocklets/z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9)
- Click the extra actions section on the left of Launch, and then click "Add Component"
- Then go to your blocklet source code repo, paste and run the component add command
- Then restart your blocklet, blocklet server will handle dependency blocklet automatically

## Compose in Blocklet Studio

[Blocklet Studio](/en/docs/blocklet-developer/blocklet-studio/)

---

## Create a Blocklet of type Docker

URL: https://www.arcblock.io/en/docs/blocklet-developer/create-docker-type-blocklet/

Before you begin:

- [Create a Blocklet](/zh/docs/blocklet-developer/blocklet-studio-create-blocklet/)
- [Publishing a Blocklet](/en/docs/blocklet-developer/publish-blocklet/)

Blocklet Studio now supports creating Blocklets from Docker images. This feature allows developers to focus on their unique innovations by leveraging existing open-source functionality available through the Docker ecosystem.

In this article, I'll describe how to create a WordPress Blocklet.

### Building a MySQL Blocklet

First, the WordPress Docker image relies on MySQL, so we'll begin by creating a MySQL Blocklet. Future WordPress deployments will then use this MySQL instance as a Blocklet dependency.

We assume you're familiar with creating a standard Blocklet using Blocklet Studio. The image below shows the basic MySQL information:

This Blocklet's DID, z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR, will be used later.

![image.png](https://media.arcblock.io/lib/83/835178c76e5b1b4d4d3f1012919b0f6a.w1600.webp)

Then in the Content section, we select <strong>Build Blocklet from Docker:</strong>

![image.png](https://media.arcblock.io/lib/0c/0c132d48b1aca57da96d7a39f8ecb1d2.w1600.webp)

Then we click Docker Command and paste the `docker run` command for MySQL:

![image.png](https://media.arcblock.io/lib/f3/f349fa7f1efe9f894c8cf0624fc011bb.w1600.webp)

The full command shown is:

```javascript
docker run \
  --name mysql
  --publish 1333:3306 \
  --volume $BLOCKLET_DATA_DIR/mysql-data:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD="$BLOCKLET_AUTOMATIC_ENV_VALUE" \
  -e MYSQL_DATABASE="blocklet" \
  -e MYSQL_USER="blocklet" \
  -e MYSQL_PASSWORD="$BLOCKLET_AUTOMATIC_ENV_VALUE" \
  mysql:8.4.3
```

Returning to the Docker Params, we see the `docker run` command has been automatically parsed:

![image.png](https://media.arcblock.io/lib/75/75d9451845417229c033f83c56af2772.w1600.webp)

Notice the red error for the `--name` parameter. Blocklet Server automatically manages container names during Docker runtime to ensure network isolation and handle internal requests. Therefore, setting this parameter is not allowed. Similarly, several other Docker parameters are also restricted to prevent potential security risks to the host machine during Blocklet operation. Any disallowed Docker parameters will be flagged with a red warning after parsing.

We can publish the Blocklet without the `--name` flag. However, to simplify installation for users, we can configure some additional settings:

Setting 1: Change the `--publish` option to `docker`. The `--publish` option exposes ports within the Docker container to the host machine. Port conflicts are handled automatically by the Blocklet Server, which reassigns ports as needed. The `--publish(web)` option, conversely, signifies that the Blocklet Server should assign a mount point for access. Since direct access to MySQL isn't required, we change the option to `docker`.

![image.png](https://media.arcblock.io/lib/43/439aa007d609ea22e47a1fab2ce604d7.w1600.webp)

Setting 2: For `--env MYSQL_ROOT_PASSWORD` and `--env MYSQL_PASSWORD`, we have two design options: require users to set these values during initial Blocklet installation, or generate them automatically.

We've automated this process. When a user runs a Blocklet, a password is generated based on the running application's private key. This password is unique to each application and remains constant for that specific application. While there isn't currently a way to retrieve this automatically generated password, this functionality will be available in the future.

For simplified user installation, these are automatically generated.

![image.png](https://media.arcblock.io/lib/c2/c20518a34d2fb6ba5fddf940720ca140.w1600.webp)

MySQL 8's final configuration:

![image.png](https://media.arcblock.io/lib/b6/b6f06a55eb82c938ee2f6528d0a11b3c.w1600.webp)

Explain the settings shown above:

- --publish 1333:3306: We've made port 3306 of the WordPress Docker container accessible to the Blocklet Server. Since this isn't a web-based Blocklet, the Blocklet Server won't assign it a mount point.
- --volume $BLOCKLET_DATA_DIR...`: Mounts any directories within the Docker container requiring persistent storage under the Blocklet data directory. The `$BLOCKLET_DATA_DIR` path is automatically prepended, and these persistent directories must be subdirectories within this path.
- --env MYSQL_ROOT_PASSWORD: This environment variable sets the root password for MySQL, which will be automatically generated when the Blocklet starts.
- --env MYSQL_MYSQL_UESR: Sets the default database name
- --env MYSQL_MYSQL_USER: Set the database username
- --env MYSQL_PASSWORD: Setting this password will automatically generate the MySQL database when the Blocklet starts

Creating a MySQL Blocklet is straightforward.

Next, we'll upload MySQL to the test store, publish it, and install it in this application. This will serve as a dependency for WordPress.

### Building a WordPress Blocklet

Assuming you've installed the recently released MySQL Blocklet Service, let's create a WordPress Blocklet.

Likewise, we complete the basic WordPress setup:

![image.png](https://media.arcblock.io/lib/12/12059b77a0ae0055d6842492959fafe9.w1600.webp)

Then we open the Content tab, click Docker Command, and paste the WordPress `docker run` command:

![image.png](https://media.arcblock.io/lib/25/2533676fd250e8c732bd9a70c6b18bbd.w1600.webp)

The full command shown is:

```javascript
docker run \
  --publish 8080:80 \
  --volume $BLOCKLET_DATA_DIR/wordpress-files:/var/www/html \
  -e WORDPRESS_DB_HOST="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-host" \
  -e WORDPRESS_DB_USER="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-env.MYSQL_USER" \
  -e WORDPRESS_DB_PASSWORD="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-env.MYSQL_PASSWORD" \
  -e WORDPRESS_DB_NAME="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-env.MYSQL_DATABASE" \
  wordpress
```

This information requires a bit of explanation. It appears complex because we're configuring the future MySQL installation to serve as the WordPress database.

WordPress requires setting the DB host. Here, we enter the DID of the MySQL instance we just created, appended with `-host`, which indicates the host address of a running Blocklet.

```javascript
-e WORDPRESS_DB_HOST="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-host"
```

WordPress requires you to set the DB User, DB Password, and DB Name. Here, we enter the `DID` of the MySQL instance we just created, followed by `-env.`, and finally the `environment variable key`. This combination represents the value of a specific environment variable after a Blocklet has finished running.

```javascript
-e WORDPRESS_DB_USER="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-env.MYSQL_USER" \
-e WORDPRESS_DB_PASSWORD="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-env.MYSQL_PASSWORD" \
-e WORDPRESS_DB_NAME="z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR-env.MYSQL_DATABASE" \
```

These settings effectively do the following:

- DB_USER is bound to the MySQL environment variable MYSQL_USER.
- The `DB_PASSWORD` environment variable is bound to MySQL's `MYSQL_PASSWORD` environment variable.
- DB_NAME is bound to the MYSQL_DATABASE environment variable for MySQL.

This combination process is currently based on a convention. Should the need arise to create Docker-based Blocklets more frequently, we will develop a more graphical configuration solution.

Switching back to Docker Params, we see that they have been automatically identified and configured.

![image.png](https://media.arcblock.io/lib/76/7640cf492417f6b220627bf87c4cb465.w1600.webp)

Because WordPress requires its own mount point, the `--publish` type is set to Web (as explained above in the MySQL `--publish` section).

Finally, let's explain the settings shown above:

- --publish(web) 8080:80 : We publish port 80 of the WordPress Docker container to the Blocklet Server on port 8080. Because it's a web Blocklet, the Blocklet Server assigns it a mount point.
- The `--volume $BLOCKLET_DATA_DIR/wordpress-files:/var/www/html` argument mounts the directory within the Docker container requiring persistence to a subdirectory within the Blocklet data directory. `$BLOCKLET_DATA_DIR` is automatically prepended, and persistent storage is restricted to subdirectories of this path.
- --env WORDPRESS_DB_HOST: This WordPress environment variable, used to configure the database host, is linked to an environment variable associated with the DID z2qa25mcpadrUTrhPNeTDW91KLAdo5v4xHGgR (the MySQL instance referenced earlier).
- All other `--env` flags follow the same logic.

Then, in the Blocklets tab, set MySQL as a dependency of WordPress. This ensures that MySQL is installed automatically when you install WordPress.

![image.png](https://media.arcblock.io/lib/61/61b4e7bc0ceba0e36e3931fc6ffb97d7.w1600.webp)

With everything configured, we can publish the WordPress Blocklet.  The publishing process is identical to that of a standard Blocklet.

We also provide a WordPress test store configured as described above, which you can install and try:

[WordPress](https://test.store.blocklet.dev/blocklets/z2qaFtQ46ta7KK4HstPUir9grvcax3Dkum2RY)

Note that installing Docker-type Blocklets requires your Blocklet Server to have Docker mode and network isolation enabled.

[Running Blocklet using Docker container](/en/docs/blocklet-developer/using-docker-run-blocklet/)

---

## Create your first blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/create-your-first-blocklet/

There are usually two ways to create a Blocklet application: [Create Blocklet](https://www.createblocklet.dev/) and the `blocklet create` command. The latter is a command provided by [@blocklet/cli](https://www.npmjs.com/package/@blocklet/cli) and built on top of the former.

`blocklet create` provides various types of Blocklet templates to meet different use cases, including:

- static and dapp types of Blocklets
- Applications built using popular front-end frameworks such as React and Vue

This chapter will use the <em>[static] react template</em> as an example to demonstrate how to quickly create a Blocklet application using the `blocklet create` command.

## Preparation

- [Install Node.js 20+](/en/docs/blocklet-developer/setup-nodejs/)
- [Install Blocklet Server](/en/docs/blocklet-developer/install-blocklet-cli/)

## Creating Blocklet Application

1. Execute the command `blocklet create` in the terminal and enter the project name as prompted:

![image.png](https://media.arcblock.io/misc/d618a9ce37de9159a6e5c667cffd1841.w1600.webp)

2. Choose a Blocklet template according to your needs, for example, `[static] react` template:

![](https://media.arcblock.io/docs/create-your-first-blocklet/images/step-2.w1600.webp)

3. Enter the author's name and email address

![](https://media.arcblock.io/docs/create-your-first-blocklet/images/step-3.w1600.webp)

1. Wait for the scaffolding to automatically wake up the browser and use the DID wallet to create the application DID

![image.png](https://media.arcblock.io/misc/8743d7e038daaccccb9a75c28172b046.w1600.webp)

![image.png](https://media.arcblock.io/misc/21c762b95f6169fdd90c455cc3d92e9e.w1600.webp)

After waiting for the command to complete, a brand new Blocklet project will be created.

## Developing Blocklet

Execute the command "cd my-blocklet" in the terminal to enter the previously created "my-blocklet" directory, then execute the following commands to install dependencies:

```javascript
npm i
# yarn
# pnpm i
```

Then execute the following command to start Blocklet development mode (make sure that your local Blocklet Server has been initialized and can be accessed normally):

```javascript
blocklet dev
# npm run dev
# yarn dev
# pnpm dev
```

Once the application is launched, a DID Domain address will be outputted in the terminal as follows:

![](https://media.arcblock.io/docs/create-your-first-blocklet/images/step-4.w1600.webp)

You can access this address using a browser and see a page similar to this one. The `window.blocklet` corresponds to [Blocklet Meta](/en/docs/blocklet-developer/blockletyml/) data.

![](https://media.arcblock.io/docs/create-your-first-blocklet/images/blocklet-home.w1600.webp)

## Bundle Blocklet

Run bundle command:

```javascript
npm run bundle
# yarn bundle
# pnpm bundle
```

After successful packaging, you will see the `.blocklet` directory in the project directory

- `.blocklet/bundle` is used to deploy blocklets directly into applications via the Blocklet CLI.
- `.blocklet/release` is used to publish blocklets to the Blocklet Store, or install them directly in the Server.

## Deploy Blocklet

#### 1 Creare Application in Blocklet Server

![image.png](https://media.arcblock.io/misc/d22643a1ea1cfea97673b04c5865c786.w1600.webp)

![image.png](https://media.arcblock.io/misc/d4daf76973bf36c29c40d96b96c075c8.w1600.webp)

#### 2 Copy Application DID and set app-id  in package.json

![image.png](https://media.arcblock.io/misc/57492be742341f1af24b2fe0d45b6b83.w1600.webp)

![image.png](https://media.arcblock.io/misc/1d86e9b54da97c0651b46da1c3652eab.w1600.webp)

> Blocklet is component, for the relationship between Blocklets and applications, please refer to
> [应用和 Blocklet](/zh/docs/blocklet-developer/application-vs-blocklet/)
>  。

#### 3 Run deploy command

```javascript
npm run deploy
# yarn deploy
# pnpm deploy
```

After the blocklet is deployed, you can manage the blocklet in the Blocklet Server, such as starting, stopping, configuring domain names, configuring environment variables, configuring user permissions, and viewing running logs.

## Further Reading

- [Develop Blocklet](/en/docs/blocklet-developer/develop-blocklet/)
- [Publish your blocklet to the world](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/)
- [Operation and maintenance your blocklet](/en/docs/blocklet-developer/operation-and-maintenance-your-blocklet/)

---

## How to add custom well-known URI

URL: https://www.arcblock.io/en/docs/blocklet-developer/custom-well-known-url/

In some cases you may want to add custom [well-known URI on your website](https://en.wikipedia.org/wiki/Well-known_URI), such as:

- Prove ownership of the website with asset-link.js
- Prove ownership of the domain with http-challenge
- Tell OpenAI that there is a plugin hosted on your website

You can achieve this with "URL Mapping" feature on the blocklet dashboard.

![Screenshot 2024-04-05 at 07.33.07.png](https://media.arcblock.io/lib/55/559169907ad1737d5c4ead53295829be.w1600.webp)

Then you will get:

![Screenshot 2024-04-05 at 07.33.23.png](https://media.arcblock.io/lib/da/dad80e90f1cf2a921e301cf21aa28359.w1600.webp)

---

## Customize user profile page

URL: https://www.arcblock.io/en/docs/blocklet-developer/customize-user-profile-page/

> As Blocklet development progresses, a demand for personalized profile page is highly likely to emerge. Because of the Blocklet platform's composability, support for multi-Blocklet personalized profile page has been incorporated from the outset. The following details how to use Blocklet components to implement a customized personal profile page for the entire application.

## What is the User Profile?

This button simply links to your profile page.

![image.png](https://media.arcblock.io/lib/28/2815b19297d65e4afe13268814c9b22a.w1600.webp)

Clicking this link will redirect you to [https://www.arcblock.io/.well-known/service/user](https://www.arcblock.io/.well-known/service/user)

This address acts as a relay, locating the application's actual profile page and redirecting to it. This mechanism allows Blocklet components to inject custom profile pages.

The profile page features a two-column layout.  The left column, highlighted in red, serves as the menu and includes default entries for each Blocklet application: `Notifications`, `Profile`, `Settings`, and `DID Spaces`.

The first menu item, `Discussions`, is powered by the Discuss Kit.

The blue area to the right is the content area, the specific application providing the content displayed within it.

[Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu)

![image.png](https://media.arcblock.io/lib/d9/d90e98b3d4943cfd50d53d7809c59fe4.w1600.webp)

## Integrating a Blocklet Component's Profile Page into Your Application

Developing a customized personal center page is easy; just follow these few steps.

### Using the `UserCenter` Component in a Custom Profile Center Page

```javascript
import { UserCenter } from '@blocklet/ui-react';

export default function CustomProfile() {
  return (
    <UserCenter currentTab={window.blocklet.prefix}>

  {customContent}

</UserCenter>
  );
}

```

The `customContent` property defines the content you want to customize, which will appear in the blue area shown above.

### Declare menus in `blocklet.yml`

Add the following to your `blocklet.yml` file to declare a menu in the user profile area.

```javascript
navigation:
  - id: profile
    title:
      en: Profile
      zh: Profile
    link: /
    section:
      - userCenter
```

### Configure menu order in Blocklet settings

Open the `/.well-known/service/admin/navigation` page for the current application.

![image.png](https://media.arcblock.io/lib/2e/2e6cf66ba0c0929decad8f55cb864d69.w1600.webp)

Select the User Center tab. The menu declared in the previous step will automatically appear there.

Drag the dot icon in front of each item to reorder the menu items. Make sure the page you want to access directly from your profile is at the top of the list.

Click the `Save` button

All setup is now complete

---

## Defend against CSRF attacks

URL: https://www.arcblock.io/en/docs/blocklet-developer/defend-csrf/

## Overview

Cross-Site Request Forgery (CSRF) is a type of attack. Attackers induce victims to visit a malicious website and, without the victim's knowledge, send forged requests to a trusted website. These requests will utilize the credentials of the user's current authenticated session, thereby allowing the attacker to exploit the user's identity and permissions to carry out destructive operations such as changing account information, deleting data, etc.

## Precondition

- Developers with basic programming skills.

## Access

In order to defend against `csrf` attacks, we provide interface defense measures at both the front end and back end:

- @blocklet/sdk: provides a `csrf` middleware for the backend to validate `csrf token`. The system will only handle the relevant requests normally after passing the validation successfully.
- @blocklet/js-sdk: Provides the `createAxios`, `createFetch` function, carrying `csrf token` when sending requests.

### Backend

@blocklet/sdk provides the `express` middleware for the backend to validate `csrf`.

#### Basic Usage

By default, the middleware exported by @blocklet/sdk will intercept all side-effectful APIs (such as POST, PUT requests) and validate their placeholders for validity.

If verification fails, an error will be thrown: `Current request status is abnormal, please retry later`.

```ts
import { csrf } from '@blocklet/sdk/lib/middlewares';

app.use(csrf());
```

#### Advanced usage

In some cases, we may need to allow certain requests based on business logic. In such cases, we can achieve this by customizing the verifyToken function for CSRF token.

```javascript
import { csrf } from '@blocklet/sdk/lib/middlewares';

app.use(
  csrf({
    verifyToken: async (req, res) => {
      const needVerifyToken = ...;
      if (needVerifyToken) { // only need to verify in certain cases
        await res.locals.verifyToken(req, res);
      }
    },
  })
);
```

### front end

@blocklet/js-sdk provides  `createAxios` , `createFetch`  function, which carries  `csrf token` while sending requests.

#### Basic Usage

The exported ``createAxios`` function from `@blocklet/js-sdk` will carry ``csrf token`` to the request header before sending (side-effectful) requests in the frontend. The backend middleware of the user will verify the token in ``csrf token``, and only after successful verification, the request will be processed.

```javascript
import { createAxios } from '@blocklet/js-sdk';

const api = createAxios({}); // It can also be createFetch

// when making a request, the csrf token will be automatically included in request.headers['x-csrf-token']
await api.put(...);
```

After successful access, you will be able to see the csrf-token in the request header, just like this:

![image.png](https://media.arcblock.io/lib/b4/b484a774e84e6d11168c585ec9ed59f5.w1600.webp)

## Use other front-end request libraries

```javascript
import { getCSRFToken } from '@blocklet/js-sdk';

// Send the request with the CSRF token in the header.
request.headers['x-csrf-token'] = getCSRFToken();
```

---

## Deploy your blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/deploy-blocklet-directly-to-the-server/

If you are a blocklet developer, or you have a blocklet release bundle, you can deploy the blocklet directly to your Blocklet Server

## <strong>Install the local Blocklet as an application directly into the locally running Server</strong>

1. Visit the Server - Blocklet list page in the browser and click "Install New Blocklets" - "Install from URL"

![image.png](https://media.arcblock.io/misc/b1f2dd83f8f8b0d49a3c8fc61938400b.w1600.webp)

2. After packaging the blocklet, copy the file path of the blocklet.json file in the release directory in the blocklet bundle directory (usually in `{your project directory}/.blocklet/release/blocklet.json`), and fill in `file://{file path}` in the url input box.

![image.png](https://media.arcblock.io/misc/375b3059086c6fc55cddcebc5f5c29f8.w1600.webp)

1. Complete the subsequent process, use DID wallet to create the application DID, and continue until the installation is successful.

## Deploy Blocklet as component into application in Blocklet Server

### STEP 1

> If it is a local server, you can skip step1 and go directly to step2

Create Access Key in your Blocklet Server

![](https://media.arcblock.io/docs/deploy-blocklet-directly-to-the-server/access-key.w1600.webp)

### STEP 2

Execute the blocklet deploy command to deploy the blocklet to the Blocklet Server

```javascript
blocklet deploy <blocklet-bundle-folder> --endpoint xxxxxx --access-key xxxxxx --access-secret xxxxxx --app-id <blocklet-app-id> --mount-point /xxx
```

- blocklet-bundle-folder: The directory built using  [blocklet bundle](/en/docs/blocklet-developer/bundle-your-blocklet/) . If you are currently in the project root directory, it is `.blocklet/bundle`.
- --endpoint: The address of the server. <strong>If it is a local server, you do not need to enter this param.</strong>
- --access-key: Access Key created in the first step. <strong>If it is a local server, you do not need to enter this param.</strong>
- --access-secret: Access Secret created in the first step. <strong>If it is a local server, you do not need to enter this param.</strong>
- --app-id: AppDID of the application, which can be viewed in the application details page of the Server
- --mount-point: Mount point of the component

You can also configure environment variables using a `.env` file; all environment variables for a blocklet will start with `BLOCKLET_`.

```javascript
BLOCKLET_DEPLOY_APP_DID="xxxx"
```

---

## Develop Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/develop-blocklet/

## Start development

### `blocklet.yml`

```javascript
scripts:
  dev: npm run start
```

`scripts.dev` can be configured as any command

> If the blocklet is purely front-end, there is no need to set scripts.dev. See [blocklet.yml: Types](/en/docs/blocklet-developer/blockletyml/#types)

### 2. Execute `blocklet dev` in the project root directory

<strong>Example:</strong>

```javascript
✔ Blocklet xxxxxxx@x.x.x was successfully started

ℹ You can access with the following URL

- http://xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.did.abtnet.io
```

> "blocklet dev" will first install an application in the Server, and then automatically hang the blocklet in the application and start it. If you want to hang your blocklet into other applications for development, see "Hang the Blocklet into Application Development"

##

To hang Blocklet into application development, add `--app-did` and optional `--mount-point` parameters to the `blocklet dev` command.

`blocklet dev --app-did <app-did> --mount-point /xxx`

Or

`BLOCKLET_DEV_APP_DID=<app-did> BLOCKLET_DEV_MOUNT_POINT=/xxx blocklet dev`

Or

1. Configure in `.env`

```javascript
BLOCKLET_DEV_APP_DID=<blocklet-app-did>
BLOCKLET_DEV_MOUNT_POINT=/xxx
```

1. `blocklet dev`

<strong>`--app-did`</strong> Can be viewed in the blocklet details page (either App DID or Permanent DID can be used)

![image.png](https://media.arcblock.io/misc/5a02406eac8c3b4f457be162257791b6.w1600.webp)

`/`, `/path`, `/path/to`

##

`/` or `/xxx`

##

Front-end: After introducing [blocklet runtime information](/en/docs/blocklet-developer/blockletjs/)`window.blocklet.prefix`

`x-path-prefix` in the request header.

```js
server.use((req, res) => {
  const mountPoint = req.headers['x-path-prefix'];
});
```

#### <strong>API</strong>

Example:

1. Component declaration API: `/api/foo`
2. `/child`
3. Client request `/child/api/foo`
4. Blocklet Service forwards the request to the component and removes the prefix `/child`
5. Component receives request `/api/foo`

#### <strong>Redirection</strong>

We need to support redirection of the backend working properly with relative paths

```js
const prefix = req.headers['x-path-prefix'];

res.redirect(`${prefix}path/to`);
```

We need to support front-end redirection working properly under relative paths

```js
const prefix = window.blocklet.prefix;

window.location.href = `${prefix}path/to`;
```

## Load front-end static resources

Because the front-end page of Blocklet will be loaded under a relative path (such as `/child1/index.html`), we need to support loading front-end static resources under a relative path.

When building the app, change the app's front-end static resource prefix to `/.blocklet/proxy/<blocklet did>`

`PUBLIC_URL='/.blocklet/proxy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' npm run build`

> You usually don't need to configure it manually. When you create a Blocklet project using Create Blocklet, everything is already configured for you.

## Stop development

After starting development, press `CTRL + C` in the terminal to stop development

## Clear data

After you stop developing a blocklet, the persistent data of the blocklet will not be automatically cleared.

You can clear all data of the blocklet through `blocklet dev clear`

If you hang the blocklet in an application, you can clear the data through `blocklet dev clear --app-did <app-did>`

[](/en/docs/blocklet-developer/blocklet-sdk/#config)

## Get configuration

After the blocklet is started, the current running environment and configuration of the Blocklet can be obtained through the Blocklet SDK

Get the running environment: see [Blocklet SDK: Environment](/en/docs/blocklet-developer/blocklet-sdk/#environment)

Get configuration: see [Blocklet SDK: Config](/en/docs/blocklet-developer/blocklet-sdk/#config)

## Declare configuration

Declare the configuration in blocklet.yml:

```javascript
environments:
  - name: KEY_1
    description: 'description for KEY_1'
    default: ''
    required: false
    secure: false
    shared: true
```

- `name`: variable name
- `description`: variable description
- `default`: default value
- `required`: Is it required?
- `shared`: whether visible to clients and components
- `secure`: Environment variables with `secure` set to `true` will be stored encrypted and will not be visible to clients and components.

When developing a blocklet, you can also set environment variables in a `.env` or `.env.development` file in the project root directory

Note: Only environment variables declared in blocklet.yml can be set in `.env` or `.env.development`

Example:

```javascript
# .env

KEY_1=value1
```

> After blocklet is installed, users can configure environment variables in the blocklet management panel.

## Get the blocklet running environment on the page

You can obtain the blocklet running environment by requesting the `__blocklet__.js` interface of the blocklet.

> The blocklet project created through Create Blocklet provides an out-of-the-box environment. You can obtain the running environment through window.blocklet

```js
// App DID
window.blocklet.appId

// App version
window.blocklet.version

// Application Name
window.blocklet.appName

// Application description
window.blocklet.appDescription

// Application Url
window.blocklet.appUrl

// Shared environment variables
window.blocklet.<shared env>
```

## Blocklet Scripts

Blocklet Server provides hook functions to do some things during the execution life cycle. Currently it includes `pre-install, post-install, pre-start, post-start, pre-stop, pre-uninstall, pre-config` Hooks.

See [blocklet.yml: Scripts](/en/docs/blocklet-developer/blockletyml/#scripts)

## Run scripts in a blocklet environment

When developing blocklets, sometimes we want to execute scripts in the blocklet environment (such as creating some test data).

This can be achieved by executing `blocklet exec`, such as

`blocklet exec mock/test.js`

```js
// mock/test.js

const { env } = require('@blocklet/sdk');
const { getWallet } = require('@blocklet/sdk');

console.log(env);
console.log(getWallet().address);
```

## Communication between Blocklet components

Use the [Blocklet SDK](/zh/docs/blocklet-developer/blocklet-sdk/#component) to communicate with other blocklets in your app

```js
const { component } = require('@blocklet/sdk');

(async () => {
  await component.call(name, path, data);
})();
```

## How to migrate during upgrade

When the data structure of the blocklet's persistent storage is incompatible with changes, we can use the migration script to complete automatic data migration.

<strong>Method:</strong>

Create a `migration` directory under the blocklet root directory

Create a migration file in the `migration` directory with the file name semver version, such as `1.0.1.js`

<strong>Example:</strong>

There are 3 files `1.0.0.js`, `1.0.1.js`, `1.1.0.js` in the migration directory

When the blocklet is upgraded from 1.0.0 to 1.2.0, the two migration scripts `1.0.1.js` and `1.1.0.js` will be executed.

Warning: The migration folder needs to be added to the files field in the blocklet.yml file as follows:

```javascript
files:
  - ...
  - migration
```

---

## Developing Blocklet in Docker

URL: https://www.arcblock.io/en/docs/blocklet-developer/develop-blocklet-with-docker/

When you are unable or unwilling to directly install `@blocklet/cli` on the computer for some reason, it can be difficult to develop Blocklet
 because `@blocklet/cli` is an essential tool for developing or running Blocklet

The following will introduce how to develop a blocklet on a computer without installing  `@blocklet/cli` , but through Docker

1. Install Docker

Please refer to the Docker [Official tutorial](https://docs.docker.com/get-docker/), or other Docker installation tutorials to complete the installation

1. Prepare the docker-compose.yaml file

```javascript
services:
  blocklet-server:
    container_name: blocklet-server-docker
    image: arcblock/blocklet-server-dev
    ports:
      - 80:80
      - 443:443
    volumes:
      - ./data:/data # Store blocklet-server data on ./data folder
      - ./code:/workspace/app # Store blocklet code on ./code folder
      - node_modules:/workspace/app/node_modules # Don't mount node_modules folder
      # - pnpm-store: /workspace/app/.pnpm-store # If you are using pnpm to install deps, you would better to add this config
    environment:
      ABT_NODE_HOST: 192.168.1.111 # Your host IP
```

1. Start the container using `docker compose up -d`
2. Enter the container using the  `docker compose exec --workdir=/workspace/app blocklet-server /bin/bash`  command
3. Perform `blocklet create ./`, choose the template you want to create, and follow the prompts to complete the project creation
4. Install dependencies  `npm i`  or  `yarn`  or  `pnpm i`
5. Execute `blocklet dev`
6. The program will start up and print an accessible address
7. Clicking on the address will let you access the current blocklet normally

---

## Developing with GitHub Codespaces

URL: https://www.arcblock.io/en/docs/blocklet-developer/develop-with-github-codespaces/

## Setting Up the Blocklet Server

### 1. Create a codespace

It is recommended to choose a blank template:

![image.png](https://media.arcblock.io/lib/c8/c81dffa6dc0ef5407716a745a9f19db5.w1600.webp)

### Install @blocklet/cli

After creating `codespace`, execute the command in the terminal:

```javascript
npm install -g @blocklet/cli
```

![image.png](https://media.arcblock.io/lib/6d/6da52770ae37cfd6067de423bbddd851.w1600.webp)

### 3. Create and Start Blocklet Server

Continue executing commands in the terminal:

```javascript
$ mkdir ~/server # Create Blocklet Server Data Directory
$ cd server    # Enter the data directory
$ blocklet server start -a # Create and start a Blocklet Server instance
```

After Blocklet Server is launched, it will print the URL of the Dashboard in the terminal. The URL is related to the current Space name and port, with the default port being 8443, so the format of the address is as follows:

```javascript
https://{Space Name}-8443.app.github.dev/.well-known/server/admin/
```

![image.png](https://media.arcblock.io/lib/22/22b8d366f08cf61be09eb7d9af799671.w1600.webp)

### Set port 8443 to Public

After the Blocklet Server is launched, it will occupy certain ports; it is important to understand which ports are used by the Blocklet Server.

In GitHub Codespaces, the Blocklet Server runs on the following port by default:

- HTTPS: 8443 (recommended)
- HTTP: 8080 (not recommended)

It is recommended to configure port 8443 for public access; otherwise, access will require GitHub authorization checks, which are likely to encounter permission issues.

![image.png](https://media.arcblock.io/lib/68/684c77ebe8b6b27d351bee9be9dee9a0.w1600.webp)

### Accessing the Blocklet Server Dashboard

When accessing in an unlogged GitHub state, a security prompt will appear. After confirming there are no issues, select "Continue" to open the Blocklet Server Dashboard.

![image.png](https://media.arcblock.io/lib/fd/fd7dd7465537106995237d4a9b1a42e7.w1600.webp)

Finally, use DID Wallet to become the Owner of the node.

![image.png](https://media.arcblock.io/lib/48/488de9802ca3ae3b33418b7c33cacb70.w1600.webp)

## Developing Blocklet

Blocklet development is not significantly different from other environments, and you can refer to
[Create Blocklet](/en/docs/blocklet-developer/create-blocklet/)
 for Blocklet development.

## Troubleshooting

<strong>404 Not Found</strong>

If not used for an extended period, the Space may be stopped. You can check whether it has been stopped; if so, reopen the Space and start the Blocklet Server and the Blocklet.

<strong>Executing blocklet dev does not lead to the expected Blocklet application link</strong>

The cause of this situation may be that the Blocklet routing has not been mounted correctly. You can verify whether the Blocklet has been mounted under the default site in the routing section of the Blocklet Server Dashboard.

![image.png](https://media.arcblock.io/lib/72/72b47d34f4bb49c560e7dd5666343b2b.w1600.webp)

<strong>Each time GitHub Codespaces or the Blocklet Server port is started, the default setting will change to Private.</strong>

If you encounter issues accessing port 8443, you can check on GitHub to see if the port has been set to Public.

## Feedback

If you encounter any issues that cannot be resolved during the process, feel free to visit our official community to report them.

[ArcBlock Community](https://community.arcblock.io/)

---

## Enable Web Application Firewall

URL: https://www.arcblock.io/en/docs/blocklet-developer/enable-web-application-firewall/

> [!NOTE]
> This page need to be updated

Blocklet Server has opt-in support for Web Application Firewall with following open-source projects:

- [https://github.com/owasp-modsecurity/ModSecurity](https://github.com/owasp-modsecurity/ModSecurity)
- [https://github.com/owasp-modsecurity/ModSecurity-nginx](https://github.com/owasp-modsecurity/ModSecurity-nginx)
- [https://github.com/coreruleset/coreruleset](https://github.com/coreruleset/coreruleset)

Since ModSecurity is not shipped with nginx by default, you will need to build a custom nginx with ModSecurity enabled to make the web application firewall work.

### Setup ModSecurity on Amazon Linux 2023

```javascript
# prepare directory
rm -rf /data/setup
mkdir -p /data/nginx
cd /data/nginx

# Install dependencies
sudo dnf groupinstall 'Development Tools' -y
sudo dnf install -y zlib-devel pcre pcre-devel  gperftools gperftools-devel perl-ExtUtils-Embed

# Install ModSecurity
cd /data/nginx
git clone --recursive https://github.com/owasp-modsecurity/ModSecurity
cd ModSecurity
git checkout v3.0.13
./build.sh
./configure
make
sudo make install

# Install ModSecurity-nginx
cd /data/nginx
git clone https://github.com/SpiderLabs/ModSecurity-nginx
cd ModSecurity-nginx
git checkout ef64996aedd4bb5fa1831631361244813d48b82f

# Install nginx
cd /data/nginx
wget https://nginx.org/download/nginx-1.24.0.tar.gz
tar -zxvf nginx-1.24.0.tar.gz
cd nginx-1.24.0
./configure --prefix=/usr/local/nginx \

--sbin-path=/usr/local/bin/nginx \

--modules-path=/usr/lib64/nginx/modules \

--with-compat \

--with-debug \

--with-file-aio \

--with-google_perftools_module \

--with-http_addition_module \

--with-http_auth_request_module \

--with-http_dav_module \

--with-http_degradation_module \

--with-http_flv_module \

--with-http_gunzip_module \

--with-http_gzip_static_module \

--with-http_mp4_module \

--with-http_random_index_module \

--with-http_realip_module \

--with-http_secure_link_module \

--with-http_slice_module \

--with-http_ssl_module \

--with-http_stub_status_module \

--with-http_sub_module \

--with-http_v2_module \

--with-mail=dynamic \

--with-mail_ssl_module \

--with-pcre \

--with-pcre-jit \

--with-stream=dynamic \

--with-stream_realip_module \

--with-stream_ssl_module \

--with-stream_ssl_preread_module \

--with-threads \

--with-cc-opt='-I/usr/local/include' \

--with-ld-opt='-L/usr/local/lib64' \

--conf-path=/usr/local/nginx/nginx.conf \

--pid-path=/usr/local/nginx/nginx.pid \

--lock-path=/usr/local/nginx/nginx.lock \

--http-client-body-temp-path=/usr/local/nginx/nginx/client_body_temp \

--http-proxy-temp-path=/usr/local/nginx/nginx/proxy_temp \

--http-fastcgi-temp-path=/usr/local/nginx/nginx/fastcgi_temp \

--http-uwsgi-temp-path=/usr/local/nginx/nginx/uwsgi_temp \

--http-scgi-temp-path=/usr/local/nginx/nginx/scgi_temp \

--http-log-path=/usr/local/nginx/nginx/access.log \

--error-log-path=/usr/local/nginx/nginx/error.log \

--add-module=../ModSecurity-nginx

make
sudo make install

sudo setcap cap_net_bind_service=+ep /usr/local/bin/nginx
```

### Setup ModSecurity on Ubuntu

This part is not complete yet.

---

## Event Bus Service (Beta)

URL: https://www.arcblock.io/en/docs/blocklet-developer/event-bus-service/

Event Bus service is a powerful communication system that helps your blocklet's components work together seamlessly. Imagine it as a smart messaging center that:

- Lets different blocklets (which are like mini-apps within your system) share information and notify each other about important changes
- Creates a smooth connection between your blocklets and the main server that manages everything

For example, if you have a shopping blocklet and an inventory blocklet, the Event Bus would help them stay synchronized - when someone buys an item, the inventory blocklet would automatically know to update its stock count.

## Usage

### Define Events

To get started, you'll need to specify what kinds of messages (events) your blocklet can send. This is done by listing them in your `blocklet.yml` configuration file, which acts like a rulebook for your blocklet's behavior.

```javascript
events:
  - type: kitchen.full
    description: dummy event from kitchen sink blocklet
  - type: kitchen.empty
    description: dummy event from kitchen sink blocklet
  - type: blocklet.kitchen.event
    description: This event name is forbidden

```

Here are some important guidelines when naming your events:

- Think of event names like describing an action: start with what's happening (like "post" or "user") followed by what was done (like "published" or "updated"). For example: "post.published" or "user.loggedIn"
- Each event name needs to be unique in your blocklet - you can't have two events with the same name
- Don't use names that start with "blocklet." - these names are reserved for system use
- Make sure to write clear descriptions for your events - these will help other developers understand what your events do

### Publish Events

```javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.publish('kitchen.full', {
  id: '123', // optional, default is a random uuid
  time: new Date().toISOString(), // optional, default is current time
  data: { object: { message: 'Hello, world!' } },
})
  .then(() => {
    console.log('Event published');
  })
  .catch((err) => {
    console.error('Failed to publish event', err);
  });

```

Before your blocklet can send out any messages (events), you need to list them in your blocklet's configuration file (`blocklet.yml`) - think of this like registering what kinds of announcements your blocklet is allowed to make. This helps keep communication organized and prevents confusion about which blocklet is sending what messages.

### Receive Events

```javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.subscribe((event) => {
  console.log('received event from eventbus', event);
});

```

Your blocklet can listen for messages (events) from other blocklets and the server. However, it won't receive the specific events that it has declared in its own `blocklet.yml` file - this prevents a blocklet from receiving its own messages, which helps avoid confusion and feedback loops.

### Discover Events

Want to know what events are available in your blocklet? You can find a complete list at the `/.well-known/service/openevent.json` web address. This list shows all the events that your blocklet and other blocklets can send and receive - it's like a directory of all possible messages that can be shared between different parts of your application.

```javascript
❯ curl -s https://bbqartjsky2iiebu2noxsg6gn7nf7ezacguwmx6q6ci.did.abtnet.io/.well-known/service/openevent.json | jq
{
  "openevent": "1.0.0",
  "info": {
    "description": "I can change this after elevated, great! haha"
  },
  "sources": [
    {
      "did": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs",
      "description": "I can change this after elevated, great! haha",
      "version": "1.0.0",
      "logo": "https://bbqartjsky2iiebu2noxsg6gn7nf7ezacguwmx6q6ci.did.abtnet.io/.well-known/service/blocklet/logo"
    },
    {
      "did": "z8iZqG23gxzv6CbTmtWFAipHGLjPEha4BjAtE",
      "title": "Profile Demo",
      "description": "Blocklet that show profile of login user, can be combined by other blocklets.",
      "version": "1.14.17",
      "logo": "https://bbqartjsky2iiebu2noxsg6gn7nf7ezacguwmx6q6ci.did.abtnet.io/.well-known/service/blocklet/logo-bundle/z8iZqG23gxzv6CbTmtWFAipHGLjPEha4BjAtE?v=1.0.0"
    },
    {
      "did": "z8ia22AX1PovjTi1YQw8ChgsbeVExYsX4dPFt",
      "title": "Kitchen Sink",
      "description": "Demo blocklet that showing how blocklet works in ABT node",
      "version": "1.5.3",
      "logo": "https://bbqartjsky2iiebu2noxsg6gn7nf7ezacguwmx6q6ci.did.abtnet.io/.well-known/service/blocklet/logo-bundle/z8ia22AX1PovjTi1YQw8ChgsbeVExYsX4dPFt?v=1.0.0"
    }
  ],
  "events": [
    {
      "type": "blocklet.user.added",
      "description": "When a new user has onboarded, will receive the user info object",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "blocklet.user.updated",
      "description": "When a user has updated/logged in, will receive the user info object",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "blocklet.user.removed",
      "description": "When a user has removed, will receive the user did",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "blocklet.user.profile.updated",
      "description": "When a user has updated his/her profile (full name, avatar, did-spaces, etc.)",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "blocklet.user.permission.updated",
      "description": "When a user permission (passport, account, kyc) has changed",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "dummy.event",
      "description": "This is a dummy event from profile demo",
      "source": "z8iZqG23gxzv6CbTmtWFAipHGLjPEha4BjAtE"
    },
    {
      "type": "kitchen.full",
      "description": "dummy event from kitchen sink blocklet",
      "source": "z8ia22AX1PovjTi1YQw8ChgsbeVExYsX4dPFt"
    },
    {
      "type": "kitchen.empty",
      "description": "dummy event from kitchen sink blocklet",
      "source": "z8ia22AX1PovjTi1YQw8ChgsbeVExYsX4dPFt"
    }
  ]
}
```

---

## Frequently Asked Questions

URL: https://www.arcblock.io/en/docs/blocklet-developer/frequently-asked-questions/

## How the documentation is organized?

Blocklet has a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things:

- [Getting Started](/en/docs/blocklet-developer/getting-started/) take you by the hand through a series of steps to create a website. Start here if you’re new to Blocklet.
- [Conceptual guides](/en/docs/blocklet-developer/conceptual-guides/) discuss key concepts at a fairly high level and provide useful background information and explanation.
- [Reference guides](/en/docs/blocklet-developer/reference-guides/) contain technical reference various aspects of Blocklet machinery. They describe how it works and how to use it but assume that you have a basic understanding of key concepts.
- [How-to guides](/en/docs/blocklet-developer/how-to-guides/) are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than Getting Started and assume some knowledge of how Blocklet works.

## What is a Blocklet?

A Blocklet is a collection of applications that can run in Blocklet Server.

- It can be a Reactjs application, created by CRA
- It can be a Vuejs application, created by vite
- It can be an express application
- ...

In short, any application can be turned into a Blocklet application and can run in the Blocklet Server.

### Composable Blocklet

In common development models, an application is usually developed as a standalone application, and when the application needs to interact with other applications, it needs to do so through a CORS-configured interface. As you can imagine, this breaks the integration of development and makes it more difficult to deploy in production environments.

If you choose to develop a Blocklet, you can develop a combination of applications in a more relaxed mode, and you can easily combine multiple applications together after development to make them look like one application.

## What is Blocklet Server?

Blocklet Server is the hosting platform of Blocklet, which provides the running environment and basic services for Blocklet.

## What is Blocklet Service?

Blocklet Service is a series of services provided by Blocklet Server for Blocklet. Blocklet Server provides Blocklet with a lot of out-of-the-box features through Blocklet Service.

- Domain: Each Blocklet can be accessed through a unique DID Domain
- Authentication Service: DID based Authentication Service
- Access Management Service: Access Management Service based on DID Passport and RBAC
- Notification service: Blocklet can send messages to DID wallet

## What is Blocklet Store?

Blocklet Store is the distribution platform for Blocklets. The Blocklet Store allows you to discover, buy and install Blocklets.

ArcBlock officially provides 2 Blocklet Store:

1. [https://store.blocklet.dev](https://store.blocklet.dev): Provides production-ready Blocklets
2. [https://dev.store.blocklet.dev](https://dev.store.blocklet.dev): Provide sample/demo Blocklets for learning and experience

<strong>Blocklet store is decentralized, you can deploy your own Blocklet store on your own Blocklet Server!</strong>

## How to check the component service port in Blocklet?

Developers should <strong>NOT</strong> use the service port of Blocklet components directly in their code.

If developers need to communicate with internal components, please use [Blocklet SDK: Component](/en/docs/blocklet-developer/blocklet-sdk/#component)

If you need to check for other reasons (such as troubleshooting), you can open the developer tools in your browser, visit the Server Dashboard -> Blocklet details page, and view it in the getBlocklet GQL interface

![](https://media.arcblock.io/docs/frequently-asked-questions/images/view-port.w1600.webp)

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-developer/getting-started/

If you are an intermediate or advanced developer, and you already have a basic understanding of how blocklet works, you can start from [Create first blocklet](/en/docs/blocklet-developer/create-your-first-blocklet/).

If you are new to the [blocklet platform](/en/docs/blocklet-developer/platform-overview/), you should following steps to get started:

- [Setup Node.js](/en/docs/blocklet-developer/setup-nodejs/)
- [Setup DID Wallet](/en/docs/blocklet-developer/setup-did-wallet/)
- [Install Blocklet CLI](/en/docs/blocklet-developer/install-blocklet-cli/)
- [Create first blocklet](/en/docs/blocklet-developer/create-your-first-blocklet/)

---

## How to configure security rules

URL: https://www.arcblock.io/en/docs/blocklet-developer/how-to-configure-security-rules/

## Overview of Security Rules

Security rules are used to constrain external requests to the application, ensuring that only requests that meet certain criteria can access the application's resources. Each application's owner or administrator can configure these rules in the application console:

![image.png](https://media.arcblock.io/lib/16/160b61da226237298ea5ee477cc922b1.w1600.webp)

The security rules are primarily composed of three parts:

1. Path Pattern: Requests are grouped and matched based on the URL, with only those requests that meet this pattern being subject to this rule (Default can match any URL).
2. Response header policy: A unified approach to adding custom headers in response to requests based on security requirements.
3. Access Policy: Specifies who can access the application.

Additionally, multiple security rules will match requests in a top-down order. If a rule is triggered, subsequent matching processes will be skipped.

## Access Policy

Access policies can control who can access the application based on whether the user is logged in and their role, with specific options illustrated in the image below (if certain terms are unclear, you can refer to [User and Passport](/en/docs/blocklet-developer/user-and-passport/)):

![image.png](https://media.arcblock.io/lib/7b/7bb184c53cb44a365b4448a84df2fa1b.w1600.webp)

## Response Header Policy

The response header policy is used to add necessary security headers to responses, controlling browser behavior and ensuring that the application meets security requirements.

### CORS Configuration

![image.png](https://media.arcblock.io/lib/dd/ddde42b80cd3590f59107dda7b9c30b8.w1600.webp)

CORS configuration allows control over which domains can access application resources, preventing malicious cross-origin requests. The main configuration options include:

- <strong>Origin</strong>: Specifies which source domains are permitted to make cross-origin requests. For instance, you can specify that cross-origin access is allowed from[ `https://example.com` ](https://).
- <strong>Methods</strong>: Allowed HTTP methods include `GET`, `POST`, `PUT`, `DELETE`, and others.
- <strong>Allowed Headers</strong>: A list of permitted request headers that specifies which headers can be sent in cross-origin requests.
- <strong>Exposed Headers</strong>: Response headers that are accessible to clients.
- <strong>Max Age</strong>: Specifies the validity period of the preflight request in seconds, indicating that the browser does not need to send preflight requests within this time frame.
- <strong>Options Success Status</strong>: Specifies the success status code for the preflight request, defaulting to `204`.
- <strong>Preflight Continue</strong>: Indicates whether to allow the continuation of the preflight request process.
- <strong>Credentials</strong>: Whether to allow cross-origin requests to include credentials (such as cookies).

### Security Header Configuration

![image.png](https://media.arcblock.io/lib/73/730593122de6716603631aae8614a6f1.w1600.webp)

Security headers are configured to enhance the security of HTTP responses and to prevent common types of attacks. The main configuration items include:

- <strong>Content-Security-Policy (CSP)</strong>: Used to prevent cross-site scripting (XSS) attacks and other code injection attacks by limiting the sources from which resources can be loaded (specific options can be found in the [CSP Reference](https://content-security-policy.com/)).
- <strong>Referrer-Policy</strong>: controls how the `Referer` header is sent, preventing the leakage of sensitive information (for specific options, refer to the [Referrer Policy Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)).
- <strong>X-Frame-Options</strong>: This header prevents webpages from being embedded within iframes, thus avoiding clickjacking attacks. Common values include `DENY` and `SAMEORIGIN`.
- <strong>Disable X-Powered-By</strong>: This prevents the exposure of server information, such as `X-Powered-By: Express`, which could be exploited by attackers.
- <strong>X-XSS-Protection</strong>: Prevents cross-site scripting (XSS) attacks. A common value is `1; mode=block`, indicating that XSS protection is enabled and page rendering is blocked.

## FAQ

### What should I do if a request is blocked by CORS?

If you encounter CORS issues, it is usually because the application has restrictions on cross-origin requests. You need to modify the CORS configuration in the application's backend response header policy by adding a whitelist or setting it to *.

![image.png](https://media.arcblock.io/lib/69/69cf8d4894cd06b5f426f9799eea7f6e.w1600.webp)

### Why can't the NFT be previewed?

For example, the NFT of the Space card shows blank：

![image.png](https://media.arcblock.io/lib/1f/1fcef564c4910d1cea68251b71998202.w1600.webp)

The reason is that the default rules for Staging DID Spaces only allow NFT previews through the `/app/resolve/display` path, while Space cards preview NFTs through the `/app/api/space/nft/display` path：

![image.png](https://media.arcblock.io/lib/dc/dcd569de9532bca73e1607d41e9dec9b.w1600.webp)

Therefore, to address the issue of previewing NFTs on Space cards, a rule needs to be added to the `/app/api/space/nft/display path`：

![image.png](https://media.arcblock.io/lib/2a/2ac9a990a69915edd8c850cfc9e0a771.w1600.webp)

Afterwards, the Space card will be able to display NFTs normally：

![image.png](https://media.arcblock.io/lib/a2/a20bd7f9443d5b8eff0c2fb4cfbdd3c6.w1600.webp)

---

## How to Guides

URL: https://www.arcblock.io/en/docs/blocklet-developer/how-to-guides/

- [Application vs Blocklet](/en/docs/blocklet-developer/application-vs-blocklet/)

- [Create Blocklet](/en/docs/blocklet-developer/create-blocklet/)

- [Compose Blocklets](/en/docs/blocklet-developer/create-composite-blocklet/)

- [Develop Blocklet](/en/docs/blocklet-developer/develop-blocklet/)

- [User and Passport](/en/docs/blocklet-developer/user-and-passport/)

- [Communicate with DID Wallet](/en/docs/blocklet-developer/communicate-with-did-wallet/)

- [Blocklet Storage](/en/docs/blocklet-developer/blocklet-storage/)

- [Using Blocklet Preferences](/en/docs/blocklet-developer/using-blocklet-preferences/)

- [Using Blocklet Logger](/en/docs/blocklet-developer/using-blocklet-logger/)

- [Add PWA Integration to Blocklet](/en/docs/blocklet-developer/service-worker-integrate/)

- [Build blocklet for profit [deprecated]](/en/docs/blocklet-developer/build-blocklet-for-profit/)

- [Bundle your blocklet](/en/docs/blocklet-developer/bundle-your-blocklet/)

- [Manage Blocklet Versions](/en/docs/blocklet-developer/3HWWvUOi0Mhqy_yag3CXeJUA/)

- [Publish your blocklet to the world](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/)

- [Deploy your blocklet](/en/docs/blocklet-developer/deploy-blocklet-directly-to-the-server/)

- [Read/Write blockchain in blocklet](/en/docs/blocklet-developer/readwrite-blockchain-in-blocklet/)

- [Operation your blocklet](/en/docs/blocklet-developer/operation-and-maintenance-your-blocklet/)

---

## How to install local Blocklet as an application into the local Server?

URL: https://www.arcblock.io/en/docs/blocklet-developer/how-to-install-local-blocklet-as-an-application-into-the-local-server/

<strong>问：如何将本地的 Blocklet 作为应用（而不是作为组件）直接安装到本地运行的 Server 中。</strong>

<strong>答：</strong>

1. 在浏览器中访问 Server - Blocklet 列表页，点击 “安装应用” - “从 URL 安装“

![image.png](https://developer.blocklet.io/content/uploads/b1f2dd83f8f8b0d49a3c8fc61938400b.png)2. 将 blocklet 打包后，复制 blocklet bundle 目录中 release 目录中的 blocklet.json 文件的地址（通常在 `{你的项目目录}/.blocklet/release/blocklet.json`），在 url 输入框中填写 `file://{文件地址}`

![image.png](https://developer.blocklet.io/content/uploads/375b3059086c6fc55cddcebc5f5c29f8.png)

1. 完成后续过程，使用 DID 钱包创建应用 did，继续，直到安装成功。

---

## How to install a resource by URL after creating it

URL: https://www.arcblock.io/en/docs/blocklet-developer/how-to-use-install-url/

### Step 1: After creating the resource, click "Install" and copy the link

![image.png](https://media.arcblock.io/lib/be/be9de00356277113103f419ebce4e0fd.w1600.webp)

### Step 2: Go to the component management page and click "Add Component"

![image.png](https://media.arcblock.io/lib/28/289870c36f13127beb3b7894dba6d854.w1600.webp)

### Step 3: Click "Add component from URL", paste the link you just copied, and click "Next"

![image.png](https://media.arcblock.io/lib/72/72f4b8e9713f445ea132f68dfe26c396.w1600.webp)

After completing the subsequent installation process, congratulations, you have added the component to the application!

---

## blocklet-developer/image-service

URL: https://www.arcblock.io/en/docs/blocklet-developer/image-service/

---

## Install Blocklet CLI

URL: https://www.arcblock.io/en/docs/blocklet-developer/install-blocklet-cli/

> [!WARNING]
> 目前只能在 Linux(Ubuntu) 或 macOS 上安装和运行 Blocklet Server，Windows 平台下的用户请使用 Docker 来运行。

The Blocklet CLI is a command-line tool for managing both Blocklets and the Blocklet Server, which provides the runtime environment for Blocklets.  When developing a Blocklet, you'll need to run the Blocklet Server locally. (For instructions on running the Blocklet Server in Docker, see [Developing Blocklet in Docker](/zh/docs/blocklet-developer/develop-blocklet-with-docker/).)

## Install the Blocklet CLI

You can install the Blocklet CLI with your preferred package manager:

- npm

```javascript
npm install -g @blocklet/cli
```

- yarn

```javascript
yarn global add @blocklet/cli
```

- pnpm

```javascript
pnpm add -g @blocklet/cli
```

If you are using pnpm v10, you must also run `pnpm approve-builds -g` to enable the execution of build scripts.

![image.png](https://media.arcblock.io/lib/b7/b76419d7b1c7341458620eb6959dd6c5.w1600.webp)

<strong>Verify successful installation:</strong>

```javascript
blocklet -V

                 Powered By
     _             ____  _            _
    / \   _ __ ___| __ )| | ___   ___| | __
   / _ \ | '__/ __|  _ \| |/ _ \ / __| |/ /
  / ___ \| | | (__| |_) | | (_) | (__|   <
 /_/   \_\_|  \___|____/|_|\___/ \___|_|\_\

            Blocklet CLI v1.16.18

1.16.18
```

<strong>If the error message</strong> <strong>`command not found: blocklet`</strong> <strong>appears, you need to configure the Blocklet CLI global environment variables.</strong>

```javascript
# 以 yarn 为例，其它包管理工具类似

# 运行命令，查看 yarn 的全局 bin 目录。
yarn global bin

# 把这个目录添加到你的 PATH 环境变量中
open ~/.bashrc

# 在 .bashrc 中写入
export PATH="$PATH:$(yarn global bin)"

# 保存文件，重新加载你的 shell 或者重启你的终端。
source ~/.bashrc
```

## Installing Nginx

We recommend using Nginx as a reverse proxy for Blocklet Server.

> If you are unable to install Nginx, you can skip this step and use the Blocklet Server’s built-in gateway.

<strong>Nginx version: 1.18.0 or later</strong>

<strong>Installing on macOS (using Homebrew)</strong>

- `Install Nginx using the Homebrew package manager.`
- Reference: [https://formulae.brew.sh/formula/nginx](https://formulae.brew.sh/formula/nginx)

<strong>Install on Linux</strong>

- Refer to: [https://www.nginx.com/resources/wiki/start/topics/tutorials/install/](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)

<strong>Verify successful installation:</strong>

```javascript
nginx -v
nginx version: nginx/1.21.6
```

## Set Up Your DID Wallet

See [DID Wallet Setup](/zh/docs/blocklet-developer/setup-did-wallet/)

## Launch Blocklet Server

After installing the Blocklet CLI, you can use an empty directory to store configuration files and initialize the Blocklet Server.

1. Run the command `mkdir -p ~/blocklet-server-data && cd ~/blocklet-server-data` to create the directory and navigate into it. The `~/blocklet-server-data` path can be replaced with any other directory.

1. Run `blocklet server init` to initialize the Blocklet Server. <em>After running the initialization command, the system will prompt you to confirm the directory where the configuration will be stored. Once confirmed, the Blocklet Server configuration will be generated automatically.</em>

1. Start the Blocklet Server by running `blocklet server start`

<details>
<summary>输出示例</summary>

```javascript
% blocklet server init
blocklet server v1.16.18
Are you sure to initialize a Blocklet Server instance in the current directory(/Users/bob/blocklet-server-data) Yes
✔ Blocklet Server configuration is successfully generated /Users/bob/blocklet-server-data/.blocklet-server/config.yml
ℹ blocklet server start

% blocklet server start
blocklet server v1.16.18
✔ Server schema successfully migrated: /Users/bob/blocklet-server-data/.blocklet-server/core/server.db
✔ Service schema successfully migrated: /Users/bob/blocklet-server-data/.blocklet-server/services/service.db
✔ certificate-manager schema successfully migrated: /Users/bob/blocklet-server-data/.blocklet-server/modules/certificate-manager/module.db
ℹ Server DID zNKty6TZ9jkvTQTDQphk12B1osEbsGXHXLFC
ℹ Server config from /Users/linchen/blocklet-server-data/.blocklet-server/config.yml
✔ Starting event hub... Done in 3.044s
✔ Updating wildcard certificates... Done in 1.145s
✔ Starting blocklet service... Done in 32.657s
✔ Starting server daemon... Done in 5.084s
✔ Fetching accessible IPs... Done in 12.142s
✔ Updating DID Domain... Done in 1.232s
✔ You can access your Blocklet Server with either of the following URLs

HTTP URLs:

- http://192.168.31.18/.well-known/server/admin/
- http://bbqa7ka3ty3it3tb4prpraivmdhyr7hfooiirymz6cm.did.abtnet.io/.well-known/server/admin/

Secure URLs (Recommended):

- https://192-168-31-18.ip.abtnet.io/.well-known/server/admin/
```

</details>

## Accessing the Blocklet Server

After the Blocklet Server starts successfully, you will see its URL in the terminal.

```text
HTTP URLs:

- http://192.168.3.28/.well-known/server/admin/
- http://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.did.abtnet.io/.well-known/server/admin/

Secure URLs (Recommended):

- https://192-168-3-28.ip.abtnet.io/.well-known/server/admin/
```

- <strong>(Recommended)</strong> [`http://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.did.abtnet.io/.well-known/server/admin/`:](http://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.did.abtnet.io/.well-known/server/admin/:) Access via DID Name Service
- <strong>(Recommended)</strong> [`https://192-168-3-28.ip.abtnet.io/.well-known/server/admin/:`](https://192-168-3-28.ip.abtnet.io/.well-known/server/admin/:) Access via IP Echo Domain
- (Not recommended) [`http://192.168.3.28/.well-known/server/admin/`](https://) Accessing via IP address

> Note: Replace `192.168.3.28` with your local network IP address.

> [!WARNING]
> 注意：请不要使用 localhost 或 127.0.0.1 地址访问 Blocklet 服务器。 您将无法使用 DID 钱包连接它。

## Stopping the Blocklet Server

You can stop the Blocklet Server by running the `blocklet server stop` command.

##

---

## Integrate Blocklet Studio

URL: https://www.arcblock.io/en/docs/blocklet-developer/integrate-blocklet-studio/

![艾涅循环.png](https://media.arcblock.io/lib/49/4996f816b4ee9ee1aa077e0c9d15eed6.w1600.webp)

Developers of ArcBlocklet should all be familiar with this diagram, which shows how AIGNE utilizes Blocklet Studio and Blocklet Store to form a flywheel effect. AIGNE users can create many applications and publish them to the Store, thereby feeding back into AIGNE's ecosystem. <strong>In fact, any developer of a Blocklet can create their own flywheel effect by integrating Blocklet Studio and Blocklet Store.</strong>

## What types of Blocklets are suitable for integration with Blocklet Studio?

Most Blocklets do not need to integrate with Blocklet Studio. All Blocklet administrators can use Blocklet Studio by default, but if you want Blocklet users to also use Blocklet Studio, you need to integrate the Blocklet with Blocklet Studio.

A typical scenario for integrating a Blocklet is when your Blocklet needs to provide users with the ability to create Blocklets and distribute them through the Blocklet Store.

Here are some examples of cases where integrating Blocklet Studio is suitable:

- AIGNE integrates with Blocklet Studio, converting each AI application created by AIGNE into a Blocklet and distributing it on Blocklet Store.
- Pages-Kit integrates with Blocklet Studio, converting created Pages components into resource-type Blocklets and distributing them on Blocklet Store.

## Seamlessly Integrate Blocklet Studio in Blocklet

Integrating Blocklet Studio in Blocklet is very simple, just declare it using React components:

```javascript
import { BlockletStudio } from '@blocklet/ui-react';

<BlockletStudio

mode="dialog"

tenantScope={project.id}

componentDid={MY_COMPONENT_DID}

open={open}

setOpen={() => setOpen()}

onOpened={() => onOpened?.()}
/>
```

### Customizing Default Parameters and Optional Resources

Each project has unique requirements, so users can customize the default parameters and optional resources of the Blocklet Studio creation process. Users can set common parameters and resources in advance according to the specific situation of the project, saving publishing steps. Here is a more complete parameter example:

```javascript
import { BlockletStudio } from '@blocklet/ui-react';

<BlockletStudio

...

// Information for creating the application

title={project.name || ''}

description={project.description || ''}

note=""

introduction=""

logo={logo}

componentDid={MY_COMPONENT_DID}

// Parameters to pass through to get blocklet resource

resourcesParams={{ projectId: project.id }}

// Whether the user can edit dependent components

dependentComponentsMode="readonly"

// Default selected resources

resources={{

[MY_COMPONENT_DID]: [],

}}
/>
```

<strong>Complete component parameters:</strong>

```javascript
interface BlockletStudioProps {
  open: boolean;
  setOpen: (open: boolean) => void;
  onOpened?: () => void;
  componentDid: string;
  tenantScope?: string;
  resourcesParams?: Record<string, any>;
  mode?: string;
  title?: string;
  logo?: string;
  description?: string;
  introduction?: string;
  note?: string;
  onUploaded?: (data: unknown) => void; // Callback function after upload
  onReleased?: (data: unknown) => void; // Callback function after releasing a new release
  onConnected?: (data: unknown) => void; // Callback function after connection
  components?: Record<string, unknown>[]; // Default components list
  resources?: Record<string, unknown>; // Default resources
  componentsTitle?: string;
  resourcesTitle?: string;
  style?: React.CSSProperties;
  zIndex?: number;
  dependentComponentsMode?: 'auto' | 'readonly'; // Disable component selection
}

```

### Integrated Effect Demonstration

By above method, the integrated Blocklet Studio effect of AIGNE internally is as follows:

<video src="https://media.arcblock.io/lib/fb/fb073c481b7e61cb376086caf70c75b6.qt" controls></video>

## Multi-tenant mode and Single-tenant mode

To meet the needs of different users, the new version distinguishes in detail between multi-tenant mode and single-tenant mode. In multi-tenant mode, each user can only manage the Blocklet they created themselves. In Dahboard, we can modify the tenant mode of Blocklet, and Blocklet Studio will follow this configuration, without the need for additional development for different tenant modes.

<video src="https://media.arcblock.io/lib/19/1902590aa95909add9b63d1fc217fb35.qt" controls></video>

---

## Known Issues or Limitations

URL: https://www.arcblock.io/en/docs/blocklet-developer/known-issues-or-limitations/

- [Can not access server/blocklet with DID Domain?](/en/docs/blocklet-developer/Wa0JbgBpWWYhSWeg8380kq-k/)

- [Permission Issues on Linux](/en/docs/blocklet-developer/permission-issues-on-linux/)

- [When stuck in maintenance mode?](/en/docs/blocklet-developer/when-stuck-in-maintenance-mode/)

- [When stuck on a blank screen?](/en/docs/blocklet-developer/when-stuck-on-a-blank-screen/)

- [Not using 80/443 ports?](/en/docs/blocklet-developer/not-using-80-443-ports/)

- [Request Entity too Large](/en/docs/blocklet-developer/07ns0Nj6haMOsyrsTdyAjlps/)

---

## Claude

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-claude/

## Preconditions

1. Open Claude Settings > Developer
2. There should be no MCP configuration under normal circumstances.

![image.png](https://media.arcblock.io/lib/6f/6f9fbaf7f9e2509620f0471488ae1b72.w1600.webp)

##
Installation

### Install the Blocklet MCP

- Visit Dashboard => Integrations => MCP Blocklet  => Claude

![image.png](https://media.arcblock.io/lib/7c/7c1ac4746e7fda7125377e4de286fb4e.w1600.webp)

- Run the following installation command

```javascript
npx @blocklet/install-mcp@latest i https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/mcp --client claude --streamableHTTP --oauth2Bearer blocklet-z4iFYFf85nNkXFKCJ3d7jKSCJm6WN983Rk5J72rjCasRX
```

- Enter the server name as prompted.

![image.png](https://media.arcblock.io/lib/cf/cf7cdb8e8742674637a7f3fe871fdda5.w1600.webp)

### Confirm Installation

1. Restart Claude
2. Open Settings to view
3. Verify that the Blocklet Server is displayed and its status is running.

![image.png](https://media.arcblock.io/lib/28/2844bfa7704b3acb0a202de643f4c7cb.w1600.webp)

## Testing MCP

1. MCP functionality can be tested through simple queries
2. Example query: "View the current Blocklet's user count"
3. Verify the presence of MCP call logs and their corresponding output.

![image.png](https://media.arcblock.io/lib/6a/6a7ab45ebad934dc3ef0cd7696f6992f.w1600.webp)

## Things to Note

- The URL in the installation command points to the test environment.
- Ensure Claude is restarted after installation for the configuration to take effect.

---

## Cline

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-cline/

## Preconditions

1. Open Cursor, go to Extensions, and install Cline.
2. After successful installation, configure the relevant API.
3. Under normal circumstances, there should be no MCP services configured.

![image.png](https://media.arcblock.io/lib/b1/b1e95bd545ff41e3600caac2f5c8de6f.w1600.webp)

##
Installation

### Install the Blocklet MCP

- Visit Dashboard > Integrations > MCP Servers > Cline

![image.png](https://media.arcblock.io/lib/58/5863b7deb9f48667539fd7d4b77a5fc8.w1600.webp)

- Run the following installation command

```javascript
npx @blocklet/install-mcp@latest i https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/mcp --client cline --streamableHTTP --oauth2Bearer blocklet-z4iFYFf85nNkXFKCJ3d7jKSCJm6WN983Rk5J72rjCasRX
```

- Enter the server name as prompted.

![image.png](https://media.arcblock.io/lib/06/06711b999c61a57c6541ddb063d2eb0d.w1600.webp)

### Confirm Installation

1. Restart Cursor
2. View the Blocklet Service MCP
3. Confirm the Blocklet Server status is running

![image.png](https://media.arcblock.io/lib/a1/a1c114e9892c9602b5366a8e3c67834c.w1600.webp)

## MCP Test

1. MCP functionality can be tested through simple queries
2. Example query: "View the current Blocklet's user count"
3. Verify the presence of MCP call logs and output.

![image.png](https://media.arcblock.io/lib/20/20d8e5576683b439132b18f108f15bc7.w1600.webp)

## Important Considerations

- The URL in the installation command points to the test environment.
- Ensure Cursor is restarted

---

## Cursor

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-cursor/

## Preconditions

1. Open Cursor, go to Settings, then MCP.
2. Under normal circumstances, there should be no MCP configuration.

![image.png](https://media.arcblock.io/lib/7a/7ae7e86ad17e31c11f95dea1bc7336df.w1600.webp)

##
Installation

### Install the Blocklet Service

- Visit  Dashboard > Integrations > MCP Servers > Cursor.

![image.png](https://media.arcblock.io/lib/d0/d0287f1d705e1113b5a1d5d96899bb44.w1600.webp)

- Run the following installation command

```javascript
npx @blocklet/install-mcp@latest i https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/mcp --client cursor --streamableHTTP --oauth2Bearer blocklet-z4iFYFf85nNkXFKCJ3d7jKSCJm6WN983Rk5J72rjCasRX
```

- Enter the server name as prompted

![image.png](https://media.arcblock.io/lib/f0/f00084ea5d423e7eae4749f4dce2da87.w1600.webp)

### Confirm Installation

1. Re-enable the Blocklet Service
2. Verify that the Blocklet Server is displayed and its status is running

![image.png](https://media.arcblock.io/lib/0a/0a36be97499c95916ddf9d08e3df3d11.w1600.webp)

## MCP Test

1. MCP functionality can be tested through simple queries
2. Example query: "View the current Blocklet's user count"
3. Verify the presence of MCP call logs and output.

![image.png](https://media.arcblock.io/lib/20/206cea94a54ab10f26b39e32a706e2e4.w1600.webp)

## Important Considerations

- The URL in the installation command points to the test environment.
- Ensure the MCP Server refreshes after installation.

---

## Roo Cline

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-roo-cline/

## Preconditions

- Open Cursor, go to Extensions, and install Roo Code.
- After successful installation, configure the relevant API.

![image.png](https://media.arcblock.io/lib/0a/0af9386ddb584af6a8a0201018024859.w1600.webp)

- There should be no MCP configuration under normal circumstances.

![image.png](https://media.arcblock.io/lib/eb/eb7edf014a74d1e1216a0341c56573f1.w1600.webp)

##
Installation

### Install the Blocklet Service

- Vist Dashboard > Integrations > MCP Servers > Roo Cline

![image.png](https://media.arcblock.io/lib/dd/dd7ed3810f6789d1091c4d471bd0c902.w1600.webp)

- Run the following installation command

```javascript
npx @blocklet/install-mcp@latest i https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/mcp --client roo-cline --streamableHTTP --oauth2Bearer blocklet-z4iFYFf85nNkXFKCJ3d7jKSCJm6WN983Rk5J72rjCasRX
```

- Enter the server name as prompted

![image.png](https://media.arcblock.io/lib/32/329983f739fc41e4297a90f566f229ea.w1600.webp)

### Confirm Installation

1. Restart Cursor
2. View the Blocklet Service MCP
3. Confirm the Blocklet Server is running

![image.png](https://media.arcblock.io/lib/f7/f713e4bfb9025944a024daa6665aa4cb.w1600.webp)

## MCP Test

1. MCP functionality can be tested through simple queries
2. Example query: "How many users does this Blocklet have?"
3. Check for MCP call logs and output.

![image.png](https://media.arcblock.io/lib/5d/5d9827ac45417827e991de2ca353685f.w1600.webp)

## Important Considerations

- The URL in the installation command points to the test environment.
- Ensure Cursor is restarted

---

## MCP Servers

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-server/

Blocklet offers an official Model Context Protocol (MCP) server, enabling access to Blocklet data within MCP-compatible AI applications.

## Introduction to MCP

Model Context Protocol (MCP) is an open protocol for standardizing how applications provide context to large language models (LLMs). Think of it as a "USB-C connector" for AI applications, allowing them to easily connect to various data sources and tools.

Blocklet's MCP server allows you to access Blocklet data directly within Claude and other MCP-compatible AI assistants.

## Using MCP

- [Claude](/zh/docs/blocklet-developer/lEHkJB_rmy8DnrzDYmmmI98L/)
- [Cursor](/zh/docs/blocklet-developer/npOpr6MZB08EX3VE5l6dAUiC/)
- [Cline](/zh/docs/blocklet-developer/bZ0daqQOp8ameS3OK6Gv2Q5w/)
- [Roo Cline](/zh/docs/blocklet-developer/vb4fF3Xc0sMfamp9kRCawg_H/)
- [Windsurf](/zh/docs/blocklet-developer/jDy5gr9e7S7jpvRxH0puzUHD/)
- [Witsy](/zh/docs/blocklet-developer/k0y4wfeylAxxC1YFqqlXtM5o/)

---

## Windsurf

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-windsurf/

## Preconditions

- Install the Windsurf client
- Open Settings
- There should be no MCP configuration under normal circumstances.

![image.png](https://media.arcblock.io/lib/bc/bc2a48b0ec088490eaf4942863ca3f66.w1600.webp)

##
Installation

### Install the Blocklet MCP

- Go to Dashboard > Integrations > MCP Servers > Windsurf

![image.png](https://media.arcblock.io/lib/d7/d73d32faa2cf256a05b42fd7dd1e09f7.w1600.webp)

- Run the following installation command

```javascript
npx @blocklet/install-mcp@latest i https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/mcp --client windsurf --streamableHTTP --oauth2Bearer blocklet-z4iFYFf85nNkXFKCJ3d7jKSCJm6WN983Rk5J72rjCasRX
```

- Enter the server name as prompted.

![image.png](https://media.arcblock.io/lib/fd/fd57ec10d0da77fc6961cbe25211853a.w1600.webp)

### Verifying the Installation

1. Restart Windsurf / Refresh the MCP
2. View the Blocklet Service MCP
3. Confirm the Blocklet Server is running

![image.png](https://media.arcblock.io/lib/a0/a08eb8634f0379eee0829cde298b996e.w1600.webp)

## MCP Test

1. MCP functionality can be tested through simple queries
2. Example query: "View the current Blocklet's user count"
3. Check for MCP call logs and output.

![image.png](https://media.arcblock.io/lib/83/838ef1b4069e951540d41add465e71b5.w1600.webp)

## Things to Note

- The URL in the installation command points to the test environment.
- Make sure to restart Windsurf or refresh MCP after the installation is complete.

---

## Witsy

URL: https://www.arcblock.io/en/docs/blocklet-developer/mcp-witsy/

## Preconditions

- Install the Witsy client
- Open settings
- Set up the API
- There should be no MCP configuration under normal circumstances.

![image.png](https://media.arcblock.io/lib/e9/e92c8d5658047e016ce622c5998db2e4.w1600.webp)

##
Installation

### Install the Blocklet MCP

- Visit Dashboard > Integrations > MCP Servers > Windsurf

![image.png](https://media.arcblock.io/lib/15/154f1705cebf52301936125475bd90fd.w1600.webp)

- Run the following installation command

```javascript
npx @blocklet/install-mcp@latest i https://bbqavvuuki6llb76sxmf5ukteogoeyx42bwhzl46s7i.did.abtnet.io/.well-known/service/mcp --client witsy --streamableHTTP --oauth2Bearer blocklet-z4iFYFf85nNkXFKCJ3d7jKSCJm6WN983Rk5J72rjCasRX
```

- Enter the server name as prompted.

![image.png](https://media.arcblock.io/lib/b1/b13df597b9fffe56c2ec5ec6fce871c2.w1600.webp)

### Confirm Installation

1. Restart Witsy / Refresh MCP
2. <em>The Blocklet MCP is visible.</em>
3. Confirm the Blocklet Server is running

![image.png](https://media.arcblock.io/lib/b0/b08e04fbe1781cd472987f3471c6f24d.w1600.webp)

## MCP Test

1. MCP functionality can be tested with simple queries
2. Example query: "View the current Blocklet's user count"
3. Check for MCP call logs and output.

![image.png](https://media.arcblock.io/lib/05/05976e72f2e9c180d078f1dd7d9ff15e.w1600.webp)

## Important Considerations

- The URL in the installation command points to the test environment.
- Make sure to restart Witsy or refresh MCP after installation is complete.

---

## Not using 80/443 ports?

URL: https://www.arcblock.io/en/docs/blocklet-developer/not-using-80-443-ports/

Sometimes after you initialize and start a blocklet server and find that the server is not using 80/443 ports, this may happen for several reasons:

- The user creating/starting the server does not have permission to listen on 80/443 ports
- The ports are being used when initializing the server.

So the solution to different causes should be straightforward:

### 1. Ensure your server has permissions for 80/443 ports

If you setup and run your `@blocklet/cli` and `node.js` as root, you usually do not need to do this, but if you want a non-root user to start a server instance, you need to make sure `nginx` or `node` are allowed to listen on 80/443, checkout the following post:

[Allow non-root process to bind to port 80 and 443?](https://superuser.com/questions/710253/allow-non-root-process-to-bind-to-port-80-and-443)

### 2. Ensure 80/443 ports are not occupied by other service

Most web server software such as Apache and Nginx may choose to start on system boot, and they usually occupies 80/43 ports, if you are not running any useful services behind the default web server software, please remember to disable them:

[Nginx - disable autostart](https://askubuntu.com/questions/177041/nginx-disable-autostart)

### 3. Ensure 80/443 ports are picked up by blocklet server

Once you have fixed the permission issue and made the ports available for blocklet server, you can now tell blocklet server to use the expected ports:

- `rm ~/.arcblock/abtnode/*-preferred-ports.json` ensure that newly created servers use 80/443
- update `.blocklet-server/config.yml` by changing `node.routing.httpPort` and `node.routing.httpsPort` to 80 and 443

Then run `blocklet server start -u` to pickup the above config.

---

## DID Connect

URL: https://www.arcblock.io/en/docs/blocklet-developer/o4UuvMTg7SIG3nezWPaHJoh6/

[Developer Guide](/en/docs/did-connect/developer-guides/)

---

## OAuth Server

URL: https://www.arcblock.io/en/docs/blocklet-developer/oauth-service/

> [!NOTE]
> This is work in progress, will introduce more about how OAuth work in Blocklet Server

## Overview

Blocklet Service can function as an OAuth server, supporting the standard OAuth 2.0 authorization code grant.  It provides unified authentication and authorization services for third-party applications (such as Grafana). The process is similar to that of GitHub or Google's OAuth and is compatible with OpenID Connect.

<strong>Features:</strong>

- OAuth 2.0 Authorization Code Grant Flow

- Retrieving Basic User Information with OpenID Connect

- Integrates with services supporting Generic OAuth, such as Grafana
- Customizable Authorization Pages and Scope Management

##  Authorization Overview

- Users choose to log in via OAuth in third-party applications
- The application redirects the user to the local OAuth Server for authentication and authorization.
- After the user grants authorization, the OAuth Server redirects to the application with an authorization code.
- The application uses the authorization code to obtain an access token
- The application retrieves user information using the access token to complete login.

## Authorization Process Details

### User Authorization

Third-party applications will redirect users to the following URL:

```javascript
GET https://your-oauth-server/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_REDIRECT_URI
    &scope=openid%20profile%20email
    &state=RANDOM_STRING
    &response_type=code
```

Argument Description:

- client_id: The application's client ID

- redirect_uri: Callback URL; this must match the registered URL.

- scope: The requested permissions

- state: To prevent CSRF attacks, generate this value randomly.

- response_type: Must be `code

### User Consent

After the user logs in and grants authorization, the OAuth Server redirects to the `redirect_uri`, including the `code` and `state` parameters:

```javascript
GET YOUR_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STRING
```

### Token Exchange for Applications

Retrieve an access token using the authorization code:

```javascript
POST https://your-oauth-server/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=AUTH_CODE
&grant_type=authorization_code
&redirect_uri=YOUR_REDIRECT_URI
```

Returns:

```javascript
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid profile email"
}
```

### Retrieve User Information

Retrieve user information with an access token:

```javascript
GET https://your-oauth-server/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN
```

```javascript
{
  "sub": "user_id",
  "name": "用户名",
  "email": "邮箱"
}
```

---

## Operation your blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/operation-and-maintenance-your-blocklet/

## How to customize Blocklet Logo

When the Blocklet is installed, you can change the default logo of the Blocklet in Blocklet Dashboard.

There are 3 types of Blocklet Logos:

- Square (or round) Logo: The most commonly used logo.
- Horizontal Logo: If your page uses Blocklet UI, the horizontal logo will be displayed in the header and footer. The default horizontal logo is the Square Logo.
- favicon: You can also customize the favicon of your site. The favicon defaults to the Square Logo.

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/config-logo.w1600.webp)

> Tips:
> When the Blocklet developer does not set the favicon in index.html, or sets the standard favicon (`<link rel="shortcut icon" href="/favicon.ico">`), the user can customize the favicon from Dashboard.
> When the Blocklet developer sets a non-standard favicon (`<link rel="shortcut icon" href="/custom-path/xxx/favicon.ico">`), the user cannot customize the favicon

## How to setup a better blocklet navigation

Blocklet Server provides a default navigation generation policy that ensures users get a good out-of-the-box result. When the default generated navigation does not meet the needs, the navigation can be configured to enable custom navigation.

### Rules for default navigation generation

The core of the default generated navigation is the handling of composite blocklets. When multiple blocklets are combined, a merged navigation menu is created based on the `navigation` configured in each `blocklet.yml`

- If an application does not combine any other blocklets, then the default generated navigation matches the result configured in the navigation field declared in `blocklet.yml` for that application
- If an application combines other blocklets, the `navigation` declared in the combined blocklet will present a different merge result depending on the section it belongs to.
- When section is header, footer, dashboard, the navigation provided in the combined blocklet will be presented in the final navigation as a first-level menu with multiple second-level menus
- When section is social, bottom, sessionManager, the navigation provided in the combined blocklet will be elevated to the first level of the menu and presented in the final navigation.

### Customized navigation menu

In the Blocklet Server's blocklet details, the system provides an ability to visually edit the navigation menu, as shown below.

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/navigation.w1600.webp)

Here you can add, edit, delete and hide any menu at will (some built-in menus are not allowed to be deleted)

The page is divided into three areas: section selection area, editing area, preview area

First of all, you need to select a section to operate in the section selection area, and then the editing area will appear in the corresponding area contains the current menu items

You can click the "New" button in the upper right corner of the edit area to add a first-level menu.

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/add-navigation.w1600.webp)

Once saved, the navigation menu you just added will appear in the edit and preview areas

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/view-navigation.w1600.webp)

Click the plus button to the right of this menu to add a secondary menu to it, but since only one secondary menu item will be elevated to a primary menu, the original primary menu is not visible in the preview area at this time

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/view-navigation-2.w1600.webp)

You can try to add another secondary menu to revert to a primary menu with two secondary menus

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/view-navigation-3.w1600.webp)

If you just want to hide some menu items or if the corresponding menu items cannot be deleted, you can add the small eye icon on the right to hide the menu items.

When you have configured different menu items for different role users, you can switch the role on the right side of the preview area to see the different effects

![](https://media.arcblock.io/docs/operation-and-maintenance-your-blocklet/images/role-navigation.w1600.webp)

Finally, click the Save button on the right side of the editing area to save all the changes, and users will be able to see your customized navigation menu when they open your app again

---

## Setup with AWS EC2

URL: https://www.arcblock.io/en/docs/blocklet-developer/OyBnVoNk1gWnagA4oe0oPx1b/

## Running in AWS

We provide a Blocklet Server AMI image to quickly run a server based on our AMI image when creating EC2.

### Step 1: Find Blocklet Server AMI

1. Open the Amazon EC2 console page at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)
2. Select the `Images -> AMI` page in the sidebar
3. Select `Public Mirror` in the filter criteria
4. Enter `Blocklet Server` to search
5. Select the latest version of the mirror, the latest version is blocklet-server-1.8.26 as shown below: ![select ami](https://media.arcblock.io/docs/setup-blocklet-server/images/select-ami-en.w1600.webp)

<strong>!!!Note: Do not select the blocklet-server-bare-xxx image</strong>，

1. Click on "Launch instance from AMI"

### Step 2: Set up security groups and other basic information

1. Fill in the instance name
2. Select the instance type, the minimum memory requirement for Blocklet Server is 1G
3. Select the secret key pair
4. Configure the network security group, Blocklet Server requires open ports 80 and 443
5. Configure storage, the recommended minimum storage is 20G
6. Other configurations can be set according to the actual situation
7. Click "Launch Instance", wait for the instance to start successfully

### Step 3: Access the server via IP Echo address

EC2 instances can be accessed through their public IP Echo addresses after they are started. For example, if the public IP is `192.168.0.10`, then the IP Echo address is [`https://192-168-0-10.ip.abtnet.io/`](https://192-168-0-10.ip.abtnet.io/).

---

## Performance

URL: https://www.arcblock.io/en/docs/blocklet-developer/performance/

## Performance Modes in Blocklet Server

By default, blocklets, the server, and services run in low-consumption mode, which is designed to save resources.

In this mode:

- 🧠 Memory usage is <strong>roughly 50% lower</strong>

- ⚙️ CPU Performance is <strong>roughly 30% lower</strong>

## How to switch to normal performance mode?

To enable normal performance and resource usage for the server and services:

```javascript
export ABT_NODE_KERNEL_MODE=performant
```

To enable normal performance and resource usage for blocklets:

```javascript
export ABT_NODE_BLOCKLET_MODE=performant
```

## How to switch to low performance mode?

To enable normal performance and resource usage for the server and services:

```javascript
export ABT_NODE_KERNEL_MODE=normal
```

To enable normal performance and resource usage for blocklets:

```javascript
export ABT_NODE_BLOCKLET_MODE=normal
```

## How to enable switch?

Then restart the server:

```javascript
blocklet server start
```

---

## Permission Issues on Linux

URL: https://www.arcblock.io/en/docs/blocklet-developer/permission-issues-on-linux/

Usually, it's recommended to run blocklet server as a non-root user for security reasons, and you should always use the same user that created the server to start/stop the server because those who created the server are granted permission to read/write to the blocklet server directory.

You may encounter issues when switching back and forth between different users when init/start/stop your blocklet server, use the following steps:

```javascript
ubuntu@fnm:~$ sudo blocklet server init -y

// the server is initialized by root
ubuntu@fnm:~$ blocklet server start

// then non-root user try to update data in server directory during start
```

If we flip the above steps:

```javascript
ubuntu@fnm:~$ blocklet server init -y

// the server is initialized by non-root
ubuntu@fnm:~$ sudo blocklet server start

// then root user try to update data in server directory during start
```

You may encounter permission issues in all the above scenarios because the server creator is not the same as blocklet server starter.

So, to keep things clean and tidy, just stick to the same user that created the server to do any furthur operations.

---

## Platform Overview

URL: https://www.arcblock.io/en/docs/blocklet-developer/platform-overview/

![](https://media.arcblock.io/docs/platform-overview/images/overview.w1600.webp)

## Bootstrapping

- [Create Blocklet](https://createblocklet.dev) Your assistant on creating new blocklet project or monorepo.

## Developing

- [Blocklet Server](/) The blocklet runtime and management console.
- [Blocklet Services](/en/docs/blocklet-developer/blocklet-service/) Authentication and notification service that works out of the box.
- [Blocklet CLI](/en/docs/blocklet-developer/blocklet-cli/) Command line tool for developing blocklet in blocklet server
- [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/) Development kit for connecting blocklets with blocklet services, and handling common blocklet best practice library.
- [Blocklet UI](/en/docs/blocklet-developer/blocklet-ui/) Component library for providing a unified user experience for composition blocklets.
- [Blocklet Pages](https://pages.blocklet.io) Content engine for blocklet that makes it easy to create website and documentation site for your application.
- [Blocklet Compose](/) Compose your blocklet with other blocks to avoid reinventing wheels.
- [DID Wallet](https://didwallet.io) Used to manage blocklet and server passport
- [DID Connect](https://didconnect.io) Protocol and SDK for connecting decentralized identity with decentralized applications.
- [DID Domain](https://domain.didlabs.org) Uniq domain with HTTPS enabled to ease the development process.

## Publishing

- [Blocklet CLI](/en/docs/blocklet-developer/blocklet-cli/) Command line tool for bundling and uploading blocklets.
- [Blocklet Store](https://store.blocklet.dev) Decentralized app store for blocklets.
- [Blocklet Actions](/en/docs/blocklet-developer/blocklet-actions/) GitHub Actions for connecting your development pipeline to blocklet store.
- [DID Wallet](https://didwallet.io) Used to manage blocklet release on blocklet store.

## Running

- [Blocklet Server](/) The production-ready blocklet runtime and management console.
- [Blocklet Launcher](https://launcher.arcblock.io) The decentralized blocklet server manager that works on various cloud providers.
- [Blocklet Actions](/) GitHub Actions for connecting your development pipeline to production servers.
- [Blocklet Compose](/) Compose blocklets on the fly to make an awesome service.
- [DID Wallet](https://didwallet.io) Used to purchase and manage server ownership NFT.
- [DID Domain](https://domain.didlabs.org) Uniq domain with HTTPS enabled to ease the setup process.

---

## Publishing a Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/publish-blocklet/

### Prerequisites

Before publishing a Blocklet, you need to become a developer of the Blocklet Store. Please refer to:

[Get your developer passport](/en/docs/blocklet-store/get-your-developer-passport/)

### Publishing a Blocklet

When we create a Blocklet, it is by default published to the connected Blocklet Store. If we want to publish to multiple different Blocklet Stores, we can associate multiple Blocklet Stores for publishing.

Open Blocklet Studio, select the Blocklet you've created, and click on "View Latest Version Details":

![image.png](https://media.arcblock.io/lib/01/010c15dd983f0e84e0415c3a1db0a2d3.w1600.webp)

On the details page, click on "Connect or Upload":

![image.png](https://media.arcblock.io/lib/a3/a397b85b145d164f36f3d3cade245316.w1600.webp)

We can associate with the official Blocklet Store. If we want to associate with a non-official Blocklet Store, we can click on "Add Blocklet Store":

![image.png](https://media.arcblock.io/lib/4f/4f827365b5af0467bb5dbea2893b93ae.w1600.webp)

Enter a Blocklet Store address:

![image.png](https://media.arcblock.io/lib/66/66f9229471e3697cfd7c32eeccc02181.w1600.webp)

Choose a Blocklet Store for association:

![image.png](https://media.arcblock.io/lib/75/75595dcefcc7912005ee57459f72a2d7.w1600.webp)

Association requires binding a developer wallet, and the application will be deployed to the account of this developer in this Blocklet Store:

![image.png](https://media.arcblock.io/lib/0a/0a2039d0beb1578fbd915694265c0824.w1600.webp)

After successful association, we can see that the "Connect" button changes to "Upload", which can be clicked to upload:

![image.png](https://media.arcblock.io/lib/da/da1e53dca58e36702acf62f3cabd94b0.w1600.webp)

After successful upload, we can click on "More" on the right to access the management page of this Store:

![image.png](https://media.arcblock.io/lib/4d/4ded594a61c83f31f64282bfcc5b349a.w1600.webp)

Then we click on "Publish", and it will be visible in the application market:

![image.png](https://media.arcblock.io/lib/0d/0d42c01331f579816c54fee80b6b6ada.w1600.webp)

If we enable auto-publishing, the application will be automatically published every time it's uploaded:

![image.png](https://media.arcblock.io/lib/f3/f3abb0a6aa24c51e501117e830164f78.w1600.webp)

After successful publication, we can see the Blocklet just published on the Blocklet Store, and other users can install and use our Blocklet:

![image.png](https://media.arcblock.io/lib/78/783b73901a4d51ed5608e98e50999007.w1600.webp)

IIf the application we create is a Resource-based Blocklet, we won't be able to see it in the application market. We can add a Resource-based Blocklet to a Blocklet instance, details of which can be found in this article:

[Why can't see the released Resource-based Blocklet be seen in the Blocklet Store?](/en/docs/blocklet-developer/hB5VWLfg9VnbWsL1JGLuLUfW/)

---

## Publish your blocklet to the world

URL: https://www.arcblock.io/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/

## Publish to Blocklet Store

1. Register as a developer from the Blocklet Store

-
  - Blocklet Store is a decentralized Blocklet
  - Arcblock provides 2 official Store: [blocklet store](https://store.blocklet.dev/) and [blocklet store(dev)](https://dev.store.blocklet.dev/)
  - You can setup a self-hosted store refer to [https://store.blocklet.dev/blocklets/z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ](https://store.blocklet.dev/blocklets/z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ)
  - You need to apply for a developer first, after the administrator has approved, you can proceed to the next step

1. Create a new access key

-
  - Use `blocklet connect <store-url>` command to create and access key from store

1. Bundle your blocklet

-
  - Refer to [Bundle your blocklet](/en/docs/blocklet-developer/bundle-your-blocklet/)

1. Upload your blocklet

-
  - Use `blocklet upload` to upload your blocklet bundle to store

1. Login to the uploaded Blocklet Store, you can see the uploaded Blocklet in the "My Blocklet" page in Admin Dashboard
2. The uploaded Blocklet is still in the "draft" status, click the "publish" button to publish

## Publish to multiple stores

- Use `blocklet connect <store-url> --profile <profile>` to save access token of different stores
- Use `blocklet upload --profile <profile>` to upload your blocklet bundle to multiple stores

#### Caveats

If you need to publish your blocklet to multiple stores during the distribution workflow, and if your blocklet has dependency components, the recommended way to declare dependency is following:

- Development: Set `COMPONENT_STORE_URL="https://test.store.blocklet.dev"` in your `.env.local`
- Production: Set `COMPONENT_STORE_URL` in your github action workflow.

> [!NOTE]
> TODO: ## Host with github release

> [!NOTE]
> TODO: ## Other hosting options

---

## Read/Write blockchain in blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/readwrite-blockchain-in-blocklet/

- ArcBlock chain: @ocap/client
- Ethereum chain: web3.js, ethers.js
- Standard chain info for DID Connect: blocklet sdk and development

---

## Reference Guides

URL: https://www.arcblock.io/en/docs/blocklet-developer/reference-guides/

- [DID Connect](/en/docs/blocklet-developer/o4UuvMTg7SIG3nezWPaHJoh6/)

- [blocklet.yml](/en/docs/blocklet-developer/blockletyml/)

- [blocklet.js](/en/docs/blocklet-developer/blockletjs/)

- [Blocklet SDK (Node.js)](/en/docs/blocklet-developer/blocklet-sdk/)

- [Blocklet SDK (Browser)](/en/docs/blocklet-developer/5z27x8H1fDFgdL3k6ZKNBvjp/)

- [Blocklet Service](/en/docs/blocklet-developer/blocklet-service/)

- [Blocklet CLI](/en/docs/blocklet-developer/blocklet-cli/)

- [Blocklet Server CLI](/en/docs/blocklet-developer/blocklet-server-cli/)

- [Blocklet UI](/en/docs/blocklet-developer/blocklet-ui/)

- [Blocklet GitHub Actions](/en/docs/blocklet-developer/blocklet-actions/)

- [Blocklet Studio](/en/docs/blocklet-developer/blocklet-studio/)

- [Blocklet Manager](/en/docs/blocklet-developer/RYjGuvTJLfhWrjnNLzepFhZX/)

- [Security](/en/docs/blocklet-developer/security/)

- [Performance](/en/docs/blocklet-developer/performance/)

- [Image Service](/en/docs/blocklet-developer/image-service/)

- [Theming](/en/docs/blocklet-developer/theming/)

- [Developer Best Practices.](/en/docs/blocklet-developer/cRaH7u7b7Rj31i0ymIlSOv6r/)

- [Known Issues or Limitations](/en/docs/blocklet-developer/known-issues-or-limitations/)

- [Setup Blocklet Server](/en/docs/blocklet-developer/setup-blocklet-server/)

- [WebHooks](/en/docs/blocklet-developer/webhook/)

- [OAuth Server](/en/docs/blocklet-developer/oauth-service/)

- [Access Key](/en/docs/blocklet-developer/access-key/)

- [MCP Servers](/en/docs/blocklet-developer/mcp-server/)

---

## Resource-based Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/resource-based-blocklet/

If a Blocklet is only associated with resources and not linked to any components, it is defined as a Resource-based Blocklet. A Resource-based Blocklet is an advanced usage intended to reuse certain resources of Blocklets.

A Resource-based application refers to a Blocklet that is not linked to any applications; such applications cannot be directly installed from the Blocklet Store, but can be installed as components within a Blocklet instance.

Here are some typical examples of Resource-based Blocklets:

- [Media Kit](https://store.blocklet.dev/blocklets/z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9) : Through a Resource-based Blocklet, multimedia resources can be reused in other Blocklets.
- [Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu) : Through a Resource-based Blocklet, articles, blogs, and forum settings can be reused in other Blocklets.
- [Pages Kit](https://store.blocklet.dev/blocklets/z8iZiDFg3vkkrPwsiba1TLXy3H9XHzFERsP8o) : Through a Resource-based Blocklet, custom components can be reused in other Blocklets.
- [AI Studio](https://store.blocklet.dev/blocklets/z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB) : Through a Resource-based Blocklet, AI projects can be reused in other Blocklets.

### How to create a Resource-based Blocklet

In Blocklet Studio, create a Blocklet without associating any components:

![image.png](https://media.arcblock.io/lib/99/99110f77f52c8870691ce8218b22ddaa.w1600.webp)

### How to install a Resource-based Blocklet

In a Blocklet instance, click the "Add Component" button:

![image.png](https://media.arcblock.io/lib/8b/8b34b707b012aefe8cc43a70a5408f37.w1600.webp)

At this point, the published Resource-based Blocklets become visible, and installation can proceed:

![image.png](https://media.arcblock.io/lib/68/68bde9bf6f2e7161c3dd42ba0e9e1f8e.w1600.webp)

---

## Migration Guide

URL: https://www.arcblock.io/en/docs/blocklet-developer/rsqfOEpttOasWtvzNVUp4nAb/

- [1.17.x 升级与迁移指南](/en/docs/blocklet-developer/server-17-migration-guide/)

---

## Blocklet Manager

URL: https://www.arcblock.io/en/docs/blocklet-developer/RYjGuvTJLfhWrjnNLzepFhZX/

- [Adding a component](/en/docs/blocklet-developer/7zbw0GQXgcD6sCcjVfwqqT2s/)

---

## Security

URL: https://www.arcblock.io/en/docs/blocklet-developer/security/

- blocklet security: sk, config, data backup
- server security: sk, ssh, data-disk
- access-key: passport
- integrations

---

## 1.17.x Upgrade and Migration Guide

URL: https://www.arcblock.io/en/docs/blocklet-developer/server-17-migration-guide/

## Overview

With the forthcoming Blocklet Server v1.17.x release, we have implemented optimizations across various security scenarios for Blocklet Server. However, these enhancements also bring with them some breaking changes:

- Removed some Blocklet environment variables (`BLOCKLET_APP_SK`, `BLOCKLET_APP_PSK`).
- @blocklet/sdk's `getWallet()` returned object <strong>removed</strong> the `wallet.secretKey` / `wallet.sk` properties;
- Most signing and verification functions in @blocklet/sdk and @ocap/wallet have transitioned from synchronous to <strong>asynchronous</strong>.
- The export methods for several packages have shifted from CommonJS default exports to <strong>ES Module named exports</strong>.
- In the following scenarios, the signing/verification private key has been changed from the original BLOCKLET_APP_SK to BLOCKLET_APP_ASK: <strong>cross-Component calls, Service API calls, Server API calls, Notifications, or WebSocket communications.</strong>
- Some environment variables have been added:
-
  - BLOCKLET_APP_ASK: A new environment variable, designed for signing in the following scenarios: <strong>Cross-Component calls / Service API or Server API invocations / Notification or WebSocket communications</strong>
  - BLOCKLET_APP_PPK: The original `BLOCKLET_APP_PSK`'s public key

This guide breaks down these changes into distinct migration steps, illustrative replacement examples, and critical regression checks, streamlining gradual modifications and comprehensive manual verification.

Before making modifications, please ensure that all <strong>related dependencies have been upgraded to the latest version (version:</strong> 1.17.1<strong>)</strong>.

<strong>This document can be copied to AI for migration and modification.</strong>

## List of Major Breaking Changes

### 1. Environment Variable Changes

<strong>Changes</strong>: BLOCKLET_APP_SK and BLOCKLET_APP_PSK have been removed. Any code relying on these private keys must now sign via the wallet interface of @blocklet/sdk or export the public key for verification.

<strong>Migration Highlights</strong>:

- If your code directly signs using a private key, refactor it to use `getWallet()` to retrieve the wallet and utilize its asynchronous signing method (refer to the example).
- To derive a sub-wallet using a private key, use `await getWallet().deriveWallet()`.
- For verification purposes only, use the public key `getWallet().publicKey` or `process.env.BLOCKLET_APP_PK` as the replacement.

<strong>SK Signature</strong>:

Old code:

```javascript
const wallet = fromSecretKey(process.env.BLOCKLET_APP_SK);
const signature = wallet.sign();
```

New Code:

```javascript
const { getWallet } = require('@blocklet/sdk/lib/wallet');
const wallet = await getWallet();
const signature = await wallet.sign();
```

<strong>JWT Signature</strong>:

Old:

```javascript
const jwtToken = jwt.sign(payload, process.env.BLOCKLET_APP_SK);
```

New:

```javascript
const { getWallet } = require('@blocklet/sdk/lib/wallet');
const wallet = await getWallet();
const jwtToken = await wallet.signJWT(payload);
```

<strong>SK Verification:</strong>

 Previous:

```javascript
const wallet = fromSecretKey(process.env.BLOCKLET_APP_SK);
const isValid = wallet.verify(data);
```

New:

```javascript
const wallet = fromSecretKey(process.env.BLOCKLET_APP_PK);
const isValid = wallet.verify(data);
```

<strong>fromAppDid:</strong>

Old:

```javascript
// BLOCKLET_APP_SK
const wallet = fromAppDid(address, process.env.BLOCKLET_APP_SK, { role: types.RoleType.ROLE_ACCOUNT }, x)

// BLOCKLET_APP_PSK
const wallet = fromAppDid(address, process.env.BLOCKLET_APP_PSK, { role: types.RoleType.ROLE_ACCOUNT }, x)
```

New:

```javascript
  const { deriveWallet } = require('@blocklet/sdk/lib/wallet');

  // BLOCKLET_APP_SK
  const wallet = await deriveWallet(address, { role: types.RoleType.ROLE_ACCOUNT }, x);

  // BLOCKLET_APP_PSK
  const wallet = await deriveWallet(address, { role: types.RoleType.ROLE_ACCOUNT }, x, 'psk');
```

### 2. Changes to the getWallet() return object

<strong>Changes</strong>: Removed properties such as wallet.secretKey / wallet.sk; all signing/verification methods are now asynchronous.

<strong>Key Migration Points</strong>:

- All calls to `wallet.sign()`, `wallet.verify()`, etc., must be `await`ed.
- If your code relies on `wallet.secretKey` for signing or derivation, please consult the modifications detailed under <strong>1. Environment Variable Changes</strong>.

<strong>Example</strong>:

Old:

```javascript
const { getWallet } = require('@blocklet/sdk/lib/wallet');

const wallet = getWallet();
const sig = wallet.sign(data);

console.log(wallet.secretKey) // sk....
```

New:

```javascript
const { getWallet } = require('@blocklet/sdk/lib/wallet');

const wallet = await getWallet();
const sig = await wallet.sign(data);

console.log(wallet.secretKey) // undefined
```

### 3. Multiple Exports Are Now Named (ESM) Exports

<strong>Changes</strong>: Some packages have been changed from default or CommonJS-style exports to named exports. The import syntax requires adjustment.

<strong>Common Replacement Patterns</strong>:

```javascript
- import parse from '@blocklet/meta/lib/parse';
+ import { parse } from '@blocklet/meta/lib/parse';

- const env = require('@blocklet/sdk/lib/env');
+ const { env } = require('@blocklet/sdk/lib/env');
```

<strong>Affected Packages and Common Exports</strong> (Please search and replace globally in the codebase):

- <strong>@blocklet/sdk</strong>: `BlockletAuthenticator`, `createConnectHandlers`, `Database`, `authMiddleware`, `fallback`, `sessionMiddleware`, `sitemap`, `userMiddleware`, `WalletAuthenticator`, `WalletHandlers`, `getWallet`, `getPkWallet`, `createRemoteWallet`, `deriveWallet`, `getPermanentWallet`, `getEthereumWallet`, `getAccessWallet`, `env`, `BlockletService`, etc.
- <strong>@blocklet/meta</strong>:`toBlockletDid`, `validateBlockletEntry`, `getComponentProcessId`, `hasReservedKey`, `getBlockletInfo`, `parseNavigation`, `parse`, `urlPathFriendly`, `verifyMultiSig`, `getApplicationWallet`, `checkBlockletEnvironment`, `env`.
- <strong>@blocklet/env</strong>: Previously, env was directly default-exported; it now requires destructuring from the blockletEnv or env named exports.

It is recommended to use your IDE's project-wide grep/replace functionality or make file-by-file adjustments, ensuring that import statements and their exported names remain consistent.

### 4. Synchronous -> Asynchronous: `await` and `async` are required at the call site.

<strong>Changes</strong>: The following functions/methods are now asynchronous (only frequently used ones are listed). Please add `await` to the call sites and mark the functions containing these calls as `async`.

<strong>4.1 @blocklet/sdk</strong>

- `verify() / sign() / getSignData()`(lib/util/verify-sign.ts)
- `signResponse() / verifyResponse()` (in lib/security)
- `getDelegation()` (lib/connect/shared.ts)
- `verifyBlockletSig()`(lib/middlewares/blocklet.ts)
- `subscribe() / unsubscribe()` (lib/service/eventbus.ts)
- `ensureClient() / on()`(lib/service/notification.ts)

<strong>4.2 @ocap/wallet</strong>

All methods of wallet instances generated by the library (or returned by `getWallet()`) are now asynchronous:

- `wallet.sign()`
- `wallet.verify()`
- `wallet.ethSign()`
- `wallet.ethVerify()`

<em>4.3</em> Other Libraries (Common)

- @arcblock/jwt:`jwt.sign()`, `jwt.verify()`, `jwt.signV2()` now require await.
- @blocklet/meta:`signResponse()`, `verifyResponse()` now require await.
- @asset/vc:`create()`, `verify()`, `verifyPresentation()`, `createCredentialList()`, `verifyCredentialList()` – all return awaitable Promises.
- @blocklet/js-sdk:`verifyResponse()` -> await.
- @blocklet/store / @blocklet/cli: `sign()` now requires `await`.
- @blocklet/server-js: `_getAuthHeaders()`, `getAuthHeaders()`, `signWithAccessKey()` -> await.

### 5. Key Considerations for Signing and Invocation Scenarios

In the following scenarios (<strong>cross-component calls, service API invocations, notifications, or WebSockets</strong>), the signing private key, previously `process.env.BLOCKLET_APP_SK`, should now be the <strong>secretKey from the access wallet</strong>.

<strong>Migration Key Points</strong>:

- To use @blocklet/sdk's `getAccessWallet()`, obtain the access wallet (which includes the signing key). The secretKey should then be explicitly passed within the options parameter of sign(), verify(), or getSignData(). Example:

```javascript
import { sign, verify, getSignData } from '@blocklet/sdk/lib/util/verify-sign';
import { getAccessWallet } from '@blocklet/sdk/lib/wallet';

const accessWallet = await getAccessWallet();

// sign
const result = await axios({
  url: '/service/api',
  data: json,
  headers: {
    'x-app-id': accessWallet.address,
    'x-app-pk': accessWallet.publicKey,
    'x-component-sig': await sign(json, { appSk: accessWallet.secretKey }),
    'x-component-did': process.env.BLOCKLET_COMPONENT_DID
  },
});

// verify
const isValid = await verify(data, signature, { appSk: accessWallet.secretKey });

// getSignData
const signData = await getSignData(data, { appSk: accessWallet.secretKey });
```

## Code Migration Checklist (Prioritized)

1. From the repository root, run the upgrade command and install dependencies. Create a separate branch.
2. Perform a global search-and-replace operation to update import methods, transitioning from CommonJS default exports to named exports.
3. A comprehensive search for usages such as `getWallet()`, `fromSecretKey()`, and `fromAppDid()`.

-
  - Usage of private key attributes (secretKey / sk) must be replaced with `getWallet()` for signing, or with `getAccessWallet()` combined with `appSk`.
  - Change all sign() / verify() / getSignData() and similar calls to use await.

1. For calls spanning components, services, notifications, and WebSockets, ensure to use `getAccessWallet()` and pass `appSk` to the signing method.
2. After modification, run TypeScript/Node builds and unit/integration tests to identify any missing synchronous calls or import errors.
3. Manual file-by-file review: Pay special attention to code paths related to middleware, service, eventbus, notification, and connect.

## Frequently Asked Questions and Troubleshooting Tips

- <strong>Bad secret key size</strong>
-
  - Reason: The dependencies were not upgraded to the latest version.
- <strong>Various verification failures</strong>
-
  - Confirm that the signature utilizes the access wallet's secretKey.
- <strong>Other components failed to start</strong>
-
  - Please upgrade all components in your application to the latest version, then perform a complete shutdown and restart.

---

## blocklet-developer/service-openapi

URL: https://www.arcblock.io/en/docs/blocklet-developer/service-openapi/

---

## Add PWA Integration to Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/service-worker-integrate/

> PWA integration is currently in its early stages, and we will continue to improve the experience.
> Make sure the version of `@blocklet-cli` is greater than `1.16.38-beta-20250115-235439-bb5a1c1b`

Before we begin, let's define what is a PWA (Progressive Web App). In summary, a PWA is an app t hat is built using web platform technologies, but provides a user experience like that of a native app. Read below for a more in-depth summary.

[Progressive web apps | MDN](https://developer.mozilla.org/docs/Web/Progressive_web_apps)

With this foundation in place, we can now explore how to add PWA support to a Blocklet.

## How does adding PWA to a Blocklet differ from a standard application?

Because of the composable nature of blocklets, an application often contains multiple components, each with its own code and Service Worker logic.

Under these circumstances, we need a robust mechanism to isolate the Service Worker logic for each component.

Now, let's explore how to equip an existing Blocklet component with Service Worker functionality.

## Adding Service Worker Code to Blocklet

This article uses a simple Blocklet to demonstrate how to integrate a Service Worker into a Blocklet.

[GitHub - blocklet/profile-demo](https://github.com/blocklet/profile-demo)

### Add the `vite-plugin-pwa` plugin and add the following code to your `vite.config.js` file.

```javascript
import { defineConfig } from 'vite';
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig(() => {

return {

// other configs

plugins: [

  // other plugins

VitePWA({

  manifest: false,

  injectRegister: false,

  registerType: 'autoUpdate',

  strategies: 'injectManifest',

  srcDir: 'src',

  filename: 'service-worker.js',

  injectManifest: {

    maximumFileSizeToCacheInBytes: 4194304,

  },

})

]

};
});

```

### Add the `src/service-worker.js` file and implement the service worker logic for this project.

```javascript
importScripts('/.well-known/service/static/share/shared-service-worker.js');

const { strategies, precaching, core, routing } = self.blocklet.workbox;

precaching.precacheAndRoute(
  (self.__WB_MANIFEST || []).filter((x) => x.url !== 'index.html').map(self.blocklet.fixRouteUrl),
);

routing.registerRoute(
  new routing.Route(
    ({ request, url }) => {
      if (!self.blocklet.canCache({ url })) return false;
      return ['image', 'font', 'style', 'script'].includes(request.destination);
    },
    new strategies.CacheFirst({
      cacheName: `static-resources-${self.registration.scope}`,
    }),
  ),
);

routing.registerRoute(
  new routing.Route(
    ({ request, url }) => {
      const whitelist = ['/.well-known/service/api/user/privacy/config'];
      if (whitelist.includes(url.pathname)) return true;
      if (!self.blocklet.canCache({ url })) return false;
      return request.method === 'GET';
    },
    new strategies.NetworkFirst({
      cacheName: `others-${self.registration.scope}`,
    }),
  ),
);

self.skipWaiting();
core.clientsClaim();
```

1.
  - The `blocklet-service` provides a set of useful functions and properties, all injected into `self.blocklet`.  Therefore, it is recommended that custom service workers import this shared module `importScripts('/.well-known/service/static/share/shared-service-worker.js');` as their first line.
  - The `self.__WB_MANIFEST` variable will then be used to access the static assets generated during compilation. This functionality is provided by the `vite-plugin-pwa` plugin.
  -
    - After the project compiles, this code snippet becomes `[{"revision":null,"url":"assets/index-BRdNHKF-.js"},{"revision":null,"url":"assets/index-CnoUf9Rp.css"},{"revision":"dc80b26617d2f88aacce576b0dd81d8a","url":"index.html"}]`, representing all the static assets for the Blocklet.
  - Then use `workbox.precaching.precacheAndRoute` to precache all the static assets obtained above.
  -
    - Workbox is available directly via `self.blocklet.workbox` and does not need to be imported.
    - Note that static assets of Blocklet components are proxied via `.blocklet/proxy/xxx`. Therefore, when pre-caching these assets, their URLs must be transformed. The `self.blocklet.fixRouteUrl` method can be used for this purpose.
  - Components can then handle logic based on their individual characteristics.
  -
    - This step allows for dynamic resource/data caching, communication between the service worker and the page, and features like background sync.
    - In this step, you'll likely use the `self.blocklet.canCache` function, which determines whether the requested resource falls within the current service worker's scope. This allows for straightforward resource isolation between different components.

### Enable/Disable a Blocklet's Service Worker

You might be thinking: We haven't added the service worker registration code yet.

Yes, it hasn't been added yet, but this Blocklet doesn't need it.

Simply enable the service worker by setting the `ENABLED_SERVICE_WORKER` environment variable to `true` in the Blocklet's configuration.

![image.png](https://media.arcblock.io/lib/8b/8b20377257e6bf3ab09993441ea5f416.w1600.webp)

![image.png](https://media.arcblock.io/lib/39/39f945c23303791bdfbfcd43479d5bd7.w1600.webp)

Restarting the current component will automatically register the service worker.

To unregister a Blocklet's service worker, set the value of `ENABLED_SERVICE_WORKER` to `false`.

### Tips

Some components simply provide a service and don't require externally accessible pages.

For example, the Media Kit, which provides file uploading and browsing capabilities to other components, is often used as an image hosting service.

Due to the component isolation strategy described above, the Media Kit's resources are not cached by the current Service Worker.  Therefore, you must set a specific environment variable, `SERVICE_WORKER_SHARING_ENABLED`, to `true` for the Media Kit. This enables shared caching within the Service Worker, preventing `self.blocklet.canCache` from intercepting the Blocklet's resources.

![image.png](https://media.arcblock.io/lib/61/61c9d0a82a97f3ad515268721a1b36f5.w1600.webp)

## Quick Reference

```typescript
type MountPoint = string;
type DID = string;
type BlockletServiceWorker = {

// property

workbox: Workbox;

did: DID;

prefix: string;

mountPoints: Array<MountPoint>;

sharedMountPoints: Array<MountPoint>;

// function

canCache: (options: { url: string }) => boolean;

getPrefix: () => string;

getDid: () => string;

getMountPoints: () => Array<MountPoint>;

getSharedMountPoints: () => Array<MountPoint>;

fixRouteUrl: (string) => string;
};
```

- workbox: Currently using `workbox-cdn`. Refer to [https://developer.chrome.com/docs/workbox/modules/workbox-sw](https://developer.chrome.com/docs/workbox/modules/workbox-sw) for more details.
- did: The DID of the Blocklet component for this page
- prefix: The mount point of the Blocklet component for the current page
- mountPoints: All component mount points in the current Blocklet
- sharedMountPoints: The mount points for all components in the current Blocklet that have enabled `SERVICE_WORKER_SHARING_ENABLED`
- canCache: Checks if a URL should be cached by the current component's service worker

---

## Setup Blocklet Server

URL: https://www.arcblock.io/en/docs/blocklet-developer/setup-blocklet-server/

Blocklet Server can run in various environments:

- [Setup with ArcBlock Launcher](/en/docs/blocklet-developer/Zquq4DW4XK79vABo7K-_JTFu/)

- [Setup with AWS EC2](/en/docs/blocklet-developer/OyBnVoNk1gWnagA4oe0oPx1b/)

- [Setup with Docker](/en/docs/blocklet-developer/WV6iDyriFb4YWGpJnFU3lkIS/)

- [Setup on Ubuntu + FNM](/en/docs/blocklet-developer/setup-on-ubuntu-fnm/)

- [Setup on Ubuntu + Nodesource](/en/docs/blocklet-developer/setup-on-ubuntu-nodesource/)

---

## Setup DID Wallet

URL: https://www.arcblock.io/en/docs/blocklet-developer/setup-did-wallet/

## Why do I need DID Wallet?

[DID Wallet](https://didwallet.io) is an decentralized app that's used to manage digital assets(such as [token](/en/docs/blockchain/understanding-tokens/) and [NFT](/en/docs/blockchain/understanding-nfts/)) and [decentralized identities](/en/docs/blockchain/understanding-dids/).

DID Wallet is required in the blocklet development workflow to accomplish the following tasks:

- Manage your decentralized identities when talking with blocklets
- Receive and present blocklet server passport
- Receive and present blocklet owner passport
- Receive and spend blockchain tokens, NFTs
- Authorize other dangerous operations for blocklet and server

## Platforms supported by DID Wallet?

DID Wallet currently fully supports the following platforms:

- [Android](https://play.google.com/store/apps/details?id=com.arcblock.wallet.app.product)
- [iOS](https://apps.apple.com/app/id1460083542)
- [Chrome Extension](https://chrome.google.com/webstore/detail/did-wallet/ibjflpbmadchofnbpppegdbnifdgincp)
- [Microsoft Edge Addons ](https://microsoftedge.microsoft.com/addons/detail/did-wallet/hjgoblidjnnnamdkinbichnfbmghmafd)

DID Wallet on the web platform are mostly used by developers because they provide a shorter feedback loop.

## How to setup DID Wallet?

There are two ways to setup a DID Wallet.

- [Create a new wallet](https://support.didwallet.io/en/howToInitWallet)
- [Restore from a backup](https://support.didwallet.io/en/howToRecoverWallet)

After setup the wallet, you will get 3 default accounts by default, and DID Wallet will generate a new DID whenever you are using with a new blocklet, for more information please refer: [Why multiple accounts?](https://support.didwallet.io/en/whyMultiAddresses)

---

## Setup Node.js

URL: https://www.arcblock.io/en/docs/blocklet-developer/setup-nodejs/

> [!TIP]
> You can safely skip this step if you have already Node.js v20+ installed on your development environment.

## Why Node.js?

Most of the components in the Blocklet toolbox are built with Node.js, so you need to install Node.js to use them.

<strong>Please ensure that the version of Node.js is v20 and above.</strong>

To find out if you have Node.js installed and check the installed version, run the following command.

```javascript
node -v
```

## Install Node.js

Node version managers are recommended way to install Node.js because they allow you to install and switch between multiple versions of Node.js on your system, so you can test your blocklets on multiple versions of Node.js to ensure they work for users on different versions.

For MACOS or Linux users, please refer to the documentation of the following version managers for instructions on how to install Node.js:

- [nvm](https://github.com/creationix/nvm)
- [n](https://github.com/tj/n)

For more available node version managers please checkout [this comparison post](https://www.honeybadger.io/blog/node-environment-managers/).

For Windows users, please stay tuned well we are testing support of the blocklet toolkit on the Windows platform.

---

## Setup on Ubuntu + FNM

URL: https://www.arcblock.io/en/docs/blocklet-developer/setup-on-ubuntu-fnm/

Ubuntu is a popular Linux distribution loved by the developer community, Blocklet Server can run on it with the following steps.

---

## Run as root user with Nginx

Following are the steps to setup your blocklet server on Ubuntu as <strong>root (</strong><strong>not recommended</strong><strong>)</strong>:

### Setup Node.js with fnm

[fnm](https://github.com/Schniz/fnm) is another awesome Node.js version manager, just like [nvm](https://github.com/nvm-sh/nvm).

```javascript
root@fnm:~$ curl -fsSL https://fnm.vercel.app/install | bash
root@fnm:~$ source /root/.bashrc
root@fnm:~$ fnm install v18
```

### Setup nginx latest version

Please refer to the nginx [official documentation](https://nginx.org/en/linux_packages.html#Ubuntu) to <strong>get the latest version of nginx on Ubuntu</strong>, otherwise, your nginx may not work for blocklet server.

### Verify your environment

```javascript
root@fnm:~$ node --version
// v18.19.0, or above version
root@fnm:~$ nginx -version
// nginx version: nginx/1.24.0
```

### Install blocklet server

```javascript
root@fnm:~$ npm install -g @blocklet/cli
```

### Get your server up and running

```javascript
root@fnm:~$ blocklet server init -f
root@fnm:~$ blocklet server start
```

---

## Run as non-root user with Nginx

If you want to run your blocklet server as <strong>non-root (</strong><strong>recommended</strong><strong>)</strong>, refer to the following steps:

### Setup Node.js with fnm

Since fnm installs node.js on a per-user basis, if you have done this as root, you should do it again as `ubuntu`

```javascript
ubuntu@fnm:~$ curl -fsSL https://fnm.vercel.app/install | bash
ubuntu@fnm:~$ source /root/.bashrc
ubuntu@fnm:~$ fnm install v18
```

### Setup nginx latest version

Just like the root user instructions, you must complete this step as the root user.

### Setup permissions for node.js and nginx

If 80/443 ports are available for blocklet server, all access URLs are clean without annoying ports, however, non-root users on ubuntu can not listen on 80/443 ports by default, but you allow nginx to listen on 80/443 port with following commands:

```javascript
ubuntu@fnm:~$ sudo apt-get install libcap2-bin
ubuntu@fnm:~$ sudo setcap cap_net_bind_service=+ep /usr/sbin/nginx
```

### Verify your environment

```javascript
ubuntu@fnm:~$ node --version
// v18.19.0, or above version
ubuntu@fnm:~$ nginx -version
// nginx version: nginx/1.24.0
```

### Install blocklet server

```javascript
ubuntu@fnm:~$ npm install -g @blocklet/cli
```

### Get your server up and running

```javascript
ubuntu@fnm:~$ blocklet server init -f
ubuntu@fnm:~$ blocklet server start
```

---

## Run as non-root user without Nginx

It's recommended that you use nginx as the routing engine for blocklet server when running it for production purposes, however you can run blocklet-server as non-root user without nginx if you want to evaluate it.

### Setup Node.js with fnm

Since fnm installs node.js on a per-user basis, if you have done this as root, you should do it again as `ubuntu`

```javascript
ubuntu@fnm:~$ curl -fsSL https://fnm.vercel.app/install | bash
ubuntu@fnm:~$ source /root/.bashrc
ubuntu@fnm:~$ fnm install v18
```

### Setup permissions for node.js

If 80/443 ports are available for blocklet server, all access URLs are clean without annoying ports, however, non-root users on ubuntu can not listen on 80/443 ports by default, but you allow node.js to listen on 80/443 ports with following commands:

```javascript
ubuntu@fnm:~$ sudo apt-get install libcap2-bin
ubuntu@fnm:~$ sudo setcap cap_net_bind_service=+ep `which node`
```

### Verify your environment

```javascript
ubuntu@fnm:~$ node --version
// v18.19.0, or above version
```

### Install blocklet server

```javascript
ubuntu@fnm:~$ npm install -g @blocklet/cli
```

### Get your server up and running

```javascript
ubuntu@fnm:~$ blocklet server init -f
ubuntu@fnm:~$ blocklet server start
```

---

## Setup on Ubuntu + Nodesource

URL: https://www.arcblock.io/en/docs/blocklet-developer/setup-on-ubuntu-nodesource/

For how to get your server up and running on ubuntu with [nodesource](https://github.com/nodesource/distributions), please checkout the recording here: [https://asciinema.org/a/629699](https://asciinema.org/a/629699)

---

## The meaning of each input item in the release resource form

URL: https://www.arcblock.io/en/docs/blocklet-developer/the-meaning-of-each-input-item-in-the-release-resource-form/

The source drawing contains no extractable text; preserve its exported image when regenerating this page.

---

## Theming

URL: https://www.arcblock.io/en/docs/blocklet-developer/theming/

This comprehensive guide covers all aspects of the Theming functionality, from basic usage to advanced features and technical details.

![image.png](https://media.arcblock.io/lib/55/551c653ea41c77ca1bf66eecba3f5ee1.w1600.webp)

# Header Section

## Theme Management

![image.png](https://media.arcblock.io/lib/78/78f4060c756c2c3d82c77c0121ac441a.w1600.webp)

- <strong>Switch Themes</strong>: Quickly switch between different theme configurations
- <strong>Add Theme:</strong> Start with a fresh theme configuration
- <strong>Duplicate Theme</strong>: Make a copy of the current theme configuration
- <strong>Rename Theme</strong>: Change the name of your theme
- <strong>Delete Theme:</strong> Permanently remove this theme
- <strong>Save Theme</strong>: Save current theme settings with a single click

## <strong>Undo/Redo System</strong>

![image.png](https://media.arcblock.io/lib/7d/7d22596877c89c72ad9b4fb8591b5c50.w1600.webp)

- <strong>Undo Button</strong>: Revert the last change made to the theme `Ctrl/Cmd + Z`
- <strong>Redo Button</strong>: Restore a previously undone change `Ctrl/Cmd + Shift + Y`
- <strong>History Tracking</strong>: Keeps a record of your most recent 50 changes

## <strong>Random Theme Generator</strong>

![image.png](https://media.arcblock.io/lib/d9/d90dcc9774bc58027dc5b2515f5cb7a7.w1600.webp)

- <strong>Shuffle Button</strong>: Generate a completely new theme with random colors and fonts
- <strong>Smart Randomization</strong>: Ensures generated themes maintain good contrast and readability

## <strong>Reset Theme</strong>

![image.png](https://media.arcblock.io/lib/43/430410c3ff0f473cc2155969917dcd35.w1600.webp)

- <strong>Reset Button</strong>: Return to default theme settings
- <strong>Confirmation Dialog</strong>: Prevents accidental resets
- <strong>Selective Reset</strong>: Reset only the current theme without affecting others

# Colors Section

## Light/Dark Mode Toggle

![image.png](https://media.arcblock.io/lib/e3/e3e1fa85f0a10109c54b3f5d06a8eda8.w1600.webp)

- <strong>Mode Switching</strong>: Toggle between light and dark themes
- <strong>Mode Disabling</strong>: Option to disable specific modes based on concept preferences
- <strong>Visual Indicators</strong>: Clear indication of which mode is active or disabled

## <strong>Color Palette Management</strong>

![image.png](https://media.arcblock.io/lib/c9/c957f3e5a163613627fc9a9c773a7f15.w1600.webp)

- <strong>Primary Colors</strong>: Main brand colors for buttons, links, and highlights
- <strong>Secondary Colors</strong>: Complementary colors for surfaces, accents, and UI elements
- <strong>Neutral Colors</strong>: Grays and whites for backgrounds, borders, and typography
- <strong>Semantic Colors</strong>: Status colors like success, warning, error, and info for messages and states

## <strong>Random Color Generation</strong>

![image.png](https://media.arcblock.io/lib/04/04cc3f1fe314472653507c0ff8f22643.w1600.webp)

- <strong>Smart Shuffle</strong>: Generates harmonious color combinations
- <strong>Contrast Preservation</strong>: Ensures generated colors maintain accessibility standards
- <strong>Brand Consistency</strong>: Option to lock specific brand colors during shuffling

# Typography Section

## F<strong>ont Family Selection</strong>

![image.png](https://media.arcblock.io/lib/d8/d8ac6194ce7a2534c58dde73c935dd9a.w1600.webp)

- <strong>Heading Fonts</strong>: Font selection for all heading elements (H1, H2, H3, etc.)
- <strong>Body Fonts</strong>: Font selection for body text and paragraphs
- <strong>Google Fonts Integration</strong>: Access to thousands of Google Fonts
- <strong>Font Preview</strong>: Live preview of how fonts will appear
- <strong>Font Categories</strong>: Organized by style (serif, sans-serif, display, etc.)

## <strong>Font Size Controls</strong>

![image.png](https://media.arcblock.io/lib/97/97b665abbef444ac5aa588777918af6c.w1600.webp)

- <strong>Global Font Size Scale</strong>: Define the base font size to control the overall typography scale
- <strong>Custom Sizes</strong>: Customize font sizes for individual variants in the theme

## <strong>Random Font Generation</strong>

![image.png](https://media.arcblock.io/lib/82/8233079fb9ea254c891bb702b30d0afe.w1600.webp)

- <strong>Font Pairing</strong>: Smart selection of complementary font combinations
- <strong>Style Matching</strong>: Ensures fonts match the overall design aesthetic
- <strong>Performance Consideration</strong>: Prioritizes fast-loading fonts

# Styles Section

## <strong>Border Radius Control</strong>

![image.png](https://media.arcblock.io/lib/e2/e2cba89d890f2f5e969c568d3c2e1bd5.w1600.webp)

- <strong>Global Border Radius</strong>: Set the default corner radius for components (`shape.borderRadius`)

# Preview Section

## <strong>Real-time Preview</strong>

![image.png](https://media.arcblock.io/lib/6b/6b6750b5aa443e35848258a2d822130b.w1600.webp)

- <strong>Blocklet Integration</strong>: Real-time preview of actual applications
- <strong>Instant Updates</strong>: All changes reflected immediately in the preview

## <strong>Responsive Preview</strong>

![image.png](https://media.arcblock.io/lib/ff/ff3d8770addf328e12c81c87ef2355c4.w1600.webp)

- <strong>Screen Size Simulation</strong>: Test theme on different device sizes
-
  - <strong>Mobile Preview</strong>: Optimized mobile layout testing
  - <strong>Tablet Preview</strong>: Tablet-specific layout verification
  - <strong>Desktop Preview</strong>: Full desktop layout testing

---

## How to transfer a Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/transfer-blocklet/

If you need to change the owner of a Blocklet, you need to transfer the Blocklet to achieve this. This article will introduce how to transfer a Blocklet.

<strong>Necessary condition</strong>

Only the owner of the Blocklet has the permission to transfer.

<strong>Effects on the application after transferring Blocklet ownership</strong>

- Access permission: The <strong>original owner</strong> will lose owner permission, but there may be other access permissions depending on the actual permission settings.
- Application Data: User data will be owned entirely by the <strong>new owner</strong>.
- Need to reconnect DID Spaces: Because the <strong>original owner</strong> no longer owns the data; which also means the original data cannot be recovered.
- On-chain asset ownership: After the transfer, a migration will be made to the on-chain account, so the on-chain assets will also be completely transferred to the <strong>new owner</strong>.

### 1. Generate transfer links

1. Log in to Blocklet Dashboard.
2. Open the "Dashboard->Configuratin" page.
3. Click the "Transfer ownership" button in the "Danger Zone" area.
4. Verify the ownership of the Blocklet using the DID wallet.

![image.png](https://media.arcblock.io/lib/3e/3e94bc4b8a58dba111670c92d8e62280.w1600.webp)

![image.png](https://media.arcblock.io/lib/fb/fbada437d3381928eb8704ff5ba9c685.w1600.webp)

### 2. Send the link to the new owner

- The expiration time of the transfer link is 24 hours.
- Any user can receive applications through the DID wallet, so be careful not to leak the transfer link to others

### 3. The recipient becomes the owner using the DID wallet

- The recipient needs to use the DID wallet to accept the transfer.
- The application will automatically restart once the transfer is successful.

![image.png](https://media.arcblock.io/lib/d6/d60e7ff7c7b34177b23d08a7b6f5c851.w1600.webp)

### 4. Transfer Subscription [Optional]

If the transferred Blocklet runs in an on-demand space, the subscription transfer is also required. For more details, refer to:
[Transfer application's subscription](/en/docs/launcher/transfer-subscription/)

---

## Configure OAuth Server using Grafana.

URL: https://www.arcblock.io/en/docs/blocklet-developer/TsU61DtP_aw-JWemvwpDhGpc/

## Requirements

- Have access to the OAuth Server Blocklet

- Have administrative privileges for any third-party applications that require integration (e.g., Grafana).

- Understand the basic OAuth 2.0 flow

## Register an OAuth App

- Log in to your OAuth server's management console (Blocklet Service).

- Create a new OAuth App (DID Connect => OAuth Apps)

- Fill in the required information, including the application name and callback URL (redirect_uri).

- Save to obtain the Client ID and Client Secret
- <strong>Keep your Client Secret secure and confidential.</strong>

![image.png](https://media.arcblock.io/lib/da/dabbcf38b96a28978103145fe65fa295.w1600.webp)

![image.png](https://media.arcblock.io/lib/8a/8a65100eb798ef047e27fd9fc0204619.w1600.webp)

## Configure an OAuth Client (Grafana)

### 1. Basic Setup

- Open the Grafana administration backend and navigate to **Authentication** > **Generic OAuth**.
- Enter Display name, Client ID, and Client Secret

![image.png](https://media.arcblock.io/lib/c1/c19adec46a8b2d01cdc9525815eb3daa.w1600.webp)

### 2. OpenID Connect Discovery

- Enter the OpenID Connect Discovery URL (typically `https://your-oauth-server/.well-known/openid-configuration`).

![image.png](https://media.arcblock.io/lib/9d/9d8ab2949e65f8f4ec6ee4cddf164ecd.w1600.webp)

- Or manually enter the Auth URL, Token URL, and API URL

### 3. Authorization and Token Configuration

- Configure Scopes (currently, only `profile:read` is required)
- Enable `Extra security measures` and select the `Use PKCE` option.
- Save

### 4. After signing out, you can sign in using the OAuth Server.

![image.png](https://media.arcblock.io/lib/e0/e09e27b11646d385e2c34d4ac4d0ff95.w1600.webp)

### 5. Frequently Asked Questions and Troubleshooting

- An incorrect callback address resulted in a 400/401 error.

- Incorrect Scope configuration prevents user information retrieval.

- Responding to a Client Secret Leak

### 6. Appendix: Example Configuration

- Provide a complete Grafana configuration screenshot

![image.png](https://media.arcblock.io/lib/34/34cb33d6772d3b087f9823f2a07825a0.w1600.webp)

![image.png](https://media.arcblock.io/lib/7c/7cbf181ba1f65d619c57d27ee9ebe6bd.w1600.webp)

![image.png](https://media.arcblock.io/lib/1e/1e215ffba70593770ee841e4f046aaa9.w1600.webp)

![image.png](https://media.arcblock.io/lib/1d/1db1ad7142957f572675f1a802694166.w1600.webp)

![image.png](https://media.arcblock.io/lib/89/897eecca09f63c5763d5734a17a7b387.w1600.webp)

---

## Understanding Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-developer/understanding-blocklet/

The core concepts in the Blocklet ecosystem and the relationships between the concepts are shown in the following diagram.

![](https://media.arcblock.io/docs/understanding-blocklet/images/blocklet-concepts.w1600.webp)

## What is Blocklet?

- Blocklets are the basic unit of application development, delivery, and operation
- Blocklets follow the same [protocol](/en/docs/blocklet-developer/blockletyml/), enjoy the same services, and when combined together can perform very powerful functions
- Blocklets are combinable, in a way very similar to Lego blocks
- Blocklets are uniquely identified by a Blocklet DID, and the DIDs in each [Blocklet Store](https://store.blocklet.dev) are non-repeatable

## What is Blocklet Component?

- A Blocklet Component is specifically a Blocklet that can be used in combination, or not, as declared in [blocklet.yml](/en/docs/blocklet-developer/blockletyml/#capabilities)
- Blocklet Components can usually be used both independently and in combination, and can behave differently in both modes
- Blocklet Components can [contain other Blocklet Components](/en/docs/blocklet-developer/blockletyml/#components), and this containment relationship can be nested, just as a codebase published in an NPM can depend on other codebases published on the NPM. However, from a performance point of view, there is a limit to the depth of nesting of Blocklet Components.

## What is Blocklet Server?

- Blocklet Server is the software that provides the complete runtime environment, basic services, and management functions for Blocklet
- The data generated when Blocklet Server is running belongs to the owner of Blocklet Server only.
- Blocklet Server is uniquely identified by an immutable DID generated at the time of Blocklet Server creation and displayed in the Blocklet Server Console
- Anyone can run their own Blocklet Server on their own computer without license and without payment

## What is Blocklet Bundle?

- A Blocklet Bundle is a package built using [blocklet bundle](/en/docs/blocklet-developer/blocklet-cli/#bundle) that can be consumed by Blocklet Server
- Blocklet Bundles are usually uploaded and hosted by developers in the [Blocklet Store](https://store.blocklet.dev), and can be hosted on any accessible network.
- A Blocklet Bundle typically contains the following two files.

```javascript
.blocklet/release
├── blocklet.json
└── static-demo-blocklet-1.4.0.tgz
```

- `blocklet.json` Blocklet description file calculated from [blocklet.yml](/en/docs/blocklet-developer/blockletyml/)
- `{name}-{version}.tgz` contains the various files needed for the blocklet runtime, including the source code after the build, external dependencies
- Theoretically, the two files could be hosted in different places, as long as `blocklet.json` contains the correct zip address

## What is Blocklet App?

- A Blocklet App is an entity that is installed, runs in the Blocklet Server, and can provide services to the public.
- The service behind a Blocklet App can consist of a single or multiple Blocklet Instances
- The unique identifier of a Blocklet App is the appId, which can be obtained from [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/#environment) and [blocklet.js](/en/docs/blocklet-developer/blockletjs/)
- The same Blocklet Bundle running in a different Blocklet Server belongs to a different Blocklet App
- The same Blocklet Bundle running in the same Blocklet Server also belongs to a different Blocklet App
- A Blocklet App can have any number of users depending on the use case
- A Blocklet App can have only one blocklet owner, but can have multiple administrators

## What is Blocklet Instance?

- Each component of a running Blocklet App is a Blocklet Instance, which is like an instance generated from a class
- Each Blocklet Instance runs in its own separate process, with its own process identity, environment variables, and data directory

---

## Understanding Blocklet Payment

URL: https://www.arcblock.io/en/docs/blocklet-developer/understanding-blocklet-payment/

> [!NOTE]
> this page is a draft and need to be updated

---

## User and Passport

URL: https://www.arcblock.io/en/docs/blocklet-developer/user-and-passport/

Blocklet Auth Service provides DID-based authentication and Passport-based access control for Blocklets.

Developers can obtain authentication and access control capabilities by configuration or API, without having to implement them from scratch.

- Get user identity
- Get user permissions
- Set who can access
- Block unauthenticated requests
- Block unauthorised requests

You can experience the above functions through [Auth Demo](https://developer.blocklet.io/samples/auth-demo)

## Configure Blocklet Auth Service

Configured in the Web Interface declared in `blocklet.yml`

```javascript
# blocklet.yml

interfaces:
  - type: web
    services:
      - name: auth # Auth service for this access interface
        config:
          whoCanAccess: all # Who can access (can be dynamically modified after the app is installed)
          blockUnauthenticated: false # Whether to automatically intercept unauthenticated requests and jump to the login page (default: false)
          blockUnauthorized: false # Whether to automatically block unauthorized requests (default: false)
          allowSwitchProfile: true # Whether to support switching profiles (default: true)
          profileFields: # Information to provide when logging in
            - fullName
            - email
            - avatar
          ignoreUrls: [] # Which interfaces allow any request to access
    # The following properties has nothing to do with auth
    protocol: http
    name: publicUrl
    port: BLOCKLET_PORT
    path: /
    prefix: '*'
```

## Login

Users can login to Blocklet without registration

### Add the login component to the page

```js
import React from 'react';
import { ThemeProvider, createTheme } from '@arcblock/ux/lib/Theme';
import { createAuthServiceSessionContext } from '@arcblock/did-connect/lib/Session';
import Header from '@blocklet/ui-react/lib/Header';

const { SessionProvider } = createAuthServiceSessionContext();

const theme = createTheme();
export default function App() {
  return (
    <ThemeProvider theme={theme}>
      <SessionProvider>
        <Header />
      </SessionProvider>
    </ThemeProvider>
  );
}
```

More: [Blocklet UI](/en/docs/blocklet-developer/blocklet-ui/)

### Use default login page

When `blockUnauthenticated` is set to `true`, unauthenticated requests will be automatically blocked to the default login page

### View Users

After a user logs into the Blocklet, Blocklet Auth Service records the user's identity.

Developers can query user information through Blocklet SDK

- [getUser()](/en/docs/blocklet-developer/blocklet-sdk/)
- [getUsers()](/en/docs/blocklet-developer/blocklet-sdk/)
- [getOwner()](/en/docs/blocklet-developer/blocklet-sdk/)

## User Permissions and Passports

Blocklet Auth Service uses role-based access control [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control)

Different from the traditional permission control system, the user's role is not stored in the server, but in the user's own wallet.

The way Blocklet grants user roles is by issuing a passport to the user, which records the user's role. The user provides the corresponding passport when logging in to obtain the right to operate the resource.

Developers can create roles and manage their permissions through [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/).

Creating a role creates a passport.

Blocklet consumers can issue and manage passports for users in the Blocklet console.

Blocklet has 4 default passports (developer does not need to create via API to use)

- `owner`: Only Blocklet owners will get this passport. The Blocklet owner is the one who installed and started the Blocklet for the first time.
- `admin`: It is recommended to issue this passport to the administrator of the Blocklet
- `member`: It is recommended to issue this passport to internal members of the Blocklet
- `guest`: Usually no passport is required for the guest, this passport can be issued if required

## Access control

- A request goes through the Blocklet Service before reaching the blocklet
- Developers can declare the default configuration in Blocklet Service in blocklet.yml, and users can also modify the default configuration in Blocklet Dashboard after installing the blocklet
- Developers can also implement access control in code
- If a blocklet contains multiple components, access control can be configured for each component separately

![](https://media.arcblock.io/docs/user-and-passport/images/access-control.svg)

### Access Control Type

- Public Access
- Non-public Access
- Accessible after login
- Invited people (internal members) can access
- Accessible with specefic passports
- Only the owner can access

### Set access control in Blocklet Service

| Permissions  | Developers configure in blocklet.yml  | Whether users can configure  |
|---|---|---|
| Public Access  | set `whoCanAccess` to `all`  | Yes  |
| Accessible after login  | Set `blockUnauthenticated` to `true`  | No  |
| Invited people (internal members) can access  | set `whoCanAccess` to `invited`  | Yes  |
| Accessible with specefic passports  | /   | Yes  |
| Only the owner can access | set whoCanAccess to owner | Yes |

### Set specified URLs to public access

If the Blocklet is set to private access, but the developer wants to set some URLs to public access, he can set it in `blocklet.yml` via `ignoreUrls`:

```javascript
ignoreUrls:
  - /api/** # All urls under the /api path are public
  - /public/** # All urls under the /public path are public
  - /path/to # # Set the specified url for public
```

<strong>Set public access for DID Connect URLs</strong>

If there is a DID Connect API in the Blocklet server, the developer needs to set the DID Connect API to public access. Because the wallet does not carry authentication information when communicating with Blocklet.

```javascript
ignoreUrls:
  - /api/did/** # If the DID Connect API in the Blocklet is mounted under /api/did
```

### Implement access control in code

Developers can use the middleware provided in the Blocklet SDK to implement access control in code, see [Middleware](/en/docs/blocklet-developer/blocklet-sdk/) for details

---

## Using Blocklet Logger

URL: https://www.arcblock.io/en/docs/blocklet-developer/using-blocklet-logger/

You can use `@blocklet/logger` to manage logs at your blocklet runtime, here are the steps:

### Add Dependency

```javascript
yarn add @blocklet/logger
```

### Setup Access Logging

```javascript
const logger = require('@blocklet/logger');
const express = require('express');

const server = express();

logger.setupAccessLogger(server); // you are all set
```

### Setup Error Logging

```javascript
const logger = require('@blocklet/logger')('app'); // chagne your label here

try {

// do something
} catch (err) {

logger.error('failed to process request', error);
}
```

### Setup Other Logging

```javascript
const logger = require('@blocklet/logger')('app'); // chagne your label here

logger.info('failed to process request', { user });
```

### Tune Log Level

By default, `@blocklet/logger` only print logs at `info` level, but you can change this by setting `LOG_LEVEL` environment at application level (remember to restart your blocklet)

---

## Using Blocklet Preferences

URL: https://www.arcblock.io/en/docs/blocklet-developer/using-blocklet-preferences/

## What are Blocklet Preferences?

Serious developers should make their Blocklets more flexible and adaptable with configurable items that can be customized. Blocklet preferences are the end-to-end capabilities provided by the Blocklet Toolkit to easily define and store preference structures and to easily modify, save, and load preference data.

The basic workflow of Blocklet preferences is

- Define: Information about which behaviors can be customized at Blocklet runtime and how to do so is stored in the `blocklet.prefs.json` file
- Design: `blocklet.prefs.json` file can be modified visually in Blocklet Studio
- Bundle: `blocklet.prefs.json` will be automatically included in the Blocklet Bundle
- Edit/Save: `blocklet.prefs.json` will be loaded into the Server with the Blocklet installation for easy modification and saving by the user
- Load: User preferences will be available on both the front-end and back-end of the Blocklet runtime, see [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/) and [blocklet.js](/en/docs/blocklet-developer/blockletjs/) for details

## How to use Blocklet preferences?

### Designing preference forms with Blocklet Studio

In development mode, switch to your Blocklet root directory and execute: `blocklet dev studio`, which will open the following screen.

![](https://media.arcblock.io/docs/using-blocklet-preferences/images/studio-home.w1600.webp)

Click on `Preference Builder`, and you will see the following interface.

![](https://media.arcblock.io/docs/using-blocklet-preferences/images/studio-prefs.w1600.webp)

If you are opening it for the first time, the form you see may be empty. Just drag and drop the input controls from the left side to the form design area according to your needs. After designing the form, click Save in the upper right corner and it will be written to or update the `blocklet.prefs.json` file on your disk.

> [!NOTE]
> Please do not modify blocklet.prefs.json manually unless you know what you are doing.

### Bundle and ship Blocklet

`blocklet.prefs.json` will be included automatically when your blocklet is packaged, so you don't need to do anything extra.

### Installing and configuring Blocklet preferences

Once your blocklet is installed into the Server, you can cut to the blocklet configuration page and find your blocklet to adjust the preferences as follows.

![](https://media.arcblock.io/docs/using-blocklet-preferences/images/prefs-server.w1600.webp)

### Using Blocklet Preference Data

If your application is a full-stack application, you can load the use of blocklet preferences on both the front-end and the back-end, as follows

#### Using Blocklet Preferences on the front-end

You can use `window.blocklet.preferences` directly in the browser environment to get all the preferences, see [blocklet.js](/en/docs/blocklet-developer/blockletjs/).

![](https://media.arcblock.io/docs/using-blocklet-preferences/images/prefs-client.w1600.webp)

#### Using Blocklet preferences on the backend

You can use the `env` module of `@blocklet/sdk` directly in the Node.js environment to get all the preferences, see [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/).

## Blocklet Preferences FAQ

### What are the preferences for a modular Blocklet?

Preferences for all components in a composition blocklet are managed independently, as follows.

![](https://media.arcblock.io/docs/using-blocklet-preferences/images/prefs-compositive.w1600.webp)

---

## Run Blocklet using Docker container

URL: https://www.arcblock.io/en/docs/blocklet-developer/using-docker-run-blocklet/

Blocklet Server enables Blocklets to run in Docker containers, thereby providing better isolation for each.

### Prerequisites

1. Ensure Docker is installed on the system.
2.
  1. Install Docker on Linux.
  2. Mac requires Docker Desktop or OrbStack ([https://orbstack.dev/](https://orbstack.dev/))
  3. Install Docker on Windows using WSL
3. Ensure the current user has permission to execute Docker commands.
4. Ensure the Docker daemon has the necessary permissions to manage the Blocklet Server data directory.

### Enable Docker Container run Blocklet

Once the requirements are met, enable the service on the server's management page.

- <strong>Run Blocklets in Containers:</strong> Run each Blocklet in a Docker container.
- <strong>Container Network Isolation</strong>: Multiple Blocklets for the same application reside within the same Docker network. Enable this option to connect multiple Docker Blocklet networks.

![image.png](https://media.arcblock.io/lib/c6/c6f9a9cdc077aacd7faa24fbef1e3ac0.w1600.webp)

---

## Can not access server/blocklet with DID Domain?

URL: https://www.arcblock.io/en/docs/blocklet-developer/Wa0JbgBpWWYhSWeg8380kq-k/

If you can not access your blocklet or server with DID Domain (in the following screenshot)

![image.png](https://media.arcblock.io/lib/39/39dee8f932adc808c84d53a1de39ce6c.w1600.webp)

![image.png](https://media.arcblock.io/lib/cb/cbca2472adb20e44918154dcf8dd1dbb.w1600.webp)

A few things to check:

#### Ensure no global proxy is turned on in your system

Turn off all global proxy and try restart your server with

- `blocklet server stop -f`
- `blocklet server start`

#### Ensure your DNS settings are correct with `dig`

If everything is fine, your dig result of DID Domain would be like:

![image.png](https://media.arcblock.io/lib/b2/b26d907ced307e25cc0865a3cf63aed1.w1600.webp)

If something went wrong in your network settings, you will not get correct DNS resolution for DID Domain.

Try update your DNS Server settings or Router Settings or Switching Network.

---

## WebHooks

URL: https://www.arcblock.io/en/docs/blocklet-developer/webhook/

## What are Webhooks?

Within the ArcBlock <strong>Blocklet</strong> ecosystem, <strong>Webhooks</strong> provide a powerful mechanism for your Blocklet to react to <strong>platform events</strong>.

Imagine constantly polling a Blocklet for new data or events, much like repeatedly refreshing your inbox. Webhooks offer a different approach: they act as smart notifications. When a specific event occurs, the <strong>Blocklet</strong> pushes event data to a pre-configured URL, similar to receiving instant push notifications for new emails. This method is both efficient and timely.

Webhooks offer extensive integration capabilities, enabling your Blocklet to connect seamlessly with other services for automated workflows.

- When the <strong>Discuss Kit Blocklet</strong> publishes new content, your Blocklet can immediately receive this update.
- When the <strong>Vote Blocklet</strong> completes voting, your Blocklet can receive real-time updates on vote creation.
- You can even <strong>define custom events</strong>, enabling your Blocklet to publish notifications.

When creating a webhook, simply specify a <strong>URL</strong> and subscribe to the events you wish to monitor on the designated Blocklet.  The Blocklet Service will then send an HTTP request containing the relevant event data to your specified URL whenever those events are triggered.  If your server is configured to listen for webhook requests at that URL, it can act immediately upon receiving them.

## Registering an Event

In a Blocklet, you don't typically register webhook events directly within `blocklet.yml`.  Instead, `blocklet.yml` primarily defines the Blocklet's metadata, configuration, and capabilities. The Blocklet Service uses this information to discover events the Blocklet needs to listen for.  See the [Event Bus Service (Beta)](/en/docs/blocklet-developer/vOR4m5WRJpX2khDwZWQfMCJn/) documentation for details.

To enable your Blocklet to send events to a webhook, you need to:

- <strong>Understand and configure the Event Bus Service:</strong> This is a crucial step. Refer to [https://www.arcblock.io/content/docs/blocklet-developer/en/event-bus-service](/en/docs/blocklet-developer/event-bus-service/) to understand its functionality and configuration. Webhooks can only discover events that are correctly published to the event bus.
- <strong>Creating Webhooks in Blocklet Services:</strong>
-
  - Access your Blocklet Service dashboard.
  - Navigate to the Webhook configuration section.
  - Here, you will be able to discover the available events exposed by the Blocklet Service via the Event Bus (e.g., `vote.published`, `discuss.published`, or your custom events).
  - Select the events you want to capture.
  - Specify the URL to which the <strong>webhook will send data</strong> when these events are triggered.

## Example Workflow

The following simplified example demonstrates how to configure a webhook to send a Slack notification when a `vote.published` event occurs:

- <strong>Configure the Event Hub:</strong>
-
  - Ensure your voting Blocklet is configured correctly and publishes `vote.published` events to the Event Bus Service.
  - For setup instructions, please see [https://www.arcblock.io/content/docs/blocklet-developer/en/event-bus-service](/en/docs/blocklet-developer/event-bus-service/).
- <strong>Creating a Webhook:</strong>
-
  - In the Blocklet Service webhook management interface, click "Create New Webhook".
  - In the event list, locate and select the event you want to capture, for example, `vote.published`.
  - In the "URL" field, enter your Slack Incoming Webhook URL (the channel-specific webhook address Slack provides) or any other webhook URL.

![image.png](https://media.arcblock.io/lib/82/820ac33cfc3c463f6799277cc1bc4dc8.w1600.webp)

- <strong>Configuration complete. Real-time notifications are now active.</strong>
-
  - After creation, when a new vote is published in your voting Blocklet (that is, when the `vote.published` event is triggered), the Blocklet Service automatically sends an HTTP request to your configured Slack URL.
  - Slack will receive the data from this request and, based on your Slack Webhook configuration, display a notification in the designated channel.

![image.png](https://media.arcblock.io/lib/36/36b75846863646aff94a2de8552089e1.w1600.webp)

---

## Welcome

URL: https://www.arcblock.io/en/docs/blocklet-developer/welcome/

## Welcome to Blocklet the Web 3.0 Application Platform

Blocklet is a [platform](/en/docs/blocklet-developer/platform-overview/) that provides a toolkit which enables developers to build composable and compelling Web 3.0 applications efficiently. The toolkit covers the end-to-end workflow for application building process, such as bootstrapping, developing, distribution and deployment.

The complete ArcBlock infrastructure and apps are built and served by the blocklet platform, including the documentation you are reading now. So, what are you waiting for? <strong>Let's start building blocklets for fun and profit today!</strong>

<strong>Getting Started</strong>
Environment setup and get your first blocklet project up and running within minutes

- [Setup Node.js](/en/docs/blocklet-developer/setup-nodejs/)
- [Setup DID Wallet](/en/docs/blocklet-developer/setup-did-wallet/)
- [Setup Blocklet CLI](/en/docs/blocklet-developer/install-blocklet-cli/)
- [Create your first blocklet](/en/docs/blocklet-developer/create-your-first-blocklet/)
- [Frequently asked questions](/en/docs/blocklet-developer/frequently-asked-questions/)

<strong>Conceptual Guides</strong>
Big-picture explanations of higher-level blocklet concepts. Most useful for building understanding of a particular topic.

- [Platform overview](/en/docs/blocklet-developer/platform-overview/)
- [Core blocklet concepts](/en/docs/blocklet-developer/understanding-blocklet/)
- [Blocklet lifecycle](/en/docs/blocklet-developer/blocklet-lifecycle/)
- [Blocklet composition](/en/docs/blocklet-developer/blocklet-composition/) and [payment](/en/docs/blocklet-developer/understanding-blocklet-payment/)
- [Blocklet server architecture](/en/docs/blocklet-developer/blocklet-server-architecture/)
- [Blocklet routing layer](/en/docs/blocklet-developer/blocklet-server-routing/) and [access control model](/en/docs/blocklet-developer/access-control/)

<strong>How To Guides</strong>
Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done.

- [Create](/en/docs/blocklet-developer/create-blocklet/) and [develop](/en/docs/blocklet-developer/develop-blocklet/) your blocklet
- [Setup and use blocklet preferences](/en/docs/blocklet-developer/using-blocklet-preferences/)
- [Manage users](/en/docs/blocklet-developer/user-and-passport/) and [talk with DID Wallet](/en/docs/blocklet-developer/communicate-with-did-wallet/)
- [Create component](/en/docs/blocklet-developer/create-blocklet/) and [compose blocklets together](/en/docs/blocklet-developer/create-composite-blocklet/)
- [Bundle](/en/docs/blocklet-developer/bundle-your-blocklet/) and [deploy](/en/docs/blocklet-developer/deploy-blocklet-directly-to-the-server/) your blocklet
- [Publish](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/) your blocklet for fun and [profit](/en/docs/blocklet-developer/build-blocklet-for-profit/)
- Put blocklet storage [locally](/en/docs/blocklet-developer/blocklet-storage/) or [on blockchain](/en/docs/blocklet-developer/readwrite-blockchain-in-blocklet/)

<strong>Reference Guides</strong>
Nitty-gritty technical descriptions of how blocklet works. Most useful when you need detailed information about APIs of components in the blocklet toolkit.

- [blocklet.yml](/en/docs/blocklet-developer/blockletyml/) and [blocklet.js](/en/docs/blocklet-developer/blockletjs/)
- [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/)
- [Blocklet Service](/en/docs/blocklet-developer/blocklet-service/)
- [Blocklet UI](/en/docs/blocklet-developer/blocklet-ui/)
- [Blocklet CLI](/en/docs/blocklet-developer/blocklet-cli/) and [Server CLI](/en/docs/blocklet-developer/blocklet-server-cli/)
- [Automate with Blocklet Actions](/en/docs/blocklet-developer/blocklet-actions/)
- [Security](/en/docs/blocklet-developer/security/), [performance](/en/docs/blocklet-developer/performance/) and [limitations](/en/docs/blocklet-developer/known-issues-or-limitations/)

## How to get help?

Having trouble? We’d like to help!

- Try the [FAQ](/en/docs/blocklet-developer/frequently-asked-questions/) – it’s got answers to many common questions.
- Looking for specific information? Try the search box with your keywords.
- Found something missing? or found a typo? Click "Submit Feedback" on each page footer to create issues on GitHub.

---

## When stuck in maintenance mode?

URL: https://www.arcblock.io/en/docs/blocklet-developer/when-stuck-in-maintenance-mode/

Blocklet server supports several maintenance operations directly from the server dashboard:

- upgrading itself to a new version, either production or beta release
- restarting the server if the server processes consumes too much resources such as memory

Due to the current distribution method, we are using npm, some exceptions may happen when doing an upgrade from the server dashboard.

If you are stuck in maintenance mode, here is a fallback way to escape and recover your server:

```javascript
npm install -g @blocklet/cli@beta

// please use version v1.16.21-beta-445a8baa and above
blocklet server cleanup --target maintenance-status

// cleanup the maintenance status in server state db
blocklet server start
```

---

## When stuck on a blank screen?

URL: https://www.arcblock.io/en/docs/blocklet-developer/when-stuck-on-a-blank-screen/

If your website shows a blank screen and refreshing and clearing cache does not help, please consider the following steps to recover:

### Step1: Open your blocklet dashboard

To open your blocklet dashboard if you are stuck on a blank screen, replace anything after the domain with `/.well-known/service/admin`

![image.png](https://media.arcblock.io/lib/41/415812bccb68d7456612a66c6a70112e.w1600.webp)

Make sure there are no duplicate slashes in the URL, then hit enter, and login as <strong>owner</strong> or <strong>admin</strong>

### <strong>Step2: Clear your blocklet cache</strong>

Click the `Configuration`  tab, scroll to the bottom until you see the `Danger Zone`, click `clear cache` and then confirm.

![](https://team.arcblock.io/comment/uploads/1693004520207-rZi9VRsz6lLafEtA_365VxMk.png)

### Step3: Verify by refresh your page

Clearing the cache will help in most of cases, if you have cleared your blocklet cache, but are still stuck in a blank screen, please contact us at [https://community.arcblock.io](https://community.arcblock.io)

---

## Why can't see the uploaded Blocklet on the Blocklet Store?

URL: https://www.arcblock.io/en/docs/blocklet-developer/why-cant-see-blocklet-in-store/

When a user successfully uploads a feature to the Store (as shown below), we need to publish the Blocklet in the Store in order to see our Blocklet on the Blocklet Store.

![image.png](https://media.arcblock.io/lib/1f/1f4562825accbee05d3b238d5115dab8.w1600.webp)

When uploaded, click on Store to view, as shown in the figure:

![image.png](https://media.arcblock.io/lib/90/90cb53d0d04525400395ce58b6604d90.w1600.webp)

Then click on release in the Blocklet Store as shown in the figure below:

![Untitled.png](https://media.arcblock.io/lib/44/442b29e164260173c5f441d41c7c7a81.w1600.webp)

![image.png](https://media.arcblock.io/lib/b4/b432f73956f08567e3d72ee97964ef5a.w1600.webp)

### At this time, you can view the Blocklet in the Blocklet Store.

![image.png](https://media.arcblock.io/lib/9b/9b0575c23f0e6d1ee4f3c45e7607ab97.w1600.webp)

> If the Blocklet has been released and is not visible in the Blocklet Store, please make sure that the Blocklet is a Resource-based Blocklet. Please refer to the document below for more details:

[Why can't see the released Resource-based Blocklet be seen in the Blocklet Store?](/en/docs/blocklet-developer/hB5VWLfg9VnbWsL1JGLuLUfW/)

---

## Setup with Docker

URL: https://www.arcblock.io/en/docs/blocklet-developer/WV6iDyriFb4YWGpJnFU3lkIS/

## Starting a server with Docker

### Step 1: Pull the mirror

```javascript
$ docker pull arcblock/blocklet-server:latest
```

### Step 2: Start the container

```javascript
$ docker run --name test-server -d -p 80:80 -p 443:443 -v /tmp/test:/data arcblock/blocklet-server
```

Parameter explanation:

- `--name` Specify the name of the container.
- `-d` Let the container run in the background.
- `-p` Specify the ports exposed by the container. Blocklet Server will run on ports 80 and 443, so the container needs to be exposed to these two ports.
- `-v` Mount the disk directory. data in Blocklet Server will be stored in the `/data` directory, to prevent data loss, so the best practice is to mount the data directory in Docker to a directory on the host.

If everything is fine, Blocklet Server will start successfully within a minute, and you can use the `docker logs {container name}` command to view the startup information in the container during the startup process:

```javascript
$ docker logs test-server
                 Powered By
     _             ____  _            _
    / \   _ __ ___| __ )| | ___   ___| | __
   / _ \ | '__/ __|  _ \| |/ _ \ / __| |/ /
  / ___ \| | | (__| |_) | | (_) | (__|   <
 /_/   \_\_|  \___|____/|_|\___/ \___|_|\_\
            Blocklet CLI v1.8.22
blocklet server v1.8.22
Blocklet Server instance already exists in /data, now starting...
✔ Blocklet Server DB Proxy ready on port 40404
ℹ Node DID from config zNKZ5v8AqMfNrZoTrdComvjZdGKkjrDqALPx
ℹ Node config from /data/.blocklet-server/config.yml
✔ Blocklet Server Event Hub ready on port 40407
✔ Blocklet Server Updater ready on port 40405
✔ Fetch wildcard certificates successfully
- Starting Blocklet Service...
✔ Starting Blocklet Service... Done in 21.351s
- Starting Blocklet Server Daemon...
✔ Starting Blocklet Server Daemon... Done in 29.49s
```

### Step 3: Access the server via IP Echo address

IP Echo is a DNS that maps IPs in URLs, and the domain name served by IP Echo is `ip.abtnet.io`. For example, [`https://192-168-1-1.ip.abtnet.io`](https://192-168-1-1.ip.abtnet.io) DNS resolves the IP to `192.168.1.1`.

The server can be accessed through the IP Echo address after the server is successfully started. For example, if the local IP is `192.168.0.10`, then the IP Echo address is [`https://192-168-0-10.ip.abtnet.io/`](https://192-168-0-10.ip.abtnet.io/).

##

---

## How to mange static asset cache?

URL: https://www.arcblock.io/en/docs/blocklet-developer/XhcgglZFunKKpQRHrnAT7sew/

The Blocklet Server is designed to cache specific assets within its routing engine to enhance performance. These assets include the Blocklet Logo, JS/CSS/Font files used in blocklets, and images along with their variants (such as different formats, sizing, and croping). To ensure smooth caching operations, it is recommended to bundle your blocklet with an asset content digest in the file name (which is supported in most modern building tools).

If there is a need to clear or reset the cache for a specific blocklet, this can be done by accessing the designated cache reset functionality for that blocklet.

![image.png](https://media.arcblock.io/lib/dc/dcf5c193ec08c6cee52b5fa84fae9983.w1600.webp)

Additionally, cache can be cleared at the Blocklet Server level.

![image.png](https://media.arcblock.io/lib/08/088eb1e46447496cc564c3d5ee374e0b.w1600.webp)

---

## Setup with ArcBlock Launcher

URL: https://www.arcblock.io/en/docs/blocklet-developer/Zquq4DW4XK79vABo7K-_JTFu/

## Launching a server via ArcBlock Launcher

ArcBlock Launcher is a service that allows you to purchase Blocklet Server servers via ABT, credit card and other payment methods. This service eliminates the need to install environments or dependencies such as Node.js/Blocklet CLI/Nginx, and allows you to fill in simple configuration information to get a running server.
Service Address: [https://launcher.arcblock.io/](https://launcher.arcblock.io/)

### Step 1: Purchase NFT

1. Selecting the right type of NFT ![select nft](https://media.arcblock.io/docs/setup-blocklet-server/images/launcher-select-plan-en.w1600.webp)
2. Select payment type: ABT
3. Click "Buy" to pay, after successful payment, it will automatically jump to the start page

### Step 2: Start the server

1. Fill in the server information and click "Agree to the EULA and continue"
2. Wait for a successful startup. The startup process takes about three minutes, and will automatically jump to the newly started server after a successful startup.

---

## Blocklet SDK (Browser)

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/

---

## SDK Client

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-client-e6412e/

The SDK Client provides the primary entry points for interacting with the `@blocklet/js-sdk`. It offers a main `BlockletSDK` class that bundles all available services, along with several factory functions (`getBlockletSDK`, `createAxios`, `createFetch`) for convenient access and instantiation.

This section provides a detailed reference for these core components. For practical examples, see the [Making API Requests](/en/docs/blocklet-sdk-browser/guides-making-api-requests-e6412e/) guide.

The following diagram illustrates the relationship between your application, the SDK exports, and the instances they create:

![SDK Client](https://media.arcblock.io/lib/a5/a513cfd42db82e3c.w1600.webp)

## BlockletSDK Class

The `BlockletSDK` class is a container that holds instances of all the different services, providing a single point of access to the SDK's functionality.

While you can instantiate it directly, the recommended way to get an instance is through the `getBlockletSDK()` factory function, which ensures a single, shared instance throughout your application.

### Properties

The following services are available as properties on a `BlockletSDK` instance:

| Property  | Service  | Description  |
|---|---|---|
| `user`  | [AuthService](/en/docs/blocklet-sdk-browser/api-services-auth-e6412e/)  | Manages user profiles, settings, and authentication actions.  |
| `userSession`  | [UserSessionService](/en/docs/blocklet-sdk-browser/api-services-user-session-e6412e/)  | Fetches and manages user login sessions across devices.  |
| `token`  | [TokenService](/en/docs/blocklet-sdk-browser/api-services-token-e6412e/)  | Low-level service for managing session and refresh tokens.  |
| `blocklet`  | [BlockletService](/en/docs/blocklet-sdk-browser/api-services-blocklet-e6412e/)  | Fetches and loads blocklet metadata.  |
| `federated`  | [FederatedService](/en/docs/blocklet-sdk-browser/api-services-federated-e6412e/)  | Interacts with Federated Login Group settings.  |
| `api`  | `Axios`  | <strong>Deprecated.</strong> An Axios instance. Use `createAxios()` instead.  |

## Factory Functions

These helper functions provide convenient ways to create SDK clients and HTTP request handlers.

### getBlockletSDK()

`getBlockletSDK()`

This function returns a singleton instance of the `BlockletSDK` class. Using a singleton ensures that all parts of your application share the same SDK state, including token information and service configurations.

<strong>Returns</strong>

A singleton `BlockletSDK` instance.

**Using getBlockletSDK**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchUserProfile() {
  try {
    const profile = await sdk.user.getProfile();
    console.log('User Profile:', profile);
  } catch (error) {
    console.error('Failed to fetch profile:', error);
  }
}

fetchUserProfile();
```

### createAxios()

`createAxios(config, requestParams)`

This is the recommended factory function for creating a pre-configured [Axios](https://axios-http.com/) instance. The instance automatically handles adding the authorization header to outgoing requests and refreshing the session token if it expires.

<strong>Parameters</strong>

- **config** `AxiosRequestConfig` — Optional. A standard Axios configuration object. Any valid Axios option can be passed here.
- **requestParams** `RequestParams` — Optional. Additional parameters for SDK-specific request handling.

<strong>Returns</strong>

An `Axios` instance with interceptors configured for automatic token management.

**Creating an Axios Client**

```javascript
import { createAxios } from '@blocklet/js-sdk';

// Create an API client with a base URL
const apiClient = createAxios({
  baseURL: '/api/v1',
});

async function getItems() {
  try {
    // The Authorization header is automatically added
    const response = await apiClient.get('/items');
    return response.data;
  } catch (error) {
    console.error('Error fetching items:', error);
    throw error;
  }
}
```

### createFetch()

`createFetch(options, requestParams)`

For developers who prefer the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), this function returns a wrapped `fetch` function that provides the same automatic token management as `createAxios`.

<strong>Parameters</strong>

- **options** `RequestInit` — Optional. Default options for the Fetch API, such as headers, as defined in the standard RequestInit type.
- **requestParams** `RequestParams` — Optional. Additional parameters for SDK-specific request handling.

<strong>Returns</strong>

A `fetch`-compatible function that automatically handles authentication.

**Creating a Fetch Client**

```javascript
import { createFetch } from '@blocklet/js-sdk';

// Create a fetcher with default JSON headers
const apiFetcher = createFetch({
  headers: {
    'Content-Type': 'application/json',
  },
});

async function postItem(item) {
  try {
    const response = await apiFetcher('/api/v1/items', {
      method: 'POST',
      body: JSON.stringify(item),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Error posting item:', error);
    throw error;
  }
}
```

With the SDK client initialized, you can now explore the various services it provides to interact with the Blocklet ecosystem.

::::card-group
::link-card{title="Authentication Guide" description="Learn how the SDK simplifies user authentication and token management." icon="key" href="/en/docs/blocklet-sdk-browser/guides-authentication-e6412e/"}
::link-card{title="Services API Reference" description="Dive into the detailed API documentation for each service." icon="book-open" href="/en/docs/blocklet-sdk-browser/api-services-e6412e/"}
::::

---

## API Reference

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-e6412e/

Welcome to the API reference for the `@blocklet/js-sdk`. This section provides detailed, technical documentation for all the classes, methods, functions, and types that the SDK exposes. It is intended for developers who need a precise understanding of the SDK's components and their functionalities.

Whether you're looking to create a custom API client, interact with a specific Blocklet service, or understand the data structures, you'll find the necessary details here.

::::card-group
::link-card{title="SDK Client" description="Reference for the main `BlockletSDK` class and factory functions like `getBlockletSDK`, `createAxios`, and `createFetch`." icon="box" href="/en/docs/blocklet-sdk-browser/api-client-e6412e/"}
::link-card{title="Services" description="Detailed API documentation for services that interact with specific Blocklet API endpoints, such as authentication and user sessions." icon="server" href="/en/docs/blocklet-sdk-browser/api-services-e6412e/"}
::link-card{title="Types" description="A comprehensive reference for all exported TypeScript types and interfaces, helping you ensure type safety in your application." icon="file" href="/en/docs/blocklet-sdk-browser/api-types-e6412e/"}
::::

This reference is organized to help you quickly find the information you need. For a more practical, task-based introduction, we recommend starting with the [Guides](/en/docs/blocklet-sdk-browser/guides-e6412e/). If you're ready to dive into the specifics, please select a category above to get started.

---

## AuthService

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-auth-e6412e/

The `AuthService` provides a comprehensive API for managing all aspects of a user's account. It handles user profiles, privacy and notification settings, social interactions like following other users, and critical authentication actions such as logging out and deleting an account. You can access it through the SDK instance at `sdk.auth`.

This service works closely with the [`TokenService`](/en/docs/blocklet-sdk-browser/api-services-token-e6412e/) to manage authentication states, but abstracts away the low-level token handling for most operations.

## User Profile Management

These methods allow you to fetch, update, and manage user profile data.

### getProfile

Retrieves the complete profile for the currently authenticated user.

```javascript
const profile = await sdk.auth.getProfile();
console.log(profile);
```

<strong>Returns</strong>

- **profile** `Promise<object>` — A promise that resolves to the user's profile object.

<strong>Example Response</strong>

```json
{
  "did": "z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ",
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "avatar": "https://example.com/avatar.png",
  "bio": "Developer and enthusiast.",
  "metadata": {}
}
```

### saveProfile

Updates the profile of the currently authenticated user. You can update fields like `locale`, `metadata`, and more.

<strong>Parameters</strong>

- **profileData** `object` *(required)* — An object containing the profile fields to update.
  - **locale** `string` — The user's preferred language locale (e.g., 'en').
  - **inviter** `string` — The DID of the user who invited the current user.
  - **metadata** `any` — An object for storing custom user data.
  - **address** `any` — The user's address information.

```javascript
const updatedProfile = await sdk.auth.saveProfile({
  metadata: { twitter: '@johndoe' },
  locale: 'en-US'
});
console.log('Profile saved:', updatedProfile);
```

<strong>Returns</strong>

- **updatedProfile** `Promise<object>` — A promise that resolves to the updated profile object.

### getUserPublicInfo

Fetches publicly available information for any user, identified by their DID.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **did** `string` *(required)* — The Decentralized Identifier (DID) of the user.

```javascript
const publicInfo = await sdk.auth.getUserPublicInfo({ did: 'z8ia...' });
console.log(publicInfo.fullName);
```

<strong>Returns</strong>

- **UserPublicInfo** `Promise<object>` — A promise that resolves to a UserPublicInfo object.
  - **avatar** `string` — URL of the user's avatar.
  - **did** `string` — The user's DID.
  - **fullName** `string` — The user's full name.
  - **sourceAppPid** `string | null` — The PID of the source application.

### refreshProfile

Forces a synchronization of the user's profile from its original source, ensuring the data is up-to-date.

```javascript
await sdk.auth.refreshProfile();
console.log('Profile refresh initiated.');
```

<strong>Returns</strong>

- **void** `Promise<void>` — A promise that resolves when the refresh request has been sent.

### updateDidSpace

Updates the user's DID Space configuration, which determines where their data is stored.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **spaceGateway** `object` *(required)* — An object containing the new DID Space gateway details.
    - **did** `string` *(required)* — DID of the space.
    - **name** `string` *(required)* — Name of the space.
    - **url** `string` *(required)* — URL of the space.
    - **endpoint** `string` *(required)* — API endpoint of the space.

```javascript
const spaceGateway = {
  did: 'zNK...',
  name: 'My Personal Space',
  url: 'https://space.example.com',
  endpoint: 'https://space.example.com/api'
};

await sdk.auth.updateDidSpace({ spaceGateway });
console.log('DID Space updated successfully.');
```

<strong>Returns</strong>

- **void** `Promise<void>` — A promise that resolves upon successful update.

### getProfileUrl

Constructs the URL for a user's public profile page.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **did** `string` *(required)* — The user's DID.
  - **locale** `string` *(required)* — The desired locale for the profile page.

```javascript
const url = await sdk.auth.getProfileUrl({ did: 'z8ia...', locale: 'en' });
console.log('Profile URL:', url);
```

<strong>Returns</strong>

- **url** `Promise<string>` — A promise that resolves to the full profile URL string.

## Settings Management

Manage user-specific settings for privacy and notifications.

### getUserPrivacyConfig

Retrieves the privacy settings for a specified user.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **did** `string` *(required)* — The DID of the user whose privacy settings are being requested.

```javascript
const privacyConfig = await sdk.auth.getUserPrivacyConfig({ did: 'z8ia...' });
console.log('Is email public?', privacyConfig.isEmailPublic);
```

<strong>Returns</strong>

- **PrivacyConfig** `Promise<object>` — A promise that resolves to the user's PrivacyConfig object, where keys are setting names and values are booleans.

### saveUserPrivacyConfig

Saves the privacy settings for the currently authenticated user.

<strong>Parameters</strong>

- **config** `object` *(required)* — An object with key-value pairs representing the privacy settings.

```javascript
const newConfig = { isEmailPublic: false, allowFriendRequests: false };
const savedConfig = await sdk.auth.saveUserPrivacyConfig(newConfig);
console.log('Privacy config saved.');
```

<strong>Returns</strong>

- **PrivacyConfig** `Promise<object>` — A promise that resolves to the saved PrivacyConfig object.

### getUserNotificationConfig

Gets the notification configuration for the current user, including webhooks and channel preferences.

```javascript
const notificationConfig = await sdk.auth.getUserNotificationConfig();
console.log('Webhooks:', notificationConfig.webhooks);
```

<strong>Returns</strong>

- **NotificationConfig** `Promise<object>` — A promise that resolves to the NotificationConfig object.
  - **webhooks** `array`
    - **webhook** `object`
      - **type** `'slack' | 'api'` *(required)*
      - **url** `string` *(required)*
  - **notifications** `object`
    - **email** `boolean`
    - **wallet** `boolean`
    - **phone** `boolean`

### saveUserNotificationConfig

Saves new notification settings for the current user.

<strong>Parameters</strong>

- **config** `object` *(required)* — The new notification configuration object.
  - **webhooks** `array`
    - **webhook** `object`
      - **type** `'slack' | 'api'` *(required)*
      - **url** `string` *(required)*
  - **notifications** `object`
    - **email** `boolean`
    - **wallet** `boolean`
    - **phone** `boolean`

```javascript
const newConfig = {
  webhooks: [
    { type: 'api', url: 'https://example.com/webhook' }
  ],
  notifications: {
    email: true,
    wallet: false
  }
};
const savedConfig = await sdk.auth.saveUserNotificationConfig(newConfig);
console.log('Notification config saved:', savedConfig);
```

<strong>Returns</strong>

- **NotificationConfig** `Promise<object>` — A promise that resolves to the saved NotificationConfig object.

### testNotificationWebhook

Tests a webhook configuration to ensure it can receive test notifications.

<strong>Parameters</strong>

- **webhook** `object` *(required)* — The webhook object to test.
  - **type** `'slack' | 'api'` *(required)*
  - **url** `string` *(required)*

```javascript
const webhookToTest = {
  type: 'slack',
  url: 'https://hooks.slack.com/services/...'
};
const result = await sdk.auth.testNotificationWebhook(webhookToTest);
console.log('Webhook test successful:', result.success);
```

<strong>Returns</strong>

- **result** `Promise<object>` — A promise that resolves to an object with a success property.
  - **success** `boolean` — Indicates if the test was successful.

## Social Interactions

Manage social connections between users.

### followUser

Follow another user.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user to follow.

```javascript
const userToFollow = 'z8ia...';
await sdk.auth.followUser({ userDid: userToFollow });
console.log(`Successfully followed ${userToFollow}.`);
```

<strong>Returns</strong>

- **void** `Promise<void>` — A promise that resolves when the operation is complete.

### unfollowUser

Unfollow a user.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user to unfollow.

```javascript
const userToUnfollow = 'z8ia...';
await sdk.auth.unfollowUser({ userDid: userToUnfollow });
console.log(`Successfully unfollowed ${userToUnfollow}.`);
```

<strong>Returns</strong>

- **void** `Promise<void>` — A promise that resolves when the operation is complete.

### isFollowingUser

Check if the current user is following a specific user.

<strong>Parameters</strong>

- **options** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user to check.

```javascript
const userToCheck = 'z8ia...';
const { isFollowing } = await sdk.auth.isFollowingUser({ userDid: userToCheck });
if (isFollowing) {
  console.log(`You are following ${userToCheck}.`);
} else {
  console.log(`You are not following ${userToCheck}.`);
}
```

<strong>Returns</strong>

- **result** `Promise<object>` — A promise that resolves to an object containing an isFollowing property.
  - **isFollowing** `boolean` — True if the current user is following the specified user.

## Authentication & Account Actions

Perform critical actions related to the user's session and account lifecycle.

### logout

Logs the current user out. It can be configured to log out from a specific device or all sessions.

<strong>Parameters</strong>

- **options** `object`
  - **visitorId** `string` — The ID of a specific device/session to log out.
  - **status** `string` — The status of the session to log out.
  - **includeFederated** `boolean` — If true, also logs out from all applications in the Federated Login Group.

```javascript
// Simple logout from the current session
await sdk.auth.logout({});
console.log('Logged out successfully.');

// Log out from a specific device and all federated apps
await sdk.auth.logout({ visitorId: 'some-visitor-id', includeFederated: true });
```

<strong>Returns</strong>

- **void** `Promise<void>` — A promise that resolves when the logout process is complete.

### destroyMyself

Permanently deletes the currently authenticated user's account. This action is irreversible and should be used with extreme caution.

```javascript
// This is a destructive action. Usually, you would confirm this with the user.
try {
  const result = await sdk.auth.destroyMyself();
  console.log(`Account ${result.did} has been permanently deleted.`);
} catch (error) {
  console.error('Failed to delete account:', error);
}
```

<strong>Returns</strong>

- **result** `Promise<object>` — A promise that resolves to an object containing the DID of the deleted user.
  - **did** `string` — The DID of the deleted user.

---

## BlockletService

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-blocklet-e6412e/

The `BlockletService` provides methods to access the metadata of a blocklet. This metadata, represented by the `Blocklet` object, contains essential information such as the application's name, URL prefix, version, and component mount points.

The service can retrieve this information in two primary ways:

::::steps
:::step{title="Client-Side:"}
By reading the global `window.blocklet` object, which is automatically available when your code is running inside a blocklet's frontend.
:::

:::step{title="Remote Fetch:"}
By fetching the blocklet's metadata from a specified base URL. This is useful for server-side contexts or when interacting with a blocklet from an external application.
:::
::::

To improve performance, the service implements an in-memory cache for remotely fetched blocklet data, which lasts for 60 seconds.

## Methods

### getBlocklet()

Fetches the blocklet's metadata object. The behavior of this method changes based on the provided arguments.

- When called without arguments on the client-side, it synchronously returns `window.blocklet`.
- When called with a `baseUrl`, it asynchronously fetches the metadata from the remote URL.

<strong>Parameters</strong>

- **baseUrl** `string` — The base URL of the blocklet to fetch metadata from. Required for server-side usage.
- **force** `boolean` (default: `false`) — If true, it will bypass the cache and fetch fresh data from the remote URL.

<strong>Returns</strong>

- **Promise<Blocklet> | Blocklet** `Promise<Blocklet> | Blocklet` — Returns a Promise that resolves with the blocklet metadata object when fetching remotely, or the object directly in a client-side context.

<strong>Examples</strong>

**Get Blocklet on Client-Side**

```javascript
// This code assumes it's running in a blocklet's frontend environment

async function logBlockletName() {
  try {
    // On the client, getBlocklet() can be synchronous if data is preloaded
    const blocklet = await sdk.blocklet.getBlocklet();
    console.log('Blocklet Name:', blocklet.appName);
  } catch (error) {
    console.error('Failed to get blocklet info:', error);
  }
}

logBlockletName();
```

**Fetch Blocklet from a URL**

```javascript
async function fetchRemoteBlocklet(url) {
  try {
    console.log(`Fetching blocklet info from ${url}...`);
    const blocklet = await sdk.blocklet.getBlocklet(url);
    console.log(`Successfully fetched: ${blocklet.appName} v${blocklet.version}`);

    // Fetch again, this time it should be from cache
    const cachedBlocklet = await sdk.blocklet.getBlocklet(url);
    console.log('Fetched from cache:', cachedBlocklet.appName);

    // Force a refetch, bypassing the cache
    const freshBlocklet = await sdk.blocklet.getBlocklet(url, true);
    console.log('Force-refetched:', freshBlocklet.appName);
  } catch (error) {
    console.error('Failed to fetch remote blocklet:', error);
  }
}

fetchRemoteBlocklet('https://store.blocklet.dev');
```

### loadBlocklet()

This is a client-side utility method that dynamically injects the `__blocklet__.js` script into the document's `<head>`. This script populates the `window.blocklet` object, making the metadata available globally. This is particularly useful for applications that are not blocklets themselves but need to interact with one.

> Note: This method will fail if called in a server-side (Node.js) environment.
>

<strong>Returns</strong>

- **Promise<void>** `Promise<void>` — A Promise that resolves when the script has been successfully loaded and rejects if there is an error.

<strong>Example</strong>

**Dynamically Load Blocklet Script**

```javascript
async function initializeBlockletData() {
  try {
    await sdk.blocklet.loadBlocklet();
    console.log('Blocklet script loaded successfully.');
    // Now window.blocklet is available
    console.log('Blocklet Name:', window.blocklet.appName);
  } catch (error) {
    console.error('Failed to load the blocklet script:', error);
  }
}

// Run this function in a browser environment
initializeBlockletData();
```

### getPrefix()

A convenience method to get the URL prefix for a blocklet. The prefix is the base path where the blocklet is served (e.g., `/` or `/my-blocklet`).

<strong>Parameters</strong>

- **blocklet** `Blocklet` — An optional Blocklet object. If provided, its prefix property will be returned.

<strong>Returns</strong>

- **string | null** `string | null` — The string prefix (e.g., '/app') or '/' as a default. In a server-side environment where window is not available and no blocklet object is passed, it returns null.

<strong>Example</strong>

**Get URL Prefix**

```javascript
// Assuming this runs on the client-side inside a blocklet
const prefix = sdk.blocklet.getPrefix();
console.log('Current blocklet prefix:', prefix);

// Or, you can pass a Blocklet object you've already fetched
async function logPrefixForRemoteBlocklet(url) {
  const remoteBlocklet = await sdk.blocklet.getBlocklet(url);
  const remotePrefix = sdk.blocklet.getPrefix(remoteBlocklet);
  console.log(`Prefix for ${remoteBlocklet.appName} is:`, remotePrefix);
}

logPrefixForRemoteBlocklet('https://store.blocklet.dev');
```

## The Blocklet Object

The `getBlocklet()` method returns a `Blocklet` object, which contains comprehensive metadata about the application. Below are some of the most commonly used properties.

- **did** `string` — The decentralized identifier (DID) of the blocklet.
- **appName** `string` — The human-readable name of the application.
- **appUrl** `string` — The full public URL of the application.
- **prefix** `string` — The URL prefix where the blocklet is mounted.
- **version** `string` — The version of the blocklet (e.g., '1.2.3').
- **isComponent** `boolean` — Indicates if the blocklet is a component.
- **componentMountPoints** `BlockletComponent[]` — An array of components mounted by this blocklet.
- **theme** `BlockletTheme` — An object containing theme configuration like colors and logos.
- **navigation** `BlockletNavigation[]` — An array of navigation items for the blocklet's UI.
- **serverDid** `string` — The DID of the Blocklet Server instance running the blocklet.

<strong>Example Response</strong>

**Blocklet Object Example**

```json
{
  "did": "z8iZz...",
  "appId": "z1s...",
  "appName": "Blocklet Store",
  "appDescription": "A marketplace for blocklets",
  "appUrl": "https://store.blocklet.dev",
  "prefix": "/",
  "version": "1.16.29",
  "isComponent": false,
  "theme": {
    "logo": "logo.png",
    "colors": {
      "primary": "#4F6AF6"
    }
  },
  "navigation": [
    {
      "id": "home",
      "title": "Home",
      "link": "/"
    }
  ],
  "componentMountPoints": [],
  "serverDid": "z2qaD...",
  "webWalletUrl": "https://web.abtwallet.io"
}
```

For a complete list of all properties, please refer to the [Types](/en/docs/blocklet-sdk-browser/api-types-e6412e/) reference page.

## Next Steps

Now that you know how to retrieve blocklet metadata, you might want to learn how to get information about its mounted components. Continue to the next section to learn about the `ComponentService`.

:::action-card{title="ComponentService" description="API for getting information about mounted components and constructing URLs for them." icon="box"}
::action{label="Read More" href="/en/docs/blocklet-sdk-browser/api-services-component-e6412e/" variant="primary"}
:::

---

## ComponentService

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-component-e6412e/

The `ComponentService` provides a convenient API for interacting with component blocklets that are mounted within your main application. It allows you to retrieve metadata about these components and construct absolute URLs to their pages or API endpoints.

This service relies on the blocklet's metadata. To learn how to load this metadata, please refer to the [BlockletService documentation](/en/docs/blocklet-sdk-browser/api-services-blocklet-e6412e/).

## Instantiation

Unlike other services, `ComponentService` must be instantiated manually. This is because it depends on the `window.blocklet` object, which may be loaded asynchronously. To ensure the service has access to the complete blocklet metadata, you should create an instance after the `blocklet` object is available.

**Instantiating ComponentService**

```javascript
import { ComponentService } from '@blocklet/js-sdk';

// Assuming window.blocklet is loaded and available
const componentService = new ComponentService();
```

## Methods

### getComponent()

Retrieves the full metadata object for a specific mounted component.

<strong>Parameters</strong>

- **name** `string` *(required)* — The identifier of the component. Can be its name, title, or did.

<strong>Returns</strong>

- **BlockletComponent | undefined** `object` — The BlockletComponent object if found, otherwise undefined.

<strong>Example</strong>

**Get Component Metadata**

```javascript
// Mock window.blocklet object for demonstration
window.blocklet = {
  componentMountPoints: [
    {
      did: 'z8iZzaC3ukTM81BCs4Ynawxbg1KAd3b3p6c7b',
      name: 'my-first-component',
      title: 'My First Component',
      mountPoint: '/components/my-first-component',
      status: 'started'
    },
    {
      did: 'z8iZzbF9tkyG27AQs5Ynawxbh2LBe4c4q7d8c',
      name: 'my-second-component',
      title: 'My Second Component',
      mountPoint: '/components/my-second-component',
      status: 'started'
    }
  ],
  // ... other blocklet properties
};

const componentService = new ComponentService();

// Find component by its name
const component = componentService.getComponent('my-first-component');
console.log(component);
```

<strong>Example Response</strong>

**Response**

```json
{
  "did": "z8iZzaC3ukTM81BCs4Ynawxbg1KAd3b3p6c7b",
  "name": "my-first-component",
  "title": "My First Component",
  "mountPoint": "/components/my-first-component",
  "status": "started"
}
```

### getComponentMountPoint()

A helper method to quickly retrieve the `mountPoint` for a component. The mount point is the relative URL path where the component is served from the main application's domain.

<strong>Parameters</strong>

- **name** `string` *(required)* — The identifier of the component (name, title, or did).

<strong>Returns</strong>

- **mountPoint** `string` — The component's mountPoint as a string (e.g., /components/my-component). Returns an empty string if the component is not found.

<strong>Example</strong>

**Get Mount Point**

```javascript
// Using the same componentService instance from the previous example
const mountPoint = componentService.getComponentMountPoint('my-first-component');

console.log(mountPoint);
// Expected output: /components/my-first-component
```

### getUrl()

Constructs a full, absolute URL to a resource within a component. This is the recommended way to create links to other components, as it correctly handles the application's base URL and the component's specific mount point.

<strong>Parameters</strong>

- **name** `string` *(required)* — The identifier of the component (name, title, or did).
- **...parts** `string[]` — One or more path segments to append to the component's URL.

<strong>Returns</strong>

- **url** `string` — A complete, absolute URL as a string.

<strong>Example</strong>

**Construct Component URL**

```javascript
// Mock window.blocklet object
window.blocklet = {
  appUrl: 'https://myapp.did.abtnet.io',
  componentMountPoints: [
    {
      name: 'api-component',
      title: 'API Component',
      mountPoint: '/api/v1',
      // ... other properties
    }
  ],
  // ... other properties
};

const componentService = new ComponentService();

// Construct a URL to an API endpoint within the component
const userApiUrl = componentService.getUrl('api-component', 'users', '123');
console.log(userApiUrl);
// Expected output: https://myapp.did.abtnet.io/api/v1/users/123

// Construct a URL to a page within the component
const settingsPageUrl = componentService.getUrl('api-component', 'settings');
console.log(settingsPageUrl);
// Expected output: https://myapp.did.abtnet.io/api/v1/settings
```

## Types

### BlockletComponent

This type represents the metadata for a single mounted component.

- **did** `string` *(required)* — The decentralized identifier (DID) of the component.
- **name** `string` *(required)* — The name of the component, as defined in its blocklet.yml.
- **title** `string` *(required)* — The human-readable title of the component.
- **mountPoint** `string` *(required)* — The URL path where the component is mounted relative to the main app's URL.
- **status** `string` *(required)* — The current status of the component (e.g., 'started', 'stopped').

Now that you know how to interact with components, you might want to learn how to manage federated login settings. See the [FederatedService documentation](/en/docs/blocklet-sdk-browser/api-services-federated-e6412e/) for more details.

---

## Services

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-e6412e/

The `@blocklet/js-sdk` is organized into several service classes, each responsible for a specific domain of functionality. These services act as dedicated clients for different Blocklet API endpoints, providing a structured and intuitive way to interact with the platform's features.

Most core services are pre-initialized and available as properties on the main `BlockletSDK` instance, which you can obtain using the `getBlockletSDK()` function.

**Accessing a Service**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

// Access the AuthService to get user info
async function getUserProfile() {
  const profile = await sdk.user.getProfile();
  console.log(profile);
}

// Access the BlockletService to get blocklet info
async function getBlockletMeta() {
  const meta = await sdk.blocklet.getMeta();
  console.log(meta);
}
```

The diagram below illustrates the structure of the `BlockletSDK` instance and its relationship with the core services.

![Services](https://media.arcblock.io/lib/11/113ac57be0d6c30e.w1600.webp)

Below is a complete list of the available services. Click on any service to view its detailed API reference.

::::card-group
::link-card{title="AuthService" description="API for managing user profiles, privacy settings, notifications, and authentication actions like logout." icon="user" href="/en/docs/blocklet-sdk-browser/api-services-auth-e6412e/"}
::link-card{title="BlockletService" description="API for fetching and loading blocklet metadata from `window.blocklet` or a remote URL." icon="box" href="/en/docs/blocklet-sdk-browser/api-services-blocklet-e6412e/"}
::link-card{title="ComponentService" description="API for getting information about mounted components and constructing URLs for them." icon="layout" href="/en/docs/blocklet-sdk-browser/api-services-component-e6412e/"}
::link-card{title="FederatedService" description="API for interacting with Federated Login Group settings and retrieving information about master and current apps." icon="routes" href="/en/docs/blocklet-sdk-browser/api-services-federated-e6412e/"}
::link-card{title="TokenService" description="Low-level API for getting, setting, and removing session and refresh tokens from storage (Cookies and LocalStorage)." icon="key" href="/en/docs/blocklet-sdk-browser/api-services-token-e6412e/"}
::link-card{title="UserSessionService" description="API for fetching and managing user login sessions." icon="users" href="/en/docs/blocklet-sdk-browser/api-services-user-session-e6412e/"}
::::

Each service provides a focused set of methods for a specific part of the Blocklet platform. To understand the data structures and types returned by these services, please see the [Types](/en/docs/blocklet-sdk-browser/api-types-e6412e/) reference.

---

## FederatedService

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-federated-e6412e/

The `FederatedService` provides an API for interacting with Federated Login Group settings. It allows you to retrieve information about the "master" application that controls the login session and the "current" application the user is interacting with. This is essential for creating features like a unified application switcher or for understanding the context of the user's session within a group of connected Blocklets.

A Federated Login Group (统一登录站点群) allows multiple Blocklets to share a single user session, providing a seamless experience as users navigate between them. One Blocklet acts as the master, handling authentication, while others are members.

![FederatedService](https://media.arcblock.io/lib/2c/2c7f3dcab8e5db47.w1600.webp)

## Common Use Case: Building an App Switcher

The most common use case for `FederatedService` is to build a UI component that lists all applications in the group, allowing the user to easily switch between them. The `getApps()` method is designed specifically for this purpose.

**Example: Fetching Apps for a UI Component**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

// Get the list of all apps in the federated group
// The master app will always be the first in the list.
const apps = sdk.federated.getApps();

console.log('Available apps:', apps);

// You can then use this 'apps' array to render a dropdown menu,
// a sidebar, or any other navigation component.
apps.forEach(app => {
  console.log(`App Name: ${app.appName}, URL: ${app.appUrl}`);
});
```

## API Reference

### getApps()

Retrieves a list of applications relevant to the current federated context. It intelligently combines the master application and the current application, ensuring the master application is always listed first if federation is enabled.

<strong>Returns</strong>

- **** `Array<AppInfo | ServerInfo>` — An array of application info objects. The master app is always the first element if federation is enabled.

<strong>Example</strong>

```javascript
const appList = sdk.federated.getApps();
console.log(appList);
```

<strong>Example Response</strong>

```json
[
  {
    "appId": "z1masterAppDid",
    "appName": "Master App",
    "appDescription": "The main application for the group.",
    "appLogo": "/assets/logo.png",
    "appPid": "z8tmasterAppPid",
    "appUrl": "https://master.example.com",
    "version": "1.2.0",
    "sourceAppPid": "z8tmasterAppPid",
    "provider": "wallet"
  },
  {
    "appId": "z1currentAppDid",
    "appName": "Current Member App",
    "appDescription": "The application you are currently using.",
    "appLogo": "/assets/logo.png",
    "appPid": "z8tcurrentAppPid",
    "appUrl": "https://member.example.com",
    "version": "1.0.0",
    "sourceAppPid": null,
    "provider": "wallet"
  }
]
```

### getCurrentApp()

Gets the information for the application that is currently running. This can be either a standard Blocklet or the Blocklet Server itself.

<strong>Returns</strong>

- **** `AppInfo | ServerInfo | null` — An object containing the current application's details, or null if it cannot be determined.

<strong>Example</strong>

```javascript
const currentApp = sdk.federated.getCurrentApp();
if (currentApp) {
  console.log(`You are currently on: ${currentApp.appName}`);
}
```

### getFederatedApp()

Gets the information for the master application in the Federated Login Group. If the current application is not part of a federated group, this method will return `null`.

<strong>Returns</strong>

- **** `AppInfo | null` — An object containing the master application's details, or null if not in federated mode.

<strong>Example</strong>

```javascript
const masterApp = sdk.federated.getFederatedApp();
if (masterApp) {
  console.log(`The master app is: ${masterApp.appName}`);
}
```

### getFederatedEnabled()

Checks if the Federated Login Group feature is enabled and has been approved by the user.

<strong>Returns</strong>

- **** `boolean` — Returns true if federation is configured and the status is 'approved', otherwise false.

<strong>Example</strong>

```javascript
const isFederated = sdk.federated.getFederatedEnabled();
if (isFederated) {
  console.log('Federated login is active.');
} else {
  console.log('This is a standalone application.');
}
```

### getTrustedDomains()

Asynchronously fetches a list of trusted domains configured for the Federated Login Group.

<strong>Returns</strong>

- **** `Promise<Array<string>>` — A promise that resolves to an array of trusted domain strings.

<strong>Example</strong>

```javascript
async function logTrustedDomains() {
  try {
    const domains = await sdk.federated.getTrustedDomains();
    console.log('Trusted domains:', domains);
  } catch (error) {
    console.error('Failed to get trusted domains:', error);
  }
}

logTrustedDomains();
```

### getBlockletData()

Asynchronously fetches and parses the `__blocklet__.js` metadata file from a given application URL. This method includes caching to avoid redundant network requests.

<strong>Parameters</strong>

- **appUrl** `string` *(required)* — The base URL of the Blocklet whose data you want to fetch.
- **force** `boolean` (default: `false`) — If true, bypasses the cache and fetches fresh data.

<strong>Returns</strong>

- **** `Promise<any | null>` — A promise that resolves to the parsed JSON data from __blocklet__.js, or null on failure.

<strong>Example</strong>

```javascript
async function fetchMetadata(url) {
  const metadata = await sdk.federated.getBlockletData(url);
  if (metadata) {
    console.log(`Metadata for ${url}:`, metadata.name, metadata.version);
  }
}

fetchMetadata('https://some-blocklet.example.com');
```

## Types

These are the primary data structures returned by the `FederatedService` methods.

### AppInfo

Represents a standard Blocklet application.

**AppInfo Type**

```typescript
type AppInfo = {
  appId: string;
  appName: string;
  appDescription: string;
  appLogo: string;
  appPid: string;
  appUrl: string;
  version: string;
  sourceAppPid: string;
  provider: string;
};
```

### ServerInfo

Represents the Blocklet Server instance.

**ServerInfo Type**

```typescript
type ServerInfo = {
  appId: string;
  appName: string;
  appDescription: string;
  appUrl: string;
  sourceAppPid: string;
  provider: string;
  type: 'server';
};
```

Now that you understand how to work with federated applications, you may want to manage the user's login sessions across different devices. Proceed to the [UserSessionService](/en/docs/blocklet-sdk-browser/api-services-user-session-e6412e/) documentation to learn more.

---

## TokenService

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-token-e6412e/

The `TokenService` provides a low-level API for direct interaction with session and refresh tokens. It handles the logic of storing and retrieving these tokens from their respective browser storage locations: cookies for session tokens and `localStorage` for refresh tokens.

While this service is available for specific use cases, most developers will not need to use it directly. Higher-level abstractions like the `AuthService` and the `createAxios`/`createFetch` helpers manage token handling automatically. For typical authentication and session management, please refer to the [Authentication Guide](/en/docs/blocklet-sdk-browser/guides-authentication-e6412e/).

## Methods

### getSessionToken

Retrieves the current session token. The service first attempts to get the token from browser cookies. As a fallback, it can check `localStorage` if a specific key is provided in the configuration.

<strong>Parameters</strong>

- **config** `object` — An optional configuration object.
  - **sessionTokenKey** `string` — The key used to find the session token in window.localStorage if it's not in the cookies.

<strong>Returns</strong>

- **** `string` — The session token, or an empty string if not found.

<strong>Example</strong>

```javascript
// Primarily checks cookies
const sessionToken = sdk.token.getSessionToken();

// Checks cookies, then localStorage with a specific key
const sessionTokenWithFallback = sdk.token.getSessionToken({
  sessionTokenKey: 'my-app-session-key',
});
```

### setSessionToken

Sets or updates the session token in the browser's cookies.

<strong>Parameters</strong>

- **value** `string` *(required)* — The session token value to store.

<strong>Returns</strong>

- **** `void` — This method does not return a value.

<strong>Example</strong>

```javascript
sdk.token.setSessionToken('new-session-token-value-from-server');
```

### removeSessionToken

Removes the session token from the browser's cookies.

<strong>Returns</strong>

- **** `void` — This method does not return a value.

<strong>Example</strong>

```javascript
sdk.token.removeSessionToken();
```

### getRefreshToken

Retrieves the refresh token from the browser's `localStorage`.

<strong>Returns</strong>

- **** `string | null` — The refresh token, or null if it does not exist.

<strong>Example</strong>

```javascript
const refreshToken = sdk.token.getRefreshToken();
if (refreshToken) {
  console.log('Refresh token is available.');
}
```

### setRefreshToken

Sets or updates the refresh token in the browser's `localStorage`.

<strong>Parameters</strong>

- **value** `string` *(required)* — The refresh token value to store.

<strong>Returns</strong>

- **** `void` — This method does not return a value.

<strong>Example</strong>

```javascript
sdk.token.setRefreshToken('new-refresh-token-value-from-server');
```

### removeRefreshToken

Removes the refresh token from the browser's `localStorage`.

<strong>Returns</strong>

- **** `void` — This method does not return a value.

<strong>Example</strong>

```javascript
sdk.token.removeRefreshToken();
```

---

## UserSessionService

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-services-user-session-e6412e/

The `UserSessionService` provides an API for fetching and managing a user's login sessions across different devices and applications. This service is essential for building features that allow users to view their active login locations, see which devices have accessed their account, and manage those sessions.

For a practical guide on using this service, please refer to the [Managing User Sessions](/en/docs/blocklet-sdk-browser/guides-managing-user-sessions-e6412e/) guide.

## Methods

### getMyLoginSessions()

Retrieves a paginated list of the current user's own login sessions.

<strong>Parameters</strong>

- **options** `object` — An object containing configuration options.
  - **appUrl** `string` — The base URL of the application to query.
- **params** `UserSessionQuery` (default: `{ page: 1, pageSize: 10 }`) — An object for pagination and filtering.
  - **page** `number` *(required)* — The page number to retrieve.
  - **pageSize** `number` *(required)* — The number of items per page.
  - **status** `'online' | 'expired' | 'offline'` — Filter sessions by their status.

<strong>Returns</strong>

- **Promise<UserSessionList>** `Promise` — A promise that resolves to an object containing a list of sessions and pagination details.

<strong>Example</strong>

**Fetching My Online Sessions**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchMySessions() {
  try {
    const sessionData = await sdk.userSession.getMyLoginSessions(
      {},
      { page: 1, pageSize: 5, status: 'online' }
    );
    console.log('Online Sessions:', sessionData.list);
    console.log('Total online sessions:', sessionData.paging.total);
  } catch (error) {
    console.error('Failed to fetch sessions:', error);
  }
}

fetchMySessions();
```

<strong>Example Response</strong>

```json
{
  "list": [
    {
      "id": "z8V...",
      "appName": "My Blocklet",
      "appPid": "my-blocklet-pid",
      "lastLoginIp": "192.168.1.1",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "updatedAt": "2023-10-27T10:00:00.000Z",
      "status": "online",
      "userDid": "zNK..."
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5,
    "total": 1
  }
}
```

### getUserSessions()

Retrieves all login sessions for a specific user DID. This method is typically used in administrative contexts.

<strong>Parameters</strong>

- **options** `object` *(required)* — An object containing the user's DID and optional app URL.
  - **did** `string` *(required)* — The DID of the user whose sessions are to be fetched.
  - **appUrl** `string` — The base URL of the application to query.

<strong>Returns</strong>

- **Promise<UserSession[]>** `Promise` — A promise that resolves to an array of UserSession objects.

<strong>Example</strong>

**Fetching Sessions for a Specific User**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchUserSessions(userDid) {
  try {
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });
    console.log(`Sessions for user ${userDid}:`, sessions);
  } catch (error) {
    console.error('Failed to fetch user sessions:', error);
  }
}

fetchUserSessions('zNK...userDid...'); // Replace with a valid user DID
```

<strong>Example Response</strong>

```json
[
  {
    "id": "z8V...",
    "appName": "My Blocklet",
    "appPid": "my-blocklet-pid",
    "lastLoginIp": "192.168.1.1",
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "updatedAt": "2023-10-27T10:00:00.000Z",
    "status": "online",
    "userDid": "zNK..."
  }
]
```

### loginByUserSession()

Initiates a new login based on an existing user session ID. This can be used for features like seamless sign-in across related applications.

<strong>Parameters</strong>

- **options** `object` *(required)* — An object containing the session details required for login.
  - **id** `string` *(required)* — The ID of the existing session to use for login.
  - **appPid** `string` *(required)* — The PID of the application being logged into.
  - **userDid** `string` *(required)* — The DID of the user associated with the session.
  - **passportId** `string` *(required)* — The ID of the user's passport.
  - **appUrl** `string` — The base URL of the application.

<strong>Returns</strong>

- **Promise<UserSession[]>** `Promise` — A promise that resolves to an array containing the new user session.

<strong>Example</strong>

**Logging In with an Existing Session**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function loginWithSession(sessionDetails) {
  try {
    const newSessions = await sdk.userSession.loginByUserSession(sessionDetails);
    console.log('Successfully logged in with new session:', newSessions[0]);
  } catch (error) {
    console.error('Login by session failed:', error);
  }
}

const existingSession = {
  id: 'session_id_to_use',
  appPid: 'target_app_pid',
  userDid: 'zNK...userDid...',
  passportId: 'passport_id_string'
};

loginWithSession(existingSession);
```

## Data Structures

The following are the primary data structures used by the `UserSessionService`.

### UserSession

Represents a single login session for a user in a specific application.

- **id** `string` *(required)* — Unique identifier for the session.
- **appName** `string` *(required)* — The name of the application where the session originated.
- **appPid** `string` *(required)* — The PID of the application.
- **lastLoginIp** `string` *(required)* — The last known IP address for this session.
- **ua** `string` *(required)* — The User-Agent string of the client device.
- **createdAt** `string` — The timestamp when the session was created.
- **updatedAt** `string` *(required)* — The timestamp of the last activity for this session.
- **status** `'online' | 'expired' | 'offline'` — The current status of the session.
- **user** `UserSessionUser` — Detailed information about the user.
- **userDid** `string` *(required)* — The DID of the user who owns the session.
- **visitorId** `string` *(required)* — An identifier for the visitor/device.
- **passportId** `string | null` *(required)* — The ID of the user's passport.
- **extra** `object` *(required)* — Additional metadata.
  - **walletOS** `'android' | 'ios' | 'web'` *(required)* — The operating system of the wallet used.

### UserSessionUser

Contains detailed information about the user associated with a session.

- **did** `string` *(required)* — The user's Decentralized Identifier (DID).
- **fullName** `string` *(required)* — The full name of the user.
- **email** `string` *(required)* — The user's email address.
- **avatar** `string` *(required)* — URL to the user's avatar image.
- **pk** `string` *(required)* — The user's public key.
- **role** `string` *(required)* — The user's role within the application (e.g., 'owner', 'admin').
- **roleTitle** `string` *(required)* — The display title for the user's role.
- **sourceProvider** `'wallet' | 'auth0' | 'nft'` *(required)* — The provider used for authentication.
- **sourceAppPid** `string | null` *(required)* — The PID of the application that sourced the user data.
- **remark** `string` — Any remarks or notes about the user.

### UserSessionList

A paginated list of user sessions.

- **list** `UserSession[]` *(required)* — An array of user session objects.
- **paging** `object` *(required)* — An object containing pagination details.
  - **page** `number` *(required)* — The current page number.
  - **pageSize** `number` *(required)* — The number of items per page.
  - **total** `number` *(required)* — The total number of items.

### UserSessionQuery

An object used to filter and paginate session queries.

- **page** `number` *(required)* — The page number to retrieve.
- **pageSize** `number` *(required)* — The number of sessions per page.
- **status** `'online' | 'expired' | 'offline'` — Filter sessions by their status.

---

## Types

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/api-types-e6412e/

This section provides a detailed reference for the core TypeScript types and interfaces exported by the `@blocklet/js-sdk`. Using these types in your project can help you leverage TypeScript's static analysis and autocompletion for a better development experience.

## Core Blocklet Types

These types define the fundamental structure of a Blocklet application and its components.

### Blocklet

Represents the complete metadata and configuration for a Blocklet. This object is typically available globally as `window.blocklet` when the application is running within the Blocklet Server environment.

- **did** `string` *(required)* — The decentralized identifier (DID) of the Blocklet.
- **appId** `string` *(required)* — The application ID, which is also the main component's DID.
- **appPk** `string` *(required)* — The public key associated with the application.
- **appIds** `string[]` — A list of associated application IDs, used in a Federated Login Group.
- **appPid** `string` *(required)* — The process ID for the application.
- **appName** `string` *(required)* — The human-readable name of the application.
- **appDescription** `string` *(required)* — A short description of the application.
- **appLogo** `string` *(required)* — URL to the application's logo (square).
- **appLogoRect** `string` *(required)* — URL to the application's logo (rectangular).
- **appUrl** `string` *(required)* — The primary URL where the application is hosted.
- **domainAliases** `string[]` — Alternative domain names for the application.
- **isComponent** `boolean` *(required)* — Indicates if the Blocklet is a component of another Blocklet.
- **prefix** `string` *(required)* — The URL prefix for the Blocklet's routes.
- **groupPrefix** `string` *(required)* — The URL prefix for the Federated Login Group.
- **pageGroup** `string` *(required)* — The group this page belongs to.
- **version** `string` *(required)* — The version of the Blocklet.
- **mode** `string` *(required)* — The running mode of the Blocklet (e.g., 'development', 'production').
- **tenantMode** `'single' | 'multiple'` *(required)* — The tenancy mode of the Blocklet.
- **theme** `BlockletTheme` *(required)* — The theme configuration for the Blocklet.
- **navigation** `BlockletNavigation[]` *(required)* — An array of navigation items for the Blocklet's UI.
- **preferences** `Record<string, any>` *(required)* — User-configurable preferences.
- **languages** `{ code: string; name: string }[]` *(required)* — A list of supported languages.
- **passportColor** `string` *(required)* — The primary color used in the DID Wallet passport.
- **componentMountPoints** `BlockletComponent[]` *(required)* — A list of child components mounted by this Blocklet.
- **alsoKnownAs** `string[]` *(required)* — A list of alternative identifiers.
- **trustedFactories** `string[]` *(required)* — A list of trusted factory DIDs.
- **status** `string` *(required)* — The current running status of the Blocklet.
- **serverDid** `string` *(required)* — The DID of the Blocklet Server instance.
- **serverVersion** `string` *(required)* — The version of the Blocklet Server.
- **componentId** `string` *(required)* — The ID of the component.
- **webWalletUrl** `string` *(required)* — The URL of the web-based DID Wallet.
- **updatedAt** `number` *(required)* — Timestamp of the last update.
- **settings** `BlockletSettings` *(required)* — Detailed settings for the Blocklet.

### BlockletSettings

Contains various settings for the Blocklet, including session management, Federated Login Group configurations, and OAuth provider details.

- **session** `object` *(required)* — Session configuration.
  - **ttl** `number` *(required)* — Session time-to-live in seconds.
  - **cacheTtl** `number` *(required)* — Cache time-to-live in seconds.
- **federated** `object` *(required)* — Federated Login Group configuration.
  - **master** `object` *(required)* — Information about the master application in the group.
    - **appId** `string` *(required)* — Master application ID.
    - **appPid** `string` *(required)* — Master application process ID.
    - **appName** `string` *(required)* — Master application name.
    - **appDescription** `string` *(required)* — Master application description.
    - **appUrl** `string` *(required)* — Master application URL.
    - **appLogo** `string` *(required)* — Master application logo URL.
    - **version** `string` *(required)* — Master application version.
  - **config** `Record<string, any>` *(required)* — Additional configuration for the federated group.
- **oauth** `Record<string, { enabled: boolean; [x: string]: any }>` *(required)* — OAuth provider configurations, keyed by provider name.

### BlockletComponent

Describes a component that is mounted within a parent Blocklet. It inherits properties from `TComponentInternalInfo`.

- **status** `keyof typeof BlockletStatus` *(required)* — The running status of the component (e.g., 'running', 'stopped').

## User and Authentication Types

These types are used by the `AuthService` to manage user profiles, settings, and authentication-related data.

### UserPublicInfo

Represents the basic public profile information of a user.

- **avatar** `string` *(required)* — URL of the user's avatar image.
- **did** `string` *(required)* — The user's decentralized identifier (DID).
- **fullName** `string` *(required)* — The user's full name.
- **sourceAppPid** `string | null` *(required)* — The process ID of the application where the user originated, if applicable.

### NotificationConfig

Defines a user's notification preferences, including webhook configurations and notification channels.

- **webhooks** `Webhook[]` — An array of configured webhooks.
- **notifications** `object` — Channel-specific notification settings.
  - **email** `boolean` — Enable or disable email notifications.
  - **wallet** `boolean` — Enable or disable DID Wallet notifications.
  - **phone** `boolean` — Enable or disable phone notifications.

### Webhook

Defines the structure for a single webhook configuration.

- **type** `'slack' | 'api'` *(required)* — The type of the webhook endpoint.
- **url** `string` *(required)* — The URL to which the webhook notification will be sent.

### PrivacyConfig

An object representing a user's privacy settings, where keys correspond to specific privacy options.

- **[key]** `boolean` *(required)* — A dynamic key representing a privacy setting, with a boolean value indicating if it's enabled.

### SpaceGateway

Defines the properties of a DID Space gateway.

- **did** `string` *(required)* — The DID of the space gateway.
- **name** `string` *(required)* — The name of the space gateway.
- **url** `string` *(required)* — The public URL of the space gateway.
- **endpoint** `string` *(required)* — The API endpoint of the space gateway.

## Session Management Types

These types are used by the `UserSessionService` to manage user login sessions across different devices and applications.

### UserSession

Represents a single user login session, containing details about the device, application, and user.

- **appName** `string` *(required)* — Name of the application for the session.
- **appPid** `string` *(required)* — Process ID of the application for the session.
- **extra** `object` *(required)* — Additional metadata about the session.
  - **walletOS** `'android' | 'ios' | 'web'` *(required)* — The operating system of the wallet used for login.
- **id** `string` *(required)* — The unique identifier for the session.
- **lastLoginIp** `string` *(required)* — The IP address of the last login.
- **passportId** `string | null` *(required)* — The ID of the passport used for login.
- **ua** `string` *(required)* — The User-Agent string of the client.
- **createdAt** `string` — ISO string timestamp of when the session was created.
- **updatedAt** `string` *(required)* — ISO string timestamp of the last session activity.
- **status** `string` — The current status of the session (e.g., 'online', 'expired').
- **user** `UserSessionUser` — Detailed information about the user associated with the session.
- **userDid** `string` *(required)* — The DID of the user.
- **visitorId** `string` *(required)* — A unique identifier for the device/browser.

### UserSessionUser

Contains detailed user information associated with a `UserSession`.

- **avatar** `string` *(required)* — URL of the user's avatar image.
- **did** `string` *(required)* — The user's decentralized identifier (DID).
- **email** `string` *(required)* — The user's email address.
- **fullName** `string` *(required)* — The user's full name.
- **pk** `string` *(required)* — The user's public key.
- **remark** `string` — An optional remark or note about the user.
- **role** `string` *(required)* — The role of the user (e.g., 'owner', 'admin').
- **roleTitle** `string` *(required)* — The display title for the user's role.
- **sourceAppPid** `string | null` *(required)* — The process ID of the application where the user originated.
- **sourceProvider** `'wallet' | 'auth0' | 'nft'` *(required)* — The original provider used for authentication.

### UserSessionList

A paginated response object for a list of user sessions.

- **list** `UserSession[]` *(required)* — An array of user session objects.
- **paging** `object` *(required)* — Pagination information.
  - **page** `number` *(required)* — The current page number.
  - **pageSize** `number` *(required)* — The number of items per page.
  - **total** `number` *(required)* — The total number of sessions available.

## Global & Environment Types

These types define globally available objects and server environment configurations.

### ServerEnv

Represents server-side environment variables that are often exposed to the client-side as `window.env`.

- **appId** `string` *(required)* — The application ID.
- **appPid** `string` *(required)* — The application process ID.
- **appName** `string` *(required)* — The application name.
- **appDescription** `string` *(required)* — The application description.
- **apiPrefix** `string` *(required)* — The prefix for backend API routes.
- **baseUrl** `string` *(required)* — The base URL of the application.

### Global Window Declarations

The SDK relies on certain global variables being present in the `window` object when running in a browser environment.

**TypeScript Definition**

```typescript
declare global {
  interface Window {
    blocklet: Blocklet;
    env?: ServerEnv;
  }
}
```

## Utility Types

Helper types used for API requests and token management.

### TokenResult

Represents the successful result of a token refresh operation.

- **nextToken** `string` *(required)* — The new session token.
- **nextRefreshToken** `string` *(required)* — The new refresh token.

### RequestParams

Defines common parameters that can be used when making requests with the SDK's API helpers.

- **lazy** `boolean` — If true, the request may be debounced or delayed.
- **lazyTime** `number` — The delay time in milliseconds for a lazy request.
- **componentDid** `string` — The DID of the component to target with the request.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/getting-started-e6412e/

This guide will walk you through the essential steps to install the `@blocklet/js-sdk` and make your first API call. Our goal is to get you up and running in just a few minutes.

## Installation

First, you need to add the SDK to your project. You can use your preferred package manager:

**Installation**

```bash
npm install @blocklet/js-sdk

# or

yarn add @blocklet/js-sdk

# or

pnpm add @blocklet/js-sdk
```

## Basic Usage

The SDK is designed to be straightforward. The two most common use cases are accessing core Blocklet services (like user authentication) and making authenticated requests to your own Blocklet's backend.

### Accessing Core Services

The easiest way to use the SDK is by importing the `getBlockletSDK` singleton factory. This function ensures that you always get the same SDK instance throughout your application, simplifying state management.

Here's how you can use it to fetch the current user's profile:

**Get User Profile**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchUserProfile() {
  try {
    const { data: userProfile } = await sdk.user.getProfile();
    console.log('User Profile:', userProfile);
  } catch (error) {
    console.error('Failed to fetch user profile:', error);
  }
}

fetchUserProfile();
```

The `sdk` instance provides access to various services like `user`, `userSession`, `blocklet`, and more. These services handle communication with the well-known Blocklet service endpoints for you.

### Making API Requests to Your Blocklet

For communicating with your own Blocklet's backend API, the SDK provides `createAxios` and `createFetch` helper functions. These are wrappers around Axios and the native Fetch API that come pre-configured with everything needed for authenticated requests.

They automatically handle:

- Setting the correct `baseURL` for your component.
- Attaching the session token to the `Authorization` header.
- Including the `x-csrf-token` for security.
- Refreshing the session token automatically if it expires.

Here’s how to create an API client for your backend using `createAxios`:

**Create an API Client**

```javascript
import { createAxios } from '@blocklet/js-sdk';

// Create an Axios instance configured for your Blocklet
const apiClient = createAxios();

async function fetchData() {
  try {
    // Make a request to your own backend, e.g., GET /api/posts
    const response = await apiClient.get('/api/posts');
    console.log('Posts:', response.data);
  } catch (error) {
    console.error('Failed to fetch data:', error);
  }
}

fetchData();
```

With this setup, you don't need to manually manage tokens or headers. The SDK takes care of the authentication flow seamlessly.

## Next Steps

You've now learned how to install the `@blocklet/js-sdk` and use it for the two most common scenarios. To dive deeper, we recommend exploring the following guides:

::::card-group
::link-card{title="Making API Requests" description="Learn more about advanced configuration for `createAxios` and `createFetch`, including error handling and request parameters." icon="file" href="/en/docs/blocklet-sdk-browser/guides-making-api-requests-e6412e/"}
::link-card{title="Authentication" description="Understand how the SDK manages session and refresh tokens under the hood to keep your users logged in." icon="key" href="/en/docs/blocklet-sdk-browser/guides-authentication-e6412e/"}
::::

---

## Authentication

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/guides-authentication-e6412e/

The `@blocklet/js-sdk` is designed to make authentication seamless by automatically handling the complexities of token-based security. It manages session and refresh tokens behind the scenes, allowing you to focus on building your application's features.

This guide explains the automatic token renewal process and demonstrates how to use the `AuthService` to manage user authentication states, such as fetching profiles and logging out. For a detailed list of all available methods, please refer to the [AuthService API Reference](/en/docs/blocklet-sdk-browser/api-services-auth-e6412e/).

## Automatic Session Token Renewal

The SDK employs a standard and secure authentication flow using short-lived session tokens and long-lived refresh tokens. When you make an API call using the SDK's request helpers (see [Making API Requests](/en/docs/blocklet-sdk-browser/guides-making-api-requests-e6412e/)), the process is fully automated:

::::steps
:::step{title="Request Initiation"}
The SDK attaches the current `sessionToken` to the authorization header of your API request.
:::

:::step{title="Token Expiration"}
If the `sessionToken` has expired, the server responds with a `401 Unauthorized` error.
:::

:::step{title="Automatic Refresh"}
The SDK's request interceptor catches this `401` error. It then automatically sends the stored `refreshToken` to the authentication endpoint to obtain a new `sessionToken` and `refreshToken`.
:::

:::step{title="Request Retry"}
Once the new tokens are received and stored, the SDK transparently retries the original API request that failed. The new, valid `sessionToken` is used this time.
:::

:::step{title="Successful Response"}
The server validates the new token and returns a successful response, which is then passed back to your application code.
:::
::::

This entire process is invisible to your application logic, ensuring that user sessions remain active without interrupting the user experience.

The diagram below illustrates this flow:

![Authentication](https://media.arcblock.io/lib/bc/bcf7dabc63e359a2.w1600.webp)

## Managing User State with AuthService

The `AuthService` provides a high-level API for common authentication and user management tasks. You can access it through the main SDK instance.

### Getting the Current User's Profile

To fetch the profile information of the currently logged-in user, use the `getProfile` method.

**Getting the User Profile**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchUserProfile() {
  try {
    const profile = await sdk.auth.getProfile();
    console.log('User Profile:', profile);
    return profile;
  } catch (error) {
    console.error('Failed to fetch profile:', error);
  }
}

fetchUserProfile();
```

### Logging Out

The `logout` method invalidates the user's current session on the server. You can call it without arguments to log out the current device, or pass a `visitorId` to log out a specific session, which is useful for managing sessions across multiple devices.

**Logging Out a User**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function handleLogout() {
  try {
    // Logs out the current session
    await sdk.auth.logout();
    console.log('Successfully logged out.');
    // Redirect to the login page or update UI state
  } catch (error) {
    console.error('Logout failed:', error);
  }
}
```

### Deleting a User Account

For users who wish to delete their accounts, the SDK provides the `destroyMyself` method. This is a destructive and irreversible action that permanently removes the user's data.

**Deleting the Current User's Account**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function deleteAccount() {
  // It's crucial to confirm this action with the user
  if (window.confirm('Are you sure you want to delete your account? This action is irreversible.')) {
    try {
      const result = await sdk.auth.destroyMyself();
      console.log(`Account for DID ${result.did} has been deleted.`);
      // Perform cleanup and redirect the user
    } catch (error) {
      console.error('Failed to delete account:', error);
    }
  }
}
```

## Next Steps

Now that you understand how authentication works in the `@blocklet/js-sdk`, you might want to explore how to manage all of a user's active sessions.

:::action-card{title="Managing User Sessions" description="Learn how to fetch and manage a user's login sessions across different devices using the UserSessionService." icon="user"}
::action{label="Read Guide" href="/en/docs/blocklet-sdk-browser/guides-managing-user-sessions-e6412e/" variant="primary"}
:::

---

## Guides

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/guides-e6412e/

Welcome to the practical guides for the `@blocklet/js-sdk`. This section is designed to get you up and running with common tasks quickly. Each guide provides step-by-step instructions and code examples to help you integrate key features like making secure API calls, handling user authentication, and managing sessions in your Blocklet application.

These guides focus on real-world use cases to help you build robust features with confidence.

::::card-group
::link-card{title="Making API Requests" description="Learn how to use the built-in `createAxios` and `createFetch` helpers for making authenticated and auto-renewing API calls to Blocklet services." icon="routes" href="/en/docs/blocklet-sdk-browser/guides-making-api-requests-e6412e/"}
::link-card{title="Authentication" description="Understand how the SDK handles session tokens automatically and how to manage user profiles, privacy, and logout actions with `AuthService`." icon="key" href="/en/docs/blocklet-sdk-browser/guides-authentication-e6412e/"}
::link-card{title="Managing User Sessions" description="Discover how to fetch and manage a user's login sessions across different devices and applications using the `UserSessionService`." icon="smartphone" href="/en/docs/blocklet-sdk-browser/guides-managing-user-sessions-e6412e/"}
::::

## Next Steps

After reviewing the guides for the tasks you need to accomplish, you may want to dive deeper into the complete [API Reference](/en/docs/blocklet-sdk-browser/api-e6412e/) for a detailed breakdown of every class, method, and type available in the SDK.

---

## Making API Requests

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/guides-making-api-requests-e6412e/

The `@blocklet/js-sdk` provides powerful, pre-configured helpers for making API requests to your Blocklet services. These helpers, `createAxios` and `createFetch`, are designed to handle the complexities of authentication and session management automatically, so you can focus on building your application's features.

Key features include:

- <strong>Automatic Token Injection</strong>: Session tokens are automatically included in the `Authorization` header.
- <strong>Automatic Token Refresh</strong>: If a request fails with a 401 Unauthorized error, the SDK automatically attempts to refresh the session token and retries the original request once.
- <strong>CSRF Protection</strong>: The `x-csrf-token` header is attached to every request for enhanced security.
- <strong>Base URL Handling</strong>: Requests are automatically prefixed with the correct component mount point, eliminating manual URL construction.
- <strong>Secure Response Verification</strong>: An optional security layer to verify the integrity of responses from the Blocklet server.

## Using createAxios

For developers who prefer the `axios` library, the `createAxios` function returns an `axios` instance with all the benefits of the SDK's request handling baked in. It supports all standard `axios` configurations and features.

### Basic Usage

Here's how to create an instance and make a simple `GET` request:

**Basic Axios Request**

```javascript
import { createAxios } from '@blocklet/js-sdk';

// Create an axios instance managed by the SDK
const api = createAxios();

async function fetchData() {
  try {
    const response = await api.get('/api/users/profile');
    console.log('User Profile:', response.data);
  } catch (error) {
    console.error('Failed to fetch user profile:', error);
  }
}

fetchData();
```

In this example, `createAxios` configures the instance to automatically handle the authentication headers and token refresh logic. The request to `/api/users/profile` will be correctly routed to the component's backend.

### Custom Configuration

You can pass any valid `axios` configuration object to `createAxios` to customize its behavior, such as setting a custom base URL or adding default headers.

**Custom Axios Configuration**

```javascript
import { createAxios } from '@blocklet/js-sdk';

const customApi = createAxios({
  baseURL: '/api/v2/',
  timeout: 10000, // 10 seconds
  headers: { 'X-Custom-Header': 'MyValue' },
});

async function postData() {
  const response = await customApi.post('/items', { name: 'New Item' });
  console.log('Item created:', response.data);
}
```

## Using createFetch

If you prefer a more lightweight solution based on the standard Web `fetch` API, the `createFetch` function is the perfect choice. It provides a wrapper around `fetch` that includes the same automatic token management and security features as the `axios` helper.

### Basic Usage

The `createFetch` function returns an async function that has a similar signature to the native `fetch`.

**Basic Fetch Request**

```javascript
import { createFetch } from '@blocklet/js-sdk';

// Create a fetch instance managed by the SDK
const fetcher = createFetch();

async function fetchData() {
  try {
    const response = await fetcher('/api/users/profile');
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log('User Profile:', data);
  } catch (error) {
    console.error('Failed to fetch user profile:', error);
  }
}

fetchData();
```

### Custom Configuration

You can pass a default `RequestInit` object to `createFetch` to set global options for all requests made with that instance. You can also override these options on a per-request basis.

**Custom Fetch Configuration**

```javascript
import { createFetch } from '@blocklet/js-sdk';

// Set global options
const fetcher = createFetch({
  headers: {
    'Content-Type': 'application/json',
  },
});

async function postData() {
  const response = await fetcher('/api/items', {
    method: 'POST',
    body: JSON.stringify({ name: 'New Item' }),
  });
  const data = await response.json();
  console.log('Item created:', data);
}
```

## Automatic Token Renewal Flow

Both `createAxios` and `createFetch` handle session expiration gracefully. The diagram below illustrates the automated process that occurs when an API call is made with an expired token.

![Making API Requests](https://media.arcblock.io/lib/ae/ae80af0c011e3f0c.w1600.webp)

This entire flow is transparent to your application code, ensuring a seamless user experience without manual intervention.

## Secure Requests

For sensitive operations, you can enable an additional layer of security by verifying the signature of the API response. This ensures that the response was not tampered with between the server and the client. To enable this, set the `secure` option to `true` in your request configuration.

### With createAxios

**Axios Secure Request**

```javascript
import { createAxios } from '@blocklet/js-sdk';
const api = createAxios();

// The SDK will verify the response signature.
// If verification fails, the promise will be rejected with an error.
const response = await api.get('/api/billing/details', { secure: true });
```

### With createFetch

**Fetch Secure Request**

```javascript
import { createFetch } from '@blocklet/js-sdk';
const fetcher = createFetch();

const response = await fetcher('/api/billing/details', { secure: true });
// The response object is only returned if the signature is valid.
const data = await response.json();
```

## Next Steps

Now that you know how to make authenticated API requests, you may want to dive deeper into how the SDK manages user identity and sessions.

::::card-group
::link-card{title="Authentication" description="Learn about the concepts of session tokens and refresh tokens, and how to manage user authentication state." icon="key" href="/en/docs/blocklet-sdk-browser/guides-authentication-e6412e/"}
::link-card{title="API Reference" description="Explore the detailed API documentation for `createAxios`, `createFetch`, and other SDK components." icon="book-open" href="/en/docs/blocklet-sdk-browser/api-client-e6412e/"}
::::

---

## Managing User Sessions

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/guides-managing-user-sessions-e6412e/

The `@blocklet/js-sdk` provides a `UserSessionService` to help you fetch and manage user login sessions across different devices. This is particularly useful for building features like a "Security" or "Devices" page where users can see all their active sessions and understand where their account is being used.

This guide will walk you through the common use cases for managing user sessions.

### Accessing the UserSessionService

First, get an instance of the Blocklet SDK. The `UserSessionService` is available under the `userSession` property.

**SDK Initialization**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();
const userSessionService = sdk.userSession;
```

## Fetching Your Own Login Sessions

The most common task is to retrieve the list of sessions for the currently authenticated user. The `getMyLoginSessions` method allows you to do this with support for pagination and filtering.

**Fetching the current user's sessions**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

async function fetchMySessions() {
  try {
    const sdk = getBlockletSDK();
    // Fetch the first page of 10 online sessions
    const result = await sdk.userSession.getMyLoginSessions({}, {
      page: 1,
      pageSize: 10,
      status: 'online', // Optional filter: 'online' | 'expired' | 'offline'
    });

    console.log(`Total online sessions: ${result.paging.total}`);
    result.list.forEach(session => {
      console.log(`- Session on ${session.ua} last active at ${session.updatedAt}`);
    });
  } catch (error) {
    console.error('Failed to fetch sessions:', error);
  }
}

fetchMySessions();
```

### Parameters

The method signature is `getMyLoginSessions({ appUrl?: string }, params: UserSessionQuery)`. The second argument is a query object with the following parameters:

- **page** `number` (default: `1`) — The page number to retrieve.
- **pageSize** `number` (default: `10`) — The number of sessions per page.
- **status** `'online' | 'expired' | 'offline'` — Filter sessions by their current status.

### Response

The method returns a promise that resolves to a `UserSessionList` object.

- **** `object` — The response object containing the session list and pagination details.
  - **list** `UserSession[]` — An array of user session objects.
    - **** `object` — A single user session object.
      - **id** `string` — Unique identifier for the session.
      - **appName** `string` — Name of the application where the session was created.
      - **appPid** `string` — Blocklet PID of the application.
      - **lastLoginIp** `string` — The last known IP address for this session.
      - **ua** `string` — The User-Agent string of the client device.
      - **updatedAt** `string` — Timestamp of the last activity.
      - **status** `string` — The current status of the session (e.g., 'online').
      - **userDid** `string` — The DID of the user associated with the session.
  - **paging** `object` — Pagination information.
    - **page** `number` — The current page number.
    - **pageSize** `number` — The number of items per page.
    - **total** `number` — The total number of sessions matching the query.

## Fetching Sessions for a Specific User

In some cases, like an admin dashboard, you might need to fetch login sessions for a user other than the one who is currently logged in. The `getUserSessions` method allows you to do this by providing a user's DID.

**Fetching sessions for a specific DID**

```javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

async function fetchUserSessions(userDid) {
  try {
    const sdk = getBlockletSDK();
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });

    console.log(`Found ${sessions.length} sessions for user ${userDid}:`);
    sessions.forEach(session => {
      console.log(`- Session ID: ${session.id}, App: ${session.appName}`);
    });
  } catch (error) {
    console.error(`Failed to fetch sessions for user ${userDid}:`, error);
  }
}

// Replace with the target user's DID
fetchUserSessions('zNK...some...user...did');
```

### Parameters

- **did** `string` *(required)* — The DID of the user whose sessions to fetch.
- **appUrl** `string` — The base URL of the application. Defaults to the current Blocklet's service URL.

### Response

The method returns a promise that resolves to an array of `UserSession` objects.

- **** `UserSession[]` — An array of user session objects for the specified user.
  - **** `object` — A single user session object.
    - **id** `string` — Unique identifier for the session.
    - **appName** `string` — Name of the application where the session was created.
    - **appPid** `string` — Blocklet PID of the application.
    - **ua** `string` — The User-Agent string of the client device.
    - **updatedAt** `string` — Timestamp of the last activity.
    - **status** `string` — The current status of the session.
    - **userDid** `string` — The DID of the user associated with the session.

This guide has covered the primary ways to retrieve user session information using the SDK. For a complete list of all available methods and detailed type definitions, please refer to the [UserSessionService API Reference](/en/docs/blocklet-sdk-browser/api-services-user-session-e6412e/).

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-sdk-browser/overview-e6412e/

The `@blocklet/js-sdk` is a comprehensive JavaScript library designed to streamline interactions with Blocklet services. Whether you're building a front-end application or a back-end service, this SDK provides a robust set of tools to handle authentication, session management, and API communication, allowing you to focus on building features rather than wrestling with low-level details.

It simplifies the entire process by abstracting away the complexities of token management and providing intuitive, high-level services for common tasks.

## Core Features

The SDK is built around a few key principles to make your development experience as smooth as possible.

::::card-group
::link-card{title="Simplified API Requests" description="Provides `createAxios` and `createFetch` helpers that come pre-configured with everything needed for authenticated API calls, including base URLs and interceptors." icon="send"}
::link-card{title="Automatic Token Management" description="Automatically handles the lifecycle of session and refresh tokens. It transparently renews expired tokens, ensuring your application remains authenticated without manual intervention." icon="key"}
::link-card{title="Modular Service Architecture" description="Organizes functionality into distinct services like `AuthService`, `UserSessionService`, and `BlockletService`, offering a clean and organized API surface." icon="box"}
::::

## How It Works

Your application interacts with the SDK's services and request helpers. The SDK, in turn, manages all communication with the Blocklet API, handling the complexities of authentication and token renewal under the hood. This architecture ensures that your application code remains clean and focused on business logic. The following diagram illustrates this relationship:

![Overview](https://media.arcblock.io/lib/2f/2f757138def2b3fc.w1600.webp)

## Get Started

Ready to integrate the SDK into your project? Our Getting Started guide will walk you through the installation process and help you make your first API call in minutes.

:::action-card{title="Getting Started" description="Follow our step-by-step guide to install the SDK and configure your application." icon="rocket"}
::action{label="Start Building" href="/en/docs/blocklet-sdk-browser/getting-started-e6412e/" variant="primary"}
:::

---

## Blocklet SDK (Node.js)

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/

---

## API Reference

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/api-reference-c33146/

Welcome to the Blocklet SDK API Reference. This section provides a detailed breakdown of all the modules, classes, functions, and utilities exported by the SDK. Whether you're managing users, sending notifications, or securing your application, you'll find the necessary details here.

For a practical, task-based approach to using these APIs, please see our [Guides](/en/docs/blocklet-sdk-nodejs/guides-c33146/). For detailed TypeScript definitions, refer to the [Type Definitions](/en/docs/blocklet-sdk-nodejs/api-reference-types-c33146/) section.

## Main Exports

The Blocklet SDK is organized into several modules, each providing a specific set of functionalities. Here’s a quick overview of the primary modules you'll be working with.

::::card-group
::link-card{title="BlockletService" description="A powerful client for interacting with the underlying Blocklet Server API to manage users, roles, permissions, and more." icon="server"}
::link-card{title="NotificationService" description="Handles real-time communication, allowing you to send notifications to users and listen for system-wide events." icon="bell"}
::link-card{title="EventBus" description="An event-driven messaging system for communication between different parts of your application." icon="git-merge"}
::link-card{title="Middlewares" description="A collection of pre-built Express.js middlewares for handling sessions, authentication, CSRF protection, and more." icon="layers"}
::link-card{title="Component Utilities" description="Functions to facilitate secure communication between different components within your blocklet." icon="box"}
::link-card{title="Config & Env" description="Access runtime configuration, environment variables, and information about other components." icon="settings"}
::link-card{title="Wallet Utilities" description="Tools for creating and managing wallet instances, essential for signing and authentication." icon="wallet"}
::link-card{title="Security Utilities" description="Provides essential security functions like data encryption/decryption and response signing." icon="shield"}
::::

## BlockletService

The `BlockletService` is a client that provides a comprehensive API for managing users, roles, permissions, and other core blocklet functionalities. It acts as an interface to the Blocklet Server's GraphQL API.

**Service Initialization**

```javascript
import { BlockletService } from '@blocklet/sdk';

const blockletService = new BlockletService();

async function getOwnerInfo() {
  const { user } = await blockletService.getOwner();
  console.log('Owner:', user);
}
```

### Key Methods

The service exposes a wide range of methods. Here are some of the most commonly used ones:

| Method  | Description  |
|---|---|
| `login(data)`  | Authenticates a user with the provided credentials.  |
| `refreshSession(data)`  | Refreshes a user's session using a refresh token.  |
| `getUser(did, options)`  | Retrieves a single user's profile by their DID.  |
| `getUsers(args)`  | Retrieves a paginated list of users.  |
| `getOwner()`  | Retrieves the blocklet owner's profile.  |
| `updateUserApproval(did, approved)`  | Approves or disapproves a user's access.  |
| `createRole(args)`  | Creates a new user role with a name, title, and description.  |
| `getRoles()`  | Retrieves a list of all available roles.  |
| `deleteRole(name)`  | Deletes a role by its name.  |
| `grantPermissionForRole(roleName, permissionName)`  | Grants a specific permission to a role.  |
| `revokePermissionFromRole(roleName, permissionName)`  | Revokes a permission from a role.  |
| `hasPermission(role, permission)`  | Checks if a role has a specific permission.  |
| `getPermissions()`  | Retrieves a list of all available permissions.  |
| `getBlocklet(attachRuntimeInfo)`  | Fetches metadata and settings for the current blocklet.  |
| `getComponent(did)`  | Retrieves the metadata for a specific component.  |
| `createAccessKey(params)`  | Creates a new access key for programmatic access.  |
| `verifyAccessKey(params)`  | Verifies the validity of an access key.  |

For a full list of methods and their parameters, please refer to the [Type Definitions](/en/docs/blocklet-sdk-nodejs/api-reference-types-c33146/).

## NotificationService

The `NotificationService` enables real-time communication. You can send notifications directly to users or broadcast messages to public channels. It also allows you to listen for system events.

**Sending a Notification**

```javascript
import NotificationService from '@blocklet/sdk/service/notification';

async function notifyUser(userId, message) {
  const notification = {
    type: 'info',
    title: 'New Update',
    content: message,
  };
  await NotificationService.sendToUser(userId, notification);
}
```

### Main Functions

| Function  | Description  |
|---|---|
| `sendToUser(receiver, notification, options)`  | Sends a direct notification to one or more users.  |
| `sendToMail(receiver, notification, options)`  | Sends a notification to a user's email.  |
| `broadcast(notification, options)`  | Broadcasts a message to the blocklet's public channel.  |
| `on(event, callback)`  | Subscribes to a system event (e.g., component updates, user events).  |
| `off(event, callback)`  | Unsubscribes from a system event.  |

## EventBus

The `EventBus` provides a simple publish-subscribe mechanism for communication within your application, helping you build decoupled, event-driven features.

**Publishing an Event**

```javascript
import EventBus from '@blocklet/sdk/service/eventbus';

// In one part of your app
async function publishOrderCreated(orderData) {
  await EventBus.publish('order.created', { data: orderData });
}

// In another part of your app
EventBus.subscribe((event) => {
  if (event.type === 'order.created') {
    console.log('New order received:', event.data);
  }
});
```

### Functions

| Function  | Description  |
|---|---|
| `publish(name, event)`  | Publishes an event with a specific name and payload.  |
| `subscribe(callback)`  | Subscribes to all events, executing the callback for each one received.  |
| `unsubscribe(callback)`  | Removes a previously registered event subscriber.  |

## Middlewares

The SDK provides a suite of pre-configured Express.js middlewares to handle common web server tasks like authentication, session management, and security.

**Using Middlewares**

```javascript
import express from 'express';
import middlewares from '@blocklet/sdk/middlewares';

const app = express();

// Session middleware must be used before auth middleware
app.use(middlewares.session());

// Protect a route, requiring 'admin' role
app.get('/admin', middlewares.auth({ roles: ['admin'] }), (req, res) => {
  res.send('Welcome, admin!');
});
```

### Available Middlewares

| Middleware  | Description  |
|---|---|
| `session()`  | Parses and verifies user sessions from tokens or access keys, attaching user info to `req.session`.  |
| `auth(rules)`  | Protects routes based on roles and permissions. Throws a 403 Forbidden error if the user is not authorized.  |
| `user()`  | A lightweight middleware that attaches user information to `req.user` if a valid session exists, but does not block unauthenticated requests.  |
| `component()`  | Middleware for securing routes that are only accessible by other components within the same blocklet.  |
| `csrf()`  | Implements CSRF (Cross-Site Request Forgery) protection.  |
| `sitemap()`  | Generates a `sitemap.xml` file for your application.  |
| `fallback()`  | A fallback middleware for Single Page Applications (SPAs) that serves `index.html` for unknown routes.  |

## Component Utilities

These utilities are designed for inter-component communication and URL management.

**Calling Another Component**

```javascript
import component from '@blocklet/sdk/component';

async function fetchUserDataFromProfileComponent() {
  try {
    const response = await component.call({
      name: 'profile-component-did', // The DID of the target component
      path: '/api/user-data',
      method: 'GET',
    });
    return response.data;
  } catch (error) {
    console.error('Failed to call component:', error);
  }
}
```

### Main Functions

| Function  | Description  |
|---|---|
| `call(options, retryOptions)`  | Makes a secure HTTP request to another component within the same blocklet.  |
| `getUrl(...parts)`  | Constructs an absolute public URL for a path within the current component.  |
| `getRelativeUrl(...parts)`  | Constructs a relative URL for a path within the current component.  |
| `getResources(options)`  | Retrieves a list of resource components available to the blocklet.  |
| `waitForComponentRunning(name, timeout)`  | Waits until a specified component is running and reachable.  |

## Config & Env

Access your blocklet's configuration, environment variables, and component metadata through the `config` export.

**Accessing Environment Data**

```javascript
import config from '@blocklet/sdk/config';

// Access environment variables
const appName = config.env.appName;
const appUrl = config.env.appUrl;

// Access the list of other components
const allComponents = config.components;
const databaseComponent = config.components.find(c => c.name === 'database');
```

### Key Properties

| Property  | Description  |
|---|---|
| `config.env`  | An object containing environment variables and application settings (e.g., `appName`, `appUrl`, `isComponent`).  |
| `config.components`  | An array of objects, where each object contains metadata about a mounted component (e.g., `did`, `name`, `status`, `mountPoint`).  |
| `config.logger`  | A logger instance (`info`, `warn`, `error`, `debug`).  |
| `config.events`  | An `EventEmitter` that fires when the blocklet's configuration or component list changes.  |

## Wallet Utilities

The `getWallet` function provides an easy way to create wallet instances from the secret keys provided in the environment. These wallets are essential for any cryptographic operations, such as signing data.

**Creating a Wallet**

```javascript
import getWallet from '@blocklet/sdk/wallet';

// Get the default wallet for the current application instance
const wallet = getWallet();
console.log('Wallet Address:', wallet.address);

// Get the permanent wallet associated with the blocklet's DID
const permanentWallet = getWallet.getPermanentWallet();
console.log('Permanent Wallet Address:', permanentWallet.address);
```

### Functions

| Function  | Description  |
|---|---|
| `getWallet(type, sk)`  | Creates a wallet instance. By default, it uses the application's runtime secret key (`BLOCKLET_APP_SK`).  |
| `getWallet.getPermanentWallet()`  | A shortcut to get the wallet derived from the permanent secret key (`BLOCKLET_APP_PSK`).  |
| `getWallet.getEthereumWallet(permanent)`  | Creates an Ethereum-compatible wallet.  |

## Security Utilities

The SDK includes a `security` module with helper functions for common cryptographic tasks like encryption and response signing.

**Encrypting Data**

```javascript
import security from '@blocklet/sdk/security';

const sensitiveData = 'This is a secret message';

// Encrypt data using the blocklet's encryption key
const encrypted = security.encrypt(sensitiveData);

// Decrypt it later
const decrypted = security.decrypt(encrypted);

console.log(decrypted === sensitiveData); // true
```

### Functions

| Function  | Description  |
|---|---|
| `encrypt(message, password, salt)`  | Encrypts a string using AES. Uses `BLOCKLET_APP_EK` and `BLOCKLET_DID` by default.  |
| `decrypt(message, password, salt)`  | Decrypts a string that was encrypted with `encrypt`.  |
| `signResponse(data)`  | Signs a data payload with the blocklet's wallet, adding signature metadata.  |
| `verifyResponse(data)`  | Verifies the signature of a response signed with `signResponse`.  |

---

## Type Definitions

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/api-reference-types-c33146/

The Blocklet SDK is strongly typed to help you write more robust and maintainable code. This section provides a reference for the most common TypeScript types and interfaces you'll encounter when working with user sessions, notifications, events, and blocklet configurations. Understanding these types will help ensure type safety and leverage your IDE's autocompletion features effectively.

## Session & User Types

These types are fundamental for managing user authentication and identity within your application.

### SessionUser

The `SessionUser` object is attached to the `request` object (as `req.user`) by the session middleware. It contains essential information about the currently logged-in user.

**SessionUser Type Definition**

```typescript
export type SessionUser = {
  did: string;
  role: string | undefined;
  provider: string;
  fullName: string;
  walletOS: string;
  emailVerified?: boolean;
  phoneVerified?: boolean;
  method?: AuthMethod;
  kyc?: number;
  [key: string]: any;
};
```

- **did** `string` *(required)* — The user's Decentralized Identifier (DID).
- **role** `string | undefined` — The role assigned to the user (e.g., 'admin', 'owner', 'guest').
- **provider** `string` *(required)* — The authentication provider used for login (e.g., 'wallet').
- **fullName** `string` *(required)* — The user's full name.
- **walletOS** `string` *(required)* — The operating system of the user's wallet.
- **emailVerified** `boolean` — Indicates if the user's email has been verified.
- **phoneVerified** `boolean` — Indicates if the user's phone has been verified.
- **method** `AuthMethod` — The authentication method used. Common values are 'loginToken', 'componentCall', 'signedToken', 'accessKey'.
- **kyc** `number` — A numeric representation of the user's KYC status.

### TUserInfo

The `TUserInfo` type provides a comprehensive view of a user's profile, including their identity, contact information, login history, and associated security credentials.

- **did** `string` *(required)* — The user's Decentralized Identifier (DID).
- **pk** `string` *(required)* — The user's public key.
- **role** `string` *(required)* — The primary role of the user.
- **avatar** `string` *(required)* — URL to the user's avatar image.
- **fullName** `string` *(required)* — The user's full name.
- **email** `string` *(required)* — The user's email address.
- **approved** `boolean` *(required)* — Indicates if the user account has been approved.
- **createdAt** `number` *(required)* — Timestamp of when the user was created.
- **lastLoginAt** `number` *(required)* — Timestamp of the user's last login.
- **passports** `TPassport[]` *(required)* — An array of passports issued to the user.
- **connectedAccounts** `TConnectedAccount[]` *(required)* — A list of external accounts linked to the user's profile.

## Notification Types

When using the [Notification Service](/en/docs/blocklet-sdk-nodejs/services-notification-service-c33146/), you will work with these types to construct and send messages to users.

### TNotification

This is the main interface for defining a notification. It includes all the necessary fields to control the content, appearance, and behavior of a notification.

- **id** `string` — A unique identifier for the notification.
- **title** `string` — The main title of the notification.
- **body** `string` — The main content or message of the notification.
- **type** `'notification' | 'connect' | 'feed' | 'hi' | 'passthrough'` — The type of notification, which can affect its handling and presentation.
- **severity** `'normal' | 'success' | 'error' | 'warning'` — The severity level, often used to color-code the notification.
- **actions** `TNotificationAction[]` — An array of interactive action buttons to include in the notification.
- **attachments** `TNotificationAttachment[]` — An array of rich content attachments, such as images, text blocks, or links.
- **activity** `TNotificationActivity` — Describes a social activity, like a comment or follow, that triggered the notification.
- **url** `string` — A URL to navigate to when the notification is clicked.

### TNotificationAttachment

Attachments allow you to add rich, structured content to your notifications.

- **type** `'asset' | 'vc' | 'token' | 'text' | 'image' | 'divider' | 'transaction' | 'dapp' | 'link' | 'section'` *(required)* — The type of content to display.
- **data** `any` — The data payload for the attachment, which varies depending on the type. For example, an 'image' type would have an object with a url property.
- **fields** `any` — Additional fields to display within the attachment, often used for 'section' types.

<strong>Example: Image Attachment</strong>

```json
{
  "type": "image",
  "data": {
    "url": "https://path.to/your/image.png",
    "alt": "Descriptive text for the image"
  }
}
```

### TNotificationAction

Actions are interactive buttons that can be added to a notification, allowing users to respond directly.

- **name** `string` *(required)* — The name of the action, often used as an identifier.
- **title** `string` — The text displayed on the button. Defaults to name if not provided.
- **link** `string` — The URL to navigate to when the button is clicked.
- **color** `string` — The text color of the button.
- **bgColor** `string` — The background color of the button.

## Event Types

When working with the event bus, events are structured using the `TEvent` interface.

### TEvent

This interface defines the structure for events emitted and consumed within the Blocklet ecosystem.

- **id** `string` *(required)* — A unique identifier for the event instance.
- **type** `string` *(required)* — The event type name (e.g., 'user:created', 'post:published').
- **time** `Date` *(required)* — The timestamp when the event occurred.
- **source** `unknown` *(required)* — The source or originator of the event.
- **spec_version** `string` *(required)* — The CloudEvents specification version.
- **object_id** `string` — The ID of the object that the event pertains to.
- **object_type** `string` — The type of the object that the event pertains to.
- **data** `object` *(required)* — The payload of the event, containing details about what happened.

## Configuration & State Types

These types define the structure of configuration objects and state information for your blocklet.

### WindowBlocklet

On the client-side, the `window.blocklet` object provides essential context about the running blocklet. This object is typed as `WindowBlocklet`.

- **did** `string` *(required)* — The DID of the blocklet instance.
- **appId** `string` *(required)* — The application ID.
- **appName** `string` *(required)* — The display name of the application.
- **appUrl** `string` *(required)* — The public URL of the application.
- **webWalletUrl** `string` *(required)* — The URL of the associated web wallet.
- **isComponent** `boolean` *(required)* — true if the blocklet is running as a component of another blocklet.
- **prefix** `string` *(required)* — The URL prefix for the blocklet's routes.
- **theme** `TTheme` *(required)* — The current theme settings for the UI.
- **navigation** `TNavigationItem[]` *(required)* — An array of navigation items for the application menu.

### TBlockletState

This type represents the complete state of a blocklet instance on the server, including its metadata, status, configuration, and relationship with other components.

- **meta** `TBlockletMeta` — The metadata of the blocklet, from its blocklet.yml file.
- **status** `enum_pb.BlockletStatusMap` *(required)* — The current running status of the blocklet (e.g., 'running', 'stopped').
- **port** `number` *(required)* — The port the blocklet is running on.
- **appDid** `string` *(required)* — The DID of the blocklet instance.
- **children** `TComponentState[]` *(required)* — An array of component states if this blocklet has children.
- **settings** `TBlockletSettings` — The user-configured settings for the blocklet.
- **environments** `TConfigEntry[]` *(required)* — A list of environment variables configured for the blocklet.

---

## Authorization Middleware

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/authentication-auth-middleware-c33146/

The `auth` middleware is a powerful tool for adding a layer of authorization to your blocklet's routes. It works in conjunction with the [session middleware](/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/) to protect endpoints by verifying a user's role, specific permissions, Know Your Customer (KYC) status, and the authentication method used. This ensures that only authorized users can access sensitive or restricted resources.

## Usage

To use the `auth` middleware, you import it from `@blocklet/sdk/middlewares` and apply it to any Express.js route or router that requires protection. You can pass a configuration object to specify the authorization rules.

Here is a basic example of protecting an admin-only route:

**routes/admin.js**

```javascript
const auth = require('@blocklet/sdk/middlewares/auth');
const router = require('express').Router();

// This route is only accessible to users with the 'admin' role.
router.get('/dashboard', auth({ roles: ['admin'] }), (req, res) => {
  res.json({
    message: 'Welcome to the admin dashboard!',
    user: req.user,
  });
});

module.exports = router;
```

If an unauthorized user attempts to access this route, the middleware will automatically respond with a `403 Forbidden` error. If the user is not logged in at all, it will respond with a `401 Unauthorized` error.

## Authorization Flow

The middleware evaluates authorization rules in a specific order. If a check fails at any point, it immediately rejects the request with the appropriate HTTP error code.

![Authorization Middleware](https://media.arcblock.io/lib/16/16c8c13a02349c1b.w1600.webp)

## Configuration Options

The `auth` middleware accepts a configuration object with the following properties to define fine-grained access control rules.

- **roles** `string[]` — An array of role names. The user must have at least one of these roles to be granted access. If the user's role is not in this list, the middleware will return a 403 Forbidden error.
- **permissions** `string[]` — An array of permission names. The middleware checks the permissions associated with the user's role. The user's role must have at least one of the specified permissions. If not, it returns a 403 Forbidden error. This check requires the Blocklet Service to be running.
- **kyc** `('email' | 'phone')[]` — An array specifying required KYC (Know Your Customer) verification methods. You can require email verification, phone verification, or both. If the user has not completed the required verification steps, the middleware returns a 403 Forbidden error with the message "kyc required".
- **methods** `AuthMethod[]` — An array of allowed authentication methods. The SessionUser object includes a method property indicating how the session was established (e.g., loginToken, accessKey, componentCall). If the user's authentication method is not in this list, the middleware returns a 403 Forbidden error.

### Example: Requiring Multiple Conditions

You can combine these options to create complex authorization rules. For example, to protect a route that should only be accessible to paying subscribers who have verified their email and are not using a temporary access key:

**routes/billing.js**

```javascript
const auth = require('@blocklet/sdk/middlewares/auth');
const router = require('express').Router();

router.post(
  '/update-subscription',
  auth({
    roles: ['subscriber'],
    kyc: ['email'],
    methods: ['loginToken', 'signedToken'], // Disallow access via accessKey
  }),
  (req, res) => {
    // Logic to update subscription
    res.json({ success: true, message: 'Subscription updated.' });
  }
);

module.exports = router;
```

In this example, a user must satisfy all three conditions:

1. Have the `subscriber` role.
2. Have their email address verified.
3. Have authenticated using a standard login token or a signed token, not a simple access key.

## Summary

The `auth` middleware is an essential utility for securing your blocklet's endpoints. By combining role, permission, KYC, and authentication method checks, you can implement robust and granular access control with minimal code.

For more information on managing users and sessions, please see the following sections:

- [Session Middleware](/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/): Learn how to establish a user session, which is a prerequisite for this authorization middleware.
- [Blocklet Service](/en/docs/blocklet-sdk-nodejs/services-blocklet-service-c33146/): Understand how to programmatically manage roles and permissions that this middleware relies on.

---

## Authentication

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/authentication-c33146/

In modern web applications, robust authentication and authorization are critical for security and user management. The Blocklet SDK provides a comprehensive suite of tools to implement these features seamlessly, leveraging decentralized identity (DID) for a secure and user-centric experience.

This section provides an overview of the key components for managing user identity, sessions, and access control in your blocklet. You will learn how to integrate DID Connect for login, verify user sessions with powerful middleware, and protect your application's routes with fine-grained authorization rules.

The authentication and authorization flow typically follows these steps, as illustrated in the diagram below:

![Authentication](https://media.arcblock.io/lib/75/7512f33264081518.w1600.webp)

::::steps
:::step{title="User Login"}
The user initiates a login request via DID Connect.
:::

:::step{title="Session Creation"}
Upon successful authentication, a session is created and a token is issued to the user.
:::

:::step{title="Session Verification"}
For subsequent requests, the `sessionMiddleware` validates the user's token.
:::

:::step{title="Access Control"}
The `authMiddleware` checks if the authenticated user has the necessary roles or permissions to access the requested resource.
:::

:::step{title="Resource Access"}
If both session verification and authorization succeed, the user is granted access to the resource.
:::
::::

To implement these features, you will primarily work with three key modules. The following sub-documents provide detailed guides and API references for each of these components.

::::card-group
::link-card{title="DID Connect" description="Integrate decentralized identity for user login using WalletAuthenticator and WalletHandler." icon="key" href="/en/docs/blocklet-sdk-nodejs/authentication-did-connect-c33146/"}
::link-card{title="Session Middleware" description="Learn to use the session middleware to verify user sessions from login tokens, access keys, or secure component calls." icon="shield-check" href="/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/"}
::link-card{title="Authorization Middleware" description="Protect your application's routes by implementing role-based and permission-based access control." icon="lock" href="/en/docs/blocklet-sdk-nodejs/authentication-auth-middleware-c33146/"}
::::

By combining these tools, you can build a secure and flexible authentication and authorization system for your blocklet, ensuring that only authenticated and authorized users can access protected resources.

Proceed to the [DID Connect](/en/docs/blocklet-sdk-nodejs/authentication-did-connect-c33146/) guide to begin implementing user login.

---

## DID Connect

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/authentication-did-connect-c33146/

The Blocklet SDK provides a streamlined way to integrate decentralized identity into your application using DID Connect. This allows users to log in securely and manage their data using a DID Wallet, offering a passwordless and user-centric authentication experience. The core components for this functionality are `WalletAuthenticator` and `WalletHandler`.

These utilities are built upon the robust `@arcblock/did-connect-js` library, simplifying the setup process within the Blocklet environment.

### How It Works

The typical DID Connect login flow involves the user, your application's frontend and backend, and the user's DID Wallet.

![DID Connect](https://media.arcblock.io/lib/9a/9a540a3a3d58dbf2.w1600.webp)

## Basic Setup

Setting up DID Connect in your Blocklet is straightforward. You need to instantiate the `WalletAuthenticator` and `WalletHandler`, providing a storage mechanism for session data.

Here is a typical setup in an Express.js application:

**Basic DID Connect Setup**

```javascript
import path from 'path';
import AuthStorage from '@arcblock/did-connect-storage-nedb';
import WalletAuthenticator from '@blocklet/sdk/lib/wallet-authenticator';
import WalletHandler from '@blocklet/sdk/lib/wallet-handler';

// 1. Initialize the authenticator
export const authenticator = new WalletAuthenticator();

// 2. Initialize the handler with the authenticator and a storage solution
export const handlers = new WalletHandler({
  authenticator,
  tokenStorage: new AuthStorage({
    dbPath: path.join(process.env.BLOCKLET_DATA_DIR, 'auth.db'),
  }),
});

// 3. Mount the handlers to your Express app
// app.use('/api/did/auth', handlers);
```

<strong>Code Breakdown:</strong>

::::steps
:::step{title="`WalletAuthenticator`"}
This class is responsible for creating and managing DID Connect sessions. It generates the data that will be encoded into the QR code displayed to the user.
:::

:::step{title="`@arcblock/did-connect-storage-nedb`"}
This is a file-based storage adapter for persisting session tokens. It's a convenient choice for Blocklets as it stores data within the blocklet's data directory (`BLOCKLET_DATA_DIR`).
:::

:::step{title="`WalletHandler`"}
This class handles the entire authentication lifecycle. It manages session creation, status updates (e.g., when a user scans the QR code), and the final authentication response from the wallet.
:::
::::

## Configuration

The `WalletHandler` constructor accepts an options object to customize its behavior. Here are some of the key parameters:

- **authenticator** `WalletAuthenticator` *(required)* — An instance of WalletAuthenticator.
- **tokenStorage** `object` *(required)* — A storage instance for persisting session tokens, e.g., AuthStorage from '@arcblock/did-connect-storage-nedb'.
- **autoConnect** `boolean` (default: `true`) — If true, returning users who have previously connected their wallet can log in automatically without needing to scan the QR code again. This is achieved by sending a push notification to their wallet.
- **connectedDidOnly** `boolean` (default: `false`) — If true, only the DID of the currently logged-in user (if any) can be used to connect. This is useful for scenarios where a user needs to link a wallet to an existing account.

### Customizing App Information

When a user scans the QR code, their DID Wallet displays information about your application, such as its name, description, and icon. The SDK automatically populates this using your blocklet's metadata. However, you can override this information by passing an `appInfo` function to the `WalletAuthenticator` constructor.

**Customizing App Info**

```javascript
import WalletAuthenticator from '@blocklet/sdk/lib/wallet-authenticator';

const authenticator = new WalletAuthenticator({
  async appInfo() {
    // This function can return custom app info
    // The returned object will be merged with the default info
    return {
      name: 'My Custom App Name',
      description: 'A custom description for the DID Connect request.',
      icon: 'https://my-app.com/logo.png',
    };
  },
});
```

## Further Reading

The `WalletAuthenticator` and `WalletHandler` provided by the Blocklet SDK are convenient wrappers for the more comprehensive `@arcblock/did-connect-js` library. For advanced use cases, deeper customization, or a more thorough understanding of the underlying mechanics, please refer to the official DID Connect SDK documentation.

:::action-card{title="DID Connect SDK Documentation" description="Explore the full capabilities of the DID Connect protocol and its JavaScript SDKs for building powerful decentralized applications." icon="book-open"}
::action{label="Read More" href="/en/docs/did-connect-sdk/did-connect-sdk-overview/" variant="primary"}
:::

After a user successfully authenticates, the next step is to manage their session within your application. The Blocklet SDK provides a robust middleware for this purpose.

To learn how to verify user sessions and protect your routes, proceed to the next section on [Session Middleware](/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/).

---

## Session Middleware

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/

The `session` middleware is a core component of the Blocklet SDK's authentication system. It acts as a gatekeeper for your Express.js routes, verifying the identity of the requester and, upon successful authentication, attaching a `SessionUser` object to the `req.user` property. This allows subsequent middleware and route handlers to access authenticated user information easily.

The middleware is highly flexible, supporting several authentication strategies out of the box, including login tokens from [DID Connect](/en/docs/blocklet-sdk-nodejs/authentication-did-connect-c33146/), programmatic access keys, and secure inter-component calls.

## How It Works

The session middleware inspects incoming requests for credentials in a specific order of priority. If a valid credential is found, it populates `req.user` and passes control to the next handler. If no valid credential is found, its behavior depends on whether `strictMode` is enabled.

![Session Middleware](https://media.arcblock.io/lib/f0/f0709aa1479b4fa0.w1600.webp)

An additional security check is performed if the `enableBlacklist` feature is turned on in your blocklet's settings. Before validating a login token, the middleware will call a service API to ensure the token has not been revoked or blocked.

## Basic Usage

You can apply the `session` middleware to your entire application or to specific routes that require authentication.

**Applying Session Middleware**

```javascript
import express from 'express';
import session from '@blocklet/sdk/middlewares/session';

const app = express();

// Apply to all routes
app.use(session());

// Or apply to a specific route that must be protected
app.get('/api/profile', session({ strictMode: true }), (req, res) => {
  // In strict mode, if req.user is not present, the middleware would have already sent a 401 response.
  if (req.user) {
    res.json(req.user);
  }
});

// A public route that behaves differently for logged-in users
app.get('/api/info', session(), (req, res) => {
  if (req.user) {
    res.json({ message: `Hello, ${req.user.fullName}`});
  } else {
    // In non-strict mode, req.user is undefined for unauthenticated users
    res.json({ message: 'Hello, guest.' });
  }
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});
```

## Configuration Options

The `sessionMiddleware` function accepts an optional configuration object to tailor its behavior.

- **strictMode** `boolean` (default: `false`) — If `true`, an invalid or missing token results in a `401 Unauthorized` response. If `false`, it calls `next()` without a `user` object, treating the request as unauthenticated.

- **loginToken** `boolean` (default: `true`) — Enables authentication via standard JWT login tokens, typically from DID Connect, found in the `login_token` cookie.

- **accessKey** `boolean` (default: `false`) — Enables authentication via long-lived access keys (e.g., for CI/CD or scripts). These are also read from the `login_token` cookie.

- **componentCall** `boolean` (default: `false`) — Enables authentication for secure, signed requests from other components, verified using headers like `x-component-sig`.

- **signedToken** `boolean` (default: `false`) — Enables authentication via a temporary, signed JWT passed as a query parameter.

- **signedTokenKey** `string` (default: `__jwt`) — The name of the query parameter used for `signedToken` authentication.

### Example Configurations

::::card-group
::link-card{title="Strict API Endpoint" description="For endpoints that must be protected, `strictMode` ensures unauthenticated requests are rejected immediately." icon="shield-check"}
::::

```
```javascript
app.use('/api/admin', session({ strictMode: true }));
```
```

**Enable Access Keys**

```javascript
app.use('/api/data', session({ accessKey: true }));
```

## The SessionUser Object

When authentication is successful, the `req.user` object is populated with the following structure. This object provides essential information about the authenticated user or component.

- **user** `object` — The SessionUser object attached to `req.user` upon successful authentication.
  - **did** `string` *(required)* — The Decentralized Identifier (DID) of the user.
  - **role** `string` *(required)* — The role assigned to the user (e.g., `owner`, `admin`, `guest`).
  - **provider** `string` *(required)* — The authentication provider used (e.g., `wallet`, `accessKey`).
  - **fullName** `string` *(required)* — The user's full name or a remark associated with the credential.
  - **method** `AuthMethod` *(required)* — The specific authentication method used for this session (e.g., `loginToken`, `accessKey`, `componentCall`).
  - **walletOS** `string` *(required)* — The operating system of the wallet used, if applicable.
  - **emailVerified** `boolean` — Indicates if the user's email has been verified.
  - **phoneVerified** `boolean` — Indicates if the user's phone has been verified.

Here is an example of what the `req.user` object might look like after a successful login:

**Example req.user Object**

```json
{
  "did": "z8iZgeJjzB6Q1bK2rR1BfA2J8cNEJ8cNEJ8c",
  "role": "owner",
  "fullName": "Alice",
  "provider": "wallet",
  "walletOS": "ios",
  "emailVerified": true,
  "phoneVerified": false,
  "method": "loginToken"
}
```

## Next Steps

Once a user is authenticated with the `session` middleware, you can perform more granular access control based on their role and permissions. Proceed to the next section to learn how to use the [Authorization Middleware](/en/docs/blocklet-sdk-nodejs/authentication-auth-middleware-c33146/) to protect routes based on user roles.

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/core-concepts-c33146/

The Blocklet SDK is built upon a few fundamental concepts that form the backbone of any application you build. Understanding these core pillars—Configuration, Wallet Management, and Security—is essential for leveraging the full power of the SDK to create robust, secure, and scalable Blocklets.

This section provides a high-level overview of these key areas. The following diagram illustrates how these core components interact within a Blocklet Application:

![Core Concepts](https://media.arcblock.io/lib/63/63d2fe31297a5fb1.w1600.webp)

Each concept is detailed in its own dedicated sub-section, which you can navigate to below.

::::card-group
::link-card{title="Configuration & Environment" description="Learn how the SDK manages configuration, environment variables, and the component store through the `config` and `env` modules." icon="settings" href="/en/docs/blocklet-sdk-nodejs/core-concepts-configuration-c33146/"}
::link-card{title="Wallet Management" description="Explore the `getWallet` utility for creating and managing wallet instances from environment variables, essential for signing and authentication." icon="wallet" href="/en/docs/blocklet-sdk-nodejs/core-concepts-wallet-c33146/"}
::link-card{title="Security Utilities" description="Understand the built-in security features, including data encryption/decryption, response signing, and signature verification." icon="shield" href="/en/docs/blocklet-sdk-nodejs/core-concepts-security-c33146/"}
::::

Mastering these concepts will enable you to build more complex and secure applications. We recommend you start with [Configuration & Environment](/en/docs/blocklet-sdk-nodejs/core-concepts-configuration-c33146/) to understand how your application interacts with its surroundings.

---

## Configuration & Environment

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/core-concepts-configuration-c33146/

The Blocklet SDK provides a robust and unified way to manage configuration and environment variables for your application. It aggregates settings from multiple sources into a single, easy-to-use interface, ensuring your blocklet has access to all the necessary information, from application metadata to component-specific settings.

This section will cover the two primary exports for accessing this information: the `env` object and the `components` store.

## The env Object

The `env` object is a centralized, read-only container for all configuration variables available to your component at runtime. The SDK automatically populates this object by merging configuration from several sources, including default values, application-level settings, and component-specific environment files.

You can access any configuration property by simply importing `env` from the SDK.

```javascript
import { env } from '@blocklet/sdk';

console.log(`Running in app: ${env.appName}`);
console.log(`My data directory is at: ${env.dataDir}`);

// Access user-defined preferences from the blocklet's settings page
const userApiKey = env.preferences.apiKey;
```

### Key Environment Properties

While the `env` object contains many properties, here are some of the most commonly used ones:

- **appName** `string` — The name of the parent application.
- **appUrl** `string` — The full public URL of the application.
- **componentDid** `string` — The Decentralized ID (DID) of the current component.
- **isComponent** `boolean` — A flag that is `true` if the code is running within a component context.
- **dataDir** `string` — The absolute path to the component's dedicated data storage directory.
- **cacheDir** `string` — The absolute path to the component's dedicated cache directory.
- **serverVersion** `string` — The version of the Blocklet Server the application is running on.
- **preferences** `Record<string, any>` — An object containing custom configuration values set by the user from the blocklet's settings page.

## The components Store

The `components` store is an array that provides real-time information about all other components running within the same application instance. This is essential for inter-component communication, allowing one component to discover the endpoints and status of another.

```javascript
import { components } from '@blocklet/sdk';

// Find a running API service component to make a request
const apiService = components.find(c => c.name === 'api-service' && c.status === 1);

if (apiService) {
  const apiUrl = apiService.webEndpoint;
  console.log(`Found API service at: ${apiUrl}`);
  // Now you can make a request to this URL
}
```

### Component Properties

Each object in the `components` array contains detailed information about a component:

- **did** `string` — The Decentralized ID (DID) of the component.
- **name** `string` — The name of the component as defined in its `blocklet.yml`.
- **mountPoint** `string` — The URL path where the component is mounted (e.g., `/admin`, `/api`).
- **webEndpoint** `string` — The full, publicly accessible URL for the component.
- **status** `number` — The current status of the component (e.g., `1` for running, `0` for stopped).

## Configuration Loading Flow

The SDK builds the `env` object by layering configurations from different sources. Each subsequent source can override the values from the previous ones, providing a clear and predictable order of precedence.

![Configuration & Environment](https://media.arcblock.io/lib/58/58313ea479669ece.w1600.webp)

This layered approach provides flexibility, allowing developers and administrators to configure blocklets at different levels.

## Dynamic Updates

The configuration is not just static. The Blocklet SDK listens for runtime changes pushed by the Blocklet Server. For instance, if a user updates a setting on the blocklet's configuration page, the SDK will automatically update the `env` object and emit an event.

You can listen for these changes using the exported `events` emitter.

```javascript
import { events, Events } from '@blocklet/sdk';

// Listen for any updates to the environment or preferences
events.on(Events.envUpdate, (updatedValues) => {
  console.log('Configuration was updated:', updatedValues);
  // You can now react to the change, e.g., re-initialize a service
});
```

This allows you to build applications that can react to configuration changes without requiring a restart.

Now that you understand how to access configuration and environment variables, you can explore how to use them for more specific tasks. A common use case is managing cryptographic keys and wallets, which is covered in the next section.

:::action-card{title="Next: Wallet Management" description="Learn how to create and manage wallet instances for signing and authentication." icon="wallet"}
::action{label="Read More" href="/en/docs/blocklet-sdk-nodejs/core-concepts-wallet-c33146/" variant="primary"}
:::

---

## Security Utilities

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/core-concepts-security-c33146/

The Blocklet SDK includes a robust set of security utilities designed to protect your application's data and communications. These tools help you handle sensitive information, ensure the integrity of API calls, and prevent common web vulnerabilities like Cross-Site Request Forgery (CSRF).

Before diving into signing and verification, it's essential to understand how wallets are managed, as they form the cryptographic foundation for these operations. You can learn more in the [Wallet Management](/en/docs/blocklet-sdk-nodejs/core-concepts-wallet-c33146/) section.

## Data Encryption & Decryption

For storing sensitive data at rest—such as API keys or personal user information in a database—the SDK provides simple symmetric encryption and decryption functions. These utilities use AES encryption and automatically derive a key from your blocklet's environment variables, simplifying key management.

- `encrypt(message)`: Encrypts a string.
- `decrypt(message)`: Decrypts an encrypted string.

The encryption key is derived from `process.env.BLOCKLET_APP_EK` (as the password) and `process.env.BLOCKLET_DID` (as the salt). Ensure these environment variables are available in your blocklet's runtime.

**Encrypting Data**

```javascript
import { encrypt } from '@blocklet/sdk/security';

const userApiKey = 'sk_live_verySecretValue12345';

// Encrypt the data before saving it to the database
const encryptedApiKey = encrypt(userApiKey);

console.log(encryptedApiKey);
// Output: A long encrypted string
```

To retrieve the original data, use the `decrypt` function.

**Decrypting Data**

```javascript
import { decrypt } from '@blocklet/sdk/security';

// Assume 'encryptedApiKey' is fetched from your database
const encryptedApiKey = 'U2FsdGVkX1...'; // Example encrypted string

const originalApiKey = decrypt(encryptedApiKey);

console.log(originalApiKey);
// Output: sk_live_verySecretValue12345
```

## Request Signing & Verification

To ensure data integrity and authenticity between services, such as during [Component-to-Component Communication](/en/docs/blocklet-sdk-nodejs/guides-component-communication-c33146/), the SDK provides utilities to sign and verify data payloads. This process uses the blocklet's wallet to create a cryptographic signature that the receiving service can validate.

### High-Level Response Signing

The easiest way to secure an entire API response is with `signResponse` and `verifyResponse`. These functions handle the standard data structure for signed responses.

`signResponse(data)`: Takes a JSON object, wraps it in a standard format with a signature and timestamp, and returns the new signed object.

**Signing an API Response**

```javascript
import { signResponse } from '@blocklet/sdk/security';
import express from 'express';

const app = express();

app.get('/api/data', (req, res) => {
  const data = { userId: '123', permissions: ['read'] };
  // signResponse adds signature, pk, and other metadata
  const signedPayload = signResponse(data);
  res.json(signedPayload);
});
```

`verifyResponse(data)`: Takes the signed payload and verifies its signature using the embedded public key.

**Verifying a Signed Response**

```javascript
import { verifyResponse } from '@blocklet/sdk/security';

async function fetchAndVerifyData() {
  const response = await fetch('/api/data');
  const signedPayload = await response.json();

  const isValid = verifyResponse(signedPayload);

  if (isValid) {
    console.log('Signature is valid. Data:', signedPayload.data);
  } else {
    console.error('Signature verification failed!');
  }
}
```

### Low-Level Signing

For scenarios requiring more control, such as signing a specific data payload without the wrapper structure provided by `signResponse`, you can use the lower-level `sign` and `verify` utilities. These functions are essential for custom signature implementations.

A key feature of these utilities is that they use a stable JSON stringification process. This ensures that the same data object will always produce the same string representation, which is critical for generating consistent and verifiable signatures.

**Low-Level Signing and Verification**

```javascript
import { sign, verify } from '@blocklet/sdk/util/verify-sign';

// The data payload to be signed
const data = { transactionId: 'xyz-789', amount: 50, currency: 'USD' };

// 1. Generate a signature using the blocklet's wallet
const signature = sign(data);
console.log('Signature:', signature);

// 2. Verify the signature
// The public key is required for verification.
const publicKey = process.env.BLOCKLET_APP_PK;
const isVerified = verify(data, signature, { appPk: publicKey });

console.log('Is Verified:', isVerified);
// Output: Is Verified: true
```

To verify a signature, you must provide the original data, the signature string, and the public key (`appPk`) of the signer. In a real application, this public key would typically be retrieved from the request headers (e.g., `x-component-sig-pk`) sent by the calling service or from a trusted configuration source.

## CSRF Protection

Cross-Site Request Forgery (CSRF) is an attack that tricks a user into submitting a malicious request. The SDK's `csrf` middleware provides a robust and easy-to-use solution to mitigate this risk by implementing the Synchronizer Token Pattern.

It works by creating a unique, secret-based token for each user session and requiring that token to be present in any state-changing requests (like `POST`, `PUT`, `DELETE`).

### Basic Usage

To enable CSRF protection, add the `csrf` and `cookie-parser` middlewares to your Express application. The `cookie-parser` middleware is a prerequisite.

**Basic CSRF Protection**

```javascript
import express from 'express';
import cookieParser from 'cookie-parser';
import { csrf } from '@blocklet/sdk/middlewares';

const app = express();

// The cookie-parser middleware is required for the csrf middleware to work
app.use(cookieParser());

// Apply the csrf middleware to all routes
app.use(csrf());

app.post('/api/update-profile', (req, res) => {
  res.json({ message: 'Profile updated successfully!' });
});

// ... your other routes
app.listen(3000);
```

#### How It Works

::::steps
:::step{title="Token Generation"}
For `GET` requests, the middleware automatically generates an `x-csrf-token` cookie based on the user's `login_token` cookie (which is typically set after a user logs in).
:::

:::step{title="Token Verification"}
For state-changing methods (`POST`, `PUT`, `PATCH`, `DELETE`), the middleware compares the value of the `x-csrf-token` cookie with the value of the `x-csrf-token` HTTP header. If they don't match, or if one is missing, the request is rejected with a 403 Forbidden error.
:::

:::step{title="Frontend Implementation"}
Your frontend application is responsible for reading the `x-csrf-token` cookie and sending its value in the `x-csrf-token` header for all state-changing API calls. Most modern HTTP clients (like Axios) can be configured to do this automatically.
:::
::::

### Advanced Usage

For more complex scenarios, you can customize the token generation and verification logic by passing an options object to the `csrf` middleware. This is useful if you need to handle tokens differently, such as storing them in the session or using custom request headers.

The example below demonstrates overriding the default behavior to:

1. Generate a token based on a `userId` stored in the session.
2. Pass the token to the frontend via `res.locals` instead of a cookie.
3. Verify the token from a custom `x-custom-csrf-token` header.

**Advanced CSRF Protection**

```javascript
import express from 'express';
import cookieParser from 'cookie-parser';
import session from 'express-session';
import { csrf } from '@blocklet/sdk/middlewares';
import { sign, verify, getCsrfSecret } from '@blocklet/sdk/util/csrf';

const app = express();

app.use(cookieParser());
app.use(session({ secret: 'custom-session-secret', resave: false, saveUninitialized: true }));

// Advanced usage with custom token handling
app.use(csrf({
  // Custom logic to generate and provide the token
  generateToken: (req, res) => {
    if (req.session.userId) {
      const token = sign(getCsrfSecret(), req.session.userId);
      // Make the token available to the template engine
      res.locals.csrfToken = token;
    }
  },
  // Custom logic to verify the token from a custom header
  verifyToken: (req) => {
    const token = req.headers['x-custom-csrf-token'];
    const userId = req.session.userId;

    if (!token || !userId) {
      throw new Error('CSRF token or user session not found.');
    }

    if (!verify(getCsrfSecret(), token, userId)) {
      throw new Error('Invalid CSRF token.');
    }
  }
}));

// A route that renders a form with the custom token
app.get('/form', (req, res, next) => {
  // Simulate a user session for demonstration
  req.session.userId = `user_${Date.now()}`;

  // The generateToken function needs to be called to set the token
  // In a real app, this might be part of a broader middleware
  const generate = res.locals.generateToken;
  generate(req, res);

  res.send(`
    <h3>Advanced CSRF Example</h3>
    <form id="myForm">
      <input type="text" name="data" value="some-data">
      <button type="submit">Submit</button>
    </form>
    <script>
      const form = document.getElementById('myForm');
      form.addEventListener('submit', async (e) => {
        e.preventDefault();
        try {
          const response = await fetch('/submit', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'x-custom-csrf-token': '${res.locals.csrfToken}'
            },
            body: JSON.stringify({ data: 'some-data' })
          });
          const result = await response.text();
          alert('Response: ' + result);
        } catch (err) {
          alert('Error: ' + err.message);
        }
      });
    </script>
  `);
});

// A route that handles the submission
app.post('/submit', (req, res) => {
  // If we get here, the custom verifyToken logic passed.
  res.send('Form submitted successfully!');
});

// Error handler to catch and display CSRF errors
app.use((err, req, res, next) => {
  if (err.message.includes('CSRF')) {
    res.status(403).send(err.message);
  } else {
    next(err);
  }
});

app.listen(3000);
```

Now that you understand these core security concepts, you are better equipped to build secure and reliable applications. To see how these tools are used in practice, proceed to the [Authentication](/en/docs/blocklet-sdk-nodejs/authentication-c33146/) guides.

---

## Wallet Management

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/core-concepts-wallet-c33146/

In the Blocklet SDK, a wallet is a fundamental cryptographic object that represents your application's identity. It's essential for signing data, authenticating requests, and interacting with blockchain networks. The SDK provides a powerful and convenient utility, `getWallet`, to create and manage wallet instances directly from your application's environment variables.

This utility abstracts the complexities of handling different cryptographic curves and key formats, whether you're working with ArcBlock's native DID or Ethereum. The wallet's keys are sourced from the environment variables set by the Blocklet Server, which you can learn more about in the [Configuration & Environment](/en/docs/blocklet-sdk-nodejs/core-concepts-configuration-c33146/) documentation.

## The getWallet Utility

The `getWallet` function is the primary method for creating a `WalletObject`. By default, it uses the application's standard secret key (`BLOCKLET_APP_SK`) and the configured chain type (`CHAIN_TYPE` or `BLOCKLET_WALLET_TYPE`) from the environment.

**Basic Usage**

```javascript
import getWallet from '@blocklet/sdk/lib/wallet';

// Create a wallet instance using environment variables
const appWallet = getWallet();

// Now you can use the wallet to sign data
const signature = appWallet.sign('data to be signed');
```

The utility is smart enough to handle different blockchain types based on the configuration.

### Parameters

While `getWallet` works out-of-the-box with environment variables, you can override its behavior by passing parameters.

- **type** `DIDTypeShortcut` — The DID type for the wallet. Can be 'ethereum' or 'arcblock' (or 'default'). Defaults to the value of the CHAIN_TYPE or BLOCKLET_WALLET_TYPE environment variable.

- **appSk** `string` — The application's secret key in hex format. Defaults to the value of the BLOCKLET_APP_SK environment variable.

### Creating Wallets for Specific Chains

You can explicitly request a wallet for a specific chain type by providing the `type` parameter.

**Creating an Ethereum Wallet**

```javascript
import getWallet from '@blocklet/sdk/lib/wallet';

// Explicitly create an Ethereum wallet using the default secret key
const ethWallet = getWallet('ethereum');
```

## Specialized Wallet Helpers

The `getWallet` function also comes with several attached helper methods for common use cases.

### getWallet.getPermanentWallet()

Some operations may require a more stable, long-term identity. For this, Blocklet Server provides a permanent secret key (`BLOCKLET_APP_PSK`). This helper creates a wallet using this permanent key.

**Using the Permanent Wallet**

```javascript
import getWallet from '@blocklet/sdk/lib/wallet';

const permanentWallet = getWallet.getPermanentWallet();
```

### getWallet.getEthereumWallet(permanent)

This is a convenient shortcut for creating an Ethereum wallet. It accepts an optional boolean parameter to specify whether to use the permanent secret key.

**Creating Ethereum Wallets**

```javascript
import getWallet from '@blocklet/sdk/lib/wallet';

// Get the standard Ethereum wallet (uses BLOCKLET_APP_SK)
const standardEthWallet = getWallet.getEthereumWallet();

// Get the permanent Ethereum wallet (uses BLOCKLET_APP_PSK)
const permanentEthWallet = getWallet.getEthereumWallet(true);
```

### getWallet.getPkWallet()

In some scenarios, you may need to work with a wallet's public key (`BLOCKLET_APP_PK`) to verify a signature without having access to the secret key. The `getPkWallet` helper creates a read-only wallet instance from the public key.

**Creating a Wallet from a Public Key**

```javascript
import getWallet from '@blocklet/sdk/lib/wallet';

// Create a wallet from the app's public key
const pkWallet = getWallet.getPkWallet();

// This wallet can be used to verify signatures, but not to sign data
// const isValid = pkWallet.verify('data', signature);
```

## Performance and Caching

For optimal performance, the `getWallet` utility includes a built-in LRU (Least Recently Used) cache. It caches up to four wallet instances based on their type and secret key, ensuring that repeated calls with the same parameters are extremely fast. This caching is handled automatically, so you don't need to implement your own.

With a solid understanding of wallet management, you're now equipped to handle cryptographic operations in your blocklet. The next logical step is to see how these wallets are used to secure your application.

:::action-card{title="Next Step: Security Utilities" description="Learn how to use the wallet for encrypting data and signing API responses." icon="shield-check"}
::action{label="Read More" href="/en/docs/blocklet-sdk-nodejs/core-concepts-security-c33146/" variant="primary"}
:::

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/getting-started-c33146/

This guide will walk you through the essential steps to install the Blocklet SDK and get a minimal application up and running. Our goal is to help you go from zero to a working example in just a few minutes.

## Prerequisites

Before you begin, ensure you have a Blocklet project set up. If you don't have one, please follow the [Blocklet Development Documentation](/en/docs/createblocklet/create-single-blocklet/) to create one.

## Step 1: Install the SDK

Navigate to your Blocklet project's directory and add the `@blocklet/sdk` package as a dependency.

**Terminal**

```bash
npm install @blocklet/sdk

# Or using yarn
yarn add @blocklet/sdk
```

## Step 2: Understand the Environment

The Blocklet SDK relies on environment variables that are automatically injected by the Blocklet Server when your application runs. These variables provide your application with context about its environment, such as its App ID, name, and secret keys.

The SDK includes a utility to verify that all necessary environment variables are present. While you typically don't need to set these manually, it's good to be aware of them.

Here are some of the key environment variables the SDK uses:

| Variable Name  | Description  |
|---|---|
| `BLOCKLET_APP_ID`  | The unique identifier for your Blocklet.  |
| `BLOCKLET_APP_SK`  | The secret key for your Blocklet, used for signing requests.  |
| `BLOCKLET_APP_NAME`  | The name of your Blocklet.  |
| `BLOCKLET_APP_URL`  | The public URL of your Blocklet.  |
| `BLOCKLET_DATA_DIR`  | The directory where your Blocklet can store persistent data.  |
| `ABT_NODE_DID`  | The DID of the node where the Blocklet is running.  |

For a more detailed look at configuration, see the [Configuration & Environment](/en/docs/blocklet-sdk-nodejs/core-concepts-configuration-c33146/) guide.

## Step 3: Create a Minimal Server

Now, let's create a simple Express.js server to see the SDK in action. Create a file named `app.js` (or your project's main entry point) and add the following code.

This example demonstrates how to:

1. Import the `env` object from the SDK to access environment information.
2. Set up a basic Express server.
3. Create a root endpoint that returns the Blocklet's App Name.

**app.js**

```javascript
const express = require('express');
const { env } = require('@blocklet/sdk');

// A global error handler is a good practice for production applications.
process
  .on('uncaughtException', (err) => {
    console.error('Uncaught Exception:', err.message);
    process.exit(1);
  })
  .on('unhandledRejection', (reason, promise) => {
    console.error('Unhandled Rejection at:', promise, 'reason:', (reason)?.message || reason);
    process.exit(1);
  });

const app = express();
const port = process.env.BLOCKLET_PORT || 3000;

app.get('/', (req, res) => {
  // The `env` object provides typed access to all Blocklet environment variables.
  res.send(`Hello from ${env.appName}!`);
});

app.listen(port, () => {
  console.log(`Blocklet listening on port ${port}`);
  console.log(`Visit your Blocklet at: ${env.appUrl}`);
});
```

## Step 4: Run Your Blocklet

With the server code in place, you can now run your Blocklet. Use the Blocklet CLI to start the development server:

**Terminal**

```bash
blocklet dev
```

Once the server starts, you'll see a message with the URL to access your application. Open that URL in your browser, and you should see the message: `Hello from [Your Blocklet Name]!`

## Next Steps

Congratulations! You've successfully set up the Blocklet SDK and built a minimal application.

To continue learning, we recommend exploring the fundamental concepts that power the SDK.

:::action-card{title="Core Concepts" description="Understand the fundamental concepts that power the Blocklet SDK, from configuration management to wallet handling and security." icon="award"}
::action{label="Read More" href="/en/docs/blocklet-sdk-nodejs/core-concepts-c33146/" variant="primary"}
:::

---

## Guides

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/guides-c33146/

Welcome to the Blocklet SDK Guides. This section provides practical, step-by-step tutorials to help you solve common challenges and implement key features in your web applications.

Whether you're looking to enable secure communication between different parts of your application or enhance your server with powerful, pre-built middlewares, these guides are designed to get you up and running quickly.

::::card-group
::link-card{title="Component-to-Component Communication" description="Enable secure communication between different components within your blocklet using the `component.call` method." icon="refresh" href="/en/docs/blocklet-sdk-nodejs/guides-component-communication-c33146/"}
::link-card{title="Using Web Server Middlewares" description="Enhance your Express.js server with ready-to-use middlewares for CSRF protection, sitemap generation, and SPA fallbacks." icon="shield" href="/en/docs/blocklet-sdk-nodejs/guides-using-middlewares-c33146/"}
::::

After following these guides, you'll have a solid foundation for building more complex and robust Blocklet applications. For a comprehensive understanding of all available functions and modules, we recommend diving into our [API Reference](/en/docs/blocklet-sdk-nodejs/api-reference-c33146/).

---

## Component-to-Component Communication

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/guides-component-communication-c33146/

In a Blocklet application composed of multiple components, enabling them to communicate with each other securely and reliably is essential. The Blocklet SDK provides a high-level utility, `component.call`, designed specifically for this purpose. This method simplifies inter-component API calls by handling service discovery, request signing, and automatic retries.

This approach is more robust than making direct HTTP requests because it abstracts away the complexities of the underlying environment, such as dynamic ports and Docker networking, while ensuring that all communication is authenticated.

## Making a Secure API Call

The primary method for inter-component communication is `component.call`. It acts as a wrapper around an HTTP client (`axios`) but automatically injects the necessary authentication headers to verify the calling component's identity.

### Basic Usage

Here is a basic example of one component calling an API endpoint on another component named 'user-service'.

**Calling another component**

```javascript
import component from '@blocklet/sdk/component';

async function getUserProfile(userId) {
  try {
    const response = await component.call({
      name: 'user-service', // Name, DID, or title of the target component
      method: 'GET',
      path: `/api/users/${userId}`,
    });

    console.log('User Profile:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to call user-service:', error.message);
  }
}
```

### How It Works

The `component.call` function streamlines the communication process through several key steps:

::::steps
:::step{title="Service Discovery"}
It looks up the target component (e.g., 'user-service') in the application's component registry to find its current location and metadata.
:::

:::step{title="Endpoint Resolution"}
It constructs the correct internal URL to reach the component, automatically handling complexities like Docker container networking.
:::

:::step{title="Request Signing"}
Before sending the request, it automatically adds special `x-component-*` headers. These headers contain a signature generated using the calling component's secret key, proving its identity.
:::

:::step{title="API Call"}
It executes the HTTP request using the configured method, path, and data.
:::

:::step{title="Automatic Retries"}
If the request fails due to a transient server error (e.g., a 5xx status code), it will automatically retry the request a few times with an increasing delay (exponential backoff).
:::
::::

This flow ensures that the communication is both reliable and secure. The receiving component can use the [session middleware](/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/) to verify the signature and authorize the request.

![Component-to-Component Communication](https://media.arcblock.io/lib/38/3806302354ced0a0.w1600.webp)

### call Parameters

The `component.call` function accepts an options object with the following properties:

- **name** `string` *(required)* — The name, title, or DID of the target component to call.
- **method** `string` (default: `POST`) — The HTTP method for the request (e.g., 'GET', 'POST', 'PUT', 'DELETE').
- **path** `string` *(required)* — The API path on the target component (e.g., '/api/v1/resource').
- **data** `any` — The request body, typically used with POST, PUT, or PATCH methods.
- **params** `any` — URL query parameters to be appended to the request URL.
- **headers** `object` — An object of custom headers to be sent with the request.
- **timeout** `number` — Request timeout in milliseconds.
- **responseType** `string` — The type of data that the server will respond with. For example, 'stream'.

### Return Value

The function returns a `Promise` that resolves to an `AxiosResponse` object, which contains properties like `data`, `status`, and `headers`.

## Advanced Usage

### Customizing Retry Behavior

You can customize the automatic retry logic by passing a second argument to `component.call`. This is useful for adjusting to the specific reliability needs of an endpoint.

**Custom Retry Options**

```javascript
import component from '@blocklet/sdk/component';

const callOptions = {
  name: 'data-processor',
  method: 'POST',
  path: '/api/process',
  data: { job: 'some-long-job' },
};

const retryOptions = {
  retries: 5,       // Attempt 5 times in total
  minTimeout: 1000, // Wait at least 1 second between retries
  factor: 2,        // Double the wait time after each failed attempt
};

async function processData() {
  const response = await component.call(callOptions, retryOptions);
  return response.data;
}
```

The `retryOptions` object can have the following properties:

- **retries** `number` (default: `3`) — The total number of attempts to make.
- **factor** `number` (default: `2`) — The exponential factor to use for backoff.
- **minTimeout** `number` (default: `500`) — The minimum timeout between retries in milliseconds.
- **maxTimeout** `number` (default: `5000`) — The maximum timeout between retries in milliseconds.
- **randomize** `boolean` (default: `true`) — Whether to randomize the timeout.
- **onFailedAttempt** `function` — A callback function that is invoked on each failed attempt.

### Handling Stream Responses

For endpoints that return a stream (e.g., downloading a large file), you can set `responseType: 'stream'`. This allows you to process the data as it arrives without buffering the entire response in memory.

**Streaming a File**

```javascript
import fs from 'fs';
import component from '@blocklet/sdk/component';

async function downloadBackup() {
  const response = await component.call({
    name: 'backup-service',
    method: 'GET',
    path: '/api/export',
    responseType: 'stream',
  });

  const writer = fs.createWriteStream('backup.zip');
  response.data.pipe(writer);

  return new Promise((resolve, reject) => {
    writer.on('finish', resolve);
    writer.on('error', reject);
  });
}
```

By using `component.call`, you can build robust and secure multi-component applications with ease. The next logical step is to learn how to protect your component's API endpoints by verifying these incoming calls. See the [Session Middleware](/en/docs/blocklet-sdk-nodejs/authentication-session-middleware-c33146/) guide for details.

---

## Using Web Server Middlewares

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/guides-using-middlewares-c33146/

The Blocklet SDK comes bundled with a suite of powerful, ready-to-use middlewares for Express.js. These tools are designed to handle common web development challenges like security, SEO, and single-page application (SPA) routing, allowing you to build more robust and feature-rich blocklets with less boilerplate code.

This guide will walk you through the most essential middlewares and how to integrate them into your application.

## CSRF Protection

Cross-Site Request Forgery (CSRF) is a common web security vulnerability. The SDK's `csrf` middleware provides a straightforward way to protect your application against such attacks.

It works by creating a unique token for each user session and requiring that token to be sent with any state-changing request (like `POST` or `PUT`).

<strong>Usage</strong>

To enable CSRF protection, simply add the `csrf` and `cookie-parser` middlewares to your Express application.

**Express.js Server Setup**

```javascript
import express from 'express';
import cookieParser from 'cookie-parser';
import { csrf } from '@blocklet/sdk/middlewares';

const app = express();

// cookie-parser is required for the csrf middleware to work
app.use(cookieParser());

// Apply the csrf middleware globally
app.use(csrf());

app.post('/api/data', (req, res) => {
  res.json({ message: 'Data updated successfully!' });
});

// Your other routes...
app.listen(3000);
```

<strong>How It Works</strong>

::::steps
:::step{title="Token Generation"}
For `GET` requests, the middleware automatically generates a `x-csrf-token` cookie based on the user's `login_token`.
:::

:::step{title="Token Verification"}
For `POST`, `PUT`, `PATCH`, and `DELETE` requests, it compares the `x-csrf-token` cookie with the value of the `x-csrf-token` HTTP header. If they don't match, the request is rejected.
:::

:::step{title="Frontend Implementation"}
Your frontend client is responsible for reading the `x-csrf-token` cookie and sending its value in the `x-csrf-token` header for all subsequent state-changing API calls.
:::
::::

## Sitemap Generation

A sitemap is crucial for SEO, as it helps search engines discover and index your application's pages. The `sitemap` middleware automates the creation of a compliant `sitemap.xml` file.

<strong>Usage</strong>

You provide a generator function that writes your application's URLs to a stream. The middleware handles the rest.

**Sitemap Generation**

```javascript
import express from 'express';
import { sitemap } from '@blocklet/sdk/middlewares';

const app = express();

// A mock function to get dynamic data
const getBlogPosts = async () => [
  { slug: 'my-first-post', updatedAt: new Date() },
  { slug: 'my-second-post', updatedAt: new Date() },
];

app.get('/sitemap.xml', sitemap(async (stream) => {
  // 1. Add static pages
  stream.write({ url: '/' });
  stream.write({ url: '/about' });
  stream.write({ url: '/contact' });

  // 2. Add dynamic pages from a database or API
  const posts = await getBlogPosts();
  posts.forEach(post => {
    stream.write({ url: `/blog/${post.slug}`, lastmod: post.updatedAt });
  });
}));

app.listen(3000);
```

When a user or search engine crawler visits `/sitemap.xml`, this endpoint will return a dynamically generated XML sitemap.

## SPA Fallback for Single-Page Applications

Single-Page Applications (SPAs) handle routing on the client side, which can be problematic for SEO and direct URL access. The `fallback` middleware solves this by ensuring that all non-asset requests serve your main `index.html` file while allowing you to inject dynamic metadata for SEO and social sharing.

<strong>Usage</strong>

The `fallback` middleware should typically be placed at the end of your middleware chain to catch any GET requests that haven't been handled by other routes (like API endpoints or static file servers).

**SPA Fallback Setup**

```javascript
import express from 'express';
import path from 'path';
import { fallback } from '@blocklet/sdk/middlewares';
import { env } from '@blocklet/sdk/config';

const app = express();
const publicPath = path.join(__dirname, '../dist');

// Serve static assets like CSS, JS, and images
app.use(express.static(publicPath));

// Your API routes go here
app.get('/api/user', (req, res) => res.json({ name: 'John Doe' }));

// The fallback middleware handles all other GET requests
app.use(fallback('index.html', {
  root: publicPath,
  // Dynamically set meta tags based on the request path
  async getPageData(req) {
    if (req.path.startsWith('/posts/')) {
      const postId = req.path.split('/').pop();
      const post = await getPostById(postId); // Fetch post data
      return {
        title: post.title,
        description: post.summary,
        ogImage: post.featuredImage,
      };
    }
    // Default metadata for other pages
    return {
      title: env.appName,
      description: env.appDescription,
    };
  },
}));

app.listen(3000);
```

<strong>Key Features</strong>

- <strong>Dynamic Metadata</strong>: The `getPageData` function is the core feature, allowing you to return page-specific `title`, `description`, and `ogImage` tags, which are then injected into the HTML response.
- <strong>Automatic Injections</strong>: The middleware automatically injects the necessary Blocklet JavaScript (`__blocklet__.js`) and theme styles into the HTML, ensuring seamless integration with the Blocklet Server environment.
- <strong>Caching</strong>: It includes an in-memory cache to improve performance for frequently accessed pages.

::::card-group
::link-card{title="Authentication" description="Learn how to secure your application with robust authentication and authorization middlewares." icon="lock" href="/en/docs/blocklet-sdk-nodejs/authentication-c33146/"}
::link-card{title="API Reference" description="Explore the full API for middlewares and other SDK utilities for advanced use cases." icon="book-open" href="/en/docs/blocklet-sdk-nodejs/api-reference-c33146/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/overview-c33146/

The Blocklet SDK (`@blocklet/sdk`) is the essential toolkit for building applications on the ArcBlock platform. It simplifies development by providing a comprehensive set of utilities, services, and middlewares that handle the core functionalities of a Blocklet, allowing you to focus on your application's unique features.

Whether you're building a simple static site, a complex web service, or a component that extends another application, the Blocklet SDK provides the necessary abstractions to interact seamlessly with the underlying Blocklet Server environment.

## Key Features

The SDK is designed to be powerful yet easy to use, offering a range of features to accelerate your development process.

::::card-group
::link-card{title="Configuration & Environment" description="Easily access environment variables, application configuration, and information about other running components through a unified `env` object and `config` module." icon="settings"}
::link-card{title="Authentication & Authorization" description="Integrate decentralized identity with built-in support for DID Connect. Protect your routes with powerful session and authorization middlewares." icon="lock"}
::link-card{title="Service Clients" description="Interact programmatically with the Blocklet Server. Use the `BlockletService` to manage users, roles, and permissions, or use the `NotificationService` to send messages." icon="server"}
::link-card{title="Web Server Middlewares" description="A suite of ready-to-use Express.js middlewares for common tasks like CSRF protection, session management, sitemap generation, and SPA fallbacks." icon="shield-check"}
::::

## Core Modules

The Blocklet SDK is organized into several key modules, each serving a specific purpose:

- <strong>`BlockletService`</strong>: A client for interacting with the Blocklet Server's API. It allows you to manage users, roles, permissions, access keys, and retrieve blocklet metadata.
- <strong>`config`</strong> <strong>&</strong> <strong>`env`</strong>: Provides access to your blocklet's runtime configuration, including environment variables, component mount points, and application settings.
- <strong>`middlewares`</strong>: A collection of Express.js middlewares for handling authentication (`auth`), sessions (`session`), CSRF protection (`csrf`), and more.
- <strong>`WalletAuthenticator`</strong> <strong>&</strong> <strong>`WalletHandlers`</strong>: Core utilities for implementing DID Connect, enabling users to log in securely with their decentralized identities. For more details, you can also refer to the [DID Connect SDK documentation](/en/docs/did-connect-sdk/did-connect-sdk-overview/).
- <strong>`getWallet`</strong>: A utility function to retrieve the blocklet's wallet instance, which is essential for signing transactions or messages.
- <strong>`Security`</strong>: Provides helper functions for data encryption, decryption, and signature verification, ensuring secure data handling within your application.

## Get Started

Ready to build your first Blocklet? Head over to our [Getting Started](/en/docs/blocklet-sdk-nodejs/getting-started-c33146/) guide for a step-by-step tutorial that will have you up and running in minutes.

---

## Blocklet Service

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/services-blocklet-service-c33146/

The `BlockletService` is a powerful client that acts as the primary interface for your blocklet to interact with the underlying ABT Node services. It simplifies tasks like user management, session handling, role-based access control (RBAC), and retrieving blocklet metadata by wrapping complex GraphQL queries and HTTP requests into a clean, promise-based JavaScript API.

This service is essential for building secure and feature-rich applications that leverage the full power of the Blocklet platform. Before diving into this service, it's helpful to understand the concepts covered in our [Authentication](/en/docs/blocklet-sdk-nodejs/authentication-c33146/) guide.

### How It Works

The `BlockletService` client within your application communicates with the `blocklet-service` running on the ABT Node. All requests are automatically authenticated using the blocklet's credentials, ensuring secure access to core functionalities.

The following diagram illustrates the communication flow between your blocklet, the Blocklet Service API, and the core services on the ABT Node:

![Blocklet Service](https://media.arcblock.io/lib/b3/b347ef7e60c8a9cb.w1600.webp)

## Getting Started

To use the service, simply import and instantiate it. The client will automatically configure itself based on the environment variables provided by the Blocklet Server.

**Getting Started**

```javascript
import BlockletService from '@blocklet/sdk/service/blocklet';

const client = new BlockletService();

async function main() {
  const { user } = await client.getOwner();
  console.log('Blocklet owner:', user.fullName);
}

main();
```

## Session Management

### login

Authenticates a user and starts a session.

<strong>Parameters</strong>

- **params** `object` *(required)* — Login credentials or data.

<strong>Returns</strong>

- **Promise<object>** `Promise<object>` — An object containing the session and user info.
  - **user** `object` — The authenticated user's profile.
  - **token** `string` — The access token for the session.
  - **refreshToken** `string` — The refresh token to extend the session.
  - **visitorId** `string` — A unique identifier for the visitor/device.

### refreshSession

Refreshes an expired session using a refresh token.

<strong>Parameters</strong>

- **refreshToken** `string` *(required)* — The refresh token from a previous session.
- **visitorId** `string` — The unique identifier for the visitor/device.

<strong>Returns</strong>

- **Promise<object>** `Promise<object>` — An object containing the new session and user info.
  - **user** `object` — The authenticated user's profile.
  - **token** `string` — The new access token.
  - **refreshToken** `string` — The new refresh token.
  - **provider** `string` — The login provider (e.g., 'wallet').

### switchProfile

Updates a user's profile information.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID of the user to update.
- **profile** `object` *(required)* — An object with the profile fields to update.
  - **avatar** `string` — New avatar URL.
  - **email** `string` — New email address.
  - **fullName** `string` — New full name.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

## User Management

### getUser

Retrieves a single user's profile by their DID.

<strong>Parameters</strong>

- **did** `string` *(required)* — The unique DID of the user to retrieve.
- **options** `object` — Optional configuration for the query.
  - **enableConnectedAccount** `boolean` — If true, includes details about the user's connected accounts (e.g., OAuth providers).
  - **includeTags** `boolean` — If true, includes any tags associated with the user.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the user's profile.
  - **user** `object` — The user profile object.

### getUsers

Retrieves a paginated list of users, with support for filtering and sorting.

<strong>Parameters</strong>

- **args** `object` — An object containing query, sorting, and pagination options.
  - **paging** `object` — Pagination options.
    - **page** `number` — The page number to retrieve.
    - **pageSize** `number` — The number of users per page.
  - **query** `object` — Filtering criteria.
    - **role** `string` — Filter by user role.
    - **approved** `boolean` — Filter by approval status.
    - **search** `string` — A search string to match against user fields.
  - **sort** `object` — Sorting criteria.
    - **updatedAt** `number` — Sort by update timestamp. `1` for ascending, `-1` for descending.
    - **createdAt** `number` — Sort by creation timestamp. `1` for ascending, `-1` for descending.
    - **lastLoginAt** `number` — Sort by last login timestamp. `1` for ascending, `-1` for descending.

<strong>Returns</strong>

- **ResponseUsers** `Promise<object>` — A paginated list of user objects.
  - **users** `TUserInfo[]` — An array of user profile objects.
  - **paging** `object` — Pagination information.
    - **total** `number` — Total number of users.
    - **pageSize** `number` — Number of users per page.
    - **page** `number` — Current page number.

### getUsersCount

Gets the total number of users.

<strong>Returns</strong>

- **ResponseGetUsersCount** `Promise<object>` — An object containing the total user count.
  - **count** `number` — The total number of users.

### getUsersCountPerRole

Gets the count of users for each role.

<strong>Returns</strong>

- **ResponseGetUsersCountPerRole** `Promise<object>` — An object containing user counts per role.
  - **counts** `TKeyValue[]` — An array of objects, where each object has a `key` (role name) and `value` (user count).

### getOwner

Retrieves the profile of the blocklet owner.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the owner's user profile.

### updateUserApproval

Approves or revokes a user's access to the blocklet.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID of the user to update.
- **approved** `boolean` *(required)* — Set to `true` to approve, `false` to revoke.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

### updateUserTags

Updates the tags associated with a user.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **did** `string` *(required)* — The DID of the user.
  - **tags** `number[]` *(required)* — An array of tag IDs to associate with the user.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

### updateUserExtra

Updates the extra metadata for a user.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **did** `string` *(required)* — The DID of the user.
  - **remark** `string` — A remark or note about the user.
  - **extra** `string` — A JSON string for storing custom data.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

### updateUserInfo

Updates a user's general information. Requires a valid user session cookie.

<strong>Parameters</strong>

- **userInfo** `object` *(required)* — An object with the user fields to update. Must include the user's `did`.
- **options** `object` *(required)* — Request options including headers.
  - **headers** `object` *(required)*
    - **cookie** `string` *(required)* — The user's session cookie.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

### updateUserAddress

Updates a user's physical address. Requires a valid user session cookie.

<strong>Parameters</strong>

- **args** `object` *(required)* — An object with the user's DID and address details.
  - **did** `string` *(required)* — The DID of the user.
  - **address** `object` — The user's address.
    - **country** `string` — Country
    - **province** `string` — State/Province
    - **city** `string` — City
    - **postalCode** `string` — Postal Code
    - **line1** `string` — Address line 1
    - **line2** `string` — Address line 2
- **options** `object` *(required)* — Request options including headers.
  - **headers** `object` *(required)*
    - **cookie** `string` *(required)* — The user's session cookie.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

## User Sessions

### getUserSessions

Retrieves a list of active sessions for a user.

<strong>Parameters</strong>

- **args** `object` — An object containing query and pagination options.
  - **paging** `object` — Pagination options.
  - **query** `object` — Filtering criteria.
    - **userDid** `string` — Filter by user DID.
    - **status** `string` — Filter by session status.

<strong>Returns</strong>

- **ResponseUserSessions** `Promise<object>` — A paginated list of user sessions.
  - **list** `TUserSession[]` — An array of session objects.
  - **paging** `object` — Pagination information.

### getUserSessionsCount

Gets the total count of user sessions, with optional filtering.

<strong>Parameters</strong>

- **args** `object` — An object containing query options.
  - **query** `object` — Filtering criteria.
    - **userDid** `string` — Filter by user DID.

<strong>Returns</strong>

- **ResponseUserSessionsCount** `Promise<object>` — An object containing the session count.
  - **count** `number` — The total number of sessions.

## Social & Community

### getUserFollowers

Retrieves a list of users who are following a specific user. Requires a valid user session cookie.

<strong>Parameters</strong>

- **args** `object` *(required)* — Query options.
  - **userDid** `string` *(required)* — The DID of the user whose followers are to be retrieved.
  - **paging** `object` — Pagination options.
- **options** `object` *(required)* — Request options including headers.
  - **headers** `object` *(required)*
    - **cookie** `string` *(required)* — The user's session cookie.

<strong>Returns</strong>

- **ResponseUserFollows** `Promise<object>` — A paginated list of follower users.

### getUserFollowing

Retrieves a list of users that a specific user is following. Requires a valid user session cookie.

<strong>Parameters</strong>

- **args** `object` *(required)* — Query options.
  - **userDid** `string` *(required)* — The DID of the user whose following list is to be retrieved.
  - **paging** `object` — Pagination options.
- **options** `object` *(required)* — Request options including headers.
  - **headers** `object` *(required)*
    - **cookie** `string` *(required)* — The user's session cookie.

<strong>Returns</strong>

- **ResponseUserFollows** `Promise<object>` — A paginated list of users being followed.

### getUserFollowStats

Gets the number of followers and following for a user. Requires a valid user session cookie.

<strong>Parameters</strong>

- **args** `object` *(required)* — Query options.
  - **userDids** `string[]` *(required)* — An array of user DIDs.
- **options** `object` *(required)* — Request options including headers.
  - **headers** `object` *(required)*
    - **cookie** `string` *(required)* — The user's session cookie.

<strong>Returns</strong>

- **ResponseUserRelationCount** `Promise<object>` — An object with follower and following counts.

### checkFollowing

Checks if a user is following one or more other users.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **followerDid** `string` *(required)* — The DID of the potential follower.
  - **userDids** `string[]` *(required)* — An array of user DIDs to check against.

<strong>Returns</strong>

- **ResponseCheckFollowing** `Promise<object>` — An object where keys are user DIDs and values are booleans indicating the follow status.

### followUser

Makes one user follow another.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **followerDid** `string` *(required)* — The DID of the user who is following.
  - **userDid** `string` *(required)* — The DID of the user to be followed.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

### unfollowUser

Makes one user unfollow another.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **followerDid** `string` *(required)* — The DID of the user who is unfollowing.
  - **userDid** `string` *(required)* — The DID of the user to be unfollowed.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

### getUserInvites

Retrieves a list of users invited by a specific user. Requires a valid user session cookie.

<strong>Parameters</strong>

- **args** `object` *(required)* — Query options.
  - **userDid** `string` *(required)* — The DID of the inviter.
  - **paging** `object` — Pagination options.
- **options** `object` *(required)* — Request options including headers.
  - **headers** `object` *(required)*
    - **cookie** `string` *(required)* — The user's session cookie.

<strong>Returns</strong>

- **ResponseUsers** `Promise<object>` — A paginated list of invited users.

## Tag Management

### getTags

Retrieves a list of all available user tags.

<strong>Parameters</strong>

- **args** `object`
  - **paging** `object` — Pagination options.

<strong>Returns</strong>

- **ResponseTags** `Promise<object>` — A paginated list of tag objects.
  - **tags** `TTag[]` — An array of tag objects.
  - **paging** `object` — Pagination information.

### createTag

Creates a new user tag.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **tag** `object` *(required)*
    - **title** `string` *(required)* — The title of the tag.
    - **description** `string` — A description for the tag.
    - **color** `string` — A hex color code for the tag.

<strong>Returns</strong>

- **ResponseTag** `Promise<object>` — An object containing the newly created tag.

### updateTag

Updates an existing user tag.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **tag** `object` *(required)*
    - **id** `number` *(required)* — The ID of the tag to update.
    - **title** `string` — The new title.
    - **description** `string` — The new description.
    - **color** `string` — The new color.

<strong>Returns</strong>

- **ResponseTag** `Promise<object>` — An object containing the updated tag.

### deleteTag

Deletes a user tag.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **tag** `object` *(required)*
    - **id** `number` *(required)* — The ID of the tag to delete.

<strong>Returns</strong>

- **ResponseTag** `Promise<object>` — An object containing the deleted tag.

## Role-Based Access Control (RBAC)

### getRoles

Retrieves a list of all available roles.

<strong>Returns</strong>

- **ResponseRoles** `Promise<object>` — An object containing a list of roles.
  - **roles** `TRole[]` — An array of role objects.

### getRole

Retrieves a single role by its name.

<strong>Parameters</strong>

- **name** `string` *(required)* — The unique name of the role.

<strong>Returns</strong>

- **ResponseRole** `Promise<object>` — An object containing the role details.

### createRole

Creates a new role.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **name** `string` *(required)* — A unique identifier for the role (e.g., `editor`).
  - **title** `string` *(required)* — A human-readable title (e.g., `Content Editor`).
  - **description** `string` — A brief description of the role's purpose.

<strong>Returns</strong>

- **ResponseRole** `Promise<object>` — An object containing the newly created role.

### updateRole

Updates an existing role.

<strong>Parameters</strong>

- **name** `string` *(required)* — The name of the role to update.
- **updates** `object` *(required)* — An object with the fields to update.
  - **title** `string` — The new title.
  - **description** `string` — The new description.

<strong>Returns</strong>

- **ResponseRole** `Promise<object>` — An object containing the updated role.

### deleteRole

Deletes a role.

<strong>Parameters</strong>

- **name** `string` *(required)* — The name of the role to delete.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

### getPermissions

Retrieves a list of all available permissions.

<strong>Returns</strong>

- **ResponsePermissions** `Promise<object>` — An object containing a list of permissions.
  - **permissions** `TPermission[]` — An array of permission objects.

### getPermissionsByRole

Retrieves all permissions granted to a specific role.

<strong>Parameters</strong>

- **role** `string` *(required)* — The name of the role.

<strong>Returns</strong>

- **ResponsePermissions** `Promise<object>` — An object containing the list of permissions for the role.

### createPermission

Creates a new permission.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **name** `string` *(required)* — A unique name for the permission (e.g., `post:create`).
  - **description** `string` — A description of what the permission allows.

<strong>Returns</strong>

- **ResponsePermission** `Promise<object>` — An object containing the newly created permission.

### updatePermission

Updates an existing permission.

<strong>Parameters</strong>

- **name** `string` *(required)* — The name of the permission to update.
- **updates** `object` *(required)*
  - **description** `string` — The new description for the permission.

<strong>Returns</strong>

- **ResponsePermission** `Promise<object>` — An object containing the updated permission.

### deletePermission

Deletes a permission.

<strong>Parameters</strong>

- **name** `string` *(required)* — The name of the permission to delete.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

### grantPermissionForRole

Assigns a permission to a role.

<strong>Parameters</strong>

- **role** `string` *(required)* — The name of the role.
- **permission** `string` *(required)* — The name of the permission to grant.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

### revokePermissionFromRole

Revokes a permission from a role.

<strong>Parameters</strong>

- **role** `string` *(required)* — The name of the role.
- **permission** `string` *(required)* — The name of the permission to revoke.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

### updatePermissionsForRole

Replaces all existing permissions for a role with a new set.

<strong>Parameters</strong>

- **role** `string` *(required)* — The name of the role.
- **permissions** `string[]` *(required)* — An array of permission names to set for the role.

<strong>Returns</strong>

- **ResponseRole** `Promise<object>` — An object containing the updated role.

### hasPermission

Checks if a role has a specific permission.

<strong>Parameters</strong>

- **role** `string` *(required)* — The name of the role to check.
- **permission** `string` *(required)* — The name of the permission to verify.

<strong>Returns</strong>

- **BooleanResponse** `Promise<object>` — An object with a boolean `result` property.
  - **result** `boolean` — `true` if the role has the permission, otherwise `false`.

## Passport Management

### issuePassportToUser

Issues a new passport to a user, assigning them a role.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user receiving the passport.
  - **role** `string` *(required)* — The role to assign with this passport.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile, including the new passport.

### enableUserPassport

Enables a previously revoked passport for a user.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user.
  - **passportId** `string` *(required)* — The ID of the passport to enable.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

### revokeUserPassport

Revokes a user's passport.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user.
  - **passportId** `string` *(required)* — The ID of the passport to revoke.

<strong>Returns</strong>

- **ResponseUser** `Promise<object>` — An object containing the updated user profile.

### removeUserPassport

Permanently removes a user's passport.

<strong>Parameters</strong>

- **args** `object` *(required)*
  - **userDid** `string` *(required)* — The DID of the user.
  - **passportId** `string` *(required)* — The ID of the passport to remove.

<strong>Returns</strong>

- **GeneralResponse** `Promise<object>` — A general response object indicating success or failure.

## Blocklet & Component Info

### getBlocklet

Retrieves the metadata and state for the current blocklet.

<strong>Parameters</strong>

- **attachRuntimeInfo** `boolean` (default: `false`) — If `true`, includes runtime information like CPU and memory usage.
- **useCache** `boolean` (default: `true`) — If `false`, bypasses the cache to fetch the latest data.

<strong>Returns</strong>

- **ResponseBlocklet** `Promise<object>` — An object containing the blocklet's state and metadata.

### getComponent

Retrieves the state of a specific component within the current blocklet by its DID.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID of the component to retrieve.

<strong>Returns</strong>

- **ComponentState** `Promise<object>` — An object containing the component's state and metadata.

### getTrustedDomains

Retrieves a list of trusted domains for federated login.

<strong>Returns</strong>

- **string[]** `Promise<string[]>` — An array of trusted domain URLs.

### getVault

Retrieves and verifies the blocklet's vault information.

<strong>Returns</strong>

- **vault** `Promise<string>` — The vault string if verification is successful.

### clearCache

Clears cached data on the node based on a pattern.

<strong>Parameters</strong>

- **args** `object`
  - **pattern** `string` — A pattern to match cache keys for removal.

<strong>Returns</strong>

- **ResponseClearCache** `Promise<object>` — An object containing a list of removed cache keys.
  - **removed** `string[]` — An array of keys that were removed from the cache.

## Access Key Management

### createAccessKey

Creates a new access key for programmatic access.

<strong>Parameters</strong>

- **params** `object` *(required)*
  - **remark** `string` — A description for the access key.
  - **passport** `string` — The role/passport to associate with the key. Defaults to 'guest'.

<strong>Returns</strong>

- **ResponseCreateAccessKey** `Promise<object>` — An object containing the newly created access key and secret.

### getAccessKey

Retrieves details for a single access key.

<strong>Parameters</strong>

- **params** `object` *(required)*
  - **accessKeyId** `string` *(required)* — The ID of the access key to retrieve.

<strong>Returns</strong>

- **ResponseAccessKey** `Promise<object>` — An object containing the access key details.

### getAccessKeys

Retrieves a list of access keys.

<strong>Parameters</strong>

- **params** `object`
  - **paging** `object` — Pagination options.

<strong>Returns</strong>

- **ResponseAccessKeys** `Promise<object>` — A paginated list of access key objects.

### verifyAccessKey

Verifies if an access key is valid.

<strong>Parameters</strong>

- **params** `object` *(required)*
  - **accessKeyId** `string` *(required)* — The ID of the access key to verify.

<strong>Returns</strong>

- **ResponseAccessKey** `Promise<object>` — An object containing the access key details if valid.

After mastering the `BlockletService`, you might want to explore how to send messages to your users. Head over to the [Notification Service](/en/docs/blocklet-sdk-nodejs/services-notification-service-c33146/) guide to learn more.

---

## Services

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/services-c33146/

The Blocklet SDK abstracts away the complexity of direct API calls by providing a suite of powerful service clients. These clients offer a clean, programmatic interface to interact with core Blocklet functionalities, such as user management, real-time notifications, and inter-component event handling. By using these services, you can build more robust and feature-rich applications with less code.

These services act as the bridge between your application and the underlying Blocklet Server, handling authentication, request formatting, and error handling for you.

![Services](https://media.arcblock.io/lib/6d/6d6c703a7b87e491.w1600.webp)

Explore the core services provided by the SDK:

::::card-group
::link-card{title="Blocklet Service" description="Programmatically manage users, roles, permissions, and access keys. It also provides methods to retrieve blocklet metadata and component information." icon="user" href="/en/docs/blocklet-sdk-nodejs/services-blocklet-service-c33146/"}
::link-card{title="Notification Service" description="Engage with your users by sending real-time notifications and handling incoming messages. Supports direct-to-user messages and public channel broadcasts." icon="bell" href="/en/docs/blocklet-sdk-nodejs/services-notification-service-c33146/"}
::link-card{title="Event Bus" description="Implement an event-driven architecture. Publish custom events and subscribe to events from other components, enabling decoupled, scalable communication." icon="routes" href="/en/docs/blocklet-sdk-nodejs/services-event-bus-c33146/"}
::::

These services are the pillars for building interactive and integrated Blocklet applications. Dive into each service's dedicated section to understand its full capabilities and see practical examples.

Next, let's explore how to manage your application's users and settings with the [Blocklet Service](/en/docs/blocklet-sdk-nodejs/services-blocklet-service-c33146/).

---

## Event Bus

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/services-event-bus-c33146/

The Event Bus provides a powerful publish-subscribe mechanism that allows different components within your blocklet and even across different blocklets (within the same ABT Node instance) to communicate with each other in a decoupled manner. This is ideal for broadcasting system-wide state changes or events without components having direct dependencies on one another.

While the [Notification Service](/en/docs/blocklet-sdk-nodejs/services-notification-service-c33146/) is designed for sending targeted messages to users, the Event Bus is designed for internal, component-to-component communication.

### How It Works

The Event Bus facilitates an asynchronous communication flow:

1. A <strong>Publisher</strong> component sends an event with a specific name and payload.
2. The Blocklet SDK sends this event to the central Event Bus service running in ABT Node.
3. The Event Bus service then broadcasts this event to all <strong>Subscriber</strong> components that are listening for that event type.

This process is visualized in the diagram below:

![Event Bus](https://media.arcblock.io/lib/b4/b472d3fdc62a5619.w1600.webp)

## API Reference

### publish

Publishes an event to the event bus, making it available to all subscribed listeners. This is an asynchronous operation.

#### Parameters

- **name** `string` *(required)* — The name of the event, e.g., user.created or order.shipped.
- **event** `object` *(required)* — An object containing the event details.
  - **id** `string` — A unique ID for the event. If not provided, one will be generated automatically.
  - **time** `string` — An ISO 8601 timestamp for when the event occurred. Defaults to the current time.
  - **data** `object` *(required)* — The main payload of the event. It can contain any JSON-serializable data. The object_type and object_id fields from this object will be promoted to the top-level event object for easier filtering.

#### Example

**Publishing a user creation event**

```javascript
import eventbus from '@blocklet/sdk/service/eventbus';

async function createUser(userData) {
  // ... logic to create the user in the database
  const newUser = { id: 'user_123', name: 'John Doe' };

  try {
    await eventbus.publish('user.created', {
      data: {
        object_type: 'User',
        object_id: newUser.id,
        object: newUser,
        source_system: 'admin_panel',
      },
    });
    console.log('User creation event published successfully.');
  } catch (error) {
    console.error('Failed to publish event:', error);
  }

  return newUser;
}
```

### subscribe

Registers a callback function to be executed whenever an event is received from the event bus. Note that a component will not receive events that it published itself.

#### Parameters

- **cb** `(event: TEvent) => void` *(required)* — A callback function that will be invoked with the event object when an event is received.

#### Event Object Structure (TEvent)

The callback function receives a single argument: the event object. This object has a standardized structure based on the CloudEvents specification.

- **id** `string` *(required)* — Unique identifier for the event instance.
- **source** `string` *(required)* — The DID of the component that published the event.
- **type** `string` *(required)* — The name of the event (e.g., user.created).
- **time** `string` *(required)* — ISO 8601 timestamp of when the event was created.
- **spec_version** `string` *(required)* — The CloudEvents specification version, e.g., '1.0.0'.
- **object_type** `string` — The type of the primary object in the event data (e.g., User).
- **object_id** `string` — The ID of the primary object in the event data.
- **data** `object` *(required)* — The detailed payload of the event.
  - **type** `string` — Content type of the data, defaults to 'application/json'.
  - **object** `any` — The actual data payload.
  - **previous_attributes** `any` — For update events, this may contain the state of the object before the change.

#### Example

**Subscribing to events**

```javascript
import eventbus from '@blocklet/sdk/service/eventbus';

const handleEvent = (event) => {
  console.log(`Received event of type: ${event.type}`);
  console.log('Event details:', event);

  if (event.type === 'user.created') {
    console.log(`A new user was created with ID: ${event.object_id}`);
    // Update UI or perform other actions
  }
};

eventbus.subscribe(handleEvent);

console.log('Listening for events from the event bus...');
```

### unsubscribe

Removes a previously registered event listener. It's crucial to call this function when a component unmounts or no longer needs to listen for events to prevent memory leaks.

#### Parameters

- **cb** `(event: TEvent) => void` *(required)* — The exact same callback function reference that was passed to subscribe.

#### Example

To properly unsubscribe, you must keep a reference to the original callback function.

**Full subscription lifecycle**

```javascript
import eventbus from '@blocklet/sdk/service/eventbus';

// 1. Define the handler function
const onUserEvent = (event) => {
  console.log(`User event received: ${event.type}`);
};

// 2. Subscribe to the event bus
eventbus.subscribe(onUserEvent);
console.log('Subscribed to user events.');

// ... later in your application's lifecycle (e.g., component unmount)

// 3. Unsubscribe using the same function reference
eventbus.unsubscribe(onUserEvent);
console.log('Unsubscribed from user events.');
```

---

## Notification Service

URL: https://www.arcblock.io/en/docs/blocklet-sdk-nodejs/services-notification-service-c33146/

The Notification Service is a core component of the Blocklet SDK, enabling your application to send various types of notifications to users and subscribe to real-time events. This service acts as an interface to the underlying ABT Node notification capabilities, handling everything from simple user messages to rich, interactive notifications delivered to DID Wallets, email, and other channels.

Whether you need to alert a user about an important event, send a transactional email, or broadcast a message to all connected clients, the Notification Service provides a unified and straightforward API.

![Notification Service](https://media.arcblock.io/lib/9b/9ba16ea4c7696518.w1600.webp)

## API Reference

### sendToUser

Sends a notification directly to one or more users identified by their DIDs. This is the primary method for targeted user communication.

#### Parameters

- **receiver** `string | string[]` *(required)* — The DID of the recipient. Can be a single DID string, an array of DIDs, or * to send to all users of the blocklet.
- **notification** `TNotification | TNotification[]` *(required)* — The notification object or an array of notification objects to send. See the The Notification Object (TNotification) section for a detailed structure.
- **options** `TSendOptions` — Additional options for sending the notification.
  - **keepForOfflineUser** `boolean` — If true, the notification will be stored and delivered when the user comes online.
  - **locale** `string` — The locale for the notification (e.g., 'en', 'zh').
  - **channels** `('app' | 'email' | 'push' | 'webhook')[]` — Specify which channels to deliver the notification through.
  - **ttl** `number` — Time to live for the message in minutes (0-7200). After this time, the message expires.
  - **allowUnsubscribe** `boolean` — If true, allows the user to unsubscribe from this type of notification.

#### Returns

- **Promise<object>** `Promise` — A promise that resolves with the response object from the server upon successful sending.

#### Example

**Send a simple notification**

```javascript
import notification from '@blocklet/sdk/service/notification';

async function notifyUser(userDid) {
  try {
    const result = await notification.sendToUser(userDid, {
      type: 'notification',
      title: 'Hello from SDK!',
      body: 'This is a test notification sent to a specific user.',
      severity: 'info',
    });
    console.log('Notification sent successfully:', result);
  } catch (error) {
    console.error('Failed to send notification:', error);
  }
}
```

#### Example Response

```json
{
  "status": "ok",
  "message": "Notification sent to 1 user(s)."
}
```

### sendToMail

Sends a notification to one or more recipients via email. The notification object structure is the same as `sendToUser`.

#### Parameters

- **receiver** `string | string[]` *(required)* — A single email address or an array of email addresses.
- **notification** `TNotification` *(required)* — The notification object. The `title` is used as the email subject and `body` or `attachments` form the email content.
- **options** `TSendOptions` — Same sending options as `sendToUser`.

#### Returns

- **Promise<object>** `Promise` — A promise that resolves with the response object from the server.

#### Example

**Send an email notification**

```javascript
import notification from '@blocklet/sdk/service/notification';

async function emailUser(userEmail) {
  try {
    const result = await notification.sendToMail(userEmail, {
      type: 'notification',
      title: 'Your Weekly Report is Ready',
      body: 'Please log in to your dashboard to view the report.',
    });
    console.log('Email sent successfully:', result);
  } catch (error) {
    console.error('Failed to send email:', error);
  }
}
```

#### Example Response

```json
{
  "status": "ok",
  "message": "Email sent successfully."
}
```

### broadcast

Broadcasts a message to clients connected to a specific WebSocket channel. By default, it sends to the blocklet's public channel.

#### Parameters

- **notification** `TNotificationInput` *(required)* — The notification object to broadcast.
- **options** `object` — Options to control the broadcast.
  - **channel** `string` — The channel to broadcast to. Defaults to the blocklet's public channel, which can be retrieved with getAppPublicChannel(did).
  - **event** `string` (default: `message`) — The event name to emit on the client-side.
  - **socketId** `string` — If provided, sends the message only to this specific socket connection.
  - **userDid** `string` — If provided, sends the message only to sockets authenticated with this DID.

#### Returns

- **Promise<object>** `Promise` — A promise that resolves with the server's response.

#### Example

**Broadcast a message**

```javascript
import notification from '@blocklet/sdk/service/notification';

function broadcastUpdate() {
  notification.broadcast(
    {
      type: 'passthrough',
      passthroughType: 'system_update',
      data: { message: 'A new version is available. Please refresh.' },
    },
    { event: 'system-update' }
  );
}
```

#### Example Response

```json
{
  "status": "ok",
  "message": "Broadcast sent."
}
```

### sendToRelay

Sends a message through the relay service to a specific topic, enabling real-time, topic-based communication between different components or even different blocklets.

#### Parameters

- **topic** `string` *(required)* — The topic to publish the event to.
- **event** `string` *(required)* — The name of the event being sent.
- **data** `any` *(required)* — The payload data for the event.

#### Returns

- **Promise<object>** `Promise` — A promise that resolves with the server's response.

#### Example

**Send a relay message**

```javascript
import notification from '@blocklet/sdk/service/notification';

async function publishNewArticle(article) {
  try {
    await notification.sendToRelay('articles', 'new-published', {
      id: article.id,
      title: article.title,
    });
    console.log('Relay message sent.');
  } catch (error) {
    console.error('Failed to send relay message:', error);
  }
}
```

#### Example Response

```json
{
  "status": "ok",
  "message": "Relay message sent."
}
```

### on

Subscribes to general events, such as internal blocklet events or team-related events, pushed from the ABT Node. The Notification Service uses an `EventEmitter` interface for this functionality.

#### Parameters

- **event** `string` *(required)* — The name of the event to listen for.
- **callback** `Function` *(required)* — The function to execute when the event is emitted.

#### Example

**Listen for team member removal**

```javascript
import notification from '@blocklet/sdk/service/notification';
import { TeamEvents } from '@blocklet/constant';

function onMemberRemoved(data) {
  console.log('Team member removed:', data.user.did);
  // Add logic to update application state
}

// Subscribe to the event
notification.on(TeamEvents.MEMBER_REMOVED, onMemberRemoved);
```

### off

Removes an event listener that was previously added with `on`.

#### Parameters

- **event** `string` *(required)* — The name of the event to stop listening for.
- **callback** `Function` *(required)* — The specific listener function to remove.

#### Example

```javascript
// To unsubscribe from the previous example
// notification.off(TeamEvents.MEMBER_REMOVED, onMemberRemoved);
```

### _message.on

This is a special-purpose listener specifically for messages sent directly to your blocklet's private message channel. It's useful for handling direct responses or commands intended for the blocklet itself.

#### Parameters

- **event** `string` *(required)* — The `type` of the incoming message to listen for.
- **callback** `Function` *(required)* — The function to execute when a message of the specified type is received.

#### Example

**Listen for direct messages**

```javascript
import notification from '@blocklet/sdk/service/notification';

function handleDirectMessage(response) {
  console.log('Received direct message:', response);
}

// The 'message' event from the messageChannel is emitted with the response.type as the event name
// e.g., if response.type is 'payment_confirmation', the event here is 'payment_confirmation'
notification._message.on('payment_confirmation', handleDirectMessage);
```

### _message.off

Removes a direct message listener that was added with `_message.on`.

#### Parameters

- **event** `string` *(required)* — The message type to stop listening for.
- **callback** `Function` *(required)* — The specific listener function to remove.

## The Notification Object (TNotification)

The notification object is a flexible data structure that defines the content and appearance of a notification. Its structure can be customized for different use cases.

- **type** `'notification' | 'connect' | 'feed' | 'hi' | 'passthrough'` *(required)* — The primary type of the notification, which determines its overall purpose and structure.
- **title** `string` — The title of the notification. Used for `notification` type.
- **body** `string` — The main content/body of the notification. Used for `notification` type.
- **severity** `'normal' | 'success' | 'error' | 'warning'` — The severity level, which can affect the notification's appearance in the wallet. Used for `notification` type.
- **attachments** `TNotificationAttachment[]` — An array of rich content attachments. These are rendered as blocks in the DID Wallet.
  - **type** `string` *(required)* — Type of the attachment. Can be asset, vc, token, text, image, divider, transaction, dapp, link, or section.
  - **data** `object` — The data payload for the attachment, which varies by type (e.g., a text attachment would have a text property here).
- **actions** `TNotificationAction[]` — An array of action buttons to be displayed with the notification.
  - **name** `string` *(required)* — An identifier for the action.
  - **title** `string` — The text displayed on the button.
  - **link** `string` — A URL to open when the button is clicked.
- **activity** `TNotificationActivity` — An object describing a social activity, like a comment or a follow. This is a structured way to represent social interactions.
  - **type** `'comment' | 'like' | 'follow' | 'tips' | 'mention' | 'assign' | 'un_assign'` *(required)* — Type of activity.
  - **actor** `string` *(required)* — The DID of the user who performed the action.
  - **target** `TActivityTarget` *(required)* — The object on which the action was performed (e.g., a blog post).
- **url** `string` — Required for `connect` type. The URL for the DID Connect session.
- **checkUrl** `string` — Optional for `connect` type. A URL to check the session status.
- **feedType** `string` — Required for `feed` type. A string identifying the type of feed.
- **passthroughType** `string` — Required for `passthrough` type. A string identifying the type of passthrough data.
- **data** `object` — Required for `feed` and `passthrough` types. The data payload for these types.

---

## Blocklet Server SDK (Node.js)

URL: https://www.arcblock.io/en/docs/blocklet-server-js/

---

## Advanced Usage

URL: https://www.arcblock.io/en/docs/blocklet-server-js/advanced-usage-c86fd7/

This section covers advanced topics for developers who need to go beyond the standard client methods or troubleshoot issues. Here, you'll learn how to execute raw GraphQL queries directly against the Blocklet Server API and how to enable debugging to inspect the underlying requests and responses.

These features provide greater flexibility and insight, allowing for custom integrations and efficient problem-solving.

::::card-group
::link-card{title="Raw Queries & Subscriptions" description="Learn how to execute raw GraphQL queries and subscriptions for maximum flexibility and custom requests." icon="file" href="/en/docs/blocklet-server-js/advanced-usage-raw-queries-c86fd7/"}
::link-card{title="Debugging" description="Get instructions on how to enable debug logging in both Node.js and browser environments to troubleshoot issues." icon="bug" href="/en/docs/blocklet-server-js/advanced-usage-debugging-c86fd7/"}
::::

## Why Use Advanced Features?

While the pre-defined methods in the Blocklet Server Client cover the vast majority of use cases, you might need advanced features for:

- <strong>Executing Newly Added API Features</strong>: Accessing GraphQL fields or mutations that have been added to Blocklet Server but are not yet available as a dedicated method in the client.
- <strong>Complex Data Fetching</strong>: Building highly specific or aggregated queries in a single request to optimize performance.
- <strong>Troubleshooting</strong>: Directly inspecting the raw request and response payloads to diagnose integration problems.

With these advanced techniques, you can extend the client's functionality and effectively diagnose any issues.

---

## Debugging

URL: https://www.arcblock.io/en/docs/blocklet-server-js/advanced-usage-debugging-c86fd7/

When building an application with `@blocklet/server-js`, you might encounter issues with API requests, authentication, or data fetching. To help you troubleshoot these problems, the client provides a detailed debugging log. This allows you to inspect the raw GraphQL queries being sent, the responses received, and other internal operations.

The library uses the popular `debug` utility, which allows for namespaced logging. You can enable these logs in both Node.js and browser environments.

## In Node.js

In a Node.js environment, you can enable debug logs by setting the `DEBUG` environment variable when you run your application. The `@blocklet/server-js` client uses the `sdk:*` namespace.

To see all debug output from the client, run your script like this:

**Terminal**

```bash
DEBUG="sdk:*" node your-app.js
```

This command will print detailed information to your console, including the GraphQL queries, variables, and the results of each operation. This is incredibly useful for understanding exactly what data is being sent to and received from the Blocklet Server.

## In the Browser

To enable debugging in a web browser, you can use the Developer Tools console to set a `localStorage` item.

1. Open your browser's Developer Tools (usually by pressing F12 or Cmd+Option+I).
2. Select the <strong>Console</strong> tab.
3. Execute the following JavaScript command:

**Browser Console**

```javascript
localStorage.setItem('debug', 'sdk:*')
```

After running the command, <strong>refresh the page</strong>. You will now see detailed debug messages from the `@blocklet/server-js` client logged in the console. This helps you inspect API calls and responses directly within the browser context.

To disable the logs, you can either clear the `debug` item or set it to an empty value:

**Browser Console**

```javascript
localStorage.removeItem('debug')
```

Using these debugging tools can significantly speed up the process of identifying and fixing issues in your application.

---

## Raw Queries & Subscriptions

URL: https://www.arcblock.io/en/docs/blocklet-server-js/advanced-usage-raw-queries-c86fd7/

While the `@blocklet/server-js` library provides convenient helper methods for most common GraphQL operations, there are situations where you might need more flexibility or access to features not yet exposed through the SDK. For these advanced use cases, the library allows you to execute raw GraphQL queries and subscriptions directly.

This approach is ideal when you need to construct highly specific queries, access the latest API features before they are officially wrapped, or optimize data fetching beyond what the standard methods offer.

## Raw Queries

The `doRawQuery` method enables you to send any valid GraphQL query string to the Blocklet Server API endpoint. This gives you complete control over the data you request and its structure.

- **query** `string` *(required)* — The raw GraphQL query string to execute.
- **requestOptions** `object` — Optional object for advanced request configurations, such as custom headers.

### Example

Here's how to use `doRawQuery` to fetch basic information about the connected node.

**doRawQuery Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function getNodeVersion() {
  try {
    const query = `{
      getNodeInfo {
        info {
          version
          name
        }
      }
    }`;

    const result = await client.doRawQuery(query);
    console.log('Node Name:', result.getNodeInfo.info.name);
    console.log('Node Version:', result.getNodeInfo.info.version);
  } catch (error) {
    console.error('Failed to execute raw query:', error);
  }
}

getNodeVersion();
```

<strong>Example Response</strong>

**Response Data**

```json
{
  "getNodeInfo": {
    "info": {
      "version": "1.8.22",
      "name": "My Dev Node"
    }
  }
}
```

This method returns a promise that resolves with the exact JSON data returned by the GraphQL server, allowing you to access nested properties directly.

## Raw Subscriptions

For real-time data updates, you can use the `doRawSubscription` method to establish a persistent connection and listen for server-pushed events. Unlike a standard query, this method returns a subscription object that allows you to register event listeners.

- **query** `string` *(required)* — The raw GraphQL subscription string.

### Example

This example demonstrates how to subscribe to blocklet status changes. The subscription will push new data whenever a blocklet's status is updated (e.g., from 'running' to 'stopped').

**doRawSubscription Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function watchBlockletStatus() {
  try {
    const subscriptionQuery = `subscription {
      blockletStatusChanged {
        did
        status
      }
    }`;

    const subscription = await client.doRawSubscription(subscriptionQuery);

    subscription.on('data', (data) => {
      const { did, status } = data.blockletStatusChanged;
      console.log(`Blocklet ${did} status changed to: ${status}`);
    });

    subscription.on('error', (err) => {
      console.error('Subscription error:', err);
    });

    console.log('Listening for blocklet status changes...');
  } catch (error) {
    console.error('Failed to start subscription:', error);
  }
}

watchBlockletStatus();
```

<strong>Example Data Stream</strong>

When a blocklet's status changes, the `data` event listener will receive a payload like this:

**Streamed Data**

```json
{
  "blockletStatusChanged": {
    "did": "z8iZpA6x3M4Jz3J6iK9y6L4oE3nF2aH5c8g7",
    "status": "stopped"
  }
}
```

Using raw queries and subscriptions provides a powerful way to interact with the Blocklet Server API when the standard helper methods don't meet your specific needs. For troubleshooting your raw queries or any other client interactions, proceed to the next section on [Debugging](/en/docs/blocklet-server-js/advanced-usage-debugging-c86fd7/).

---

## API Reference

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-c86fd7/

Welcome to the complete API reference for the `@blocklet/server-js`. This section provides detailed documentation for every GraphQL query, mutation, and type available through the Blocklet Server Client. Whether you need to fetch data, modify server state, or understand the structure of the data you're working with, this is your comprehensive guide.

The API is organized into three main categories:

::::card-group
::link-card{title="Queries" description="Use queries to fetch data from the Blocklet Server. This includes retrieving information about blocklets, users, roles, and system status." icon="database" href="/en/docs/blocklet-server-js/api-reference-queries-c86fd7/"}
::link-card{title="Mutations" description="Use mutations to create, update, or delete data on the Blocklet Server. This covers actions like installing blocklets, managing users, and updating configurations." icon="edit" href="/en/docs/blocklet-server-js/api-reference-mutations-c86fd7/"}
::link-card{title="Types" description="Understand the data structures used throughout the API. This section details all input objects, enums, and response types." icon="box" href="/en/docs/blocklet-server-js/api-reference-types-c86fd7/"}
::::

## Queries

Queries are used to read or fetch data from the Blocklet Server. The Blocklet Server Client provides a set of convenient methods that wrap these GraphQL queries, making it easy to retrieve information without writing raw GraphQL. These methods cover a wide range of functionalities, from checking the node's status to fetching detailed user information.

For a complete list of all available query methods and their detailed documentation, please visit the [Queries section](/en/docs/blocklet-server-js/api-reference-queries-c86fd7/).

## Mutations

Mutations are used to modify server-side data. This includes actions like creating, updating, or deleting resources. The Blocklet Server Client offers a comprehensive set of mutation methods that allow you to manage the entire lifecycle of your blocklets, users, and other server resources programmatically.

For a complete list of all available mutation methods and their detailed documentation, please visit the [Mutations section](/en/docs/blocklet-server-js/api-reference-mutations-c86fd7/).

## Types

Types define the structure of the data you can query and send. This includes object types, input types, and enums. Understanding these types is crucial for effectively using the API, as they dictate the shape of the data in both requests and responses.

For a complete reference of all data types used in the API, please visit the [Types section](/en/docs/blocklet-server-js/api-reference-types-c86fd7/).

---

## Mutations

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-mutations-c86fd7/

Mutations are GraphQL operations used to create, update, or delete data on the Blocklet Server. The `@blocklet/server-js` library provides a set of convenient methods that wrap these mutations, making it easy to perform write operations from your application.

This section provides an overview of the available mutation categories. For detailed information on specific methods, including parameters and return types, please refer to the individual sub-sections. If you need to fetch data without modifying it, see the [Queries](/en/docs/blocklet-server-js/api-reference-queries-c86fd7/) section.

All mutation methods follow a similar pattern: they accept an object with an `input` property that corresponds to the required GraphQL input type.

**Calling a Mutation**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function updateNodeName() {
  try {
    const { info } = await client.updateNodeInfo({
      input: {
        name: 'My Awesome Node',
        description: 'This is my newly updated node.'
      }
    });
    console.log('Node updated successfully:', info.name);
  } catch (error) {
    console.error('Failed to update node info:', error);
  }
}

updateNodeName();
```

## Mutation Categories

Mutations are grouped by functionality to help you find the methods you need more easily.

::::card-group
::link-card{title="Node & Blocklet Management" description="Mutations for managing the lifecycle (install, start, stop, delete), configuration, and settings of the node and individual blocklets." icon="server" href="/en/docs/blocklet-server-js/api-reference-mutations-node-blocklet-management-c86fd7/"}
::link-card{title="User & Access Management" description="Methods for creating, updating, and deleting users, roles, permissions, and access keys. Also includes session and passport management." icon="users" href="/en/docs/blocklet-server-js/api-reference-mutations-user-access-management-c86fd7/"}
::link-card{title="Networking & Services" description="Operations for configuring routing rules, managing domain aliases, issuing and updating SSL certificates, and setting up webhooks." icon="routes" href="/en/docs/blocklet-server-js/api-reference-mutations-networking-services-c86fd7/"}
::link-card{title="Data & Operations" description="Mutations for performing operational tasks such as creating and restoring blocklet backups." icon="database" href="/en/docs/blocklet-server-js/api-reference-mutations-data-operations-c86fd7/"}
::link-card{title="Publishing & Projects" description="Manage the entire publishing workflow, including creating projects, drafting releases, connecting to stores, and publishing blocklets." icon="rocket" href="/en/docs/blocklet-server-js/api-reference-mutations-publishing-projects-c86fd7/"}
::::

### Next Steps

After exploring the mutations, you might want to understand the data structures they return. Check out the [Types](/en/docs/blocklet-server-js/api-reference-types-c86fd7/) section for a complete reference of all data models.

---

## Data & Operations

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-mutations-data-operations-c86fd7/

This section details mutations for data management and operational tasks within Blocklet Server, primarily focusing on creating and managing backups, and migrating data structures. These operations are crucial for data integrity, updates, and disaster recovery.

For queries related to backups and logs, please refer to the [Data & Operations Queries](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/) documentation.

## backupBlocklet

Initiates a backup process for a specified blocklet. The backup can be saved to either the local disk or a configured DID Space. This is an asynchronous operation that starts a backup job in the background.

### Parameters

- **input** `RequestBackupBlockletInput` *(required)* — The input object for the backupBlocklet mutation.
  - **appDid** `string` *(required)* — The DID of the blocklet to be backed up.
  - **to** `BackupTo` *(required)* — The destination for the backup. Must be one of `spaces` or `disk`.

### Returns

Returns a `GeneralResponse` object indicating the status of the request.

- **backupBlocklet** `GeneralResponse` — The response object from the mutation.
  - **code** `StatusCode` — Returns `ok` if the backup job was successfully initiated.

### Example

**Backup Blocklet to Disk**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createBackup() {
  try {
    const response = await client.backupBlocklet({
      input: {
        appDid: 'z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G',
        to: 'disk',
      },
    });
    console.log('Backup initiated:', response.code);
  } catch (error) {
    console.error('Error initiating backup:', error);
  }
}

createBackup();
```

<strong>Example Response</strong>

```json
{
  "backupBlocklet": {
    "code": "ok"
  }
}
```

This example shows how to start a backup process for a specific blocklet, saving the backup to the local disk.

## abortBlockletBackup

Aborts an in-progress backup operation for a specific blocklet. This is useful for canceling long-running backups.

### Parameters

- **input** `RequestAbortBlockletBackupInput` *(required)* — The input object for the abortBlockletBackup mutation.
  - **appPid** `string` *(required)* — The process ID (which is the blocklet DID) of the blocklet whose backup should be aborted.

### Returns

Returns a `GeneralResponse` object indicating the status of the request.

- **abortBlockletBackup** `GeneralResponse` — The response object from the mutation.
  - **code** `StatusCode` — Returns `ok` if the backup abortion was successfully requested.

### Example

**Abort Backup**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function cancelBackup(blockletDid) {
  try {
    const response = await client.abortBlockletBackup({
      input: {
        appPid: blockletDid,
      },
    });
    console.log('Backup cancellation requested:', response.code);
  } catch (error) {
    console.error('Error aborting backup:', error);
  }
}

cancelBackup('z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G');
```

<strong>Example Response</strong>

```json
{
  "abortBlockletBackup": {
    "code": "ok"
  }
}
```

This example demonstrates how to cancel a running backup for a given blocklet.

## restoreBlocklet

Restores a blocklet from a backup. The source of the backup can be either the local disk or a DID Space. This operation will overwrite the existing blocklet data if it exists.

### Parameters

- **input** `RequestRestoreBlockletInput` *(required)* — The input object for the restoreBlocklet mutation.
  - **appDid** `string` *(required)* — The DID of the blocklet to restore.
  - **appPid** `string` *(required)* — The process ID (DID) of the blocklet being restored.
  - **from** `BackupTo` *(required)* — The source of the backup. Must be one of `spaces` or `disk`.
  - **endpoint** `string` — The backup endpoint URL. Required when restoring from `spaces`.
  - **delegation** `string` — Optional. Delegation information for accessing the backup.
  - **password** `Bytes` — Optional. Password for decrypting the backup, if it's encrypted.
  - **wallet** `any` — Optional. The wallet object for authentication if required.

### Returns

Returns a `GeneralResponse` object indicating the status of the request.

- **restoreBlocklet** `GeneralResponse` — The response object from the mutation.
  - **code** `StatusCode` — Returns `ok` if the restore job was successfully initiated.

### Example

**Restore from Disk**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restoreFromBackup() {
  try {
    const response = await client.restoreBlocklet({
      input: {
        appDid: 'z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G',
        appPid: 'z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G',
        from: 'disk',
      },
    });
    console.log('Restore initiated:', response.code);
  } catch (error) {
    console.error('Error initiating restore:', error);
  }
}

restoreFromBackup();
```

<strong>Example Response</strong>

```json
{
  "restoreBlocklet": {
    "code": "ok"
  }
}
```

This example shows how to start a restore process for a blocklet from a local disk backup.

## migrateApplicationToStructV2

Migrates an application from an older data structure to the V2 structure. This is a one-time operation typically required for older blocklets to support newer features like componentization and enhanced backup/restore capabilities.

### Parameters

- **input** `RequestMigrateApplicationToStructV2Input` *(required)* — The input object for the migration mutation.
  - **did** `string` *(required)* — The DID of the application to migrate.
  - **appSk** `string` *(required)* — The secret key of the application.

### Returns

Returns a `GeneralResponse` object indicating the status of the request.

- **migrateApplicationToStructV2** `GeneralResponse` — The response object from the mutation.
  - **code** `StatusCode` — Returns `ok` if the migration was successful.

### Example

**Migrate Application**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function migrateApp(appDid, appSecretKey) {
  try {
    const response = await client.migrateApplicationToStructV2({
      input: {
        did: appDid,
        appSk: appSecretKey,
      },
    });
    console.log('Migration successful:', response.code);
  } catch (error) {
    console.error('Error migrating application:', error);
  }
}

migrateApp('z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G', 'your_app_secret_key');
```

<strong>Example Response</strong>

```json
{
  "migrateApplicationToStructV2": {
    "code": "ok"
  }
}
```

This example shows how to trigger the data structure migration for an older application.

---

## Networking & Services

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-mutations-networking-services-c86fd7/

This section details the mutations available for managing networking and services on your Blocklet Server. You can perform actions such as configuring routing rules, managing SSL/TLS certificates, setting up webhooks, and handling notifications. For methods to retrieve networking and service data, please see the [Networking & Services Queries](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/) section.

## Routing Management

These mutations allow you to manage how traffic is routed to your blocklets and services.

### addRoutingSite

Adds a new routing site, which is a collection of rules for a specific domain.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the site details.
  - **domain** `string` *(required)* — The primary domain for the site.
  - **type** `string` *(required)* — The type of the site.
  - **rules** `RoutingRuleInput[]` — An array of routing rules to apply to this site.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the newly created site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The newly created routing site object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createRoutingSite() {
  try {
    const { site } = await client.addRoutingSite({
      input: {
        domain: 'example.com',
        type: 'blocklet',
        rules: [
          {
            from: { pathPrefix: '/' },
            to: { type: 'blocklet', did: 'z8iZuf...' },
          },
        ],
      },
    });
    console.log('Routing site created:', site.id);
  } catch (error) {
    console.error('Error creating routing site:', error);
  }
}

createRoutingSite();
```

### addDomainAlias

Adds a domain alias to an existing routing site.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the alias details.
  - **id** `string` *(required)* — The ID of the routing site to add the alias to.
  - **domainAlias** `string` *(required)* — The domain alias to add.
  - **force** `boolean` — Whether to force the addition even if conflicts exist.
  - **teamDid** `string` — The DID of the team associated with this action.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the updated site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The updated routing site object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function addAlias(siteId) {
  try {
    const { site } = await client.addDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('Domain alias added:', site.domainAliases);
  } catch (error) {
    console.error('Error adding domain alias:', error);
  }
}

addAlias('z2as...'); // Replace with your site ID
```

### deleteDomainAlias

Deletes a domain alias from a routing site.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the details for deletion.
  - **id** `string` *(required)* — The ID of the routing site.
  - **domainAlias** `string` *(required)* — The domain alias to delete.
  - **teamDid** `string` — The DID of the team.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the updated site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The updated routing site object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeAlias(siteId) {
  try {
    const { site } = await client.deleteDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('Domain alias removed:', site.domainAliases);
  } catch (error) {
    console.error('Error removing domain alias:', error);
  }
}

removeAlias('z2as...'); // Replace with your site ID
```

### updateRoutingSite

Updates properties of an existing routing site, such as CORS allowed origins.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the update details.
  - **id** `string` *(required)* — The ID of the routing site to update.
  - **corsAllowedOrigins** `string[]` — An array of allowed origins for CORS.
  - **domain** `string` — The new primary domain for the site.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the updated site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The updated routing site object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function updateSite(siteId) {
  try {
    const { site } = await client.updateRoutingSite({
      input: {
        id: siteId,
        corsAllowedOrigins: ['https://app.example.com'],
      },
    });
    console.log('Routing site updated:', site.id);
  } catch (error) {
    console.error('Error updating routing site:', error);
  }
}

updateSite('z2as...'); // Replace with your site ID
```

### addRoutingRule

Adds a new routing rule to an existing site.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the routing rule details.
  - **id** `string` *(required)* — The ID of the site to add the rule to.
  - **rule** `RoutingRuleInput` *(required)* — The routing rule object to add.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the updated site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The updated routing site object.

### updateRoutingRule

Updates an existing routing rule within a site.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the routing rule update details.
  - **id** `string` *(required)* — The ID of the site containing the rule.
  - **rule** `RoutingRuleInput` *(required)* — The updated routing rule object. The rule's `id` field must be provided.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the updated site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The updated routing site object.

### deleteRoutingRule

Deletes a routing rule from a site.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the identifiers for the rule to be deleted.
  - **id** `string` *(required)* — The ID of the site containing the rule.
  - **ruleId** `string` *(required)* — The ID of the rule to delete.

<strong>Returns</strong>

- **ResponseRoutingSite** `object` — The response object containing the updated site.
  - **code** `StatusCode` — The status code of the operation.
  - **site** `RoutingSite` — The updated routing site object.

### deleteRoutingSite

Deletes an entire routing site.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the ID of the site to delete.
  - **id** `string` *(required)* — The ID of the routing site to delete.

<strong>Returns</strong>

- **GeneralResponse** `object` — The response object indicating success or failure.
  - **code** `StatusCode` — The status code of the operation.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteSite(siteId) {
  try {
    await client.deleteRoutingSite({ input: { id: siteId } });
    console.log('Routing site deleted successfully.');
  } catch (error) {
    console.error('Error deleting routing site:', error);
  }
}

deleteSite('z2as...'); // Replace with your site ID
```

### takeRoutingSnapshot

Creates a snapshot of the current routing configuration, which can be used for backup or rollback purposes.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing snapshot options.
  - **dryRun** `boolean` — If `true`, performs a dry run without creating the snapshot.
  - **message** `string` — A descriptive message for the snapshot.

<strong>Returns</strong>

- **ResponseTakeRoutingSnapshot** `object` — The response object containing the snapshot hash.
  - **code** `StatusCode` — The status code of the operation.
  - **hash** `string` — The hash of the created snapshot.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createSnapshot() {
  try {
    const { hash } = await client.takeRoutingSnapshot({
      input: { message: 'Backup before major update' },
    });
    console.log('Routing snapshot created with hash:', hash);
  } catch (error) {
    console.error('Error creating snapshot:', error);
  }
}

createSnapshot();
```

## Certificate Management

Manage SSL/TLS certificates for your domains.

### addCertificate

Adds a custom SSL/TLS certificate to the server.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the certificate details.
  - **name** `string` *(required)* — A unique name for the certificate.
  - **privateKey** `string` *(required)* — The private key in PEM format.
  - **certificate** `string` *(required)* — The certificate chain in PEM format.

<strong>Returns</strong>

- **ResponseAddNginxHttpsCert** `object` — The response object indicating success or failure.
  - **code** `StatusCode` — The status code of the operation.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function uploadCertificate() {
  try {
    await client.addCertificate({
      input: {
        name: 'my-example-cert',
        privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
        certificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
      },
    });
    console.log('Certificate added successfully.');
  } catch (error) {
    console.error('Error adding certificate:', error);
  }
}

uploadCertificate();
```

### issueLetsEncryptCert

Issues a new certificate from Let's Encrypt for a specified domain.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the domain and associated site information.
  - **domain** `string` *(required)* — The domain to issue the certificate for.
  - **did** `string` *(required)* — The DID of the blocklet or team associated with this domain.
  - **siteId** `string` *(required)* — The ID of the routing site this certificate will be used for.

<strong>Returns</strong>

- **ResponseAddLetsEncryptCert** `object` — The response object indicating success or failure.
  - **code** `StatusCode` — The status code of the operation.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function issueCert(domain, did, siteId) {
  try {
    await client.issueLetsEncryptCert({
      input: {
        domain: domain,
        did: did,
        siteId: siteId,
      },
    });
    console.log(`Let's Encrypt certificate issuance initiated for ${domain}.`);
  } catch (error) {
    console.error('Error issuing certificate:', error);
  }
}

issueCert('example.com', 'z8iZuf...', 'z2as...');
```

### updateCertificate

Updates the name of an existing custom certificate.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the certificate update details.
  - **id** `string` *(required)* — The ID of the certificate to update.
  - **name** `string` *(required)* — The new name for the certificate.

<strong>Returns</strong>

- **ResponseUpdateNginxHttpsCert** `object` — The response object indicating success or failure.
  - **code** `StatusCode` — The status code of the operation.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function renameCertificate(certId) {
  try {
    await client.updateCertificate({
      input: {
        id: certId,
        name: 'new-cert-name',
      },
    });
    console.log('Certificate updated successfully.');
  } catch (error) {
    console.error('Error updating certificate:', error);
  }
}

renameCertificate('cert_xxx'); // Replace with your certificate ID
```

### deleteCertificate

Deletes a custom SSL/TLS certificate from the server.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the ID of the certificate to delete.
  - **id** `string` *(required)* — The ID of the certificate to delete.

<strong>Returns</strong>

- **ResponseDeleteNginxHttpsCert** `object` — The response object indicating success or failure.
  - **code** `StatusCode` — The status code of the operation.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeCertificate(certId) {
  try {
    await client.deleteCertificate({ input: { id: certId } });
    console.log('Certificate deleted successfully.');
  } catch (error) {
    console.error('Error deleting certificate:', error);
  }
}

removeCertificate('cert_xxx'); // Replace with your certificate ID
```

## Webhook Management

Create and manage webhooks to receive notifications about events on your Blocklet Server.

### createWebHook

Creates a new webhook sender configuration.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the webhook details.
  - **type** `SenderType` *(required)* — The type of webhook sender (e.g., 'slack', 'api').
  - **title** `string` *(required)* — A title for the webhook.
  - **description** `string` — A description for the webhook.
  - **params** `WebHookParamInput[]` — An array of parameters for the webhook, such as the target URL.

<strong>Returns</strong>

- **ResponseCreateWebHook** `object` — The response object containing the new webhook sender.
  - **code** `StatusCode` — The status code of the operation.
  - **webhook** `WebHookSender` — The created webhook sender object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createWebhook() {
  try {
    const { webhook } = await client.createWebHook({
      input: {
        type: 'api',
        title: 'My Custom Webhook',
        description: 'Sends notifications to my service.',
        params: [{ name: 'url', value: 'https://myservice.com/webhook' }],
      },
    });
    console.log('Webhook created:', webhook.id);
  } catch (error) {
    console.error('Error creating webhook:', error);
  }
}

createWebhook();
```

### deleteWebHook

Deletes an existing webhook sender.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the ID of the webhook to delete.
  - **id** `string` *(required)* — The ID of the webhook to delete.

<strong>Returns</strong>

- **ResponseDeleteWebHook** `object` — The response object indicating success or failure.
  - **code** `StatusCode` — The status code of the operation.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteWebhook(webhookId) {
  try {
    await client.deleteWebHook({ input: { id: webhookId } });
    console.log('Webhook deleted successfully.');
  } catch (error) {
    console.error('Error deleting webhook:', error);
  }
}

deleteWebhook('wh_xxx'); // Replace with your webhook ID
```

### createWebhookEndpoint

Creates a new webhook endpoint to receive events from the Blocklet Server.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the webhook endpoint details.
  - **teamDid** `string` *(required)* — The DID of the team associated with this endpoint.
  - **input** `WebhookEndpointStateInput` *(required)* — The configuration for the new endpoint.

<strong>Returns</strong>

- **ResponseCreateWebhookEndpoint** `object` — The response object containing the new webhook endpoint.
  - **data** `WebhookEndpointState` — The created webhook endpoint object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createEndpoint() {
  try {
    const { data } = await client.createWebhookEndpoint({
      input: {
        teamDid: 'z2qa...',
        input: {
          url: 'https://myapp.com/api/webhooks',
          description: 'My application endpoint',
          enabledEvents: [{ type: 'blocklet.started', source: 'system' }],
        },
      },
    });
    console.log('Webhook endpoint created:', data.id);
  } catch (error) {
    console.error('Error creating endpoint:', error);
  }
}

createEndpoint();
```

### updateWebhookEndpoint

Updates an existing webhook endpoint.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the webhook endpoint update details.
  - **teamDid** `string` *(required)* — The DID of the team.
  - **id** `string` *(required)* — The ID of the endpoint to update.
  - **data** `WebhookEndpointStateInput` *(required)* — The new configuration for the endpoint.

<strong>Returns</strong>

- **ResponseUpdateWebhookEndpoint** `object` — The response object containing the updated webhook endpoint.
  - **data** `WebhookEndpointState` — The updated webhook endpoint object.

### deleteWebhookEndpoint

Deletes a webhook endpoint.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the ID of the endpoint to delete.
  - **teamDid** `string` *(required)* — The DID of the team.
  - **id** `string` *(required)* — The ID of the endpoint to delete.

<strong>Returns</strong>

- **ResponseDeleteWebhookEndpoint** `object` — The response object containing the deleted webhook endpoint.
  - **data** `WebhookEndpointState` — The deleted webhook endpoint object.

### retryWebhookAttempt

Retries a failed webhook delivery attempt.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the details of the attempt to retry.
  - **teamDid** `string` *(required)* — The DID of the team.
  - **eventId** `string` *(required)* — The ID of the event.
  - **webhookId** `string` *(required)* — The ID of the webhook.
  - **attemptId** `string` *(required)* — The ID of the failed attempt.

<strong>Returns</strong>

- **ResponseGetWebhookAttempt** `object` — The response object containing the new attempt state.
  - **data** `WebhookAttemptState` — The state of the new webhook attempt.

## Notification Management

Manage user notifications within the Blocklet Server.

### readNotifications

Marks one or more notifications as read.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the notification IDs to mark as read.
  - **notificationIds** `string[]` *(required)* — An array of notification IDs.
  - **teamDid** `string` — The team DID scope.
  - **receiver** `string` — The receiver's DID.

<strong>Returns</strong>

- **ResponseReadNotifications** `object` — The response object indicating the number of affected notifications.
  - **code** `StatusCode` — The status code of the operation.
  - **numAffected** `number` — The number of notifications marked as read.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsRead(notificationIds) {
  try {
    const { numAffected } = await client.readNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} notifications marked as read.`);
  } catch (error) {
    console.error('Error marking notifications as read:', error);
  }
}

markAsRead(['notif_xxx', 'notif_yyy']);
```

### unreadNotifications

Marks one or more notifications as unread.

<strong>Parameters</strong>

- **input** `object` *(required)* — An object containing the notification IDs to mark as unread.
  - **notificationIds** `string[]` *(required)* — An array of notification IDs.
  - **teamDid** `string` — The team DID scope.
  - **receiver** `string` — The receiver's DID.

<strong>Returns</strong>

- **ResponseReadNotifications** `object` — The response object indicating the number of affected notifications.
  - **code** `StatusCode` — The status code of the operation.
  - **numAffected** `number` — The number of notifications marked as unread.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsUnread(notificationIds) {
  try {
    const { numAffected } = await client.unreadNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} notifications marked as unread.`);
  } catch (error) {
    console.error('Error marking notifications as unread:', error);
  }
}

markAsUnread(['notif_xxx']);
```

This section covered mutations for networking and services. Next, you can explore mutations for managing backups and other operational tasks.

:::action-card{title="Next: Data & Operations" description="Learn how to perform mutations related to data management and operational tasks." icon="database"}
::action{label="Read More" href="/en/docs/blocklet-server-js/api-reference-mutations-data-operations-c86fd7/" variant="primary"}
:::

---

## Node & Blocklet Management

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-mutations-node-blocklet-management-c86fd7/

This section provides a detailed reference for mutations related to managing the lifecycle and configuration of the Blocklet Server node and the blocklets running on it. These operations allow you to programmatically install, start, stop, configure, and upgrade both individual blocklets and the node itself.

## Blocklet Lifecycle

These mutations control the fundamental lifecycle of a blocklet, from installation to removal.

### installBlocklet

Installs a new blocklet onto the node from various sources like a store, a URL, or a local file.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the installBlocklet mutation.
  - **type** `string` — The installation type. Can be 'store', 'url', or 'upload'.
  - **did** `string` — The DID of the blocklet to install (required for store installations).
  - **storeUrl** `string` — The URL of the Blocklet Store.
  - **url** `string` — The URL to the blocklet's meta file or bundle (required for URL installations).
  - **file** `Upload` — The blocklet bundle file to upload.
  - **diffVersion** `string` — The version to apply a diff against during an upgrade.
  - **deleteSet** `string[]` — A list of files to delete during a diff-based upgrade.
  - **title** `string` — A custom title for the new blocklet instance.
  - **description** `string` — A custom description for the new blocklet instance.
  - **startImmediately** `boolean` — If true, the blocklet will be started automatically after installation.
  - **downloadTokenList** `DownloadTokenInput[]` — A list of download tokens for private components.
    - **did** `string` *(required)* — The DID of the component requiring a token.
    - **token** `string` *(required)* — The download token.

<strong>Example: Install from Store</strong>

**Install from Store**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function installMyBlocklet() {
  try {
    const { blocklet } = await client.installBlocklet({
      input: {
        did: 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf',
        storeUrl: 'https://store.blocklet.dev',
        startImmediately: true,
      },
    });
    console.log(`Blocklet '${blocklet.meta.title}' installed successfully.`);
  } catch (error) {
    console.error('Failed to install blocklet:', error);
  }
}

installMyBlocklet();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf",
      "name": "@blocklet/did-wallet-adapter",
      "version": "1.16.111",
      "title": "DID Wallet Adapter"
    },
    "status": "installed",
    "appDid": "z12A1B...",
    "appPid": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
  }
}
```

This example installs the DID Wallet Adapter blocklet from the official store and starts it immediately. The response contains the complete state object of the newly installed blocklet.

### startBlocklet

Starts one or more components of a blocklet that are currently in a stopped or error state.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the startBlocklet mutation.
  - **did** `string` *(required)* — The root DID of the blocklet.
  - **componentDids** `string[]` — An optional array of component DIDs to start. If omitted, all components will be started.

<strong>Example</strong>

**Start a Blocklet**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function startMyBlocklet() {
  try {
    const { blocklet } = await client.startBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' is now ${blocklet.status}.`);
  } catch (error) {
    console.error('Failed to start blocklet:', error);
  }
}

startMyBlocklet();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}
```

### stopBlocklet

Stops one or more running components of a blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the stopBlocklet mutation.
  - **did** `string` *(required)* — The root DID of the blocklet.
  - **componentDids** `string[]` — An optional array of component DIDs to stop. If omitted, all running components will be stopped.

<strong>Example</strong>

**Stop a Blocklet**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function stopMyBlocklet() {
  try {
    const { blocklet } = await client.stopBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' is now ${blocklet.status}.`);
  } catch (error) {
    console.error('Failed to stop blocklet:', error);
  }
}

stopMyBlocklet();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "stopped"
    // ... other properties
  }
}
```

### reloadBlocklet

Reloads one or more running components of a blocklet, applying any code changes without a full restart. This is often faster than a restart.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the reloadBlocklet mutation.
  - **did** `string` *(required)* — The root DID of the blocklet.
  - **componentDids** `string[]` — An optional array of component DIDs to reload. If omitted, all reloadable components will be reloaded.

<strong>Example</strong>

**Reload a Blocklet**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function reloadMyBlocklet() {
  try {
    const { blocklet } = await client.reloadBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' has been reloaded.`);
  } catch (error) {
    console.error('Failed to reload blocklet:', error);
  }
}

reloadMyBlocklet();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}
```

### restartBlocklet

Restarts one or more components of a blocklet. This is equivalent to stopping and then starting them.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the restartBlocklet mutation.
  - **did** `string` *(required)* — The root DID of the blocklet.
  - **componentDids** `string[]` — An optional array of component DIDs to restart. If omitted, all components will be restarted.

<strong>Example</strong>

**Restart a Blocklet**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function restartMyBlocklet() {
  try {
    const { blocklet } = await client.restartBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' has been restarted.`);
  } catch (error) {
    console.error('Failed to restart blocklet:', error);
  }
}

restartMyBlocklet();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}
```

### deleteBlocklet

Permanently removes a blocklet and its components from the node.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the deleteBlocklet mutation.
  - **did** `string` *(required)* — The root DID of the blocklet to delete.
  - **keepData** `boolean` (default: `false`) — If true, the blocklet's data directory will be preserved.

<strong>Example</strong>

**Delete a Blocklet**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function deleteMyBlocklet() {
  try {
    await client.deleteBlocklet({ input: { did: blockletDid } });
    console.log('Blocklet deleted successfully.');
  } catch (error) {
    console.error('Failed to delete blocklet:', error);
  }
}

deleteMyBlocklet();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "deleted"
    // ... other properties
  }
}
```

### cancelDownloadBlocklet

Cancels an in-progress blocklet download.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the cancelDownloadBlocklet mutation.
  - **did** `string` *(required)* — The root DID of the blocklet whose download should be canceled.

<strong>Example</strong>

**Cancel a Download**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function cancelDownload() {
  try {
    const { blocklet } = await client.cancelDownloadBlocklet({ input: { did: blockletDid } });
    console.log(`Download for blocklet '${blocklet.meta.title}' cancelled.`);
  } catch (error) {
    console.error('Failed to cancel download:', error);
  }
}

cancelDownload();
```

## Component Management

These mutations are used to manage the components within a blocklet, including installation, upgrades, and configuration changes.

### installComponent

Installs a new component into an existing blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the installComponent mutation.
  - **rootDid** `string` *(required)* — The root DID of the parent blocklet.
  - **mountPoint** `string` *(required)* — The path where the component will be mounted.
  - **url** `string` — The URL to the component's meta file or bundle.
  - **did** `string` — The DID of the component to install.
  - **title** `string` — A custom title for the component.
  - **configs** `ConfigEntryInput[]` — An array of initial configuration values for the component.

<strong>Example</strong>

**Install a Component**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const rootBlockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function installNewComponent() {
  try {
    const { blocklet } = await client.installComponent({
      input: {
        rootDid: rootBlockletDid,
        mountPoint: '/new-component',
        did: 'z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x',
        title: 'My New Component',
      },
    });
    console.log('Component installed successfully.');
  } catch (error) {
    console.error('Failed to install component:', error);
  }
}

installNewComponent();
```

### deleteComponent

Permanently removes a component from a blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the deleteComponent mutation.
  - **did** `string` *(required)* — The DID of the component to delete.
  - **rootDid** `string` *(required)* — The root DID of the parent blocklet.
  - **keepData** `boolean` (default: `false`) — If true, the component's data will be preserved.

<strong>Example</strong>

**Delete a Component**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const rootBlockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';
const componentDid = 'z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x';

async function deleteMyComponent() {
  try {
    await client.deleteComponent({
      input: { did: componentDid, rootDid: rootBlockletDid },
    });
    console.log('Component deleted successfully.');
  } catch (error) {
    console.error('Failed to delete component:', error);
  }
}

deleteMyComponent();
```

### checkComponentsForUpdates

Checks for available updates for the components within a blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the checkComponentsForUpdates mutation.
  - **did** `string` *(required)* — The root DID of the blocklet to check for updates.

<strong>Returns</strong>

- **preUpdateInfo** `object` — Information about available updates.
  - **updateId** `string` — A unique ID for this update session.
  - **updateList** `UpdateList[]` — A list of components with available updates.
    - **id** `string` — The DID of the component.
    - **meta** `BlockletMeta` — The metadata of the new version.

<strong>Example</strong>

**Check for Updates**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function checkUpdates() {
  try {
    const { preUpdateInfo } = await client.checkComponentsForUpdates({ input: { did: blockletDid } });
    if (preUpdateInfo.updateList.length > 0) {
      console.log('Updates available:', preUpdateInfo.updateList);
    } else {
      console.log('All components are up to date.');
    }
  } catch (error) {
    console.error('Failed to check for updates:', error);
  }
}

checkUpdates();
```

### upgradeComponents

Upgrades selected components to their latest versions based on an `updateId` from `checkComponentsForUpdates`.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the upgradeComponents mutation.
  - **updateId** `string` *(required)* — The update session ID from checkComponentsForUpdates.
  - **rootDid** `string` *(required)* — The root DID of the blocklet.
  - **selectedComponents** `string[]` *(required)* — An array of component DIDs to upgrade.

<strong>Example</strong>

**Upgrade Components**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const updateId = '...'; // from checkComponentsForUpdates
const rootDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';
const componentsToUpgrade = ['z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x'];

async function performUpgrade() {
  try {
    await client.upgradeComponents({
      input: {
        updateId,
        rootDid,
        selectedComponents: componentsToUpgrade,
      },
    });
    console.log('Components upgraded successfully.');
  } catch (error) {
    console.error('Failed to upgrade components:', error);
  }
}

performUpgrade();
```

### updateComponentTitle

Updates the display title of a specific component within a blocklet.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID of the component to update.
- **rootDid** `string` *(required)* — The root DID of the parent blocklet.
- **title** `string` *(required)* — The new title for the component.

### updateComponentMountPoint

Changes the URL path (mount point) for a specific component within a blocklet.

<strong>Parameters</strong>

- **did** `string` *(required)* — The DID of the component to update.
- **rootDid** `string` *(required)* — The root DID of the parent blocklet.
- **mountPoint** `string` *(required)* — The new mount point for the component (e.g., '/new-path').

## Configuration & Settings

These mutations handle the dynamic configuration of blocklets and the node.

### configBlocklet

Updates the configuration (environment variables) for a blocklet or one of its components.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the configBlocklet mutation.
  - **did** `string[]` *(required)* — An array containing the root DID and optionally a component DID.
  - **configs** `ConfigEntryInput[]` *(required)* — An array of configuration objects to update.
    - **key** `string` *(required)* — The environment variable name.
    - **value** `string` *(required)* — The new value for the variable.

<strong>Example</strong>

**Configure a Blocklet**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function updateConfiguration() {
  try {
    await client.configBlocklet({
      input: {
        did: [blockletDid],
        configs: [
          { key: 'API_ENDPOINT', value: 'https://api.new.com' },
          { key: 'API_KEY', value: 'new-secret-key' },
        ],
      },
    });
    console.log('Blocklet configuration updated.');
  } catch (error) {
    console.error('Failed to configure blocklet:', error);
  }
}

updateConfiguration();
```

### updateBlockletSettings

Updates various settings for a specific blocklet, such as gateway policies, invite settings, and AI service configurations.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the updateBlockletSettings mutation.
  - **did** `string` *(required)* — The DID of the blocklet to update.
  - **enableSessionHardening** `boolean` — Enable or disable session hardening for enhanced security.
  - **invite** `InviteSettingsInput` — Settings related to user invitations.
    - **enabled** `boolean` — Enable or disable the invitation feature.
  - **gateway** `BlockletGatewayInput` — Configuration for the blocklet's gateway, including rate limiting and security policies.
  - **aigne** `AigneConfigInput` — Configuration for the AIGNE service integration.

### updateAutoBackup

Enables or disables the automatic backup feature for a blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the updateAutoBackup mutation.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **autoBackup** `AutoBackupInput` *(required)* — The auto-backup configuration.
    - **enabled** `boolean` *(required)* — Set to true to enable automatic backups, false to disable.

### updateAutoCheckUpdate

Enables or disables the automatic check for updates feature for a blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the updateAutoCheckUpdate mutation.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **autoCheckUpdate** `AutoCheckUpdateInput` *(required)* — The auto-check-update configuration.
    - **enabled** `boolean` *(required)* — Set to true to enable automatic update checks, false to disable.

## Node Management

These mutations are used to manage the Blocklet Server node itself.

### updateNodeInfo

Updates the general information and settings for the Blocklet Server node.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the updateNodeInfo mutation.
  - **name** `string` — The new name for the node.
  - **description** `string` — The new description for the node.
  - **autoUpgrade** `boolean` — Enable or disable automatic node upgrades.
  - **enableWelcomePage** `boolean` — Enable or disable the welcome page.
  - **webWalletUrl** `string` — The URL of the web wallet to be used with the node.
  - **enableBetaRelease** `boolean` — Enable or disable the beta release channel for updates.

<strong>Example</strong>

**Configure Node**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function configureNode() {
  try {
    const { info } = await client.updateNodeInfo({
      input: {
        name: 'My Production Node',
        autoUpgrade: true,
      },
    });
    console.log(`Node name updated to: ${info.name}`);
  } catch (error) {
    console.error('Failed to update node info:', error);
  }
}

configureNode();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "info": {
    "did": "z12A1B...",
    "name": "My Production Node",
    "autoUpgrade": true
    // ... other properties
  }
}
```

### upgradeNodeVersion

Initiates an upgrade of the Blocklet Server to the next available version.

<strong>Parameters</strong>

- **input** `object` — The input object for the upgradeNodeVersion mutation.
  - **sessionId** `string` — An optional session ID for tracking the upgrade process.

<strong>Example</strong>

**Upgrade Node**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function upgradeMyNode() {
  try {
    const { sessionId } = await client.upgradeNodeVersion({});
    console.log(`Node upgrade started with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to start node upgrade:', error);
  }
}

upgradeMyNode();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "sessionId": "unique-session-id-for-upgrade"
}
```

### restartServer

Restarts the Blocklet Server daemon. This will temporarily interrupt all running blocklets and services.

<strong>Example</strong>

**Restart Server**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restartMyServer() {
  try {
    const { sessionId } = await client.restartServer();
    console.log(`Server restart initiated with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to restart server:', error);
  }
}

restartMyServer();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "sessionId": "unique-session-id-for-restart"
}
```

### resetNode

Resets various parts of the node's configuration and data. This is a destructive operation and should be used with caution.

<strong>Parameters</strong>

- **input** `object` *(required)* — The input object for the resetNode mutation.
  - **owner** `boolean` — Reset the node owner.
  - **blocklets** `boolean` — Delete all installed blocklets.
  - **webhooks** `boolean` — Delete all webhooks.
  - **certificates** `boolean` — Delete all SSL certificates.
  - **accessKeys** `boolean` — Delete all access keys.
  - **routingRules** `boolean` — Delete all routing rules.
  - **users** `boolean` — Delete all users except the owner.
  - **invitations** `boolean` — Delete all pending invitations.

<strong>Example</strong>

**Reset Node Data**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function resetNodeData() {
  try {
    await client.resetNode({
      input: {
        blocklets: true,
        users: true,
      },
    });
    console.log('Node blocklets and users have been reset.');
  } catch (error) {
    console.error('Failed to reset node:', error);
  }
}

resetNodeData();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok"
}
```

### restartAllContainers

Restarts all running Docker containers managed by the Blocklet Server. This is useful for applying system-wide changes that affect the Docker environment.

<strong>Example</strong>

**Restart All Containers**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restartContainers() {
  try {
    const { sessionId } = await client.restartAllContainers();
    console.log(`Restarting all containers with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to restart containers:', error);
  }
}

restartContainers();
```

<strong>Example Response</strong>

**Response**

```json
{
  "code": "ok",
  "sessionId": "unique-session-id-for-restart-all"
}
```

---

## Publishing & Projects

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-mutations-publishing-projects-c86fd7/

This section details the mutations available for managing the entire lifecycle of your blocklet projects, from creation and release management to connecting with blocklet stores and publishing your work. These mutations enable programmatic control over how your projects are developed, versioned, and distributed.

For fetching project-related data, please see the [Publishing & Projects Queries](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/) documentation.

## Project Management

These mutations handle the creation, modification, and deletion of your development projects.

### createProject

Creates a new project for a specified blocklet component, setting it up for future releases and publishing.

<strong>Parameters</strong>

- **input** `RequestCreateProjectInput` *(required)* — An object containing the project details.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **type** `PublishType` *(required)* — The type of project, either 'resource' or 'pack'.
  - **blockletDid** `string` *(required)* — The DID of the blocklet being published.
  - **blockletTitle** `string` *(required)* — The title of the blocklet.
  - **componentDid** `string` — The DID of the component associated with the project.
  - **tenantScope** `string` — The scope of the tenant.

<strong>Example</strong>

**Create Project**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { project } = await client.mutation.createProject({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      type: 'resource',
      blockletDid: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      blockletTitle: 'My New Blocklet Project',
      componentDid: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
    },
  });
  console.log('Project created:', project.id);
} catch (error) {
  console.error('Error creating project:', error);
}
```

<strong>Response</strong>

- **ResponseProject** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **project** `Project` — The newly created project object.

### updateProject

Updates the details of an existing project, such as its title, description, or introduction.

<strong>Parameters</strong>

- **input** `RequestUpdateProjectInput` *(required)* — An object containing the project details to update.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **projectId** `string` *(required)* — The ID of the project to update.
  - **blockletTitle** `string` — The new title for the blocklet.
  - **blockletDescription** `string` — The new description for the blocklet.
  - **blockletIntroduction** `string` — The new introduction for the blocklet.
  - **autoUpload** `boolean` — Whether to automatically upload resources.
  - **possibleSameStore** `boolean` — Whether it's possible to publish to the same store.
  - **blockletSupport** `string` — URL for blocklet support.
  - **blockletCommunity** `string` — URL for the blocklet community.
  - **blockletHomepage** `string` — URL for the blocklet's homepage.

<strong>Example</strong>

**Update Project**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { project } = await client.mutation.updateProject({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      blockletTitle: 'My Updated Blocklet Project',
      blockletDescription: 'An updated description for my project.',
    },
  });
  console.log('Project updated:', project.id);
} catch (error) {
  console.error('Error updating project:', error);
}
```

<strong>Response</strong>

- **ResponseProject** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **project** `Project` — The updated project object.

### deleteProject

Permanently deletes a project. This action cannot be undone.

<strong>Parameters</strong>

- **input** `RequestProjectInput` *(required)* — An object containing the project identifier.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **projectId** `string` *(required)* — The ID of the project to delete.

<strong>Example</strong>

**Delete Project**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.deleteProject({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
    },
  });
  console.log('Project deleted successfully.');
} catch (error) {
  console.error('Error deleting project:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

## Release Management

These mutations are used to create and manage releases for your projects.

### createRelease

Creates a new release for a project, capturing a specific version of the blocklet with associated metadata.

<strong>Parameters</strong>

- **input** `RequestCreateReleaseInput` *(required)* — An object containing the release details.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **projectId** `string` *(required)* — The ID of the project for this release.
  - **blockletDid** `string` *(required)* — The DID of the blocklet version for this release.
  - **blockletVersion** `string` *(required)* — The version number of the blocklet.
  - **note** `string` — Release notes or a summary of changes.
  - **blockletTitle** `string` — The title for this release.
  - **blockletDescription** `string` — The description for this release.
  - **blockletScreenshots** `string[]` — An array of URLs for screenshots.

<strong>Example</strong>

**Create Release**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { release } = await client.mutation.createRelease({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      blockletDid: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      blockletVersion: '1.0.0',
      note: 'Initial release with core features.',
    },
  });
  console.log('Release created:', release.id);
} catch (error) {
  console.error('Error creating release:', error);
}
```

<strong>Response</strong>

- **ResponseRelease** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **release** `Release` — The newly created release object.

### deleteRelease

Permanently deletes a release from a project.

<strong>Parameters</strong>

- **input** `RequestReleaseInput` *(required)* — An object containing the release identifier.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **projectId** `string` *(required)* — The ID of the project containing the release.
  - **releaseId** `string` *(required)* — The ID of the release to delete.

<strong>Example</strong>

**Delete Release**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.deleteRelease({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      releaseId: 'release_67890',
    },
  });
  console.log('Release deleted successfully.');
} catch (error) {
  console.error('Error deleting release:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

## Resource Management

This mutation is used for managing resources associated with a project release.

### updateSelectedResources

Updates the list of resources selected for a specific release of a component within a project.

<strong>Parameters</strong>

- **input** `RequestUpdateSelectedResourcesInput` *(required)* — An object containing the resource selection details.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **projectId** `string` *(required)* — The ID of the project.
  - **releaseId** `string` *(required)* — The ID of the release.
  - **componentDid** `string` *(required)* — The DID of the component whose resources are being updated.
  - **resources** `string[]` *(required)* — An array of resource identifiers to be selected.

<strong>Example</strong>

**Update Selected Resources**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.updateSelectedResources({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      releaseId: 'release_67890',
      componentDid: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      resources: ['resource_a', 'resource_b'],
    },
  });
  console.log('Selected resources updated.');
} catch (error) {
  console.error('Error updating resources:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

## Store & Endpoint Connectivity

These mutations manage the connection between your projects and various publishing destinations like Blocklet Stores and endpoints.

### connectToStore

Initiates a connection between a project and a Blocklet Store, returning a URL for completing the authorization process.

<strong>Parameters</strong>

- **input** `RequestConnectToStoreInput` *(required)* — An object containing the store connection details.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **storeId** `string` *(required)* — The unique identifier of the Blocklet Store.
  - **storeUrl** `string` *(required)* — The URL of the Blocklet Store.
  - **storeName** `string` *(required)* — The name of the Blocklet Store.
  - **projectId** `string` *(required)* — The ID of the project to connect.

<strong>Example</strong>

**Connect to Store**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { url } = await client.mutation.connectToStore({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      storeId: 'store_abc',
      storeUrl: 'https://store.example.com',
      storeName: 'Example Store',
    },
  });
  console.log('Connect to store URL:', url);
} catch (error) {
  console.error('Error connecting to store:', error);
}
```

<strong>Response</strong>

- **ResponseConnectToStore** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **url** `string` — The authorization URL to complete the connection.

### publishToStore

Publishes a specific release of a project to a connected Blocklet Store.

<strong>Parameters</strong>

- **input** `RequestPublishToStoreInput` *(required)* — An object containing the publishing details.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **projectId** `string` *(required)* — The ID of the project being published.
  - **releaseId** `string` *(required)* — The ID of the release to publish.
  - **type** `string` *(required)* — The type of content being published (e.g., 'resource').
  - **storeId** `string` *(required)* — The ID of the target Blocklet Store.

<strong>Example</strong>

**Publish to Store**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { url } = await client.mutation.publishToStore({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      releaseId: 'release_67890',
      storeId: 'store_abc',
      type: 'resource',
    },
  });
  console.log('Publish to store URL:', url);
} catch (error) {
  console.error('Error publishing to store:', error);
}
```

<strong>Response</strong>

- **ResponsePublishToStore** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **url** `string` — A URL to track the status of the publishing process.

### disconnectFromStore

Disconnects a project from a Blocklet Store, removing the association.

<strong>Parameters</strong>

- **input** `RequestDisconnectFromStoreInput` *(required)* — An object containing the details for disconnecting from the store.
  - **did** `string` *(required)* — The DID of the blocklet that owns the project.
  - **storeId** `string` *(required)* — The ID of the store to disconnect from.
  - **projectId** `string` *(required)* — The ID of the project to disconnect.
  - **storeScope** `string` — The scope of the store connection.

<strong>Example</strong>

**Disconnect from Store**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.disconnectFromStore({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      projectId: 'project_12345',
      storeId: 'store_abc',
    },
  });
  console.log('Successfully disconnected from the store.');
} catch (error) {
  console.error('Error disconnecting from store:', error);
}
```

<strong>Response</strong>

- **ResponseDisconnectFromStore** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

### connectToAigne

Connects a blocklet to an AIGNE service, which provides AI capabilities.

<strong>Parameters</strong>

- **input** `RequestConnectToAigneInput` *(required)* — An object containing AIGNE connection details.
  - **did** `string` *(required)* — The DID of the blocklet to connect.
  - **baseUrl** `string` *(required)* — The base URL of the AIGNE service.
  - **provider** `string` *(required)* — The AI provider (e.g., 'openai').
  - **model** `string` *(required)* — The specific model to use (e.g., 'gpt-4').

<strong>Example</strong>

**Connect to AIGNE**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { url } = await client.mutation.connectToAigne({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      baseUrl: 'https://aigne.example.com',
      provider: 'openai',
      model: 'gpt-4-turbo',
    },
  });
  console.log('Connect to AIGNE URL:', url);
} catch (error) {
  console.error('Error connecting to AIGNE:', error);
}
```

<strong>Response</strong>

- **ResponseConnectToEndpoint** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **url** `string` — The authorization URL to complete the connection.

### disconnectToAigne

Disconnects a blocklet from an AIGNE service.

<strong>Parameters</strong>

- **input** `RequestDisconnectToAigneInput` *(required)* — An object containing details for disconnecting from AIGNE.
  - **did** `string` *(required)* — The DID of the blocklet to disconnect.
  - **url** `string` *(required)* — The URL of the AIGNE service to disconnect from.
  - **key** `string` *(required)* — The API key used for the connection.

<strong>Example</strong>

**Disconnect from AIGNE**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.disconnectToAigne({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      url: 'https://aigne.example.com',
      key: 'your-api-key',
    },
  });
  console.log('Successfully disconnected from AIGNE.');
} catch (error) {
  console.error('Error disconnecting from AIGNE:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

### verifyAigneConnection

Verifies the connection to an AIGNE service for a blocklet.

<strong>Parameters</strong>

- **input** `RequestVerifyAigneConnectionInput` *(required)* — An object containing the blocklet DID.
  - **did** `string` *(required)* — The DID of the blocklet whose AIGNE connection is to be verified.

<strong>Example</strong>

**Verify AIGNE Connection**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.verifyAigneConnection({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
    },
  });
  console.log('AIGNE connection verified successfully.');
} catch (error) {
  console.error('Error verifying AIGNE connection:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

### connectToEndpoint

Establishes a connection between a project and a generic publishing endpoint.

<strong>Parameters</strong>

- **input** `RequestConnectToEndpointInput` *(required)* — Details for connecting to the endpoint.
  - **did** `string` *(required)* — The DID of the blocklet owning the project.
  - **endpointId** `string` *(required)* — The ID of the endpoint to connect to.
  - **projectId** `string` *(required)* — The ID of the project.

<strong>Example</strong>

**Connect to Endpoint**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { url } = await client.mutation.connectToEndpoint({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      endpointId: 'endpoint_xyz',
      projectId: 'project_12345',
    },
  });
  console.log('Connect to endpoint URL:', url);
} catch (error) {
  console.error('Error connecting to endpoint:', error);
}
```

<strong>Response</strong>

- **ResponseConnectToEndpoint** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **url** `string` — The authorization URL to complete the connection.

### publishToEndpoint

Publishes a specific release of a project to a connected endpoint.

<strong>Parameters</strong>

- **input** `RequestPublishToEndpointInput` *(required)* — Details for publishing to the endpoint.
  - **did** `string` *(required)* — The DID of the blocklet owning the project.
  - **endpointId** `string` *(required)* — The ID of the target endpoint.
  - **projectId** `string` *(required)* — The ID of the project being published.
  - **releaseId** `string` *(required)* — The ID of the release to publish.

<strong>Example</strong>

**Publish to Endpoint**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { url } = await client.mutation.publishToEndpoint({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      endpointId: 'endpoint_xyz',
      projectId: 'project_12345',
      releaseId: 'release_67890',
    },
  });
  console.log('Publish to endpoint URL:', url);
} catch (error) {
  console.error('Error publishing to endpoint:', error);
}
```

<strong>Response</strong>

- **ResponsePublishToEndpoint** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **url** `string` — A URL to track the publishing status.

### disconnectFromEndpoint

Disconnects a project from a publishing endpoint.

<strong>Parameters</strong>

- **input** `RequestDisconnectFromEndpointInput` *(required)* — Details for disconnecting from the endpoint.
  - **did** `string` *(required)* — The DID of the blocklet owning the project.
  - **endpointId** `string` *(required)* — The ID of the endpoint to disconnect from.
  - **projectId** `string` *(required)* — The ID of the project.

<strong>Example</strong>

**Disconnect from Endpoint**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.disconnectFromEndpoint({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      endpointId: 'endpoint_xyz',
      projectId: 'project_12345',
    },
  });
  console.log('Successfully disconnected from the endpoint.');
} catch (error) {
  console.error('Error disconnecting from endpoint:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

### addUploadEndpoint

Adds a new upload endpoint for a team.

<strong>Parameters</strong>

- **input** `RequestAddUploadEndpointInput` *(required)* — Details for the new upload endpoint.
  - **teamDid** `string` *(required)* — The DID of the team.
  - **url** `string` *(required)* — The URL of the upload endpoint.
  - **scope** `string` — The scope of the endpoint.

<strong>Example</strong>

**Add Upload Endpoint**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.addUploadEndpoint({
    input: {
      teamDid: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      url: 'https://uploads.example.com',
      scope: 'images',
    },
  });
  console.log('Upload endpoint added successfully.');
} catch (error) {
  console.error('Error adding upload endpoint:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

### deleteUploadEndpoint

Deletes an existing upload endpoint.

<strong>Parameters</strong>

- **input** `RequestDeleteUploadEndpointInput` *(required)* — Details for deleting the upload endpoint.
  - **teamDid** `string` *(required)* — The DID of the team.
  - **did** `string` *(required)* — The DID of the upload endpoint to delete.
  - **scope** `string` — The scope of the endpoint.
  - **projectId** `string` — The ID of the associated project.

<strong>Example</strong>

**Delete Upload Endpoint**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.mutation.deleteUploadEndpoint({
    input: {
      teamDid: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      did: 'endpoint_did_123',
    },
  });
  console.log('Upload endpoint deleted successfully.');
} catch (error) {
  console.error('Error deleting upload endpoint:', error);
}
```

<strong>Response</strong>

- **GeneralResponse** `object`
  - **code** `StatusCode` — Indicates the result of the operation.

### connectByStudio

Establishes a connection with a Blocklet Store via Blocklet Studio.

<strong>Parameters</strong>

- **input** `RequestConnectByStudioInput` *(required)* — Details for connecting via Blocklet Studio.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **storeId** `string` *(required)* — The ID of the store.
  - **storeUrl** `string` *(required)* — The URL of the store.
  - **storeName** `string` *(required)* — The name of the store.
  - **blockletTitle** `string` *(required)* — The title of the blocklet.
  - **type** `string` *(required)* — The connection type.
  - **tenantScope** `string` — The scope of the tenant.
  - **componentDid** `string` — The DID of the component.
  - **messageId** `string` — The message ID for tracking.

<strong>Example</strong>

**Connect by Studio**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { url } = await client.mutation.connectByStudio({
    input: {
      did: 'z8iZpA522J9Q2i8mY8J2mY6J2mY8J2mY6J2',
      storeId: 'store_abc',
      storeUrl: 'https://studio.blocklet.dev',
      storeName: 'Blocklet Studio',
      blockletTitle: 'My Awesome Blocklet',
      type: 'publish',
    },
  });
  console.log('Connect by Studio URL:', url);
} catch (error) {
  console.error('Error connecting by Studio:', error);
}
```

<strong>Response</strong>

- **ResponseConnectByStudio** `object`
  - **code** `StatusCode` — Indicates the result of the operation.
  - **url** `string` — The URL to complete the connection process.

---

## User & Access Management

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-mutations-user-access-management-c86fd7/

This section provides a detailed reference for mutations that manage users, roles, permissions, invitations, and access keys within a Blocklet. These operations are essential for controlling access and managing identities in your application.

For fetching user and access control data, please see the [User & Access Management Queries](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/) documentation.

::::card-group
::link-card{title="User Management" description="Mutations for creating, updating, deleting, and managing user profiles and attributes." icon="users"}
::link-card{title="Role & Permission Management" description="Operations for defining roles and assigning granular permissions to control access to resources." icon="shield-check"}
::link-card{title="Invitation Management" description="Methods for creating and managing user invitations to join a team or transfer ownership." icon="mail"}
::link-card{title="Access Key Management" description="Functions for creating, updating, and deleting API access keys for programmatic access." icon="key"}
::link-card{title="Tag Management" description="Mutations for creating, updating, and deleting tags used to organize users." icon="tags"}
::link-card{title="Passport Management" description="Operations related to issuing and configuring verifiable credentials (Passports)." icon="user"}
::::

## User Management

These mutations allow for comprehensive management of user accounts.

### removeUser

Permanently removes a user from a team.

<strong>Parameters</strong>
- **input** `RequestTeamUserInput` *(required)* — An object containing teamDid and the user's did.
- **teamDid** `string` *(required)* — The DID of the team.
- **user** `UserInfoInput` *(required)* — User information.
- **did** `string` *(required)* — The DID of the user to remove.

<strong>Example</strong>

**removeUser**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.removeUser({
    input: {
      teamDid: 'zdfw...',
      user: {
        did: 'z8...',
      },
    },
  });
  console.log('User removed:', user.did);
} catch (error) {
  console.error('Error removing user:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object containing the details of the removed user.

**Response**

```json
{
  "removeUser": {
    "code": "ok",
    "user": {
      "did": "z8...",
      "fullName": "John Doe"
    }
  }
}
```

### updateUserTags

Updates the tags associated with a specific user.

<strong>Parameters</strong>
- **input** `RequestUpdateUserTagsInput` *(required)* — An object containing teamDid, the user's did, and an array of tag IDs.
- **teamDid** `string` *(required)* — The DID of the team.
- **did** `string` *(required)* — The DID of the user.
- **tags** `number[]` *(required)* — An array of tag IDs to associate with the user.

<strong>Example</strong>

**updateUserTags**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.updateUserTags({
    input: {
      teamDid: 'zdfw...',
      did: 'z8...',
      tags: [1, 3],
    },
  });
  console.log('User tags updated:', user.tags);
} catch (error) {
  console.error('Error updating user tags:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object with the user's updated information.

**Response**

```json
{
  "updateUserTags": {
    "code": "ok",
    "user": {
      "did": "z8...",
      "tags": [
        { "id": 1, "title": "Developer" },
        { "id": 3, "title": "Early Adopter" }
      ]
    }
  }
}
```

### updateUserExtra

Updates the `remark` and `extra` (a JSON string) fields for a user.

<strong>Parameters</strong>
- **input** `RequestUpdateUserExtraInput` *(required)* — An object containing teamDid, user DID, and the extra data.
- **teamDid** `string` *(required)* — The DID of the team.
- **did** `string` *(required)* — The DID of the user to update.
- **remark** `string` — A new remark for the user.
- **extra** `string` — A JSON string containing custom data.

<strong>Example</strong>

**updateUserExtra**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.updateUserExtra({
    input: {
      teamDid: 'zdfw...',
      did: 'z8...',
      remark: 'Internal user account',
      extra: JSON.stringify({ department: 'Engineering' }),
    },
  });
  console.log('User extra data updated:', user.extra);
} catch (error) {
  console.error('Error updating user extra data:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object with the updated user details.

**Response**

```json
{
  "updateUserExtra": {
    "code": "ok",
    "user": {
      "did": "z8...",
      "remark": "Internal user account",
      "extra": {
        "department": "Engineering"
      }
    }
  }
}
```

### updateUserApproval

Sets the approval status of a user.

<strong>Parameters</strong>
- **input** `RequestTeamUserInput` *(required)* — An object containing teamDid and user details including did and the new approved status.
- **teamDid** `string` *(required)* — The DID of the team.
- **user** `UserInfoInput` *(required)* — User information.
- **did** `string` *(required)* — The DID of the user.
- **approved** `boolean` *(required)* — The new approval status.

<strong>Example</strong>

**updateUserApproval**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.updateUserApproval({
    input: {
      teamDid: 'zdfw...',
      user: {
        did: 'z8...',
        approved: true,
      },
    },
  });
  console.log('User approval status:', user.approved);
} catch (error) {
  console.error('Error updating user approval:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object with the updated approval status.

**Response**

```json
{
  "updateUserApproval": {
    "code": "ok",
    "user": {
      "did": "z8...",
      "approved": true
    }
  }
}
```

### issuePassportToUser

Issues a new passport (verifiable credential) to a user, typically assigning them a role.

<strong>Parameters</strong>
- **input** `RequestIssuePassportToUserInput` *(required)* — An object containing teamDid, userDid, role, and display details.
- **teamDid** `string` *(required)* — The DID of the team.
- **userDid** `string` *(required)* — The DID of the user to receive the passport.
- **role** `string` *(required)* — The role to assign with this passport.
- **display** `PassportDisplayInput` — Display information for the passport.
- **type** `string` *(required)* — Display type (e.g., 'text').
- **content** `string` *(required)* — The content to display.
- **notify** `boolean` — Whether to send a notification to the user.

<strong>Example</strong>

**issuePassportToUser**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.issuePassportToUser({
    input: {
      teamDid: 'zdfw...',
      userDid: 'z8...',
      role: 'guest',
      display: {
        type: 'text',
        content: 'Guest Access Pass',
      },
      notify: true,
    },
  });
  console.log('Passport issued to user:', user.did);
} catch (error) {
  console.error('Error issuing passport:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object, which may include the newly issued passport in the user's `passports` array.

**Response**

```json
{
  "issuePassportToUser": {
    "code": "ok",
    "user": {
      "did": "z8...",
      "passports": [
        {
          "id": "...",
          "role": "guest"
        }
      ]
    }
  }
}
```

### revokeUserPassport

Revokes a previously issued passport from a user.

<strong>Parameters</strong>
- **input** `RequestRevokeUserPassportInput` *(required)* — An object containing teamDid, userDid, and the passportId to revoke.
- **teamDid** `string` *(required)* — The DID of the team.
- **userDid** `string` *(required)* — The DID of the user.
- **passportId** `string` *(required)* — The ID of the passport to revoke.

<strong>Example</strong>

**revokeUserPassport**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.revokeUserPassport({
    input: {
      teamDid: 'zdfw...',
      userDid: 'z8...',
      passportId: 'z...',
    },
  });
  console.log('User passport revoked.');
} catch (error) {
  console.error('Error revoking passport:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object reflecting the change in the user's passports.

**Response**

```json
{
  "revokeUserPassport": {
    "code": "ok",
    "user": {
      "did": "z8..."
    }
  }
}
```

### enableUserPassport

Re-enables a passport that was previously revoked.

<strong>Parameters</strong>
- **input** `RequestRevokeUserPassportInput` *(required)* — An object containing teamDid, userDid, and the passportId to enable.
- **teamDid** `string` *(required)* — The DID of the team.
- **userDid** `string` *(required)* — The DID of the user.
- **passportId** `string` *(required)* — The ID of the passport to re-enable.

<strong>Example</strong>

**enableUserPassport**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.enableUserPassport({
    input: {
      teamDid: 'zdfw...',
      userDid: 'z8...',
      passportId: 'z...',
    },
  });
  console.log('User passport re-enabled.');
} catch (error) {
  console.error('Error enabling passport:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object with the user's updated passport status.

**Response**

```json
{
  "enableUserPassport": {
    "code": "ok",
    "user": {
      "did": "z8..."
    }
  }
}
```

### removeUserPassport

Permanently removes a passport from a user's record.

<strong>Parameters</strong>
- **input** `RequestRevokeUserPassportInput` *(required)* — An object containing teamDid, userDid, and the passportId to remove.
- **teamDid** `string` *(required)* — The DID of the team.
- **userDid** `string` *(required)* — The DID of the user.
- **passportId** `string` *(required)* — The ID of the passport to remove.

<strong>Example</strong>

**removeUserPassport**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.removeUserPassport({
    input: {
      teamDid: 'zdfw...',
      userDid: 'z8...',
      passportId: 'z...',
    },
  });
  console.log('User passport permanently removed.');
} catch (error) {
  console.error('Error removing passport:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "removeUserPassport": {
    "code": "ok"
  }
}
```

### updateUserInfo

Updates a user's general information, such as `fullName`, `email`, and `avatar`.

<strong>Parameters</strong>
- **input** `RequestUpdateUserInfoInput` *(required)* — An object containing teamDid and a user object with the fields to update.
- **teamDid** `string` *(required)* — The DID of the team.
- **user** `UserInfoInput` *(required)* — An object with the user fields to update.
- **did** `string` *(required)* — The DID of the user.
- **fullName** `string` — The user's full name.
- **email** `string` — The user's email address.

<strong>Example</strong>

**updateUserInfo**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { user } = await client.updateUserInfo({
    input: {
      teamDid: 'zdfw...',
      user: {
        did: 'z8...',
        fullName: 'Johnathan Doe',
        email: 'john.doe.new@example.com',
      },
    },
  });
  console.log('User info updated:', user.fullName);
} catch (error) {
  console.error('Error updating user info:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUser` object with the updated user information.

**Response**

```json
{
  "updateUserInfo": {
    "code": "ok",
    "user": {
      "did": "z8...",
      "fullName": "Johnathan Doe",
      "email": "john.doe.new@example.com"
    }
  }
}
```

## Role & Permission Management

These mutations are used to define roles and manage the permissions associated with them.

### createRole

Creates a new role within a team.

<strong>Parameters</strong>
- **input** `RequestCreateRoleInput` *(required)* — An object containing teamDid, name, title, and optionally permissions.
- **teamDid** `string` *(required)* — The DID of the team.
- **name** `string` *(required)* — A unique name for the role (e.g., 'editor').
- **title** `string` *(required)* — A human-readable title for the role (e.g., 'Editor').
- **description** `string` — A brief description of the role.
- **permissions** `string[]` — An array of permission names to grant to this role.

<strong>Example</strong>

**createRole**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { role } = await client.createRole({
    input: {
      teamDid: 'zdfw...',
      name: 'editor',
      title: 'Editor',
      description: 'Can create and edit content',
      permissions: ['content:create', 'content:edit'],
    },
  });
  console.log('Role created:', role.name);
} catch (error) {
  console.error('Error creating role:', error);
}
```

<strong>Response</strong>

Returns a `ResponseRole` object containing the details of the newly created role.

**Response**

```json
{
  "createRole": {
    "code": "ok",
    "role": {
      "name": "editor",
      "title": "Editor",
      "grants": ["content:create", "content:edit"]
    }
  }
}
```

### updateRole

Updates the details of an existing role.

<strong>Parameters</strong>
- **input** `RequestTeamRoleInput` *(required)* — An object containing teamDid and a role object with the fields to update.
- **teamDid** `string` *(required)* — The DID of the team.
- **role** `RoleUpdateInput` *(required)* — An object with the role fields to update.
- **name** `string` *(required)* — The name of the role to update.
- **title** `string` — The new title for the role.
- **description** `string` — The new description for the role.

<strong>Example</strong>

**updateRole**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { role } = await client.updateRole({
    input: {
      teamDid: 'zdfw...',
      role: {
        name: 'editor',
        title: 'Content Editor',
      },
    },
  });
  console.log('Role updated:', role.title);
} catch (error) {
  console.error('Error updating role:', error);
}
```

<strong>Response</strong>

Returns a `ResponseRole` object with the updated role information.

**Response**

```json
{
  "updateRole": {
    "code": "ok",
    "role": {
      "name": "editor",
      "title": "Content Editor"
    }
  }
}
```

### deleteRole

Permanently deletes a role.

<strong>Parameters</strong>
- **input** `RequestDeleteRoleInput` *(required)* — An object containing teamDid and the name of the role to delete.
- **teamDid** `string` *(required)* — The DID of the team.
- **name** `string` *(required)* — The name of the role to delete.

<strong>Example</strong>

**deleteRole**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.deleteRole({
    input: {
      teamDid: 'zdfw...',
      name: 'editor',
    },
  });
  console.log('Role "editor" deleted.');
} catch (error) {
  console.error('Error deleting role:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "deleteRole": {
    "code": "ok"
  }
}
```

### createPermission

Creates a new permission that can be granted to roles.

<strong>Parameters</strong>
- **input** `RequestCreatePermissionInput` *(required)* — An object containing teamDid, name, and description.
- **teamDid** `string` *(required)* — The DID of the team.
- **name** `string` *(required)* — A unique name for the permission (e.g., 'content:publish').
- **description** `string` — A brief description of the permission.

<strong>Example</strong>

**createPermission**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { permission } = await client.createPermission({
    input: {
      teamDid: 'zdfw...',
      name: 'content:publish',
      description: 'Allows publishing content',
    },
  });
  console.log('Permission created:', permission.name);
} catch (error) {
  console.error('Error creating permission:', error);
}
```

<strong>Response</strong>

Returns a `ResponsePermission` object with the details of the new permission.

**Response**

```json
{
  "createPermission": {
    "code": "ok",
    "permission": {
      "name": "content:publish",
      "description": "Allows publishing content"
    }
  }
}
```

### updatePermission

Updates the description of an existing permission.

<strong>Parameters</strong>
- **input** `RequestTeamPermissionInput` *(required)* — An object containing teamDid and the permission details to update.
- **teamDid** `string` *(required)* — The DID of the team.
- **permission** `PermissionInput` *(required)* — An object with the permission name and new description.
- **name** `string` *(required)* — The name of the permission to update.
- **description** `string` *(required)* — The new description for the permission.

<strong>Example</strong>

**updatePermission**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { permission } = await client.updatePermission({
    input: {
      teamDid: 'zdfw...',
      permission: {
        name: 'content:publish',
        description: 'Allows publishing content to the live site.',
      },
    },
  });
  console.log('Permission updated:', permission.description);
} catch (error) {
  console.error('Error updating permission:', error);
}
```

<strong>Response</strong>

Returns a `ResponsePermission` object with the updated permission details.

**Response**

```json
{
  "updatePermission": {
    "code": "ok",
    "permission": {
      "name": "content:publish",
      "description": "Allows publishing content to the live site."
    }
  }
}
```

### deletePermission

Permanently deletes a permission. This will also revoke it from any roles that have it.

<strong>Parameters</strong>
- **input** `RequestDeletePermissionInput` *(required)* — An object containing teamDid and the name of the permission to delete.
- **teamDid** `string` *(required)* — The DID of the team.
- **name** `string` *(required)* — The name of the permission to delete.

<strong>Example</strong>

**deletePermission**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.deletePermission({
    input: {
      teamDid: 'zdfw...',
      name: 'content:publish',
    },
  });
  console.log('Permission deleted.');
} catch (error) {
  console.error('Error deleting permission:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "deletePermission": {
    "code": "ok"
  }
}
```

### grantPermissionForRole

Grants a specific permission to a role.

<strong>Parameters</strong>
- **input** `RequestGrantPermissionForRoleInput` *(required)* — An object containing teamDid, the roleName, and the grantName (permission).
- **teamDid** `string` *(required)* — The DID of the team.
- **roleName** `string` *(required)* — The name of the role.
- **grantName** `string` *(required)* — The name of the permission to grant.

<strong>Example</strong>

**grantPermissionForRole**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.grantPermissionForRole({
    input: {
      teamDid: 'zdfw...',
      roleName: 'editor',
      grantName: 'content:publish',
    },
  });
  console.log('Permission granted.');
} catch (error) {
  console.error('Error granting permission:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "grantPermissionForRole": {
    "code": "ok"
  }
}
```

### revokePermissionFromRole

Revokes a specific permission from a role.

<strong>Parameters</strong>
- **input** `RequestRevokePermissionFromRoleInput` *(required)* — An object containing teamDid, the roleName, and the grantName (permission).
- **teamDid** `string` *(required)* — The DID of the team.
- **roleName** `string` *(required)* — The name of the role.
- **grantName** `string` *(required)* — The name of the permission to revoke.

<strong>Example</strong>

**revokePermissionFromRole**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.revokePermissionFromRole({
    input: {
      teamDid: 'zdfw...',
      roleName: 'editor',
      grantName: 'content:publish',
    },
  });
  console.log('Permission revoked.');
} catch (error) {
  console.error('Error revoking permission:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "revokePermissionFromRole": {
    "code": "ok"
  }
}
```

### updatePermissionsForRole

Sets the complete list of permissions for a role, replacing any existing permissions.

<strong>Parameters</strong>
- **input** `RequestUpdatePermissionsForRoleInput` *(required)* — An object containing teamDid, roleName, and an array of permission names.
- **teamDid** `string` *(required)* — The DID of the team.
- **roleName** `string` *(required)* — The name of the role.
- **grantNames** `string[]` *(required)* — An array of permission names to set for the role.

<strong>Example</strong>

**updatePermissionsForRole**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { role } = await client.updatePermissionsForRole({
    input: {
      teamDid: 'zdfw...',
      roleName: 'editor',
      grantNames: ['content:create', 'content:edit', 'content:delete'],
    },
  });
  console.log('Role permissions updated:', role.grants);
} catch (error) {
  console.error('Error updating role permissions:', error);
}
```

<strong>Response</strong>

Returns a `ResponseRole` object with the updated list of permissions.

**Response**

```json
{
  "updatePermissionsForRole": {
    "code": "ok",
    "role": {
      "name": "editor",
      "grants": ["content:create", "content:edit", "content:delete"]
    }
  }
}
```

## Invitation Management

These mutations are used to manage user invitations.

### createMemberInvitation

Creates an invitation for a new member to join a team with a specific role.

<strong>Parameters</strong>
- **input** `RequestCreateInvitationInput` *(required)* — An object containing teamDid, role, and other invitation details.
- **teamDid** `string` *(required)* — The DID of the team.
- **role** `string` *(required)* — The role to assign to the invited member.
- **remark** `string` — A remark or note for the invitation.

<strong>Example</strong>

**createMemberInvitation**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { inviteInfo } = await client.createMemberInvitation({
    input: {
      teamDid: 'zdfw...',
      role: 'guest',
      remark: 'Invitation for new team member',
    },
  });
  console.log('Invitation created:', inviteInfo.inviteId);
} catch (error) {
  console.error('Error creating invitation:', error);
}
```

<strong>Response</strong>

Returns a `ResponseCreateInvitation` object containing details about the created invitation.

**Response**

```json
{
  "createMemberInvitation": {
    "code": "ok",
    "inviteInfo": {
      "inviteId": "...",
      "role": "guest"
    }
  }
}
```

### createTransferInvitation

Creates an invitation to transfer ownership of the node.

<strong>Parameters</strong>
- **input** `RequestCreateTransferNodeInvitationInput` *(required)* — An object containing teamDid and a remark.
- **teamDid** `string` *(required)* — The DID of the team.
- **remark** `string` — A remark for the transfer invitation.

<strong>Example</strong>

**createTransferInvitation**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { inviteInfo } = await client.createTransferInvitation({
    input: {
      teamDid: 'zdfw...',
      remark: 'Transferring node ownership',
    },
  });
  console.log('Transfer invitation created:', inviteInfo.inviteId);
} catch (error) {
  console.error('Error creating transfer invitation:', error);
}
```

<strong>Response</strong>

Returns a `ResponseCreateTransferNodeInvitation` object with details of the invitation.

**Response**

```json
{
  "createTransferInvitation": {
    "code": "ok",
    "inviteInfo": {
      "inviteId": "...",
      "role": "owner"
    }
  }
}
```

### deleteInvitation

Permanently deletes an invitation.

<strong>Parameters</strong>
- **input** `RequestDeleteInvitationInput` *(required)* — An object containing teamDid and the inviteId to delete.
- **teamDid** `string` *(required)* — The DID of the team.
- **inviteId** `string` *(required)* — The ID of the invitation to delete.

<strong>Example</strong>

**deleteInvitation**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.deleteInvitation({
    input: {
      teamDid: 'zdfw...',
      inviteId: '...',
    },
  });
  console.log('Invitation deleted.');
} catch (error) {
  console.error('Error deleting invitation:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "deleteInvitation": {
    "code": "ok"
  }
}
```

## Access Key Management

These mutations are used to manage API access keys for programmatic access.

### createAccessKey

Creates a new access key.

<strong>Parameters</strong>
- **input** `RequestCreateAccessKeyInput` *(required)* — An object containing teamDid, remark, and other key details.
- **teamDid** `string` *(required)* — The DID of the team.
- **remark** `string` — A remark to identify the key's purpose.
- **authType** `string` — Authentication type (e.g., 'role').

<strong>Example</strong>

**createAccessKey**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { data } = await client.createAccessKey({
    input: {
      teamDid: 'zdfw...',
      remark: 'Key for CI/CD pipeline',
      authType: 'role',
    },
  });
  console.log('Access Key created:', data.accessKeyId);
  console.log('Secret:', data.accessKeySecret); // Save this secret securely
} catch (error) {
  console.error('Error creating access key:', error);
}
```

<strong>Response</strong>

Returns a `ResponseCreateAccessKey` object containing the new key's ID and secret. <strong>The secret is only returned on creation.</strong>

**Response**

```json
{
  "createAccessKey": {
    "code": "ok",
    "data": {
      "accessKeyId": "...",
      "accessKeySecret": "...",
      "remark": "Key for CI/CD pipeline"
    }
  }
}
```

### updateAccessKey

Updates the details of an existing access key, such as its remark or expiration.

<strong>Parameters</strong>
- **input** `RequestUpdateAccessKeyInput` *(required)* — An object containing teamDid, accessKeyId, and the fields to update.
- **teamDid** `string` *(required)* — The DID of the team.
- **accessKeyId** `string` *(required)* — The ID of the access key to update.
- **remark** `string` — The new remark for the key.

<strong>Example</strong>

**updateAccessKey**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { data } = await client.updateAccessKey({
    input: {
      teamDid: 'zdfw...',
      accessKeyId: '...',
      remark: 'Updated remark for CI/CD pipeline',
    },
  });
  console.log('Access Key updated:', data.remark);
} catch (error) {
  console.error('Error updating access key:', error);
}
```

<strong>Response</strong>

Returns a `ResponseUpdateAccessKey` object with the updated key details.

**Response**

```json
{
  "updateAccessKey": {
    "code": "ok",
    "data": {
      "accessKeyId": "...",
      "remark": "Updated remark for CI/CD pipeline"
    }
  }
}
```

### deleteAccessKey

Permanently deletes an access key.

<strong>Parameters</strong>
- **input** `RequestDeleteAccessKeyInput` *(required)* — An object containing teamDid and the accessKeyId to delete.
- **teamDid** `string` *(required)* — The DID of the team.
- **accessKeyId** `string` *(required)* — The ID of the access key to delete.

<strong>Example</strong>

**deleteAccessKey**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.deleteAccessKey({
    input: {
      teamDid: 'zdfw...',
      accessKeyId: '...',
    },
  });
  console.log('Access Key deleted.');
} catch (error) {
  console.error('Error deleting access key:', error);
}
```

<strong>Response</strong>

Returns a `ResponseDeleteAccessKey` object indicating success or failure.

**Response**

```json
{
  "deleteAccessKey": {
    "code": "ok"
  }
}
```

### verifyAccessKey

Verifies if an access key is valid and has access to a specific resource.

<strong>Parameters</strong>
- **input** `RequestVerifyAccessKeyInput` *(required)* — An object containing teamDid, accessKeyId, and resource details.
- **teamDid** `string` *(required)* — The DID of the team.
- **accessKeyId** `string` *(required)* — The ID of the access key to verify.
- **resourceType** `string` — The type of the resource (e.g., 'blocklet').
- **resourceId** `string` — The ID of the resource.
- **componentDid** `string` — The DID of the component associated with the resource.

<strong>Example</strong>

**verifyAccessKey**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { data } = await client.verifyAccessKey({
    input: {
      teamDid: 'zdfw...',
      accessKeyId: '...',
    },
  });
  console.log('Access key is valid:', data);
} catch (error) {
  console.error('Access key verification failed:', error);
}
```

<strong>Response</strong>

Returns a `ResponseAccessKey` object with the key's details if verification is successful.

**Response**

```json
{
  "verifyAccessKey": {
    "code": "ok",
    "data": {
      "accessKeyId": "...",
      "remark": "Key for CI/CD pipeline"
    }
  }
}
```

## Tag Management

These mutations are used to manage user tags.

### createTag

Creates a new tag.

<strong>Parameters</strong>
- **input** `RequestTagInput` *(required)* — An object containing teamDid and the tag details to create.
- **teamDid** `string` *(required)* — The DID of the team.
- **tag** `TagInput` *(required)* — An object with the tag details.
- **title** `string` *(required)* — The title of the tag.
- **description** `string` — A description for the tag.
- **color** `string` — A hex color code for the tag.

<strong>Example</strong>

**createTag**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { tag } = await client.createTag({
    input: {
      teamDid: 'zdfw...',
      tag: {
        title: 'VIP',
        description: 'Very Important Person',
        color: '#FFD700',
      },
    },
  });
  console.log('Tag created:', tag.title);
} catch (error) {
  console.error('Error creating tag:', error);
}
```

<strong>Response</strong>

Returns a `ResponseTag` object with the details of the newly created tag.

**Response**

```json
{
  "createTag": {
    "code": "ok",
    "tag": {
      "id": 4,
      "title": "VIP",
      "color": "#FFD700"
    }
  }
}
```

### updateTag

Updates an existing tag.

<strong>Parameters</strong>
- **input** `RequestTagInput` *(required)* — An object containing teamDid and a tag object with the id and fields to update.
- **teamDid** `string` *(required)* — The DID of the team.
- **tag** `TagInput` *(required)* — An object with the tag ID and fields to update.
- **id** `number` *(required)* — The ID of the tag to update.
- **title** `string` — The new title for the tag.
- **color** `string` — The new color for the tag.

<strong>Example</strong>

**updateTag**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { tag } = await client.updateTag({
    input: {
      teamDid: 'zdfw...',
      tag: {
        id: 4,
        color: '#E5C100',
      },
    },
  });
  console.log('Tag updated:', tag.color);
} catch (error) {
  console.error('Error updating tag:', error);
}
```

<strong>Response</strong>

Returns a `ResponseTag` object with the updated tag information.

**Response**

```json
{
  "updateTag": {
    "code": "ok",
    "tag": {
      "id": 4,
      "title": "VIP",
      "color": "#E5C100"
    }
  }
}
```

### deleteTag

Permanently deletes a tag.

<strong>Parameters</strong>
- **input** `RequestTagInput` *(required)* — An object containing teamDid and the tag id to delete.
- **teamDid** `string` *(required)* — The DID of the team.
- **tag** `TagInput` *(required)* — An object containing the ID of the tag to delete.
- **id** `number` *(required)* — The ID of the tag to delete.

<strong>Example</strong>

**deleteTag**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.deleteTag({
    input: {
      teamDid: 'zdfw...',
      tag: {
        id: 4,
      },
    },
  });
  console.log('Tag deleted.');
} catch (error) {
  console.error('Error deleting tag:', error);
}
```

<strong>Response</strong>

Returns a `ResponseTag` object of the deleted tag.

**Response**

```json
{
  "deleteTag": {
    "code": "ok",
    "tag": {
      "id": 4
    }
  }
}
```

## Passport Management

These mutations are used to manage passport issuance and trust configurations.

### createPassportIssuance

Creates a new passport issuance configuration for a team.

<strong>Parameters</strong>
- **input** `RequestCreatePassportIssuanceInput` *(required)* — An object containing teamDid, ownerDid, name, and display details.
- **teamDid** `string` *(required)* — The DID of the team.
- **ownerDid** `string` *(required)* — The DID of the owner of this issuance.
- **name** `string` *(required)* — The name of the passport issuance.
- **display** `PassportDisplayInput` — Display information for the passport.
- **type** `string` *(required)* — Display type.
- **content** `string` *(required)* — Display content.

<strong>Example</strong>

**createPassportIssuance**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  const { info } = await client.createPassportIssuance({
    input: {
      teamDid: 'zdfw...',
      ownerDid: 'z8...',
      name: 'Community Contributor',
      display: {
        type: 'text',
        content: 'Community Contributor Badge',
      },
    },
  });
  console.log('Passport issuance created:', info.id);
} catch (error) {
  console.error('Error creating passport issuance:', error);
}
```

<strong>Response</strong>

Returns a `ResponseCreatePassportIssuance` object with details of the new issuance configuration.

**Response**

```json
{
  "createPassportIssuance": {
    "code": "ok",
    "info": {
      "id": "...",
      "name": "Community Contributor"
    }
  }
}
```

### deletePassportIssuance

Deletes a passport issuance configuration.

<strong>Parameters</strong>
- **input** `RequestDeleteTeamSessionInput` *(required)* — An object containing teamDid and the sessionId (issuance ID) to delete.
- **teamDid** `string` *(required)* — The DID of the team.
- **sessionId** `string` *(required)* — The ID of the passport issuance to delete.

<strong>Example</strong>

**deletePassportIssuance**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.deletePassportIssuance({
    input: {
      teamDid: 'zdfw...',
      sessionId: '...',
    },
  });
  console.log('Passport issuance deleted.');
} catch (error) {
  console.error('Error deleting passport issuance:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "deletePassportIssuance": {
    "code": "ok"
  }
}
```

### configPassportIssuance

Enables or disables passport issuance for a team.

<strong>Parameters</strong>
- **input** `RequestConfigPassportIssuanceInput` *(required)* — An object containing teamDid and a boolean enable flag.
- **teamDid** `string` *(required)* — The DID of the team.
- **enable** `boolean` *(required)* — Set to true to enable, false to disable.

<strong>Example</strong>

**configPassportIssuance**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.configPassportIssuance({
    input: {
      teamDid: 'zdfw...',
      enable: true,
    },
  });
  console.log('Passport issuance enabled.');
} catch (error) {
  console.error('Error configuring passport issuance:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "configPassportIssuance": {
    "code": "ok"
  }
}
```

### configTrustedPassports

Configures a list of trusted passport issuers and their role mappings.

<strong>Parameters</strong>
- **input** `RequestConfigTrustedPassportsInput` *(required)* — An object containing teamDid and the list of trusted passports.
- **teamDid** `string` *(required)* — The DID of the team.
- **trustedPassports** `TrustedPassportInput[]` *(required)* — An array of trusted passport configurations.
- **issuerDid** `string` *(required)* — The DID of the trusted issuer.
- **mappings** `TrustedPassportMappingInput[]` *(required)* — Role mapping rules.
- **from** `TrustedPassportMappingFromInput` *(required)* — Source passport details.
- **passport** `string` *(required)* — The name or type of the source passport.
- **to** `TrustedPassportMappingToInput` *(required)* — Target role details.
- **role** `string` *(required)* — The local role to map to.

<strong>Example</strong>

**configTrustedPassports**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.configTrustedPassports({
    input: {
      teamDid: 'zdfw...',
      trustedPassports: [
        {
          issuerDid: 'z...', // DID of another trusted blocklet
          mappings: [
            {
              from: { passport: 'developer_badge' },
              to: { role: 'developer' },
            },
          ],
        },
      ],
    },
  });
  console.log('Trusted passports configured.');
} catch (error) {
  console.error('Error configuring trusted passports:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "configTrustedPassports": {
    "code": "ok"
  }
}
```

### configTrustedFactories

Configures a list of trusted NFT factories.

<strong>Parameters</strong>
- **input** `RequestConfigTrustedFactoriesInput` *(required)* — An object containing teamDid and the list of trusted factories.
- **teamDid** `string` *(required)* — The DID of the team.
- **trustedFactories** `TrustedFactoryInput[]` *(required)* — An array of trusted factory configurations.
- **factoryAddress** `string` *(required)* — The address of the NFT factory.
- **remark** `string` — A remark for the factory.

<strong>Example</strong>

**configTrustedFactories**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

try {
  await client.configTrustedFactories({
    input: {
      teamDid: 'zdfw...',
      trustedFactories: [
        {
          factoryAddress: '0x...',
          remark: 'Official Community NFT Factory',
        },
      ],
    },
  });
  console.log('Trusted factories configured.');
} catch (error) {
  console.error('Error configuring trusted factories:', error);
}
```

<strong>Response</strong>

Returns a `GeneralResponse` object indicating success or failure.

**Response**

```json
{
  "configTrustedFactories": {
    "code": "ok"
  }
}
```

---

## Queries

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-queries-c86fd7/

Queries are used to fetch data from the Blocklet Server. The `@blocklet/server-js` library provides a set of methods that correspond to the available GraphQL queries, making it easy to retrieve information without writing raw GraphQL.

All query methods are available under the `client.queries` property.

**Get Node Information**

```javascript
import BlockletServerClient from '@blocklet/server-js';

// Initialize the client for a browser environment
const client = new BlockletServerClient();

async function fetchNodeInfo() {
  try {
    const { info } = await client.queries.getNodeInfo();
    console.log('Node Name:', info.name);
    console.log('Node Version:', info.version);
  } catch (error) {
    console.error('Failed to fetch node info:', error);
  }
}

fetchNodeInfo();
```

## Query Categories

The available queries are grouped into the following categories for easier navigation. Click on a category to see detailed information and examples for each query.

::::card-group
::link-card{title="Node & Blocklet Management" description="Queries for managing the lifecycle, status, and configuration of the node and blocklets." icon="server" href="/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/"}
::link-card{title="User & Access Management" description="Queries for managing users, roles, permissions, sessions, and access keys." icon="users" href="/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/"}
::link-card{title="Networking & Services" description="Queries for handling routing, domains, certificates, webhooks, and notifications." icon="routes" href="/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/"}
::link-card{title="Data & Operations" description="Queries for accessing backups, logs, analytics, and other operational data." icon="database" href="/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/"}
::link-card{title="Publishing & Projects" description="Queries for managing publishing projects, releases, and related resources." icon="upload" href="/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/"}
::::

## Complete List of Queries

For a quick overview, here is a complete list of all available query methods.

| Method  | Description  | Category  |
|---|---|---|
| `getBlocklet`  | Retrieves detailed information about a specific blocklet.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlockletMetaFromUrl`  | Fetches blocklet metadata from a given URL.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlockletDiff`  | Compares a local blocklet with a remote version to get the difference.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlocklets`  | Lists all installed blocklets on the node.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlockletRuntimeHistory`  | Gets the runtime history (CPU, memory) for a blocklet.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlockletsFromBackup`  | Lists blocklets available in a backup.  | [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/)  |
| `getDynamicComponents`  | Retrieves dynamic components from a URL.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getNodeInfo`  | Fetches general information about the Blocklet Server node.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `resetNodeStatus`  | Resets the status of the node.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getNodeEnv`  | Retrieves environment information of the node.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `checkNodeVersion`  | Checks for available updates for the Blocklet Server.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getDelegationState`  | Gets the delegation state of the node.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getNodeRuntimeHistory`  | Gets the runtime history (CPU, memory) for the node.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlockletMeta`  | Retrieves the metadata for a specific blocklet.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getNotifications`  | Fetches a list of notifications.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `makeAllNotificationsAsRead`  | Marks all notifications as read.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getNotificationSendLog`  | Retrieves the send log for notifications.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getReceivers`  | Gets a list of notification receivers.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getNotificationComponents`  | Retrieves components that can send notifications.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `resendNotification`  | Resends a specific notification.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getRoutingSites`  | Fetches all configured routing sites.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getRoutingSnapshots`  | Retrieves snapshots of the routing configuration.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getSnapshotSites`  | Gets the sites from a specific routing snapshot.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getRoutingProviders`  | Lists available routing providers.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `isDidDomain`  | Checks if a given domain is a DID domain.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getCertificates`  | Retrieves all SSL/TLS certificates.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `checkDomains`  | Checks the status and configuration of specified domains.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `findCertificateByDomain`  | Finds a certificate associated with a specific domain.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getAccessKeys`  | Lists all access keys.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getAccessKey`  | Retrieves a specific access key by its ID.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getWebHooks`  | Fetches all configured webhooks.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getWebhookSenders`  | Retrieves a list of available webhook senders.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `sendTestMessage`  | Sends a test message to a webhook for verification.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getSession`  | Retrieves session information.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getRoles`  | Lists all user roles.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getRole`  | Retrieves details for a specific role.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getPermissions`  | Lists all available permissions.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getInvitations`  | Fetches all pending invitations.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUsers`  | Retrieves a list of users.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUser`  | Fetches details for a specific user.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUserSessions`  | Lists active sessions for a user.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUserSessionsCount`  | Gets the total count of user sessions.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUsersCount`  | Retrieves the total number of users.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUsersCountPerRole`  | Gets the count of users for each role.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getOwner`  | Retrieves the node owner's user information.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getPermissionsByRole`  | Lists permissions associated with a specific role.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getPassportIssuances`  | Fetches information about passport issuances.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `logoutUser`  | Logs out a user session.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `destroySelf`  | Allows a user to delete their own account.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUserFollowers`  | Retrieves a list of a user's followers.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUserFollowing`  | Retrieves a list of users that a user is following.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUserFollowStats`  | Gets follow statistics for a user.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `checkFollowing`  | Checks if one user is following another.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `followUser`  | Follows a user.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `unfollowUser`  | Unfollows a user.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getUserInvites`  | Retrieves a list of a user's invitees.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getTags`  | Retrieves a list of tags.  | [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/)  |
| `getAuditLogs`  | Fetches audit logs for tracking activities.  | [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/)  |
| `getLauncherSession`  | Retrieves session information from the Blocklet Launcher.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getBlockletBackups`  | Lists all backups for a specific blocklet.  | [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/)  |
| `getBlockletBackupSummary`  | Gets a summary of blocklet backup activities.  | [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/)  |
| `getBlockletSpaceGateways`  | Retrieves configured space gateways for a blocklet.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getTrafficInsights`  | Fetches traffic analytics and insights.  | [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/)  |
| `getProjects`  | Lists all publishing projects.  | [Publishing & Projects](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/)  |
| `getProject`  | Retrieves details for a specific project.  | [Publishing & Projects](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/)  |
| `getReleases`  | Lists all releases for a project.  | [Publishing & Projects](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/)  |
| `getRelease`  | Fetches details for a specific release.  | [Publishing & Projects](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/)  |
| `getSelectedResources`  | Gets the resources selected for a release.  | [Publishing & Projects](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/)  |
| `getBlockletSecurityRule`  | Retrieves a specific security rule for a blocklet.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getBlockletSecurityRules`  | Lists all security rules for a blocklet.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getBlockletResponseHeaderPolicy`  | Gets a specific response header policy.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getBlockletResponseHeaderPolicies`  | Lists all response header policies.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getBlockletAccessPolicy`  | Retrieves a specific access policy.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getBlockletAccessPolicies`  | Lists all access policies.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getWebhookEndpoints`  | Retrieves a list of webhook endpoints.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getWebhookEndpoint`  | Fetches details of a single webhook endpoint.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getWebhookAttempts`  | Gets the delivery attempt history for a webhook.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getPassportRoleCounts`  | Counts the number of passports per role.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getPassportsByRole`  | Retrieves passports filtered by a specific role.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getPassportLogs`  | Fetches logs related to passport activities.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getRelatedPassports`  | Gets passports related to a given passport.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `getBlockletBaseInfo`  | Retrieves basic information about a blocklet.  | [Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/)  |
| `getDomainDNS`  | Fetches DNS information for a domain.  | [Networking & Services](/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/)  |
| `getOAuthClients`  | Lists all configured OAuth clients.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `createOAuthClient`  | Creates a new OAuth client.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `updateOAuthClient`  | Updates an existing OAuth client.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |
| `deleteOAuthClient`  | Deletes an OAuth client.  | [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/)  |

## Next Steps

Now that you know how to fetch data, the next step is to learn how to modify it. Continue to the [Mutations](/en/docs/blocklet-server-js/api-reference-mutations-c86fd7/) section to explore how to create, update, and delete resources on the Blocklet Server.

---

## Data & Operations

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/

This section provides detailed references for GraphQL queries used to fetch operational data from your Blocklet Server. These queries are essential for monitoring system health, managing backups, auditing activities, and gaining insights into traffic patterns. For mutations related to data and operations, see the [Data & Operations Mutations section](/en/docs/blocklet-server-js/api-reference-mutations-data-operations-c86fd7/).

## Backups

Manage and monitor blocklet backup records.

### getBlockletBackups

Retrieves a list of backup records for a specific blocklet, optionally filtered by a time range.

<strong>Parameters</strong>

- **input** `RequestGetBlockletBackupsInput` *(required)* — An object containing the query parameters.
  - **did** `string` *(required)* — The DID of the blocklet to retrieve backups for.
  - **startTime** `string` — The start of the time range for the backup records.
  - **endTime** `string` — The end of the time range for the backup records.

<strong>Example Usage</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const backups = await client.getBlockletBackups({
  input: { did: 'z8ia22V5CfqF2e4sAFc9a2B9z9mC6a8x461sC' }
});
console.log(backups);
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "backups": [
    {
      "appPid": "z8ia22V5CfqF2e4sAFc9a2B9z9mC6a8x461sC",
      "userDid": "z1...",
      "strategy": 1,
      "sourceUrl": "/path/to/backup",
      "target": "disk",
      "targetName": "Local Disk",
      "targetUrl": "/path/to/backup/target",
      "createdAt": 1678886400,
      "updatedAt": 1678886400,
      "status": 1,
      "message": "Backup completed successfully",
      "progress": 100,
      "metadata": {}
    }
  ]
}
```

### getBlockletBackupSummary

Retrieves a summary of backup activities, including success and error counts, for a blocklet within a specified time range, grouped by date.

<strong>Parameters</strong>

- **input** `RequestGetBlockletBackupSummaryInput` *(required)* — An object containing the query parameters.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **startTime** `string` — The start of the time range for the backup summary.
  - **endTime** `string` — The end of the time range for the backup summary.

<strong>Example Usage</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const summary = await client.getBlockletBackupSummary({
  input: { did: 'z8ia22V5CfqF2e4sAFc9a2B9z9mC6a8x461sC' }
});
console.log(summary);
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "summary": [
    {
      "date": "2023-03-15",
      "successCount": 5,
      "errorCount": 1
    }
  ]
}
```

## Logs

Access audit and activity logs for monitoring and troubleshooting.

### getAuditLogs

Fetches a paginated list of audit logs, allowing you to track activities across the node. You can filter logs by scope, category, and content.

<strong>Parameters</strong>

- **input** `RequestGetAuditLogsInput` — An object containing the query parameters.
  - **paging** `PagingInput` — Pagination options.
  - **scope** `string` — Filter by scope (e.g., 'node', 'z8ia...').
  - **category** `string` — Filter by category (e.g., 'user', 'blocklet').
  - **actionOrContent** `string` — Search string for action or content fields.

<strong>Example Usage</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const logs = await client.getAuditLogs({
  input: {
    paging: { page: 1, pageSize: 10 },
    category: 'user'
  }
});
console.log(logs);
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "list": [
    {
      "id": "...",
      "scope": "node",
      "category": "user",
      "action": "login",
      "content": "User z1... logged in",
      "actor": {
        "did": "z1...",
        "role": "owner",
        "fullName": "Alice"
      },
      "env": {},
      "createdAt": 1678886400,
      "ip": "127.0.0.1",
      "ua": "Mozilla/5.0..."
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 10,
    "pageCount": 1,
    "page": 1
  }
}
```

### getPassportLogs

Retrieves activity logs for a specific passport, tracking actions such as issuance, revocation, and usage.

<strong>Parameters</strong>

- **input** `RequestPassportLogInput` *(required)* — An object containing the query parameters.
  - **teamDid** `string` *(required)* — The DID of the team or blocklet.
  - **query** `PassportLogQueryInput` *(required)* — Query filters.
    - **passportId** `string` *(required)* — The ID of the passport to retrieve logs for.
  - **paging** `PagingInput` — Pagination options.

<strong>Example Usage</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const logs = await client.getPassportLogs({
  input: {
    teamDid: 'z8ia22V5CfqF2e4sAFc9a2B9z9mC6a8x461sC',
    query: { passportId: 'zpassport_...' },
    paging: { page: 1, pageSize: 10 }
  }
});
console.log(logs);
```

<strong>Example Response</strong>

```json
{
  "passportLogs": [
    {
      "id": 1,
      "passportId": "zpassport_...",
      "action": "issued",
      "operatorIp": "127.0.0.1",
      "operatorUa": "Mozilla/5.0...",
      "operatorDid": "z1...",
      "metadata": {},
      "createdAt": 1678886400
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 10,
    "pageCount": 1,
    "page": 1
  }
}
```

## Analytics & Insights

Gain insights into blocklet performance and usage.

### getTrafficInsights

Provides traffic analytics for a specific blocklet, including request counts, unique visitors, and bandwidth usage within a specified date range.

<strong>Parameters</strong>

- **input** `RequestGetTrafficInsightsInput` *(required)* — An object containing the query parameters.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **startDate** `string` — Start date for the analytics period (e.g., 'YYYY-MM-DD').
  - **endDate** `string` — End date for the analytics period (e.g., 'YYYY-MM-DD').
  - **paging** `PagingInput` — Pagination options.

<strong>Example Usage</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const insights = await client.getTrafficInsights({
  input: {
    did: 'z8ia22V5CfqF2e4sAFc9a2B9z9mC6a8x461sC',
    startDate: '2023-01-01',
    endDate: '2023-01-31'
  }
});
console.log(insights);
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "list": [
    {
      "did": "z8ia22V5CfqF2e4sAFc9a2B9z9mC6a8x461sC",
      "date": "2023-01-15",
      "totalRequests": 1500,
      "uniqueVisitors": 200,
      "bandwidth": 512000000
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 10,
    "pageCount": 1,
    "page": 1
  }
}
```

You now have the tools to query operational data from your Blocklet Server. To learn how to manage publishing workflows and project resources, proceed to the [Publishing & Projects](/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/) section.

---

## Networking & Services

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-queries-networking-services-c86fd7/

This section provides a detailed reference for all GraphQL queries related to networking and services on the Blocklet Server. These methods allow you to fetch data and configurations for routing, domains, certificates, webhooks, and notifications. For operations that modify these settings, please see the [Networking & Services Mutations](/en/docs/blocklet-server-js/api-reference-mutations-networking-services-c86fd7/) section.

## Notifications

Queries for managing and retrieving notifications.

### getNotifications

Retrieves a list of notifications based on specified filters.

<strong>Parameters</strong>

- **input** `RequestGetNotificationsInput` *(required)* — An object containing filter criteria.
  - **receiver** `string` — Filter by notification receiver DID.
  - **sender** `string` — Filter by notification sender DID.
  - **read** `boolean` — Filter by read status.
  - **paging** `PagingInput` — Pagination options.
  - **teamDid** `string` — The DID of the team/blocklet.
  - **severity** `string[]` — Filter by severity levels (e.g., 'info', 'error').
  - **componentDid** `string[]` — Filter by component DID.
  - **entityId** `string[]` — Filter by entity ID.
  - **source** `string[]` — Filter by source (e.g., 'system', 'component').

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetNotifications` object containing the list of notifications and pagination details.

<strong>Request Example</strong>

**getNotifications Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUnreadNotifications() {
  try {
    const response = await client.getNotifications({
      input: {
        read: false,
        paging: { pageSize: 10, page: 1 },
      },
    });
    console.log('Unread notifications:', response.list);
    console.log('Unread count:', response.unreadCount);
  } catch (error) {
    console.error('Error fetching notifications:', error);
  }
}

fetchUnreadNotifications();
```

<strong>Response Example</strong>

**Response**

```json
{
  "code": "ok",
  "list": [
    {
      "id": "...",
      "title": "New Update Available",
      "description": "A new version of your blocklet is ready to be installed.",
      "read": false,
      "createdAt": 1678886400
    }
  ],
  "paging": {
    "total": 5,
    "pageSize": 10,
    "pageCount": 1,
    "page": 1
  },
  "unreadCount": 5
}
```

### makeAllNotificationsAsRead

Marks all notifications that match the given criteria as read.

<strong>Parameters</strong>

- **input** `RequestMakeAllNotificationsAsReadInput` *(required)* — An object containing filter criteria for which notifications to mark as read.
  - **receiver** `string` *(required)* — The DID of the notification receiver.
  - **teamDid** `string` — The DID of the team/blocklet.
  - **severity** `string` — (Optional) Filter by a specific severity level.
  - **componentDid** `string` — (Optional) Filter by a specific component DID.
  - **entityId** `string` — (Optional) Filter by a specific entity ID.
  - **source** `string` — (Optional) Filter by a specific source.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseMakeAllNotificationsAsRead` object indicating the number of notifications affected.

<strong>Request Example</strong>

**makeAllNotificationsAsRead Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAllAsRead() {
  try {
    const response = await client.makeAllNotificationsAsRead({
      input: { receiver: 'z8iZ...aYp' },
    });
    console.log(`Marked ${response.data.numAffected} notifications as read.`);
  } catch (error) {
    console.error('Error marking notifications as read:', error);
  }
}

markAllAsRead();
```

<strong>Response Example</strong>

**Response**

```json
{
  "code": "ok",
  "data": {
    "numAffected": 5,
    "notificationIds": ["...", "..."]
  }
}
```

### getNotificationSendLog

Retrieves the send log for notifications, allowing you to track delivery status across different channels.

<strong>Parameters</strong>

- **input** `RequestNotificationSendLogInput` *(required)* — An object containing filter criteria for the send log.
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **dateRange** `string[]` — Filter logs within a specific date range (e.g., ['2023-01-01', '2023-01-31']).
  - **paging** `PagingInput` — Pagination options.
  - **source** `string` — Filter by notification source.
  - **componentDids** `string[]` — Filter by an array of component DIDs.
  - **severities** `string[]` — Filter by an array of severity levels.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseNotificationSendLog` object containing the list of notification logs and pagination details.

### getReceivers

Retrieves a list of notification receivers based on various filter criteria, such as their send status for different channels.

<strong>Parameters</strong>

- **input** `RequestReceiversInput` *(required)* — An object containing filter criteria for receivers.
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **notificationId** `string` — Filter receivers for a specific notification.
  - **userName** `string` — Search for receivers by their name.
  - **userDid** `string` — Filter by a specific user DID.
  - **walletSendStatus** `number[]` — Filter by wallet send status codes.
  - **pushKitSendStatus** `number[]` — Filter by push notification send status codes.
  - **emailSendStatus** `number[]` — Filter by email send status codes.
  - **dateRange** `string[]` — Filter receivers within a specific date range.
  - **paging** `PagingInput` — Pagination options.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseReceivers` object containing the list of receivers and pagination details.

### getNotificationComponents

Retrieves a list of component DIDs that have sent notifications.

<strong>Parameters</strong>

- **input** `RequestNotificationComponentsInput` *(required)* — An object containing filter criteria.
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **receiver** `string` — Filter by the DID of the notification receiver.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseNotificationComponents` object containing an array of component DIDs.

### resendNotification

Triggers a resend of a specific notification to designated receivers and channels.

<strong>Parameters</strong>

- **input** `RequestResendNotificationInput` *(required)* — An object containing the details for the resend operation.
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **notificationId** `string` *(required)* — The ID of the notification to resend.
  - **receivers** `string[]` — A list of user DIDs to resend the notification to.
  - **channels** `string[]` — A list of channels to use for resending (e.g., 'wallet', 'email').
  - **webhookUrls** `string[]` — A list of specific webhook URLs to resend to.
  - **resendFailedOnly** `boolean` — If true, only resends to receivers who previously failed to receive the notification.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseResendNotification` object.

## Routing & Domains

Queries for managing routing rules and domain configurations.

### getRoutingSites

Retrieves the list of all configured routing sites.

<strong>Parameters</strong>

- **input** `RequestGetRoutingSitesInput` — An object containing filter criteria.
  - **snapshotHash** `string` — (Optional) If provided, retrieves the routing sites from a specific historical snapshot.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetRoutingSites` object containing an array of `RoutingSite` objects.

<strong>Request Example</strong>

**getRoutingSites Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoutingSites() {
  try {
    const response = await client.getRoutingSites();
    console.log('Routing sites:', response.sites);
  } catch (error) {
    console.error('Error fetching routing sites:', error);
  }
}

fetchRoutingSites();
```

<strong>Response Example</strong>

**Response**

```json
{
  "code": "ok",
  "sites": [
    {
      "id": "...",
      "domain": "example.com",
      "domainAliases": [{"value": "www.example.com"}],
      "rules": [/* ... */]
    }
  ]
}
```

### getRoutingSnapshots

Retrieves a list of historical snapshots of the routing configuration.

<strong>Parameters</strong>

- **input** `RequestGetRoutingSnapshotsInput` — An object containing filter criteria.
  - **limit** `number` — The maximum number of snapshots to return.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetRoutingSnapshots` object containing an array of `RoutingSnapshot` objects.

### getSnapshotSites

Retrieves the routing sites from a specific snapshot hash.

<strong>Parameters</strong>

- **input** `RequestGetSnapshotSitesInput` *(required)* — An object containing the snapshot hash.
  - **hash** `string` *(required)* — The hash of the snapshot to retrieve.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetSnapshotSites` object containing an array of `RoutingSite` objects from that snapshot.

### getRoutingProviders

Retrieves a list of available routing providers (e.g., Nginx) and their current status.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetRoutingProviders` object containing an array of `RoutingProvider` objects.

### isDidDomain

Checks if a given domain is a DID-based domain.

<strong>Parameters</strong>

- **input** `RequestIsDidDomainInput` *(required)*
  - **domain** `string` *(required)* — The domain to check.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseIsDidDomain` object with a boolean `value` indicating the result.

### getDomainDNS

Checks the DNS resolution status for a given domain, verifying if it points correctly to the Blocklet Server.

<strong>Parameters</strong>

- **input** `RequestDomainDNSInput` *(required)*
  - **teamDid** `string` *(required)* — The DID of the team/blocklet associated with the domain.
  - **domain** `string` *(required)* — The domain to check.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseDomainDNS` object detailing the DNS status.

## Certificates

Queries for managing SSL/TLS certificates.

### getCertificates

Retrieves all SSL certificates installed on the node.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetCertificates` object containing an array of `Certificate` objects.

<strong>Request Example</strong>

**getCertificates Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function listCertificates() {
  try {
    const response = await client.getCertificates();
    console.log('Installed certificates:', response.certificates);
  } catch (error) {
    console.error('Error fetching certificates:', error);
  }
}

listCertificates();
```

<strong>Response Example</strong>

**Response**

```json
{
  "code": "ok",
  "certificates": [
    {
      "id": "...",
      "name": "example.com-cert",
      "domain": "example.com",
      "source": "letsencrypt",
      "status": "valid"
    }
  ]
}
```

### findCertificateByDomain

Finds a specific certificate by its associated domain name.

<strong>Parameters</strong>

- **input** `RequestFindCertificateByDomainInput` *(required)*
  - **domain** `string` *(required)* — The domain name associated with the certificate.
  - **did** `string` — (Optional) The DID of the blocklet to narrow down the search.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseFindCertificateByDomain` object containing the `Certificate` if found.

### checkDomains

Checks the status and validity of multiple domains at once, often used before issuing certificates.

<strong>Parameters</strong>

- **input** `RequestCheckDomainsInput` *(required)*
  - **domains** `string[]` *(required)* — An array of domain names to check.
  - **did** `string` — (Optional) The DID of the blocklet.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseCheckDomains` object indicating the status of the check.

## Webhooks

Queries for managing webhooks and their senders.

### getWebHooks

Retrieves a list of all configured webhooks.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseWebHooks` object containing an array of `WebHook` objects.

<strong>Request Example</strong>

**getWebHooks Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function listWebhooks() {
  try {
    const response = await client.getWebHooks();
    console.log('Configured webhooks:', response.webhooks);
  } catch (error) {
    console.error('Error fetching webhooks:', error);
  }
}

listWebhooks();
```

<strong>Response Example</strong>

**Response**

```json
{
  "code": "ok",
  "webhooks": [
    {
      "id": "...",
      "type": "slack",
      "params": [{"name": "url", "value": "https://hooks.slack.com/..."}]
    }
  ]
}
```

### getWebhookSenders

Retrieves a list of available webhook sender types (e.g., Slack, API) and their required parameters.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseSenderList` object containing an array of `WebHookSender` objects.

### sendTestMessage

Sends a test message to a specified webhook to verify its configuration.

<strong>Parameters</strong>

- **input** `RequestSendMsgInput` *(required)*
  - **webhookId** `string` *(required)* — The ID of the webhook to test.
  - **message** `string` *(required)* — The test message content.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseSendMsg` object indicating the result of the operation.

### getWebhookEndpoints

Retrieves a paginated list of configured webhook endpoints.

<strong>Parameters</strong>

- **input** `RequestGetWebhookEndpointsInput` *(required)*
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **paging** `PagingInput` — Pagination options.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetWebhookEndpoints` object.

### getWebhookEndpoint

Retrieves a single webhook endpoint by its ID.

<strong>Parameters</strong>

- **input** `RequestGetWebhookEndpointInput` *(required)*
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **id** `string` *(required)* — The ID of the webhook endpoint.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetWebhookEndpoint` object.

### getWebhookAttempts

Retrieves the delivery attempt history for a specific webhook event.

<strong>Parameters</strong>

- **input** `RequestGetWebhookAttemptsInput` *(required)*
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.
  - **input** `RequestAttemptIdInput` *(required)* — Object containing the eventId and webhookId.
    - **eventId** `string` *(required)* — The ID of the event.
    - **webhookId** `string` *(required)* — The ID of the webhook.
  - **paging** `PagingInput` — Pagination options.

<strong>Returns</strong>

Returns a `Promise` that resolves to a `ResponseGetWebhookAttempts` object.

You have now reviewed the queries for managing networking and services. To explore how to fetch data related to backups, logs, and analytics, proceed to the [Data & Operations](/en/docs/blocklet-server-js/api-reference-queries-data-operations-c86fd7/) section.

---

## Node & Blocklet Management

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-queries-node-blocklet-management-c86fd7/

This section provides a detailed reference for GraphQL queries used to manage and retrieve information about the Blocklet Server node and the blocklets it runs. These queries allow you to monitor status, fetch configuration, and access lifecycle information.

For operations that modify state, such as installing or starting a blocklet, refer to the [Mutations > Node & Blocklet Management](/en/docs/blocklet-server-js/api-reference-mutations-node-blocklet-management-c86fd7/) documentation.

## Node Information Queries

These queries provide information about the Blocklet Server instance itself.

### getNodeInfo

Fetches comprehensive state information about the current Blocklet Server node, including its DID, version, status, and configuration.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseGetNodeInfo>` — A promise that resolves to an object containing the node's state information.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchNodeInfo() {
  try {
    const response = await client.getNodeInfo();
    console.log('Node Info:', response.info);
  } catch (error) {
    console.error('Error fetching node info:', error);
  }
}

fetchNodeInfo();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "info": {
    "did": "z1v7.....",
    "pk": "...",
    "version": "1.7.0",
    "name": "My ABT Node",
    "description": "This is my personal Blocklet Server.",
    "initialized": true,
    "autoUpgrade": true
    // ... other NodeState properties
  }
}
```

### getNodeEnv

Retrieves environment details of the Blocklet Server, such as the operating system, IP addresses, Docker status, and available blocklet engines.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseGetNodeEnv>` — A promise that resolves to an object containing the node's environment information.

<strong>Example</strong>

```javascript
async function fetchNodeEnv() {
  try {
    const response = await client.getNodeEnv();
    console.log('Node Environment:', response.info);
  } catch (error) {
    console.error('Error fetching node environment:', error);
  }
}

fetchNodeEnv();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "info": {
    "ip": {
      "externalV4": "192.0.2.1"
    },
    "os": "linux",
    "docker": true,
    "blockletEngines": [
      {
        "name": "node",
        "version": "18.17.0",
        "available": true
      }
    ]
    // ... other NodeEnvInfo properties
  }
}
```

### checkNodeVersion

Checks if a newer version of the Blocklet Server software is available for upgrade.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseCheckNodeVersion>` — A promise that resolves to an object containing the latest available version, if any.

<strong>Example</strong>

```javascript
async function checkForUpdates() {
  try {
    const response = await client.checkNodeVersion();
    console.log('Latest available version:', response.version);
  } catch (error) {
    console.error('Error checking for updates:', error);
  }
}

checkForUpdates();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "version": "1.7.1"
}
```

### getNodeRuntimeHistory

Fetches historical runtime data, including CPU and memory usage, for the node over a specified period.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **hours** `number` *(required)* — The number of past hours for which to retrieve history.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseNodeRuntimeHistory>` — A promise that resolves to an array of historical data points.

<strong>Example</strong>

```javascript
async function fetchNodeHistory() {
  try {
    const response = await client.getNodeRuntimeHistory({ input: { hours: 24 } });
    console.log('Node runtime history for the last 24 hours:', response.history);
  } catch (error) {
    console.error('Error fetching node runtime history:', error);
  }
}

fetchNodeHistory();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "history": [
    {
      "date": 1672531200000,
      "cpu": 15.5,
      "mem": 2048.5
    }
    // ... other NodeHistoryItem data points
  ]
}
```

### getDelegationState

Retrieves the delegation state of the node.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseDelegationState>` — A promise that resolves to an object containing the delegation state.

<strong>Example</strong>

```javascript
async function fetchDelegationState() {
  try {
    const response = await client.getDelegationState();
    console.log('Delegation State:', response.state);
  } catch (error) {
    console.error('Error fetching delegation state:', error);
  }
}

fetchDelegationState();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "state": {
    "delegated": true
  }
}
```

### resetNodeStatus

Resets the status of the node.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseGetNodeInfo>` — A promise that resolves to an object containing the node's updated state information.

<strong>Example</strong>

```javascript
async function resetStatus() {
  try {
    const response = await client.resetNodeStatus();
    console.log('Node status reset:', response.info);
  } catch (error) {
    console.error('Error resetting node status:', error);
  }
}

resetStatus();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "info": {
    "did": "z1v7.....",
    "pk": "...",
    "version": "1.7.0",
    "name": "My ABT Node",
    "status": 0
    // ... other NodeState properties
  }
}
```

## Blocklet Information Queries

These queries are used to fetch information about individual or multiple blocklets.

### getBlocklet

Retrieves the detailed state and metadata for a specific blocklet using its DID.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **did** `string` *(required)* — The DID of the blocklet to retrieve.
  - **attachRuntimeInfo** `boolean` — If true, includes real-time CPU and memory usage. Defaults to false.
  - **attachDiskInfo** `boolean` — If true, includes disk usage information. Defaults to false.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlocklet>` — A promise that resolves to an object containing the blocklet's state.

<strong>Example</strong>

```javascript
async function fetchBlockletDetails(blockletDid) {
  try {
    const response = await client.getBlocklet({
      input: {
        did: blockletDid,
        attachRuntimeInfo: true,
      },
    });
    console.log('Blocklet Details:', response.blocklet);
  } catch (error) {
    console.error('Error fetching blocklet details:', error);
  }
}

fetchBlockletDetails('z8ia...'); // Replace with a valid blocklet DID
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia...",
      "name": "my-awesome-blocklet",
      "version": "1.0.0",
      "title": "My Awesome Blocklet"
    },
    "status": "running",
    "appDid": "z1s...",
    "runtimeInfo": {
      "cpuUsage": 5.2,
      "memoryUsage": 128.7
    }
    // ... other BlockletState properties
  }
}
```

### getBlocklets

Fetches a list of all blocklets installed on the node.

<strong>Parameters</strong>

- **input** `object`
  - **includeRuntimeInfo** `boolean` — If true, includes runtime info for each blocklet. Defaults to true.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseGetBlocklets>` — A promise that resolves to an object containing a list of all installed blocklets.

<strong>Example</strong>

```javascript
async function listAllBlocklets() {
  try {
    const response = await client.getBlocklets();
    console.log(`Found ${response.blocklets.length} blocklets.`);
    response.blocklets.forEach(b => console.log(`- ${b.meta.title}`));
  } catch (error) {
    console.error('Error listing blocklets:', error);
  }
}

listAllBlocklets();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "blocklets": [
    {
      "meta": { "did": "z8ia...", "title": "My Awesome Blocklet" },
      "status": "running"
    },
    {
      "meta": { "did": "z8ib...", "title": "Another Blocklet" },
      "status": "stopped"
    }
    // ... other blocklets
  ]
}
```

### getBlockletMeta

Retrieves blocklet metadata from a specified blocklet store using the blocklet's DID.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **did** `string` *(required)* — The DID of the blocklet.
  - **storeUrl** `string` *(required)* — The URL of the blocklet store to query.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlockletMeta>` — A promise that resolves to an object containing the blocklet's metadata.

<strong>Example</strong>

```javascript
async function fetchBlockletMeta(blockletDid) {
  try {
    const response = await client.getBlockletMeta({
      input: {
        did: blockletDid,
        storeUrl: 'https://store.blocklet.dev',
      },
    });
    console.log('Blocklet Metadata:', response.meta);
  } catch (error) {
    console.error('Error fetching blocklet metadata:', error);
  }
}

fetchBlockletMeta('z8ia...'); // Replace with a valid blocklet DID
```

### getBlockletMetaFromUrl

Fetches blocklet metadata directly from a registry URL. This is useful for inspecting a blocklet before installation.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **url** `string` *(required)* — The registry URL of the blocklet metadata.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlockletMetaFromUrl>` — A promise that resolves to an object containing the metadata and other store-related info.

<strong>Example</strong>

```javascript
async function fetchMetaFromUrl() {
  try {
    const response = await client.getBlockletMetaFromUrl({
      input: { url: 'https://store.blocklet.dev/api/blocklets/z8ia...' },
    });
    console.log('Metadata from URL:', response.meta);
  } catch (error) {
    console.error('Error fetching metadata from URL:', error);
  }
}

fetchMetaFromUrl();
```

### getBlockletRuntimeHistory

Fetches historical runtime data (CPU and memory usage) for a specific blocklet.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **did** `string` *(required)* — The DID of the blocklet.
  - **hours** `number` *(required)* — The number of past hours to retrieve history for.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlockletRuntimeHistory>` — A promise that resolves to an array of historical data points.

<strong>Example</strong>

```javascript
async function fetchBlockletHistory(blockletDid) {
  try {
    const response = await client.getBlockletRuntimeHistory({
      input: { did: blockletDid, hours: 12 },
    });
    console.log('Blocklet runtime history:', response.historyList);
  } catch (error) {
    console.error('Error fetching blocklet runtime history:', error);
  }
}

fetchBlockletHistory('z8ia...'); // Replace with a valid blocklet DID
```

### getBlockletDiff

Compares local blocklet files with a provided hash list to identify added, changed, or deleted files. This is useful for incremental updates.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **did** `string` *(required)* — The DID of the blocklet.
  - **hashFiles** `HashFileInput[]` *(required)* — An array of objects, each containing a file path and its hash.
  - **rootDid** `string` — The root blocklet DID if the target is a component.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlockletDiff>` — A promise that resolves to an object detailing the differences.

<strong>Example</strong>

```javascript
async function checkBlockletDiff(blockletDid) {
  try {
    const response = await client.getBlockletDiff({
      input: {
        did: blockletDid,
        hashFiles: [
          { file: 'index.js', hash: '...' },
          { file: 'style.css', hash: '...' }
        ]
      }
    });
    console.log('Blocklet Diff:', response.blockletDiff);
  } catch (error) {
    console.error('Error checking blocklet diff:', error);
  }
}

checkBlockletDiff('z8ia...');
```

### getDynamicComponents

Retrieves metadata for dynamic components from a given URL.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **url** `string` *(required)* — The URL to fetch dynamic component metadata from.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseGetDynamicComponents>` — A promise that resolves to a list of dynamic components.

<strong>Example</strong>

```javascript
async function fetchDynamicComponents(registryUrl) {
  try {
    const response = await client.getDynamicComponents({ input: { url: registryUrl } });
    console.log('Dynamic Components:', response.components);
  } catch (error) {
    console.error('Error fetching dynamic components:', error);
  }
}

fetchDynamicComponents('https://store.blocklet.dev/api/components');
```

### getBlockletsFromBackup

Lists available blocklets from a backup source.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlockletsFromBackup>` — A promise that resolves to a list of blocklets available in the backup.

<strong>Example</strong>

```javascript
async function listBlockletsFromBackup() {
  try {
    const response = await client.getBlockletsFromBackup();
    console.log('Blocklets from backup:', response.backups);
  } catch (error) {
    console.error('Error listing blocklets from backup:', error);
  }
}

listBlockletsFromBackup();
```

### getBlockletBaseInfo

Retrieves basic information for a blocklet, including user counts, passport stats, and the latest backup status.

<strong>Parameters</strong>

- **input** `object` *(required)*
  - **teamDid** `string` *(required)* — The DID of the team/blocklet.

<strong>Returns</strong>

- **response** `Promise<BlockletServerClient.ResponseBlockletInfo>` — A promise that resolves to an object containing basic blocklet information.

<strong>Example</strong>

```javascript
async function fetchBaseInfo(blockletDid) {
  try {
    const response = await client.getBlockletBaseInfo({ input: { teamDid: blockletDid } });
    console.log('Base Info:', response);
  } catch (error) {
    console.error('Error fetching base info:', error);
  }
}

fetchBaseInfo('z8ia...');
```

<strong>Example Response</strong>

```json
{
  "user": {
    "users": 10,
    "approvedUsers": 8
  },
  "passport": {
    "passports": 12,
    "activePassports": 10
  },
  "backup": {
    "appPid": "z8ia...",
    "status": 1,
    "updatedAt": 1672531200
  }
}
```

Now that you know how to query node and blocklet information, you can explore how to manage users and permissions in the [User & Access Management](/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/) section.

---

## Publishing & Projects

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-queries-publishing-projects-c86fd7/

This section provides a detailed reference for GraphQL queries used to manage publishing projects, releases, and associated resources. These queries allow you to retrieve information about your blocklets' publishing lifecycle. For operations that modify this data, such as creating or updating projects and releases, please refer to the [Publishing & Projects Mutations documentation](/en/docs/blocklet-server-js/api-reference-mutations-publishing-projects-c86fd7/).

## getProjects

Retrieves a list of publishing projects associated with a specific blocklet.

### Example

**Get a list of projects**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchProjects() {
  try {
    const { projects, paging } = await client.getProjects({
      input: {
        did: 'z8ia262k3g55v12a874bf7ae1666c268882b6',
        paging: {
          page: 1,
          pageSize: 10,
        },
      },
    });
    console.log('Projects:', projects);
    console.log('Paging Info:', paging);
  } catch (error) {
    console.error('Error fetching projects:', error);
  }
}

fetchProjects();
```

### Parameters

- **input** `RequestGetProjectsInput` *(required)* — The input object for the query.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **paging** `PagingInput` — Pagination information.
  - **componentDid** `string` — Filter projects by component DID.
  - **tenantScope** `string` — Filter projects by tenant scope.

### Return Type

Returns a `ResponseGetProjects` object containing an array of `Project` objects and pagination details.

### Example Response

**Response for getProjects**

```json
{
  "code": "ok",
  "projects": [
    {
      "id": "z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3",
      "type": "pack",
      "blockletDid": "z8ia262k3g55v12a874bf7ae1666c268882b6",
      "blockletTitle": "My Awesome Blocklet",
      "createdAt": "2023-10-27T10:00:00.000Z",
      "updatedAt": "2023-10-27T10:00:00.000Z",
      "lastReleaseId": "z3t8b..._release_id_...",
      "connectedStores": []
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "pageCount": 1
  }
}
```

## getProject

Retrieves details for a single publishing project using its ID.

### Example

**Get a single project**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchProject(projectId) {
  try {
    const { project } = await client.getProject({
      input: {
        did: 'z8ia262k3g55v12a874bf7ae1666c268882b6',
        projectId: projectId,
      },
    });
    console.log('Project Details:', project);
  } catch (error) {
    console.error('Error fetching project:', error);
  }
}

fetchProject('z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3');
```

### Parameters

- **input** `RequestProjectInput` *(required)* — The input object for the query.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **projectId** `string` *(required)* — The unique identifier of the project to retrieve.
  - **messageId** `string` — A message identifier for tracking requests.

### Return Type

Returns a `ResponseGetProject` object containing the `Project` details.

### Example Response

**Response for getProject**

```json
{
  "code": "ok",
  "project": {
    "id": "z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3",
    "type": "pack",
    "blockletDid": "z8ia262k3g55v12a874bf7ae1666c268882b6",
    "blockletTitle": "My Awesome Blocklet",
    "blockletDescription": "A blocklet that does awesome things.",
    "autoUpload": true,
    "connectedStores": []
  }
}
```

## getReleases

Fetches a list of releases for a given publishing project.

### Example

**Get releases for a project**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchReleases(projectId) {
  try {
    const { releases } = await client.getReleases({
      input: {
        did: 'z8ia262k3g55v12a874bf7ae1666c268882b6',
        projectId: projectId,
      },
    });
    console.log('Releases:', releases);
  } catch (error) {
    console.error('Error fetching releases:', error);
  }
}

fetchReleases('z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3');
```

### Parameters

- **input** `RequestGetReleasesInput` *(required)* — The input object for the query.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **projectId** `string` *(required)* — The ID of the project whose releases are to be fetched.
  - **paging** `PagingInput` — Pagination information.

### Return Type

Returns a `ResponseGetReleases` object containing an array of `Release` objects and pagination information.

### Example Response

**Response for getReleases**

```json
{
  "code": "ok",
  "releases": [
    {
      "id": "z3t8bCDE...",
      "projectId": "z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3",
      "blockletDid": "z8ia262k3g55v12a874bf7ae1666c268882b6",
      "blockletVersion": "1.2.0",
      "note": "Initial release with new features.",
      "status": "published",
      "createdAt": "2023-10-27T12:00:00.000Z"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "pageCount": 1
  }
}
```

## getRelease

Retrieves details for a single release using its ID.

### Example

**Get a single release**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRelease(projectId, releaseId) {
  try {
    const { release } = await client.getRelease({
      input: {
        did: 'z8ia262k3g55v12a874bf7ae1666c268882b6',
        projectId: projectId,
        releaseId: releaseId,
      },
    });
    console.log('Release Details:', release);
  } catch (error) {
    console.error('Error fetching release:', error);
  }
}

fetchRelease('z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3', 'z3t8bCDE...');
```

### Parameters

- **input** `RequestReleaseInput` *(required)* — The input object for the query.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **projectId** `string` *(required)* — The ID of the parent project.
  - **releaseId** `string` *(required)* — The unique identifier of the release to retrieve.

### Return Type

Returns a `ResponseGetRelease` object containing the `Release` details.

### Example Response

**Response for getRelease**

```json
{
  "code": "ok",
  "release": {
    "id": "z3t8bCDE...",
    "projectId": "z2qa7xsgE59VUp2r1LqfE9F2fJ6dZ8cR9yB3",
    "blockletVersion": "1.2.0",
    "blockletTitle": "My Awesome Blocklet",
    "note": "Initial release with new features.",
    "status": "published"
  }
}
```

## getSelectedResources

Fetches a list of resource identifiers that have been selected for a specific component within a release.

### Example

**Get selected resources for a release**

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchSelectedResources(projectId, releaseId, componentDid) {
  try {
    const { resources } = await client.getSelectedResources({
      input: {
        did: 'z8ia262k3g55v12a874bf7ae1666c268882b6',
        projectId: projectId,
        releaseId: releaseId,
        componentDid: componentDid,
      },
    });
    console.log('Selected Resources:', resources);
  } catch (error) {
    console.error('Error fetching selected resources:', error);
  }
}

fetchSelectedResources('z2qa7...', 'z3t8b...', 'z2qa...');
```

### Parameters

- **input** `RequestGetSelectedResourcesInput` *(required)* — The input object for the query.
  - **did** `string` *(required)* — The DID of the blocklet.
  - **projectId** `string` *(required)* — The ID of the project.
  - **releaseId** `string` *(required)* — The ID of the release.
  - **componentDid** `string` *(required)* — The DID of the component whose selected resources are to be fetched.

### Return Type

Returns a `ResponseGetSelectedResources` object containing an array of resource strings.

### Example Response

**Response for getSelectedResources**

```json
{
  "code": "ok",
  "resources": [
    "resource:zde22a874bf7ae1666c268882b6...",
    "resource:zde22a874bf7ae1666c268882b7..."
  ]
}
```

To create, update, or delete these entities, please proceed to the [Publishing & Projects Mutations](/en/docs/blocklet-server-js/api-reference-mutations-publishing-projects-c86fd7/) section.

---

## User & Access Management

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-queries-user-access-management-c86fd7/

This section provides a detailed reference for queries related to managing users, roles, permissions, sessions, and access keys within Blocklet Server. These queries allow you to retrieve information about your application's users and their access levels.

For operations that modify user and access data, such as creating users or updating permissions, please refer to the [User & Access Management Mutations](/en/docs/blocklet-server-js/api-reference-mutations-user-access-management-c86fd7/) documentation.

## User Queries

### getUsers

Retrieves a paginated list of users, with options for filtering and sorting.

<strong>Parameters</strong>

- **input** `RequestUsersInput` *(required)* — An object containing the query parameters.
  - **teamDid** `string` *(required)* — The DID of the blocklet or team.
  - **query** `UserQueryInput` — Filtering criteria for the user list.
  - **sort** `UserSortInput` — Sorting criteria for the user list.
  - **paging** `PagingInput` — Pagination options.
  - **dids** `string[]` — An array of user DIDs to retrieve specifically.

<strong>Returns</strong>

- **** `ResponseUsers` — An object containing the list of users and pagination information.
  - **users** `UserInfo[]` — An array of user objects.
  - **paging** `Paging` — Pagination information for the result set.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUsers() {
  try {
    const { users, paging } = await client.getUsers({
      input: {
        teamDid: 'z1...',
        paging: { page: 1, pageSize: 10 },
        query: {
          role: 'guest',
          approved: true,
          search: 'john.doe',
        },
        sort: {
          lastLoginAt: -1, // Sort by last login time descending
        },
      },
    });
    console.log('Fetched users:', users);
    console.log('Pagination info:', paging);
  } catch (error) {
    console.error('Error fetching users:', error);
  }
}

fetchUsers();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "users": [
    {
      "did": "z8ia...",
      "pk": "...",
      "role": "guest",
      "avatar": "/path/to/avatar.png",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "approved": true,
      "createdAt": 1672531200,
      "lastLoginAt": 1675209600
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "pageCount": 1
  }
}
```

### getUser

Retrieves the details of a single user by their DID.

<strong>Parameters</strong>

- **input** `RequestTeamUserInput` *(required)* — An object containing the query parameters.
  - **teamDid** `string` *(required)* — The DID of the blocklet or team.
  - **user** `UserInfoInput` *(required)* — An object containing the user's DID. Only the `did` field is required.
    - **did** `string` *(required)*
  - **options** `RequestTeamUserOptionsInput` — Optional flags to include additional related data.
    - **includeTags** `boolean` — Whether to include the user's tags.
    - **includePassports** `boolean` — Whether to include the user's passports.
    - **includeConnectedAccounts** `boolean` — Whether to include the user's connected accounts.

<strong>Returns</strong>

- **user** `UserInfo` — The requested user object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUser(userDid) {
  try {
    const { user } = await client.getUser({
      input: {
        teamDid: 'z1...',
        user: { did: userDid },
        options: {
          includePassports: true,
          includeTags: true,
        },
      },
    });
    console.log('User details:', user);
  } catch (error) {
    console.error('Error fetching user:', error);
  }
}

fetchUser('z8ia...'); // Replace with a valid user DID
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "user": {
    "did": "z8ia...",
    "fullName": "Jane Doe",
    "email": "jane.doe@example.com",
    "role": "admin",
    "approved": true,
    "passports": [],
    "tags": []
  }
}
```

### getUsersCount

Retrieves the total count of users for a specific team or blocklet.

<strong>Parameters</strong>

- **input** `TeamInput` *(required)* — An object containing the team DID.
  - **teamDid** `string` *(required)*

<strong>Returns</strong>

- **count** `number` — The total number of users.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUsers() {
  try {
    const { count } = await client.getUsersCount({
      input: { teamDid: 'z1...' },
    });
    console.log('Total users:', count);
  } catch (error) {
    console.error('Error counting users:', error);
  }
}

countUsers();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "count": 125
}
```

### getUsersCountPerRole

Retrieves the count of users for each role within a team or blocklet.

<strong>Parameters</strong>

- **input** `TeamInput` *(required)* — An object containing the team DID.
  - **teamDid** `string` *(required)*

<strong>Returns</strong>

- **counts** `KeyValue[]` — An array of objects, where each object's `key` is the role name and `value` is the count.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUsersByRole() {
  try {
    const { counts } = await client.getUsersCountPerRole({
      input: { teamDid: 'z1...' },
    });
    console.log('User counts per role:', counts);
  } catch (error) {
    console.error('Error counting users by role:', error);
  }
}

countUsersByRole();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "counts": [
    { "key": "owner", "value": 1 },
    { "key": "admin", "value": 5 },
    { "key": "member", "value": 119 }
  ]
}
```

### getOwner

Retrieves the user information for the owner of a blocklet or team.

<strong>Parameters</strong>

- **input** `TeamInput` *(required)* — An object containing the team DID.
  - **teamDid** `string` *(required)*

<strong>Returns</strong>

- **user** `UserInfo` — The owner's user object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchOwner() {
  try {
    const { user } = await client.getOwner({
      input: { teamDid: 'z1...' },
    });
    console.log('Owner info:', user);
  } catch (error) {
    console.error('Error fetching owner:', error);
  }
}

fetchOwner();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "user": {
    "did": "zNK...",
    "fullName": "Node Owner",
    "email": "owner@example.com",
    "role": "owner"
  }
}
```

### destroySelf

Allows a user to delete their own account within a specific blocklet. This action is irreversible.

<strong>Parameters</strong>

- **input** `RequestTeamUserInput` *(required)* — An object containing the user's details for self-destruction.
  - **teamDid** `string` *(required)* — The DID of the blocklet or team.
  - **user** `UserInfoInput` *(required)* — An object containing the user's DID. Only the `did` field is required.
    - **did** `string` *(required)*

<strong>Returns</strong>

- **user** `UserInfo` — The user object of the account that was deleted.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

// Assuming the client is authenticated as the user to be deleted
const client = new BlockletServerClient();

async function deleteMyAccount(userDid) {
  try {
    const { user } = await client.destroySelf({
      input: {
        teamDid: 'z1...',
        user: { did: userDid },
      },
    });
    console.log('User account deleted:', user.did);
  } catch (error) {
    console.error('Error deleting account:', error);
  }
}

deleteMyAccount('z8ia...'); // The DID of the currently authenticated user
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "user": {
    "did": "z8ia...",
    "fullName": "Former User"
  }
}
```

## User Social Queries

### getUserFollowers

Retrieves a list of users who are following a specified user.

<strong>Parameters</strong>

- **input** `RequestUserRelationQueryInput` *(required)*
  - **teamDid** `string` *(required)*
  - **userDid** `string` *(required)*
  - **paging** `PagingInput`
  - **options** `QueryUserFollowOptionsInput`

<strong>Returns</strong>

- **** `ResponseUserFollows`
  - **data** `UserFollows[]`
  - **paging** `Paging`

### getUserFollowing

Retrieves a list of users that a specified user is following.

<strong>Parameters</strong>

- **input** `RequestUserRelationQueryInput` *(required)*
  - **teamDid** `string` *(required)*
  - **userDid** `string` *(required)*
  - **paging** `PagingInput`
  - **options** `QueryUserFollowOptionsInput`

<strong>Returns</strong>

- **** `ResponseUserFollows`
  - **data** `UserFollows[]`
  - **paging** `Paging`

### getUserFollowStats

Retrieves follow-related statistics for one or more users, such as follower and following counts.

<strong>Parameters</strong>

- **input** `RequestUserRelationCountInput` *(required)*
  - **teamDid** `string` *(required)*
  - **userDids** `string[]` *(required)*
  - **options** `QueryUserFollowStateOptionsInput`

<strong>Returns</strong>

- **data** `any` — An object containing the follow statistics.

### checkFollowing

Checks if a specific user is following one or more other users.

<strong>Parameters</strong>

- **input** `RequestCheckFollowingInput` *(required)*
  - **teamDid** `string` *(required)*
  - **followerDid** `string` *(required)* — The DID of the user who is potentially following others.
  - **userDids** `string[]` *(required)* — An array of DIDs to check if they are being followed.

<strong>Returns</strong>

- **data** `any` — An object where keys are the `userDids` and values are booleans indicating the follow status.

### getUserInvites

Retrieves a list of users invited by a specific user.

<strong>Parameters</strong>

- **input** `RequestUserRelationQueryInput` *(required)*
  - **teamDid** `string` *(required)*
  - **userDid** `string` *(required)* — The DID of the inviter.
  - **paging** `PagingInput`

<strong>Returns</strong>

- **** `ResponseUsers` — An object containing the list of invited users and pagination information.
  - **users** `UserInfo[]`
  - **paging** `Paging`

## Roles & Permissions

### getRoles

Retrieves a list of all available roles within a team or blocklet.

<strong>Parameters</strong>

- **input** `TeamInput` *(required)* — An object containing the team DID.
  - **teamDid** `string` *(required)*

<strong>Returns</strong>

- **roles** `Role[]` — An array of role objects.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoles() {
  try {
    const { roles } = await client.getRoles({
      input: { teamDid: 'z1...' },
    });
    console.log('Available roles:', roles);
  } catch (error) {
    console.error('Error fetching roles:', error);
  }
}

fetchRoles();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "roles": [
    { "name": "owner", "title": "Owner", "description": "Full access to all resources." },
    { "name": "admin", "title": "Administrator", "description": "Can manage users and settings." },
    { "name": "member", "title": "Member", "description": "Standard user access." },
    { "name": "guest", "title": "Guest", "description": "Limited access." }
  ]
}
```

### getRole

Retrieves the details of a specific role by its name.

<strong>Parameters</strong>

- **input** `RequestTeamRoleInput` *(required)* — An object containing the team DID and role name.
  - **teamDid** `string` *(required)*
  - **role** `RoleUpdateInput` *(required)*
    - **name** `string` *(required)*

<strong>Returns</strong>

- **role** `Role` — The requested role object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoleDetails(roleName) {
  try {
    const { role } = await client.getRole({
      input: {
        teamDid: 'z1...',
        role: { name: roleName },
      },
    });
    console.log('Role details:', role);
  } catch (error) {
    console.error('Error fetching role details:', error);
  }
}

fetchRoleDetails('admin');
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "role": {
    "name": "admin",
    "title": "Administrator",
    "description": "Can manage users and settings.",
    "grants": ["user:create", "user:update", "setting:update"]
  }
}
```

### getPermissions

Retrieves a list of all available permissions within a team or blocklet.

<strong>Parameters</strong>

- **input** `TeamInput` *(required)* — An object containing the team DID.
  - **teamDid** `string` *(required)*

<strong>Returns</strong>

- **permissions** `Permission[]` — An array of permission objects.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchPermissions() {
  try {
    const { permissions } = await client.getPermissions({
      input: { teamDid: 'z1...' },
    });
    console.log('Available permissions:', permissions);
  } catch (error) {
    console.error('Error fetching permissions:', error);
  }
}

fetchPermissions();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "permissions": [
    { "name": "user:create", "description": "Allows creating new users." },
    { "name": "user:read", "description": "Allows viewing user profiles." },
    { "name": "post:publish", "description": "Allows publishing new posts." }
  ]
}
```

### getPermissionsByRole

Retrieves the list of permissions associated with a specific role.

<strong>Parameters</strong>

- **input** `RequestTeamRoleInput` *(required)* — An object containing the team DID and role name.
  - **teamDid** `string` *(required)*
  - **role** `RoleUpdateInput` *(required)*
    - **name** `string` *(required)*

<strong>Returns</strong>

- **permissions** `Permission[]` — An array of permission objects associated with the role.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRolePermissions(roleName) {
  try {
    const { permissions } = await client.getPermissionsByRole({
      input: {
        teamDid: 'z1...',
        role: { name: roleName },
      },
    });
    console.log(`Permissions for role '${roleName}':`, permissions);
  } catch (error) {
    console.error('Error fetching role permissions:', error);
  }
}

fetchRolePermissions('member');
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "permissions": [
    { "name": "post:create", "description": "Allows creating new posts." },
    { "name": "post:read", "description": "Allows reading posts." }
  ]
}
```

## Invitations & Access Keys

### getInvitations

Retrieves a list of all pending invitations for a team or blocklet.

<strong>Parameters</strong>

- **input** `TeamInput` *(required)* — An object containing the team DID.
  - **teamDid** `string` *(required)*

<strong>Returns</strong>

- **invitations** `InviteInfo[]` — An array of invitation objects.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchInvitations() {
  try {
    const { invitations } = await client.getInvitations({
      input: { teamDid: 'z1...' },
    });
    console.log('Pending invitations:', invitations);
  } catch (error) {
    console.error('Error fetching invitations:', error);
  }
}

fetchInvitations();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "invitations": [
    {
      "inviteId": "...",
      "role": "member",
      "remark": "Invitation for new developer",
      "expireDate": "2024-12-31T23:59:59Z",
      "inviter": {
        "did": "z8ia...",
        "fullName": "Admin User"
      }
    }
  ]
}
```

### getAccessKeys

Retrieves a list of access keys associated with a team or blocklet.

<strong>Parameters</strong>

- **input** `RequestAccessKeysInput` *(required)* — An object containing query parameters for filtering access keys.
  - **teamDid** `string` *(required)*
  - **paging** `PagingInput`
  - **remark** `string`
  - **componentDid** `string`
  - **resourceType** `string`
  - **resourceId** `string`

<strong>Returns</strong>

- **** `ResponseAccessKeys`
  - **list** `AccessKey[]` — An array of access key objects.
  - **paging** `Paging` — Pagination information.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchAccessKeys() {
  try {
    const { list } = await client.getAccessKeys({
      input: {
        teamDid: 'z1...',
        paging: { pageSize: 20 },
      },
    });
    console.log('Access keys:', list);
  } catch (error) {
    console.error('Error fetching access keys:', error);
  }
}

fetchAccessKeys();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "list": [
    {
      "accessKeyId": "...",
      "remark": "CI/CD Key",
      "createdAt": 1672531200,
      "lastUsedAt": 1675209600
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 20,
    "page": 1
  }
}
```

### getAccessKey

Retrieves details for a single access key by its ID.

<strong>Parameters</strong>

- **input** `RequestAccessKeyInput` *(required)* — An object containing the team DID and the access key ID.
  - **teamDid** `string` *(required)*
  - **accessKeyId** `string` *(required)*

<strong>Returns</strong>

- **data** `AccessKey` — The requested access key object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchAccessKey(keyId) {
  try {
    const { data } = await client.getAccessKey({
      input: {
        teamDid: 'z1...',
        accessKeyId: keyId,
      },
    });
    console.log('Access key details:', data);
  } catch (error) {
    console.error('Error fetching access key:', error);
  }
}

fetchAccessKey('...'); // Replace with a valid access key ID
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "data": {
    "accessKeyId": "...",
    "accessKeyPublic": "...",
    "remark": "API access for integration tests",
    "createdAt": 1672531200
  }
}
```

## Sessions

### getSession

Retrieves details for a specific session by its ID.

<strong>Parameters</strong>

- **input** `RequestGetSessionInput` *(required)* — An object containing the session ID.
  - **id** `string` *(required)*

<strong>Returns</strong>

- **session** `any` — The requested session object.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchSession(sessionId) {
  try {
    const { session } = await client.getSession({
      input: { id: sessionId },
    });
    console.log('Session details:', session);
  } catch (error) {
    console.error('Error fetching session:', error);
  }
}

fetchSession('...'); // Replace with a valid session ID
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "session": {
    "sessionId": "...",
    "userDid": "z8ia...",
    "status": "active",
    "createdAt": 1675209600
  }
}
```

### getUserSessions

Retrieves a paginated list of sessions for a specific user.

<strong>Parameters</strong>

- **input** `RequestUserSessionsInput` *(required)* — An object containing query parameters for user sessions.
  - **teamDid** `string` *(required)*
  - **query** `UserSessionQueryInput`
    - **userDid** `string` *(required)*
  - **paging** `PagingInput`

<strong>Returns</strong>

- **** `ResponseUserSessions`
  - **list** `UserSession[]` — An array of session objects.
  - **paging** `Paging` — Pagination information.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUserSessions(userDid) {
  try {
    const { list, paging } = await client.getUserSessions({
      input: {
        teamDid: 'z1...',
        query: { userDid: userDid },
        paging: { pageSize: 5 },
      },
    });
    console.log('User sessions:', list);
  } catch (error) {
    console.error('Error fetching user sessions:', error);
  }
}

fetchUserSessions('z8ia...');
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "list": [
    {
      "id": "...",
      "userDid": "z8ia...",
      "status": "active",
      "lastLoginIp": "192.168.1.1",
      "createdAt": 1675209600
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 5,
    "page": 1
  }
}
```

### getUserSessionsCount

Retrieves the total count of sessions for a specific user.

<strong>Parameters</strong>

- **input** `RequestUserSessionsCountInput` *(required)* — An object containing query parameters for counting user sessions.
  - **teamDid** `string` *(required)*
  - **query** `UserSessionQueryInput`
    - **userDid** `string` *(required)*

<strong>Returns</strong>

- **count** `number` — The total number of sessions for the user.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUserSessions(userDid) {
  try {
    const { count } = await client.getUserSessionsCount({
      input: {
        teamDid: 'z1...',
        query: { userDid: userDid },
      },
    });
    console.log('Total sessions for user:', count);
  } catch (error) {
    console.error('Error counting user sessions:', error);
  }
}

countUserSessions('z8ia...');
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "count": 5
}
```

## Tags

### getTags

Retrieves a paginated list of tags for a team or blocklet.

<strong>Parameters</strong>

- **input** `RequestTagsInput` *(required)*
  - **teamDid** `string` *(required)*
  - **paging** `PagingInput`

<strong>Returns</strong>

- **** `ResponseTags`
  - **tags** `Tag[]` — An array of tag objects.
  - **paging** `Paging` — Pagination information.

<strong>Example</strong>

```javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchTags() {
  try {
    const { tags } = await client.getTags({
      input: {
        teamDid: 'z1...',
        paging: { pageSize: 100 },
      },
    });
    console.log('Available tags:', tags);
  } catch (error) {
    console.error('Error fetching tags:', error);
  }
}

fetchTags();
```

<strong>Example Response</strong>

```json
{
  "code": "ok",
  "tags": [
    {
      "id": 1,
      "title": "Developer",
      "description": "Users with development access",
      "color": "#3498db"
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 100,
    "page": 1
  }
}
```

---

## Types

URL: https://www.arcblock.io/en/docs/blocklet-server-js/api-reference-types-c86fd7/

The Blocklet Server Client API utilizes a variety of GraphQL types to structure the data for queries and mutations. This section provides a comprehensive reference for all data types, input objects, enums, and scalars used throughout the API. Understanding these types is crucial for constructing valid requests and interpreting the responses from the Blocklet Server.

## Scalar Types

Scalar types represent the leaves of a GraphQL query. They are primitive values like strings, numbers, or booleans.

| Scalar  | Description  |
|---|---|
| `String`  | Represents textual data, represented as UTF-8 character sequences.  |
| `Boolean`  | Represents `true` or `false`.  |
| `Int`  | Represents a signed 32‐bit integer.  |
| `Float`  | Represents signed double-precision floating-point values.  |
| `ID`  | Represents a unique identifier, often used to refetch an object or as a key for a cache.  |
| `Any`  | Represents any JSON-compatible value.  |
| `Bytes`  | Represents a byte array.  |
| `Int32`  | Represents a 32-bit signed integer.  |
| `Uint32`  | Represents a 32-bit unsigned integer.  |
| `Int64`  | Represents a 64-bit signed integer.  |
| `Uint64`  | Represents a 64-bit unsigned integer.  |
| `Float32`  | Represents a 32-bit floating-point number.  |
| `Upload`  | Represents a file upload, typically used in mutations.  |

## Enum Types

Enums are a special kind of scalar that is restricted to a particular set of allowed values.

### BackendServiceType

Defines the type of backend service a routing rule points to.

| Value  | Description  |
|---|---|
| `daemon`  | The service is the node daemon itself.  |
| `blocklet`  | The service is a running blocklet.  |
| `redirect`  | The rule performs an HTTP redirect.  |
| `none`  | No backend service is configured.  |
| `general_proxy`  | The rule acts as a general proxy to a specified URL.  |
| `direct_response`  | The rule returns a direct, static response.  |
| `rewrite`  | The rule rewrites the request path.  |
| `component`  | The service is a specific component within a blocklet.  |

### BackupTo

Specifies the destination for a blocklet backup.

| Value  | Description  |
|---|---|
| `spaces`  | Backup to a decentralized storage space.  |
| `disk`  | Backup to the local disk.  |

### BlockletSource

Indicates the origin from which a blocklet was installed.

| Value  | Description  |
|---|---|
| `registry`  | Installed from a blocklet registry/store.  |
| `local`  | Installed from a local directory.  |
| `upload`  | Installed from an uploaded file.  |
| `url`  | Installed from a direct URL.  |
| `custom`  | Installed through a custom or unknown method.  |

### BlockletStatus

Represents the current lifecycle status of a blocklet.

| Value  | Description  |
|---|---|
| `added`  | Blocklet has been added but not yet downloaded.  |
| `downloading`  | Blocklet is currently being downloaded.  |
| `downloaded`  | Blocklet has been downloaded successfully.  |
| `installing`  | Blocklet is currently being installed.  |
| `installed`  | Blocklet has been installed but is not running.  |
| `starting`  | Blocklet is in the process of starting.  |
| `running`  | Blocklet is currently running.  |
| `stopping`  | Blocklet is in the process of stopping.  |
| `stopped`  | Blocklet is stopped.  |
| `error`  | An error occurred in the blocklet's lifecycle.  |
| `upgrading`  | Blocklet is currently being upgraded.  |
| `restarting`  | Blocklet is restarting.  |
| `corrupted`  | Blocklet installation is corrupted.  |
| `waiting`  | Blocklet is waiting for a dependency or resource.  |
| `deleted`  | Blocklet has been deleted.  |
| `unknown`  | The status of the blocklet is unknown.  |

### HeaderMatchType

Defines the matching strategy for HTTP headers in routing rules.

| Value  | Description  |
|---|---|
| `exact`  | The header value must be an exact match.  |
| `partial`  | The header value must contain the specified string.  |
| `regexp`  | The header value must match the specified regular expression.  |

### Notification_NotificationSeverity

Defines the severity level of a notification.

| Value  | Description  |
|---|---|
| `info`  | Informational message.  |
| `success`  | Indicates a successful operation.  |
| `error`  | Indicates an error has occurred.  |
| `warning`  | Indicates a potential issue or warning.  |

### Notification_NotificationSource

Specifies the source of the notification.

| Value  | Description  |
|---|---|
| `system`  | Notification originated from the system/node.  |
| `component`  | Notification originated from a blocklet component.  |

### Notification_NotificationType

Defines the type or category of the notification.

| Value  | Description  |
|---|---|
| `notification`  | A standard notification message.  |
| `connect`  | A notification related to DID Connect.  |
| `feed`  | A feed-style update.  |
| `hi`  | A simple greeting or test notification.  |
| `passthrough`  | A notification that is passed through without special handling.  |

### NotificationActivity_ActivityTypeEnum

Defines the type of user activity for feed-style notifications.

| Value  | Description  |
|---|---|
| `comment`  | A user made a comment.  |
| `like`  | A user liked an item.  |
| `follow`  | A user followed another user or item.  |
| `tips`  | A user sent a tip.  |
| `mention`  | A user was mentioned.  |
| `assign`  | A user was assigned a task.  |
| `un_assign`  | A user was unassigned from a task.  |

### NotificationAttachmentType

Defines the type of attachment included in a notification.

| Value  | Description  |
|---|---|
| `asset`  | A digital asset.  |
| `vc`  | A Verifiable Credential.  |
| `token`  | A digital token.  |
| `text`  | A plain text attachment.  |
| `image`  | An image attachment.  |
| `divider`  | A visual divider for formatting.  |
| `transaction`  | A transaction record.  |
| `dapp`  | A decentralized application link.  |
| `link`  | A hyperlink.  |
| `section`  | A formatted section of content.  |

### PublishType

Specifies the type of artifact being published.

| Value  | Description  |
|---|---|
| `resource`  | A single resource file.  |
| `pack`  | A packed blocklet bundle.  |

### ReleaseStatus

Indicates the status of a release in a publishing project.

| Value  | Description  |
|---|---|
| `draft`  | The release is a draft and not yet published.  |
| `published`  | The release has been published.  |

### SenderType

Defines the type of webhook sender.

| Value  | Description  |
|---|---|
| `slack`  | A Slack webhook.  |
| `api`  | A generic API webhook.  |

### StatusCode

Represents the status code of an API response.

| Value  | Description  |
|---|---|
| `ok`  | The request was successful.  |
| `blocklet_not_found`  | The requested blocklet could not be found.  |
| `blocklet_not_purchased`  | The requested blocklet has not been purchased.  |
| `forbidden`  | The request is forbidden due to insufficient permissions.  |
| `internal`  | An internal server error occurred.  |
| `timeout`  | The request timed out.  |

## Input Objects

Input objects are complex types used as arguments for mutations and queries, allowing you to pass structured data in a single parameter.

### AigneConfigInput

Configuration for the AI Gateway (Aigne).

- **provider** `String` — The AI service provider (e.g., 'openai').
- **model** `String` — The specific model to use (e.g., 'gpt-4').
- **key** `String` — The API key for the service.
- **url** `String` — The base URL for the API endpoint.
- **accessKeyId** `String` — Access Key ID for providers like AWS.
- **secretAccessKey** `String` — Secret Access Key for providers like AWS.
- **validationResult** `String` — The result of the last connection validation.

### AutoBackupInput

Configuration for automatic backups.

- **enabled** `Boolean` — Whether automatic backups are enabled.

### AutoBlockPolicyInput

Configuration for automatic IP blocking policies.

- **enabled** `Boolean` — Whether automatic blocking is enabled.
- **windowSize** `Uint32` — The time window in seconds to monitor requests.
- **windowQuota** `Uint32` — The maximum number of requests allowed within the window.
- **blockDuration** `Uint32` — The duration in seconds to block an IP after exceeding the quota.
- **statusCodes** `[Uint32!]` — A list of HTTP status codes to consider for blocking.

### AutoCheckUpdateInput

Configuration for automatic update checks.

- **enabled** `Boolean` — Whether automatic update checks are enabled.

### BaseUserInfoInput

Basic user information used in various input types.

- **did** `String` — The user's Decentralized Identifier (DID).
- **pk** `String` — The user's public key.
- **role** `String` — The user's role.
- **avatar** `String` — URL to the user's avatar image.
- **fullName** `String` — The user's full name.
- **email** `String` — The user's email address.
- **approved** `Boolean` — Whether the user is approved.
- **createdAt** `Uint32` — Timestamp of when the user was created.
- **updatedAt** `Uint32` — Timestamp of the last update to the user's profile.
- **locale** `String` — The user's preferred locale (e.g., 'en').

### BlockPolicyInput

Configuration for IP blocking policies.

- **enabled** `Boolean` — Whether the block policy is enabled.
- **blacklist** `[String!]` — A list of IP addresses to permanently block.
- **autoBlocking** `AutoBlockPolicyInput` — Configuration for automatic IP blocking.

### BlockletAccessPolicyInput

Defines a blocklet access policy.

- **id** `String` — The unique identifier for the policy.
- **name** `String` — A descriptive name for the policy.
- **description** `String` — A detailed description of the policy.
- **roles** `Any` — The roles this policy applies to.
- **reverse** `Boolean` — If true, the policy logic is inverted (deny instead of allow).
- **isProtected** `Boolean` — If true, the policy cannot be easily modified or deleted.

### BlockletAccessPolicyQueryInput

Input for querying BlockletAccessPolicy objects.

- **search** `String` — A search string to filter policies by name or description.

### BlockletDistInput

Describes the distribution file of a blocklet.

- **tarball** `String` — The URL of the blocklet's tarball file.
- **integrity** `String` — The integrity hash of the tarball for verification.

### BlockletDockerInput

Defines Docker-related settings for a blocklet.

- **dockerImage** `String` — The name of the Docker image to use.
- **dockerArgs** `[DockerRunKeyValuePairInput!]` — Arguments to pass to the docker run command.
- **dockerEnvs** `[DockerEnvKeyValuePairInput!]` — Environment variables to set in the container.
- **dockerCommand** `String` — The command to execute inside the container.

### BlockletGatewayInput

Configuration for a blocklet's gateway settings.

- **requestLimit** `RequestLimitInput` — Request limiting configuration.
- **blockPolicy** `BlockPolicyInput` — IP blocking policy configuration.
- **proxyPolicy** `ProxyPolicyInput` — Proxy policy configuration.
- **cacheEnabled** `Boolean` — Whether caching is enabled at the gateway.
- **wafPolicy** `WAFPolicyInput` — Web Application Firewall policy configuration.
- **teamDid** `String` — The DID of the team associated with this configuration.

### BlockletResponseHeaderPolicyInput

Defines a response header policy.

- **id** `String` — The unique identifier for the policy.
- **name** `String` — A descriptive name for the policy.
- **description** `String` — A detailed description of the policy.
- **securityHeader** `String` — JSON string of security-related headers.
- **cors** `String` — JSON string of CORS headers.
- **customHeader** `String` — JSON string of custom headers to add.
- **removeHeader** `String` — JSON string of headers to remove.
- **isProtected** `Boolean` — If true, the policy cannot be easily modified or deleted.

### BlockletResponseHeaderPolicyQueryInput

Input for querying BlockletResponseHeaderPolicy objects.

- **search** `String` — A search string to filter policies by name or description.

### BlockletSecurityRuleInput

Defines a security rule that combines access and header policies for a specific path.

- **id** `String` — The unique identifier for the rule.
- **pathPattern** `String` — The URL path pattern this rule applies to.
- **componentDid** `String` — The DID of the component this rule is associated with.
- **priority** `Uint32` — The execution priority of the rule (lower numbers execute first).
- **responseHeaderPolicyId** `String` — The ID of the response header policy to apply.
- **accessPolicyId** `String` — The ID of the access policy to apply.
- **enabled** `Boolean` — Whether the rule is currently active.
- **remark** `String` — An optional remark or note about the rule.
- **accessPolicy** `BlockletAccessPolicyInput` — The full access policy object (used when creating a new rule).
- **responseHeaderPolicy** `BlockletResponseHeaderPolicyInput` — The full response header policy object (used when creating a new rule).

### BlockletSecurityRuleQueryInput

Input for querying BlockletSecurityRule objects.

- **search** `String` — A search string to filter rules by path pattern or remark.

### BlockletStoreInput

Represents a blocklet store/registry.

- **name** `String` — The name of the store.
- **description** `String` — A description of the store.
- **url** `String` — The URL of the store.
- **logoUrl** `String` — The URL of the store's logo.
- **maintainer** `String` — The maintainer of the store.
- **cdnUrl** `String` — The CDN URL used by the store.
- **protected** `Boolean` — Whether the store requires authentication.
- **id** `String` — The unique identifier of the store.
- **scope** `String` — The scope of the store (e.g., 'public', 'private').

### ConfigEntryInput

Represents a single configuration key-value pair.

- **key** `String` — The configuration key.
- **value** `String` — The configuration value.
- **required** `Boolean` — Whether this configuration is required.
- **description** `String` — A description of the configuration item.
- **validation** `String` — A validation rule or pattern for the value.
- **secure** `Boolean` — If true, the value is sensitive and should be treated as a secret.
- **custom** `Boolean` — If true, this is a custom, user-defined configuration.
- **shared** `Boolean` — If true, this configuration is shared among components.

### ConfigNavigationInput

Represents a navigation item in the user interface.

- **id** `String` — The unique ID of the navigation item.
- **title** `String` — The display title.
- **link** `String` — The destination URL or path.
- **icon** `String` — The icon for the navigation item.
- **section** `String` — The section where this item should appear (e.g., 'sidebar').
- **component** `String` — The component this navigation item belongs to.
- **parent** `String` — The ID of the parent navigation item, if any.
- **role** `String` — The role required to see this item.
- **visible** `Boolean` — Whether the item is visible.
- **from** `String` — The source of this navigation configuration (e.g., 'blocklet', 'user').
- **activeIcon** `String` — The icon to display when the navigation item is active.
- **color** `String` — The color of the navigation item text.
- **activeColor** `String` — The color when the navigation item is active.
- **description** `String` — A description for the navigation item.
- **private** `Boolean` — Indicates if the navigation item is private.

### ConnectedAccountInfoInput

Information about a user's account from a third-party provider.

- **name** `String` — User's name from the provider.
- **picture** `String` — URL of the user's profile picture.
- **email** `String` — User's email from the provider.
- **emailVerified** `Boolean` — Whether the email is verified by the provider.
- **sub** `String` — The subject identifier from the provider.
- **extraData** `Any` — Any additional data from the provider.

### ConnectedAccountInput

Represents a user's connected third-party account.

- **provider** `String` — The name of the third-party provider (e.g., 'github').
- **did** `String` — The DID associated with this connected account.
- **pk** `String` — The public key.
- **id** `String` — The unique ID of the connection.
- **lastLoginAt** `Uint32` — Timestamp of the last login with this account.
- **userInfo** `ConnectedAccountInfoInput` — Detailed user information from the provider.
- **extra** `Any` — Any additional metadata.

### DockerEnvKeyValuePairInput

Represents a single environment variable for a Docker container.

- **key** `String` — The environment variable key.
- **value** `String` — The environment variable value.
- **description** `String` — A description of the variable.
- **secure** `Boolean` — If true, the value is sensitive.
- **shared** `Boolean` — If true, the variable is shared.
- **required** `Boolean` — If true, this variable must be set.
- **custom** `String` — Indicates if it's a custom variable.

### DockerRunKeyValuePairInput

Represents a key-value pair for Docker run arguments, such as volume mounts or port mappings.

- **key** `String` — The argument key (e.g., '-v', '-p').
- **value** `String` — The argument value.
- **path** `String` — The path for volume mounts.
- **type** `String` — The type of argument.
- **name** `String` — The name of the argument.
- **prefix** `String` — A prefix for the argument.
- **protocol** `String` — The protocol for port mappings (e.g., 'tcp').
- **proxyBehavior** `String` — Defines how this argument affects proxying.

### DownloadTokenInput

Token used for downloading a private blocklet.

- **did** `String` — The DID of the blocklet requiring the token.
- **token** `String` — The download token.

### EnableEventInput

Structure for enabling a specific event for a webhook.

- **type** `String` — The type of the event (e.g., 'blocklet.started').
- **source** `String` — The source of the event.

### GatewayInput

Structure for configuring the main node gateway.

- **requestLimit** `RequestLimitInput` — Request limiting configuration.
- **blockPolicy** `BlockPolicyInput` — IP blocking policy configuration.
- **proxyPolicy** `ProxyPolicyInput` — Proxy policy configuration.
- **cacheEnabled** `Boolean` — Whether caching is enabled at the gateway.
- **wafPolicy** `WAFPolicyInput` — Web Application Firewall policy configuration.

### HashFileInput

Represents a file and its corresponding hash.

- **file** `String` — The path to the file.
- **hash** `String` — The hash of the file content.

### InviteSettingsInput

Structure for configuring user invitation settings.

- **enabled** `Boolean` — Whether user invitations are enabled.

### IssuerInput

Represents the issuer of a credential or passport.

- **id** `String` — The DID of the issuer.
- **name** `String` — The name of the issuer.
- **pk** `String` — The public key of the issuer.

### LoginEmailSettingsInput

Structure for email-based login settings.

- **enabled** `Boolean` — Whether email login is enabled.
- **requireVerified** `Boolean` — If true, users must verify their email address.
- **requireUnique** `Boolean` — If true, email addresses must be unique across all users.
- **trustOauthProviders** `Boolean` — If true, email addresses from OAuth providers are trusted by default.
- **enableDomainBlackList** `Boolean` — Whether to use a domain blacklist.
- **domainBlackList** `[String!]` — A list of email domains to block.
- **enableDomainWhiteList** `Boolean` — Whether to use a domain whitelist.
- **domainWhiteList** `[String!]` — A list of allowed email domains.
- **trustedIssuers** `[IssuerInput!]` — A list of trusted issuers for email verification.

### LoginPhoneSettingsInput

Structure for phone-based login settings.

- **enabled** `Boolean` — Whether phone login is enabled.
- **requireVerified** `Boolean` — If true, users must verify their phone number.
- **requireUnique** `Boolean` — If true, phone numbers must be unique.
- **trustedIssuers** `[IssuerInput!]` — A list of trusted issuers for phone verification.
- **enableRegionBlackList** `Boolean` — Whether to use a region blacklist.
- **regionBlackList** `[String!]` — A list of blocked country codes.
- **enableRegionWhiteList** `Boolean` — Whether to use a region whitelist.
- **regionWhiteList** `[String!]` — A list of allowed country codes.

### NodeInfoInput

Structure for updating the node's information.

- **name** `String` — The display name of the node.
- **description** `String` — A description of the node.
- **autoUpgrade** `Boolean` — Whether the node should upgrade automatically.
- **enableWelcomePage** `Boolean` — Whether to show the welcome page.
- **registerUrl** `String` — The URL for user registration.
- **webWalletUrl** `String` — The URL of the web wallet.
- **blockletRegistryList** `[BlockletStoreInput!]` — A list of configured blocklet registries.
- **diskAlertThreshold** `Uint32` — The disk usage percentage at which to trigger an alert.
- **enableBetaRelease** `Boolean` — Whether to allow installation of beta releases.
- **nftDomainUrl** `String` — The URL for NFT domain services.
- **enableFileSystemIsolation** `Boolean` — Whether to isolate blocklet file systems.
- **enableDocker** `Boolean` — Whether to enable Docker for blocklets.
- **isDockerInstalled** `Boolean` — Read-only field indicating if Docker is installed.
- **enableDockerNetwork** `Boolean` — Whether to enable custom Docker networking.
- **enableSessionHardening** `Boolean` — Whether to enable advanced session security features.

### OauthClientInput

Structure for creating or updating an OAuth client.

- **redirectUris** `[String!]` — An array of allowed redirect URIs.
- **tokenEndpointAuthMethod** `String` — The authentication method for the token endpoint.
- **grantTypes** `[String!]` — The OAuth grant types this client is allowed to use.
- **responseTypes** `[String!]` — The OAuth response types this client is allowed to use.
- **clientName** `String` — The name of the client application.
- **clientId** `String` — The unique ID of the client.
- **clientSecret** `String` — The client secret.

### PagingInput

Standard structure for pagination parameters.

- **page** `Uint32` — The page number to retrieve.
- **pageSize** `Uint32` — The number of items per page.

### PassportDisplayInput

Structure for defining how a passport is displayed.

- **type** `String` — The display type (e.g., 'text', 'image').
- **content** `String` — The content to be displayed.

### PermissionInput

Structure for creating or updating a permission.

- **name** `String` — The name of the permission (e.g., 'user:create').
- **description** `String` — A description of what the permission allows.
- **isProtected** `Boolean` — If true, the permission cannot be easily modified or deleted.

### ProxyPolicyInput

Structure for configuring proxy behavior.

- **enabled** `Boolean` — Whether the proxy policy is enabled.
- **trustRecursive** `Boolean` — Whether to trust all proxies in the chain.
- **trustedProxies** `[String!]` — A list of trusted proxy IP addresses.
- **realIpHeader** `String` — The HTTP header used to identify the real client IP.

### RequestLimitInput

Structure for configuring request rate limiting.

- **enabled** `Boolean` — Whether rate limiting is enabled.
- **global** `Uint32` — The global request limit.
- **rate** `Uint32` — The number of requests per time unit.
- **methods** `[String!]` — The HTTP methods to which this limit applies.

### RoleUpdateInput

Structure for updating a user role.

- **name** `String` — The unique name of the role.
- **title** `String` — The human-readable title of the role.
- **description** `String` — A description of the role.
- **extra** `String` — Extra metadata for the role in JSON format.

### RoutingRuleInput

Structure for defining a routing rule.

- **id** `String` — The unique ID of the rule.
- **from** `RoutingRuleFromInput` — The source criteria for the rule.
- **to** `RoutingRuleToInput` — The destination target for the rule.
- **isProtected** `Boolean` — If true, the rule cannot be easily modified or deleted.

### SessionConfigInput

Structure for configuring user session settings.

- **cacheTtl** `Uint32` — The Time-to-Live (TTL) for session cache, in seconds.
- **ttl** `Uint32` — The TTL for the session itself, in seconds.
- **email** `LoginEmailSettingsInput` — Email login settings.
- **phone** `LoginPhoneSettingsInput` — Phone login settings.
- **salt** `String` — The salt used for session key generation.
- **enableBlacklist** `Boolean` — Whether to enable session blacklisting.

### TagInput

Structure for creating or updating a tag.

- **id** `Uint32` — The unique ID of the tag (used for updates).
- **title** `String` — The title of the tag.
- **description** `String` — A description of the tag.
- **color** `String` — The color associated with the tag (hex code).

### UserAddressInput

Structure for a user's physical address.

- **country** `String` — The country.
- **province** `String` — The state or province.
- **city** `String` — The city.
- **postalCode** `String` — The postal code.
- **line1** `String` — The first line of the address.
- **line2** `String` — The second line of the address.

### UserInfoInput

Comprehensive structure for user information, used for creating or updating users.

- **did** `String` — The user's DID.
- **pk** `String` — The user's public key.
- **role** `String` — The user's assigned role.
- **avatar** `String` — URL to the user's avatar.
- **fullName** `String` — The user's full name.
- **email** `String` — The user's email address.
- **approved** `Boolean` — Whether the user's account is approved.
- **remark** `String` — An administrative remark about the user.
- **extra** `Any` — Extra metadata in JSON format.
- **tags** `[TagInput!]` — A list of tags to associate with the user.
- **address** `UserAddressInput` — The user's physical address.

### UserQueryInput

Structure for filtering and querying users.

- **role** `String` — Filter users by role.
- **approved** `Boolean` — Filter users by approval status.
- **search** `String` — A search term to match against user fields.
- **tags** `[Uint32!]` — Filter users by associated tag IDs.
- **includeTags** `Boolean` — Whether to include tag details in the response.
- **includeUserSessions** `Boolean` — Whether to include session details in the response.

### UserSessionQueryInput

Structure for querying user sessions.

- **userDid** `String` — Filter sessions by user DID.
- **visitorId** `String` — Filter sessions by visitor ID.
- **appPid** `String` — Filter sessions by application PID.
- **status** `String` — Filter sessions by status (e.g., 'active').
- **includeUser** `Boolean` — Whether to include user details in the response.

### WAFPolicyInput

Structure for Web Application Firewall (WAF) configuration.

- **enabled** `Boolean` — Whether the WAF is enabled.
- **mode** `String` — The operational mode of the WAF (e.g., 'detection', 'blocking').
- **inboundAnomalyScoreThreshold** `Uint32` — The anomaly score threshold for inbound traffic.
- **outboundAnomalyScoreThreshold** `Uint32` — The anomaly score threshold for outbound traffic.
- **logLevel** `Uint32` — The logging level for WAF events.

### WebHookParamInput

Structure for defining a parameter for a webhook.

- **name** `String` — The name of the parameter.
- **description** `String` — A description of the parameter.
- **required** `Boolean` — Whether the parameter is required.
- **defaultValue** `String` — The default value for the parameter.
- **value** `String` — The current value of the parameter.
- **type** `String` — The data type of the parameter (e.g., 'string').

### WebhookEndpointStateInput

Structure for creating or updating a webhook endpoint.

- **url** `String` — The URL to which webhook payloads will be sent.
- **description** `String` — A description of the webhook endpoint.
- **enabledEvents** `[EnableEventInput!]` — A list of events that this endpoint subscribes to.
- **status** `String` — The status of the endpoint (e.g., 'enabled', 'disabled').

---

## Authentication

URL: https://www.arcblock.io/en/docs/blocklet-server-js/authentication-c86fd7/

The `@blocklet/server-js` library provides two primary methods for authenticating API requests: Auth Tokens and Access Keys. The appropriate method depends on your application's environment and security requirements. Auth tokens are typically used in user-facing applications like browsers, while access keys are designed for secure server-to-server communication.

This section explains how to implement both authentication strategies.

![Authentication](https://media.arcblock.io/lib/09/0993c28536c9e843.w1600.webp)

## Using an Auth Token

This is the most common authentication method for applications where a user is actively logged in, such as a web application running in a browser. The auth token is typically retrieved from the user's session and is valid for a limited time.

To use this method, instantiate the client and provide the token using the `setAuthToken` method.

**Using setAuthToken**

```javascript
import BlockletServerClient from '@blocklet/server-js';

// The endpoint of your Blocklet Server
const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);

// Token obtained from a user's session after they log in.
// You can typically find this in the browser's localStorage under the key `__sst` on your Blocklet Server domain.
const userAuthToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoidXNlciIsImRpZCI6Inoxbjd5TG5BRDV3VHJ5RjU2S0IzU3N0MVJlbVpVQTQ4OEhoIiwicm9sZSI6ImFkbWluIiwicHJvdmlkZXIiOiJ3YWxsZXQiLCJreWMiOjAsImVsZXZhdGVkIjpmYWxzZSwiZnVsbE5hbWUiOiJza3lwZXNreSIsImlhdCI6MTc2MTAzODQ1OSwiZXhwIjoxNzYxMDQyMDU5fQ.rLoDz0o2Jg83BP_IGF8bwhHT3Qnyhy8KfVQNzSa1ycY';

client.setAuthToken(userAuthToken);

// All subsequent API calls will be automatically authenticated
async function fetchNodeInfo() {
  try {
    const response = await client.getNodeInfo();
    console.log('Node Info:', response.info.name);
  } catch (error) {
    console.error('Failed to fetch node info:', error);
  }
}

fetchNodeInfo();
```

Once the token is set, the client automatically includes an `Authorization: Bearer <token>` header in all subsequent GraphQL requests.

## Using an Access Key

Access keys are intended for server-to-server communication, background services, or any non-interactive environment where a user session is not available. This method provides a more secure and persistent way to grant programmatic access.

To use an access key, you must use the native version of the client, which includes the necessary cryptographic libraries.

**Importing the Native Client**

```javascript
import BlockletServerClient from '@blocklet/server-js/native';
```

Then, configure the client using the `setAuthAccessKey` method. This method accepts an object with the following fields:

- **accessKeyId** `string` *(required)* — The public identifier for the key. This is typically the DID address of the associated wallet.
- **accessKeySecret** `string` *(required)* — The secret key (or private key) used to sign requests. Never expose this in client-side code.
- **type** `any` *(required)* — The signing algorithm or wallet type. Supported values include wallet types from @ocap/wallet (e.g., eth, arc), as well as 'sha256', and 'totp'. The type must match how the access key was configured in Blocklet Server.

**Using setAuthAccessKey**

```javascript
import BlockletServerClient from '@blocklet/server-js/native';

const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);

client.setAuthAccessKey({
  accessKeyId: 'zNKjw25A312AbC5A1234567890abcdefABCDEF', // Your Access Key ID
  accessKeySecret: 'sk_1234567890abcdefABCDEF1234567890abcdef', // Your Access Key Secret
  type: 'eth' // The wallet type associated with the key
});

// All subsequent API calls will be authenticated using signed headers
async function fetchBlocklets() {
  try {
    const response = await client.getBlocklets();
    console.log(`Found ${response.blocklets.length} blocklets.`);
  } catch (error) {
    console.error('Failed to fetch blocklets:', error);
  }
}

fetchBlocklets();
```

When using an access key, the client generates a unique signature for each request and sends it in the `x-access-signature` header, along with `x-access-key-id` and other necessary authentication headers. This ensures that each request is securely authenticated without exposing the secret key.

Now that you know how to authenticate your requests, you can proceed to the [API Reference](/en/docs/blocklet-server-js/api-reference-c86fd7/) to explore the available queries and mutations.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-server-js/getting-started-c86fd7/

This guide provides a step-by-step walkthrough to get you up and running with the `@blocklet/server-js` library. You'll learn how to install the client, connect to a Blocklet Server, and make your first API call.

## Installation

First, you need to add the `@blocklet/server-js` package to your project. You can use your preferred package manager:

**npm**

```bash
npm install @blocklet/server-js
```

**yarn**

```bash
yarn add @blocklet/server-js
```

**pnpm**

```bash
pnpm add @blocklet/server-js
```

## Usage

The library is designed to work seamlessly in both Node.js and browser environments. The first step is to import and instantiate the `BlockletServerClient` with the GraphQL endpoint of your Blocklet Server.

### Node.js

In a Node.js environment, you can use `require` or `import` to get the client class.

**Node.js Example**

```javascript
const BlockletServerClient = require('@blocklet/server-js');

// Replace with your Blocklet Server's GraphQL endpoint
const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);
```

### Browser

For frontend applications, you can import the client directly into your components or scripts.

**Browser Example**

```javascript
import BlockletServerClient from '@blocklet/server-js';

// The endpoint is typically the one your frontend is served from
const endpoint = '/api'; // Or a full URL like 'https://my-node.abtnode.com/api'
const client = new BlockletServerClient(endpoint);
```

## Making Your First API Call

Once the client is initialized, you can use its methods to interact with the Blocklet Server's GraphQL API. Let's make a simple query to fetch basic information about the node.

All API methods return an object containing either a `response` or an `error`.

**fetch-node-info.js**

```javascript
const BlockletServerClient = require('@blocklet/server-js');

async function fetchNodeInfo() {
  try {
    // Replace with your Blocklet Server's GraphQL endpoint
    const client = new BlockletServerClient('http://localhost:4000/api');

    // Fetch the node's information
    const { response, error } = await client.getNodeInfo();

    if (error) {
      console.error('Error fetching node info:', error.message);
      return;
    }

    console.log('Node Info:', response.info);
  } catch (err) {
    console.error('An unexpected error occurred:', err);
  }
}

fetchNodeInfo();
```

#### Example Response

If the call is successful, you will receive a response object similar to this:

**Response**

```json
{
  "info": {
    "name": "My Development Node",
    "version": "1.16.22",
    "did": "z8iZge7d3iYy2iZb..."
  }
}
```

## Next Steps

Congratulations! You've successfully installed the Blocklet Server Client and made your first API call.

Most API calls require authentication to ensure that only authorized users or applications can access or modify data. The next step is to learn how to authenticate your requests.

:::action-card{title="Authentication" description="Proceed to the Authentication guide to understand how to use auth tokens and access keys to secure your API calls." icon="key"}
::action{label="Learn about Authentication" href="/en/docs/blocklet-server-js/authentication-c86fd7/" variant="primary"}
:::

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-server-js/overview-c86fd7/

The `@blocklet/server-js` library is the official JavaScript client for interacting with the Blocklet Server GraphQL API. It provides a convenient and powerful interface for both Node.js and browser-based applications to communicate with a Blocklet Server instance, simplifying tasks like managing blocklets, users, and services.

Whether you're building a web application that integrates with Blocklet Server or automating administrative tasks, this library abstracts away the complexity of raw GraphQL requests, offering a streamlined, developer-friendly experience.

![Overview](https://media.arcblock.io/lib/f6/f62c70540fcfd702.w1600.webp)

## Key Features

::::card-group
::link-card{title="Universal Compatibility" description="Designed as an isomorphic library, it works seamlessly in both Node.js server-side environments and modern web browsers, allowing you to share code across your stack." icon="globe"}
::link-card{title="Full API Coverage" description="Provides strongly-typed methods for all available GraphQL queries and mutations, ensuring you have access to the full power of the Blocklet Server API." icon="database"}
::link-card{title="Simplified Authentication" description="Handles authentication transparently. Easily configure the client with auth tokens or access keys for secure communication. Learn more in our [Authentication Guide](./authentication.md)." icon="key"}
::link-card{title="Developer Friendly" description="The API is designed to be intuitive and easy to use, enabling you to focus on your application's logic instead of boilerplate for API communication." icon="code"}
::::

## Next Steps

Ready to integrate your application with Blocklet Server? Here's where to go next:

::::card-group
::link-card{title="Getting Started" description="Follow our step-by-step guide to install the client and make your first API call in minutes." icon="rocket" href="/en/docs/blocklet-server-js/getting-started-c86fd7/"}
::link-card{title="API Reference" description="Dive deep into the complete list of available methods, parameters, and data types." icon="book-open" href="/en/docs/blocklet-server-js/api-reference-c86fd7/"}
::::

---

## Blocklet Service

URL: https://www.arcblock.io/en/docs/blocklet-service/

---

## Developer Guide

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-4f480d/

Welcome to the Developer Guide for Blocklet Service. This guide provides comprehensive information for developers who want to programmatically integrate and utilize the various reusable services in their own applications. Blocklet Service is designed to be a robust backend, offering a suite of powerful, out-of-the-box services that handle common application functionalities, allowing you to focus on building unique features for your users.

Below is a summary of the core services available. Each service is designed to be modular and can be integrated independently. Please refer to the detailed documentation for each service to understand its full capabilities and API specifications.

::::card-group
::link-card{title="Authentication Service" description="Integrate with the authentication service for user login, session management, and profile retrieval, including DID-based and third-party OAuth authentication." icon="key" href="/en/docs/blocklet-service/developer-guide-authentication-4f480d/"}
::link-card{title="Notification Service" description="Use the API to send multi-channel notifications to users, including wallet messages, emails, and push notifications via PushKit." icon="bell" href="/en/docs/blocklet-service/developer-guide-notification-4f480d/"}
::link-card{title="Image Service" description="Access on-the-fly image processing, including resizing, cropping, format conversion, and applying various filters through URL query parameters." icon="image" href="/en/docs/blocklet-service/developer-guide-image-4f480d/"}
::link-card{title="MCP Service" description="Interact with the Model Context Protocol (MCP) server to build AI-powered features and tools within your blocklets." icon="cpu" href="/en/docs/blocklet-service/developer-guide-mcp-4f480d/"}
::link-card{title="EventBus Service" description="Define, publish, and subscribe to events, enabling seamless, decoupled communication between different blocklets and the core system." icon="routes" href="/en/docs/blocklet-service/developer-guide-eventbus-4f480d/"}
::link-card{title="OAuth Service" description="Integrate third-party authentication providers like Google and GitHub, and learn about the configuration and API flow for federated login." icon="lock" href="/en/docs/blocklet-service/developer-guide-oauth-4f480d/"}
::link-card{title="KYC Service" description="Integrate with the Know Your Customer (KYC) service to verify user identities, such as email or phone numbers, within your application." icon="shield-check" href="/en/docs/blocklet-service/developer-guide-kyc-4f480d/"}
::link-card{title="Discovery & SEO Services" description="A collection of guides on services that enhance the discoverability and search engine optimization of your blocklet, including Open Graph and OpenEmbed." icon="search" href="/en/docs/blocklet-service/developer-guide-discovery-seo-4f480d/"}
::::

## Summary

This guide is intended to provide all the necessary details for integrating these services into your blocklet. By leveraging the Blocklet Service, you can significantly reduce development time and effort, ensuring your application is built on a reliable and scalable foundation.

For administrators and non-technical users looking to configure these services through a graphical interface, please refer to the [User Guide](/en/docs/blocklet-service/user-guide-4f480d/).

---

## Authentication Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-authentication-4f480d/

The Authentication Service provides a comprehensive solution for managing user identity, authentication, and session control within your blocklet. It is designed to be secure, flexible, and easy to integrate, supporting various authentication methods to cater to different user needs.

This service handles the entire user lifecycle, from registration and login to session management and profile retrieval. Developers can leverage this service to secure their applications and provide a seamless user experience without building an authentication system from scratch. It supports decentralized identity through DID Wallet, traditional email-based login, and federated login with third-party OAuth providers such as Google or GitHub.

## How It Works

The authentication process is designed to be straightforward. When a user attempts to log in to your application, your blocklet redirects them to the Blocklet Service's authentication endpoint. The service then handles the interaction with the chosen identity provider (e.g., DID Wallet, Google). Upon successful authentication, the service generates a secure session for the user and redirects them back to your application with the necessary session tokens. Your application can then use these tokens to retrieve user profile information and manage the user's session.

The following diagram illustrates this authentication flow:

![Authentication Service](https://media.arcblock.io/lib/61/61c63285c52a703a.w1600.webp)

## Key Features

- <strong>Multiple Authentication Methods</strong>: Supports DID-based authentication via DID Wallet, email-based sign-in, and federated login through third-party OAuth providers.
- <strong>Session Management</strong>: Securely manages user sessions using JWT-based session and refresh tokens.
- <strong>User Profile Management</strong>: Provides APIs to retrieve and update user profile information.
- <strong>Access Control</strong>: Integrates with a role-based access control (RBAC) system to enforce security policies.
- <strong>KYC Integration</strong>: Works alongside the [KYC Service](/en/docs/blocklet-service/developer-guide-kyc-4f480d/) to ensure users are properly verified when required.
- <strong>Quick Login</strong>: Allows users to log in quickly using a previously established session on the same device.

## API Reference

The Authentication Service exposes a set of RESTful API endpoints for developers to integrate into their applications.

### Login and Session

These endpoints are used to initiate and manage user authentication and sessions.

#### Login with SDK

This endpoint is used by the Blocklet SDK to log in a user with either a DID Wallet or an OAuth provider. It authenticates the user and returns session tokens. The `provider` field determines the authentication method.

- <strong>Endpoint</strong>: `POST /.well-known/service/api/user/login`

##### Parameters (Wallet Provider)

- **provider** `string` *(required)* — The authentication provider. Must be set to 'wallet'.
- **did** `string` *(required)* — The user's Decentralized Identifier (DID).
- **pk** `string` *(required)* — The user's public key corresponding to the DID.
- **fullName** `string` *(required)* — The user's full name.
- **email** `string` — The user's email address.
- **avatar** `string` — A data URI or URL for the user's avatar image.
- **inviter** `string` — The DID of the user who invited this user.

##### Parameters (OAuth Provider)

- **provider** `string` *(required)* — The name of the OAuth provider (e.g., 'google', 'github').
- **id** `string` *(required)* — The unique identifier for the user from the OAuth provider.
- **fullName** `string` *(required)* — The user's full name.
- **email** `string` *(required)* — The user's email address.
- **avatar** `string` — A URL for the user's avatar image.
- **inviter** `string` — The DID of the user who invited this user.

##### Returns

- **user** `object` *(required)* — Object containing basic user information.
  - **did** `string` *(required)* — User's DID.
  - **fullName** `string` *(required)* — User's full name.
  - **email** `string` — User's email address.
  - **avatar** `string` — URL path to the user's avatar.
- **token** `string` *(required)* — The session token (JWT) for authenticating subsequent requests.
- **refreshToken** `string` *(required)* — The refresh token used to obtain a new session token.
- **visitorId** `string` *(required)* — A unique identifier for the user's session on the device.

#### Login with DID Wallet

This endpoint is used for native DID Wallet login flows. It verifies a user's signature from DID Wallet and establishes a session.

- <strong>Endpoint</strong>: `POST /.well-known/service/api/user/loginByWallet`

##### Parameters

- **userDid** `string` *(required)* — The user's DID.
- **userPk** `string` *(required)* — The user's public key.
- **signature** `string` *(required)* — The JWT signature provided by the wallet.
- **walletOS** `string` *(required)* — The operating system of the wallet (e.g., 'iOS', 'Android').
- **challenge** `string` *(required)* — A random string used to prevent replay attacks.
- **componentId** `string` *(required)* — The identifier of the blocklet component initiating the login.
- **visitorId** `string` — The unique session identifier for the device.
- **passportId** `string` — The ID of the passport to use for this session.
- **sourceAppPid** `string` — The PID of the source application in a federated context.
- **locale** `string` — The user's preferred language locale.
- **inviter** `string` — The DID of the user who invited this user.

##### Returns

- **sessionToken** `string` *(required)* — The session token (JWT).
- **refreshToken** `string` *(required)* — The refresh token.
- **challenge** `string` *(required)* — The original challenge string, returned for validation.
- **visitorId** `string` *(required)* — The session identifier for the device.

#### Get Current Session

Retrieves the profile and session details for the currently authenticated user.

- <strong>Endpoint</strong>: `GET /.well-known/service/api/did/session`
- <strong>Authentication</strong>: Requires `Bearer` token in the `Authorization` header.

##### Returns

- **user** `object` *(required)* — The full user object.
  - **did** `string` *(required)* — User's DID.
  - **fullName** `string` *(required)* — User's full name.
  - **email** `string` — User's email address.
  - **avatar** `string` — URL path to the user's avatar.
  - **role** `string` — The user's current role for this session.
  - **passports** `array` — A list of valid passports held by the user.
    - **id** `string` *(required)* — Passport ID.
    - **name** `string` *(required)* — Passport name.
    - **title** `string` *(required)* — Passport title.
    - **role** `string` *(required)* — The role associated with the passport.
  - **permissions** `array` — A list of permissions granted to the user's role.
- **provider** `string` *(required)* — The provider used for the current session (e.g., 'wallet').
- **walletOS** `string` — The operating system of the wallet used for login.

#### Refresh Session

Allows an application to obtain a new session token using a valid refresh token.

- <strong>Endpoint</strong>: `POST /.well-known/service/api/did/refreshSession`
- <strong>Authentication</strong>: Requires `Bearer` token containing the refresh token in the `Authorization` header.

##### Returns

- **user** `object` *(required)* — The user object associated with the session.
- **nextToken** `string` *(required)* — A new session token.
- **nextRefreshToken** `string` *(required)* — A new refresh token.
- **provider** `string` *(required)* — The original login provider.
- **walletOS** `string` — The original wallet OS.

#### Logout

Logs out the current user and invalidates their session. It can target a specific session or all sessions for the user.

- <strong>Endpoint</strong>: `POST /.well-known/service/api/user/logout`

##### Parameters

- **visitorId** `string` — The unique identifier of the session to log out. If omitted, all sessions for the user may be targeted depending on other parameters.
- **refreshToken** `string` — The refresh token of the session to invalidate.

### User Profile Management

These endpoints allow for the retrieval and modification of user data.

#### Get Public User Profile

Fetches publicly available information for any user. The exact data returned depends on the user's privacy settings.

- <strong>Endpoint</strong>: `GET /.well-known/service/api/user`

##### Parameters

- **did** `string` *(required)* — The DID of the user to query.

##### Returns

A user object containing only publicly visible fields.

#### Manage Private User Profile

These endpoints manage the private profile of the currently logged-in user.

- <strong>Get Profile</strong>: `GET /.well-known/service/api/user/profile`
- <strong>Update Profile</strong>: `PUT /.well-known/service/api/user/profile`
- <strong>Authentication</strong>: Requires `Bearer` token in the `Authorization` header.

##### Parameters (for PUT request)

- **fullName** `string` — The user's full name.
- **email** `string` — The user's email address.
- **locale** `string` — The user's preferred language locale.
- **metadata** `object` — An object for storing additional profile data.
  - **bio** `string` — A short biography of the user.
  - **timezone** `string` — The user's timezone.

##### Returns (for GET and PUT requests)

- **did** `string` *(required)* — The user's DID.
- **locale** `string` *(required)* — The user's locale.
- **avatar** `string` — URL path to the user's avatar.
- **fullName** `string` *(required)* — The user's full name.
- **email** `string` — The user's email address.
- **emailVerified** `boolean` *(required)* — Indicates if the user's email has been verified.
- **phoneVerified** `boolean` *(required)* — Indicates if the user's phone has been verified.
- **metadata** `object` — Additional profile metadata.

## Summary

The Authentication Service is a core component for building secure and user-friendly applications on the Blocklet platform. By handling the complexities of user identity and session management, it allows developers to focus on their application's core logic. For more details on integrating specific login methods, please refer to the [OAuth Service](/en/docs/blocklet-service/developer-guide-oauth-4f480d/) guide.

---

## Discovery & SEO Services

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-discovery-seo-4f480d/

Effective Search Engine Optimization (SEO) and content discoverability are critical for any web application's success. They ensure that your blocklet can be easily found, understood, and shared by users and other services across the internet. Blocklet Service provides a suite of tools designed to enhance your application's visibility on search engines, social media platforms, and other websites.

This guide provides an overview of the key discovery and SEO services available for your blocklet. By leveraging these services, you can improve how your content is presented and integrated across the web, leading to better engagement and a wider reach.

::::card-group
::link-card{title="Open Graph" description="Learn how to dynamically generate and customize preview images for social media sharing, ensuring your content looks compelling when linked on platforms like Twitter and Facebook." icon="image" href="/en/docs/blocklet-service/developer-guide-discovery-seo-open-graph-4f480d/"}
::link-card{title="OpenEmbed" description="Discover how to expose oEmbed-compatible endpoints, allowing rich, embedded representations of your blocklet's components to appear on other websites and platforms." icon="code-2" href="/en/docs/blocklet-service/developer-guide-discovery-seo-openembed-4f480d/"}
::::

## Key Services

The following services are automatically enabled and configured to help improve your blocklet's discoverability.

### Open Graph Service

The Open Graph service dynamically generates social media preview images for your blocklet's pages. When a user shares a link to your application on platforms like Facebook, Twitter, or Slack, a rich preview card with a title, description, and a custom image is displayed. This is crucial for increasing click-through rates and ensuring brand consistency.

The service offers several templates to control the appearance of these images, allowing you to include titles, descriptions, logos, and other branding elements.

For detailed instructions on implementation and customization, please refer to the [Open Graph Guide](/en/docs/blocklet-service/developer-guide-discovery-seo-open-graph-4f480d/).

### OpenEmbed Service

The OpenEmbed service allows parts of your blocklet to be easily embedded into other websites, similar to embedding a YouTube video or a Tweet. It follows the oEmbed specification, a standard format for allowing an embedded representation of a URL on third-party sites. By exposing oEmbed-compatible endpoints, you make it simple for other content creators to integrate and showcase your blocklet's features within their own platforms.

Each component within your blocklet can provide its own `openembed.json` file, which is automatically aggregated into a single, site-wide discovery endpoint.

To learn how to configure your components for embedding, see the [OpenEmbed Guide](/en/docs/blocklet-service/developer-guide-discovery-seo-openembed-4f480d/).

### OpenAPI Specification

For blocklets that expose APIs, the service can automatically discover and merge OpenAPI specification files (`openapi.yml` or `openapi.json`) from your blocklet and its components. This creates a unified API definition that can be used by developer tools, API clients, and discovery services to understand and interact with your blocklet's programmatic interfaces. This enhances the developer experience and promotes integration.

### Sitemap and Robots.txt

Blocklet Service automatically generates and serves `sitemap.xml` and `robots.txt` files for your application.

- <strong>sitemap.xml</strong>: This file lists the important pages on your website, helping search engine crawlers like Google find and index your content more efficiently.
- <strong>robots.txt</strong>: This file instructs web crawlers on which pages or files they can or cannot request from your site.

These files are managed by the system to follow best practices for SEO and require no manual configuration from the developer.

## Summary

By utilizing the Discovery and SEO services provided by Blocklet Service, you can significantly improve how your application is perceived and indexed by external platforms. These tools are designed to work with minimal configuration while offering powerful customization options for those who need them. We encourage you to explore the detailed guides for each service to make the most of what they offer.

---

## Open Graph

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-discovery-seo-open-graph-4f480d/

## Overview

The Open Graph service is a component of the Blocklet Service designed to dynamically generate customized images for social media sharing. When a link to your application is shared on platforms like Twitter, Facebook, or Slack, these platforms crawl the URL and look for Open Graph meta tags (`og:image`). This service provides a dynamic endpoint that generates an `og:image` on-the-fly, ensuring that shared links display rich, informative, and branded preview cards.

This functionality enhances user engagement and brand consistency by replacing generic link previews with visually appealing images that can include your application's logo, a custom title, description, and other relevant information. The service is built on Satori for SVG generation from HTML/CSS and Sharp for fast image processing, providing a robust and efficient solution for creating social sharing cards.

## How It Works

The Open Graph image generation process is straightforward and automated. Here is a step-by-step breakdown of the workflow:

![Open Graph](https://media.arcblock.io/lib/7c/7cfc32ee8eb2deab.w1600.webp)

::::steps
:::step{title="Request"}
A user or a social media crawler accesses a specific URL endpoint for the Open Graph image. The URL includes query parameters that define the content and appearance of the image, such as the template, title, and description.
:::

:::step{title="Parameter Validation"}
The service receives the request and validates the query parameters against a predefined schema to ensure all required fields are present and correctly formatted for the chosen template.
:::

:::step{title="Data Population"}
The service populates an HTML template with the provided data. If certain parameters like `title`, `description`, or `logo` are omitted, the service automatically uses the default values configured for the blocklet.
:::

:::step{title="SVG Generation"}
The populated HTML is processed by the Satori engine, which converts it into an SVG (Scalable Vector Graphic) image. This step includes rendering text, applying styles, and embedding any specified logos or cover images.
:::

:::step{title="Image Conversion"}
The generated SVG is then passed to the Sharp library, which converts it into a standard image format, typically PNG.
:::

:::step{title="Caching and Delivery"}
The final image is saved to a cache directory. On subsequent requests with the same parameters, the cached image is served directly to improve performance. The image is then delivered to the client with appropriate HTTP headers.
:::
::::

This entire process happens in real-time, allowing for the dynamic creation of a wide variety of social media cards tailored to different content within your application.

## Usage

To generate an Open Graph image, you need to construct a URL pointing to the service endpoint and append the desired query parameters. This URL can then be placed in the `content` attribute of the `<meta property="og:image" content="...">` tag in your application's HTML head.

### Endpoint

The image is generated via a GET request to the following endpoint:

```
/.well-known/service/blocklet/og.png
```

For example, if your application is running at `https://example.com`, the full endpoint URL would be: `https://example.com/.well-known/service/blocklet/og.png`

### Query Parameters

The appearance and content of the generated image are controlled by a set of URL query parameters. Below is a detailed list of the available parameters.

- **template** `string` (default: `default`) — Specifies the layout template to use. Each template is designed for a different use case. Possible values are: default, section, cover, banner.
- **title** `string` — The main title text to be displayed on the image. Limited to 128 characters. If not provided, the blocklet's name is used. Required for section, cover, and banner templates.
- **description** `string` — The subtitle or description text. Limited to 512 characters. If not provided, the blocklet's description is used. Required for the section template.
- **section** `string` — A short text string, typically used to indicate a category or section name. Displayed above the title. Limited to 64 characters. Required for the section template.
- **cover** `string` — A URL for a cover image. The image must be accessible via HTTPS. Required for the cover template.
- **logo** `string` — A URL for a custom logo. The image must be accessible via HTTPS. If not provided, the blocklet's default logo is used. Required for the banner template.
- **logoRounded** `string` — Determines if the logo should be rendered with rounded corners. Set to 1 for a circular logo or 0 for a square logo.
- **emoji** `string` (default: `twemoji`) — Specifies the emoji style to use when rendering emojis in the text. Defaults to twemoji.
- **nocache** `string` — Set to 1 to bypass the cache and force the regeneration of the image. Useful for development and testing.

## Templates

The service provides four distinct templates, each suited for different types of content.

### Default Template

The `default` template is a general-purpose layout. It displays the application logo, a title, and a description against the blocklet's configured Open Graph background image.

- <strong>URL Example:</strong> `/.well-known/service/blocklet/og.png?template=default&title=Welcome%20to%20Our%20Application&description=Discover%20amazing%20features%20and%20services.`

### Section Template

The `section` template is ideal for articles, blog posts, or documentation pages. It includes a `section` field to display a category or topic above the main title.

- <strong>URL Example:</strong> `/.well-known/service/blocklet/og.png?template=section&section=Developer%20Guide&title=Getting%20Started&description=An%20introduction%20to%20our%20core%20features%20for%20developers.`

### Cover Template

The `cover` template is designed to highlight a specific visual. It features a prominent cover image on one side with the title, description, and logo on the other.

- <strong>URL Example:</strong> `/.well-known/service/blocklet/og.png?template=cover&title=New%20Feature&description=Announcing%20Our%20Latest%20Update&cover=https://picsum.photos/id/10/660/630`

### Banner Template

The `banner` template provides a wide-format image suitable for banners or headers. It prominently displays a large logo alongside the title.

- <strong>URL Example:</strong> `/.well-known/service/blocklet/og.png?template=banner&title=Official%20Partner%20Event&logo=https://picsum.photos/id/20/150/150&logoRounded=1`

## Summary

The Open Graph service automates the creation of high-quality, branded images for social media sharing. By utilizing a simple URL-based API, developers can dynamically generate context-rich preview cards that improve visibility and user engagement. For more information on configuring your blocklet's default branding, see the [Branding](/en/docs/blocklet-service/user-guide-website-branding-4f480d/) guide.

---

## OpenEmbed

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-discovery-seo-openembed-4f480d/

This is a placeholder for a diagram. Do not edit this line directly.

OpenEmbed is a service that allows your blocklet and its components to expose oEmbed-compatible endpoints. This makes it possible for other websites and applications to easily discover and embed content from your blocklet, enhancing its discoverability and integration capabilities. The service aggregates OpenEmbed data from all running components and provides it in both JSON and YAML formats.

This guide explains how the OpenEmbed service works and how you, as a developer, can make your blocklet's components compatible with it.

## How It Works

The OpenEmbed service operates on a discovery and aggregation model. When an external application (a consumer) wants to embed content from your blocklet, it first needs to discover the available embeddable resources. Blocklet Service facilitates this by providing a standardized endpoint.

The process is as follows:

::::steps
:::step{title="Discovery"}
An oEmbed consumer queries the well-known endpoint provided by the Blocklet Service: `/.well-known/openembed.json`.
:::

:::step{title="Internal Query"}
The Blocklet Service, upon receiving the request, scans for all active child components that are configured to provide OpenEmbed data.
:::

:::step{title="Data Fetching"}
For each compatible component, the service makes an internal request to a specific path within that component (`/__blocklet__/openembed.json`) to retrieve its list of embeddable content URLs.
:::

:::step{title="Aggregation & Enrichment"}
The service collects the responses from all components. It enriches this data by prefixing each embeddable path with its component's mount point and adding relevant metadata.
:::

:::step{title="Response"}
The service returns a single, aggregated `openembed.json` (or `.yaml`) file to the consumer, containing a complete list of all embeddable content from the entire blocklet application.
:::
::::

The following diagram illustrates this data flow: This is a placeholder for a diagram. Do not edit this line directly.

## Developer Implementation

To make a component's content embeddable, you must expose a JSON endpoint that provides metadata about the resources you want to make available.

### 1. Create the OpenEmbed Endpoint

Within your component, create a route that responds to GET requests at `/__blocklet__/openembed.json`. This is the fixed path that the Blocklet Service will query.

The response from this endpoint must include the `x-blocklet-openembed: true` header to be recognized by the service.

### 2. Define the JSON Structure

The JSON file served by your endpoint should define the embeddable paths and their properties. The core of this file is the `embeds` object, where each key is a URL path (relative to the component's root) and the value is an object describing the resource, following the oEmbed specification.

Here is an example of what a component's `openembed.json` file might look like:

**component/openembed.json**

```json
{
  "info": {
    "version": "1.2.0"
  },
  "embeds": {
    "/posts/{post-id}": {
      "get": {
        "summary": "Embed a single blog post",
        "description": "Provides an oEmbed-compatible response for a single blog post, allowing it to be embedded in external sites.",
        "parameters": [
          {
            "name": "post-id",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the post to embed.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "oEmbed Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string", "example": "rich" },
                    "version": { "type": "string", "example": "1.0" },
                    "title": { "type": "string" },
                    "author_name": { "type": "string" },
                    "provider_name": { "type": "string" },
                    "html": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Service API Endpoints

The Blocklet Service exposes the following public endpoints for consumers to discover embeddable content.

### Get Aggregated OpenEmbed Data

- <strong>Endpoint (JSON)</strong>: `/.well-known/openembed.json`
- <strong>Endpoint (YAML)</strong>: `/.well-known/openembed.yaml`
- <strong>Method</strong>: `GET`
- <strong>Description</strong>: Retrieves the aggregated OpenEmbed metadata for all running and compatible components within the blocklet.
- <strong>Query Parameters</strong>:
-
  - `did` (optional): If provided, the service will only return the OpenEmbed data for the component with the matching DID.

## Data Structures

The final output from the service endpoint is a merged and enriched version of the data provided by the individual components.

### Top-Level Object

- **openembed** `string` *(required)* — The version of the OpenEmbed specification being used. Example: '0.1.0'.
- **info** `object` *(required)* — Contains metadata about the root blocklet application.
  - **title** `string` — The title of the blocklet application.
  - **description** `string` — A short description of the blocklet application.
  - **contact** `object` — Contact information for the blocklet owner.
    - **email** `string` — The owner's email address.
    - **name** `string` — The owner's full name.
    - **url** `string` — A URL pointing to the owner's user profile.
  - **version** `string` — The version of the root blocklet.
- **tags** `array` *(required)* — An array of tag objects, used to group related embeds. Tags are derived from component metadata.
  - **name** `string` — The name of the tag (typically the component title).
  - **description** `string` — A description for the tag (typically the component description).
- **embeds** `object` *(required)* — An object containing all discoverable embed endpoints from all components.

### Embed Item Object

Each key within the main `embeds` object is a full URL path (e.g., `/my-component/posts/{post-id}`), and its value is an object with the following structure.

- **tags** `array` — An array of strings that associate this embed with one or more tags. Example: ['My Component'].
- **x-meta** `object` — An object containing metadata added by the Blocklet Service for internal tracking and identification.
  - **id** `string` — A unique, deterministically generated address for this specific embeddable path.
  - **did** `string` — The DID of the component that provides this embed.
  - **path** `string` — The original path as defined within the component (without the mount point prefix).
  - **version** `string` — The version of the component.
  - **prefix** `string` — The mount point of the component.

---

## EventBus Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-eventbus-4f480d/

The EventBus Service is a messaging system that facilitates communication between different blocklets and the core system. It employs a publish-subscribe pattern, allowing components to broadcast and receive events without being directly coupled. This enables a modular architecture where blocklets can react to changes and actions occurring elsewhere in the system.

For instance, a `shopping` blocklet could publish an `order.created` event. An `inventory` blocklet could subscribe to this event to update stock levels, while a `notification` blocklet could subscribe to it to send an order confirmation email to the user.

## Architecture Overview

The service operates around a central message bus. Blocklets can assume the role of a publisher, a subscriber, or both.

::::steps
:::step{title="Publisher"}
A blocklet that emits an event to the EventBus.
:::

:::step{title="Subscriber"}
A blocklet that listens for specific events on the EventBus.
:::

:::step{title="EventBus"}
The intermediary that receives events from publishers and forwards them to all relevant subscribers.
:::
::::

A blocklet cannot subscribe to its own events, which is a built-in mechanism to prevent infinite loops.

The following diagram illustrates the overall architecture and flow of events:

![EventBus Service](https://media.arcblock.io/lib/95/95da448a646da88b.w1600.webp)

## Defining Events

To publish an event, it must first be declared in the blocklet's `blocklet.yml` configuration file. This declaration acts as a formal part of the blocklet's interface.

```yaml
events:
  - type: kitchen.full
    description: dummy event from kitchen sink blocklet
  - type: kitchen.empty
    description: dummy event from kitchen sink blocklet
```

### Naming Conventions

- <strong>Format</strong>: It is recommended to follow a `noun.verb` pattern, such as `post.published` or `user.loggedIn`.
- <strong>Uniqueness</strong>: The `type` of each event must be unique within a single blocklet.
- <strong>Reserved Namespace</strong>: Event types cannot begin with `blocklet.`, as this prefix is reserved for system events.
- <strong>Description</strong>: A clear and informative `description` for each event is mandatory.

## Publishing Events

Events are published using the `EventBus.publish` method provided by the Blocklet SDK. The event must be one of the types defined in the blocklet's `blocklet.yml`.

**Publishing an event**

```javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.publish('kitchen.full', {
  id: '123', // optional, default is a random uuid
  time: new Date().toISOString(), // optional, default is current time
  data: { object: { message: 'Hello, world!' } },
})
  .then(() => {
    console.log('Event published');
  })
  .catch((err) => {
    console.error('Failed to publish event', err);
  });
```

The second argument to the `publish` function is an object containing the event payload. This payload can include an `id`, a `time`, and a `data` field for any relevant information.

## Subscribing to Events

To receive events, a blocklet can use the `EventBus.subscribe` method. This method registers a callback function that is executed for each incoming event.

**Subscribing to events**

```javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.subscribe((event) => {
  console.log('received event from eventbus', event);
});
```

The subscriber will receive events from all other blocklets and the core system but will be automatically filtered from receiving its own published events.

## Discovering Events

A list of all available events within the system can be discovered by querying a well-known endpoint. This endpoint returns a JSON object that details all registered events from both the core system and all installed blocklets. This discovery mechanism is crucial for enabling interoperability between blocklets.

You can retrieve the list of events by making a GET request to `/.well-known/service/openevent.json` on your blocklet's domain.

**Discovering available events**

```shell
❯ curl -s https://<your-blocklet-url>/.well-known/service/openevent.json | jq
```

### Example Response

The JSON response includes a list of `sources` (the blocklets or system components that publish events) and a list of `events`.

**Example openevent.json response**

```json
{
  "openevent": "1.0.0",
  "info": {
    "description": "I can change this after elevated, great! haha"
  },
  "sources": [
    {
      "did": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs",
      "description": "I can change this after elevated, great! haha",
      "version": "1.0.0",
      "logo": "https://bbqartjsky2iiebu2noxsg6gn7nf7ezacguwmx6q6ci.did.abtnet.io/.well-known/service/blocklet/logo"
    }
  ],
  "events": [
    {
      "type": "blocklet.user.added",
      "description": "When a new user has onboarded, will receive the user info object",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "kitchen.full",
      "description": "dummy event from kitchen sink blocklet",
      "source": "z8ia22AX1PovjTi1YQw8ChgsbeVExYsX4dPFt"
    }
  ]
}
```

## System Events

The Blocklet Service core publishes a set of standard events related to the user lifecycle. Blocklets can subscribe to these to trigger workflows based on user activity.

| Event Type  | Description  |
|---|---|
| `blocklet.user.added`  | Triggered when a new user is onboarded. The event payload contains the user's information object.  |
| `blocklet.user.updated`  | Triggered when a user's session is updated, such as during login. The payload contains the user's information.  |
| `blocklet.user.removed`  | Triggered when a user is removed from the system. The payload contains the user's DID.  |
| `blocklet.user.profile.updated`  | Triggered when a user updates their profile information (e.g., name, avatar).  |
| `blocklet.user.permission.updated`  | Triggered when a user's permissions or roles are modified.  |

## Summary

The EventBus Service is a fundamental component for building decoupled, event-driven applications with Blocklets. By defining, publishing, and subscribing to events, developers can create complex workflows and interactions between different parts of the system in a scalable and maintainable way. For further details on other services, please see the related documents.

::::card-group
::link-card{title="Authentication Service" description="Learn how to integrate user authentication and manage user sessions." icon="key" href="/en/docs/blocklet-service/developer-guide-authentication-4f480d/"}
::link-card{title="Notification Service" description="Discover how to send multi-channel notifications to your users." icon="bell" href="/en/docs/blocklet-service/developer-guide-notification-4f480d/"}
::::

---

## Image Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-image-4f480d/

The Image Service provides robust, on-the-fly image processing capabilities through a simple URL-based API. Developers can perform various manipulations such as resizing, cropping, format conversion, and applying filters by adding query parameters to an image URL. This service is designed to optimize image delivery and enhance performance by generating and caching different image variations dynamically.

## How It Works

The service intercepts requests for images that include specific `imageFilter` query parameters. When such a request is received, the service follows a clear, efficient workflow. The following diagram illustrates this process:

![Image Service](https://media.arcblock.io/lib/bb/bb288f25ae92783b.w1600.webp)

::::steps
:::step{title="Request & Cache Check"}
The service first checks if a processed version of the requested image with the same parameters already exists in its cache.
:::

:::step{title="Cache Hit"}
If a cached version is found, it is served directly to the user, ensuring a fast response.
:::

:::step{title="Cache Miss"}
If the image is not in the cache, the service fetches the original, source image from its upstream location.
:::

:::step{title="Image Processing"}
The source image is then processed in real-time based on the query parameters provided in the URL (e.g., resizing, applying a filter).
:::

:::step{title="Caching & Delivery"}
The newly generated image is saved to the cache for future requests and then delivered to the user.
:::
::::

This process ensures that image manipulations are performed only once for a given set of parameters, minimizing server load and speeding up subsequent deliveries.

## Usage

To use the Image Service, append query parameters to the URL of the image you wish to modify. The primary parameter is `imageFilter`, which specifies the main operation to be performed.

The basic structure of a request is as follows:

```text
https://<your-blocklet-url>/path/to/image.jpg?imageFilter=<operation>&<...other_parameters>
```

## Operations

The service supports three main operations, determined by the `imageFilter` parameter.

### Resize

The `resize` operation changes the dimensions of an image. You must provide at least a width (`w`) or a height (`h`).

<strong>Example:</strong> Resize an image to a width of 300 pixels.

```text
?imageFilter=resize&w=300
```

### Crop

The `crop` operation extracts a specific region of an image. You must provide both a width (`w`) and a height (`h`). You can also specify the top (`t`) and left (`l`) coordinates for the crop area.

<strong>Example:</strong> Crop a 100x100 area from the top-left corner.

```text
?imageFilter=crop&w=100&h=100&t=0&l=0
```

### Convert

The `convert` operation changes the image format. You must specify the target format (`f`).

<strong>Example:</strong> Convert an image to the WebP format.

```text
?imageFilter=convert&f=webp
```

## Parameters

The following table details all available query parameters for image manipulation. These can be combined to create complex transformations.

| Parameter  | Name  | Description  | Values  | Default  |
|---|---|---|---|---|
| `imageFilter`  | <strong>Operation</strong>  | The main processing operation to perform.  | `resize`, `crop`, `convert`  | (Required)  |
| `w`  | <strong>Width</strong>  | The target width in pixels. Required for `crop`.  | Integer (1-2048)  | -  |
| `h`  | <strong>Height</strong>  | The target height in pixels. Required for `crop`.  | Integer (1-2048)  | -  |
| `q`  | <strong>Quality</strong>  | The compression quality for the output image.  | Integer (10-100)  | Varies by format (e.g., 80 for WebP)  |
| `f`  | <strong>Format</strong>  | The target image format. Required for `convert`.  | `png`, `jpeg`, `webp`, `gif`, `avif`, `heif`  | Original format  |
| `m`  | <strong>Mode</strong>  | The resizing mode (fit).  | `cover`, `contain`, `fill`, `inside`, `outside`  | `inside`  |
| `t`  | <strong>Top</strong>  | The top offset in pixels for cropping.  | Integer (0-2048)  | `0`  |
| `l`  | <strong>Left</strong>  | The left offset in pixels for cropping.  | Integer (0-2048)  | `0`  |
| `r`  | <strong>Rotate</strong>  | Rotates the image by a specified angle.  | `90`, `180`, `270`  | -  |
| `g`  | <strong>Greyscale</strong>  | Converts the image to greyscale.  | `0` (off), `1` (on)  | `0`  |
| `b`  | <strong>Blur</strong>  | Applies a Gaussian blur effect.  | Integer (1-2000)  | -  |
| `s`  | <strong>Sharpen</strong>  | Applies a sharpening effect.  | Integer (0-2000)  | -  |
| `n`  | <strong>Negative</strong>  | Applies a negative (invert) effect.  | `0` (off), `1` (on)  | `0`  |
| `p`  | <strong>Progressive</strong>  | Enables progressive rendering for formats like JPEG.  | `0` (off), `1` (on)  | `1`  |
| `a`  | <strong>Alpha</strong>  | Toggles the alpha (transparency) channel.  | `0` (remove), `1` (ensure)  | `1`  |
| `e`  | <strong>Error</strong>  | If an error occurs, returns a text message instead of a default error image.  | `0` (off), `1` (on)  | `0`  |

### Combined Example

You can combine multiple parameters in a single request. For instance, to resize an image to 200x200, convert it to WebP format with 75% quality, and apply a greyscale filter, you would use the following query string:

```text
?imageFilter=resize&w=200&h=200&f=webp&q=75&g=1
```

This provides a powerful way to generate complex image variations without needing to store each version manually.

---

## KYC Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-kyc-4f480d/

The Know Your Customer (KYC) Service provides a standardized way to verify user identity attributes within your application. This service enables developers to implement verification flows for credentials such as email addresses, ensuring that users are who they claim to be. Integrating this service enhances security and trust for your application.

This guide details the API endpoints and the process for integrating email verification. For administrative configurations, such as enabling KYC requirements or managing domain restrictions, please refer to the [DID Connect Settings](/en/docs/blocklet-service/user-guide-did-connect-settings-4f480d/) documentation.

## Email Verification Flow

The email verification process is designed as a two-step flow. First, the user requests a verification code to be sent to their email address. Second, the user submits this code back to the service to confirm ownership of the email account. Upon successful verification, the service can issue a verifiable credential to the user's DID.

![KYC Service](https://media.arcblock.io/lib/3c/3c97f818b0c41283.w1600.webp)

## API Endpoints

The KYC service exposes a set of RESTful API endpoints for managing the verification process.

### Request Verification Code

This endpoint initiates the email verification process by sending a unique code to the user's specified email address. The system enforces rate limiting based on both IP address and the target email to prevent abuse.

<strong>Endpoint</strong>

```
POST /.well-known/service/api/kyc/email/send
```

<strong>Parameters</strong>

- **email** `string` *(required)* — The user's email address to be verified. It must be a valid email format.

<strong>Example Request</strong>

**Request to send verification code**

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}' \
  'https://your-blocklet-url/.well-known/service/api/kyc/email/send'
```

<strong>Example Response (Success)</strong>

**Success Response**

```json
{
  "message": "Verify code successfully sent"
}
```

<strong>Error Responses</strong>

The endpoint will return a 400 status code with a corresponding error message under various conditions:

| Error Code  | Description  |
|---|---|
| `email_invalid`  | The provided email address format is not valid.  |
| `email_already_verified`  | The email address has already been verified for the current user.  |
| `email_not_allowed`  | The email domain is not in the configured whitelist.  |
| `email_blocked`  | The email domain is in the configured blacklist.  |
| `email_already_sent`  | A verification code has recently been sent to this email. The user should check their inbox and wait before requesting another.  |

### Submit Verification Code

This endpoint consumes the verification code sent to the user's email to finalize the verification process.

<strong>Endpoint</strong>

```
POST /.well-known/service/api/kyc/email/verify
```

<strong>Parameters</strong>

- **code** `string` *(required)* — The verification code received by the user via email.

<strong>Example Request</strong>

**Request to verify code**

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}' \
  'https://your-blocklet-url/.well-known/service/api/kyc/email/verify'
```

<strong>Example Response (Success)</strong>

**Success Response**

```json
{
  "message": "Email is successfully verified"
}
```

If the provided code is incorrect or expired, the API will return a 400 Bad Request error with a descriptive message.

### Check KYC Status

This endpoint allows you to check if a specific user has already completed KYC verification for a given subject (e.g., an email address). The request must be properly signed to authenticate the user's DID.

<strong>Endpoint</strong>

```
POST /.well-known/service/api/kyc/status
```

<strong>Parameters</strong>

- **subject** `string` *(required)* — The subject to check the verification status for, such as an email address.

<strong>Example Request</strong>

The request must include headers for signature verification, which are typically handled by a client-side library like `@blocklet/did-space-js`.

**Check KYC Status Request**

```bash
# This is a conceptual example. In practice, the signing process
# would be handled by an SDK.
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-did-wallet-type: ..." \
  -H "x-did-wallet-version: ..." \
  -H "x-did-action: ..." \
  -H "x-did-challenge: ..." \
  -H "x-did-signature: ..." \
  -d '{"subject": "user@example.com"}' \
  'https://your-blocklet-url/.well-known/service/api/kyc/status'
```

<strong>Example Response</strong>

**KYC Status Response**

```json
{
  "verified": true
}
```

If the user has not been verified, the `verified` field will be `false`. If an error occurs (e.g., user not found, invalid subject), an `error` field will be included in the response.

**KYC Status Not Verified**

```json
{
  "verified": false,
  "error": "User not found"
}
```

## Summary

The KYC Service provides a simple yet powerful mechanism for adding an essential layer of user identity verification to your application. By integrating these endpoints, you can build a more secure and trustworthy platform.

For more information on related topics, please see the following documentation:

- [Authentication Service](/en/docs/blocklet-service/developer-guide-authentication-4f480d/)
- [DID Connect Settings](/en/docs/blocklet-service/user-guide-did-connect-settings-4f480d/)

---

## MCP Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-mcp-4f480d/

The Model Context Protocol (MCP) Service provides a standardized way for blocklets and their components to expose AI-powered tools and capabilities. It acts as a central gateway, allowing AI agents and other clients to discover and interact with various AI functionalities provided by the installed blocklets in a unified manner.

This guide is for developers who want to build AI-powered features within their blocklets, making them available to MCP clients like Aistro. You will learn how to expose your component's capabilities as "tools," how to list available tools, and how to execute them through the Blocklet Service's MCP endpoints.

## Architecture Overview

The MCP Service aggregates tools from all installed components that support the protocol. When an external client, such as an AI Chat application, needs to perform a function, it communicates with the central Blocklet Service MCP endpoint. The service then authenticates the request and routes it to the appropriate component to execute the tool. This architecture simplifies client-side implementation, as the client only needs to know about a single endpoint to access a wide range of tools.

The following diagram illustrates this architecture:

![MCP Service](https://media.arcblock.io/lib/1b/1b5372ac9b4d4b60.w1600.webp)

## How It Works

::::steps
:::step{title="Discovery"}
An MCP client can query the Blocklet Service to get a list of all available tools from all installed components.
:::

:::step{title="Routing"}
When a client calls a specific tool, it sends the request to the Blocklet Service, specifying the `componentDid` of the blocklet that provides the tool and the `name` of the tool.
:::

:::step{title="Execution"}
The Blocklet Service validates the request and proxies it to the correct component's MCP server.
:::

:::step{title="Response"}
The component executes the tool's logic and returns the result, which is then relayed back to the client through the Blocklet Service.
:::
::::

## Exposing Tools from Your Blocklet

To make your blocklet's tools discoverable by the MCP Service, you must first declare that your component supports the protocol.

### 1. Enable MCP Capability

In your blocklet's `blocklet.yml` metadata file, add the `mcp: true` capability:

```yaml
name: my-ai-blocklet
version: 1.0.0
capabilities:
  mcp: true
# ... other metadata
```

This flag signals to the Blocklet Service that your component has an MCP server and its tools should be included in the aggregated list.

### 2. Implement an MCP Server

Your blocklet component must run its own MCP server and expose an endpoint at the path `/mcp`. You can use the `@modelcontextprotocol/sdk` to create a server and define your tools.

A tool is essentially a function with a defined input schema and a description of what it does. The MCP server handles the protocol-level communication, allowing you to focus on the tool's implementation.

## Using the MCP Service API

All MCP Service endpoints require user authentication. The client must be logged into the Blocklet Service to make successful requests.

### List Available Tools

To discover all tools provided by the installed components, send a `GET` request to the `/mcp/tools` endpoint.

<strong>Endpoint</strong>

`GET /.well-known/service/mcp/tools`

<strong>Example Request</strong>

Here is an example of how to fetch the list of available tools using JavaScript's `fetch` API.

**Fetching Tools**

```javascript
async function listAllTools() {
  try {
    const response = await fetch('/.well-known/service/mcp/tools', {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const tools = await response.json();
    console.log('Available Tools:', tools);
    return tools;
  } catch (error) {
    console.error('Failed to fetch tools:', error);
  }
}

listAllTools();
```

<strong>Example Response</strong>

The endpoint returns a JSON array of tool objects. Each object describes a tool's name, purpose, input schema, and the component that provides it.

**Example Tool List Response**

```json
[
  {
    "name": "sendNotification",
    "description": "Sends a notification to a user's wallet.",
    "arguments": {
      "type": "object",
      "properties": {
        "userDid": {
          "type": "string",
          "description": "The DID of the user to notify."
        },
        "message": {
          "type": "string",
          "description": "The content of the notification."
        }
      },
      "required": ["userDid", "message"]
    },
    "appPid": "z2qa...",
    "componentDid": "z8iZ..."
  },
  {
    "name": "createImage",
    "description": "Generates an image based on a text prompt.",
    "arguments": {
      "type": "object",
      "properties": {
        "prompt": {
          "type": "string",
          "description": "A text description of the desired image."
        }
      },
      "required": ["prompt"]
    },
    "appPid": "z2qa...",
    "componentDid": "z8iK..."
  }
]
```

### Call a Tool

To execute a specific tool, send a `POST` request to the `/mcp/tools` endpoint with the tool's details in the request body.

<strong>Endpoint</strong>

`POST /.well-known/service/mcp/tools`

<strong>Request Body</strong>

The request body must be a JSON object containing the name of the tool, the DID of the component providing it, and the input arguments.

- **name** `string` *(required)* — The name of the tool to be executed.
- **componentDid** `string` *(required)* — The DID of the component that exposes the tool.
- **input** `any` *(required)* — The arguments for the tool, matching the schema defined by the tool.

<strong>Example Request</strong>

This example demonstrates how to call the `sendNotification` tool.

**Calling a Tool**

```javascript
async function callMcpTool() {
  const toolPayload = {
    name: 'sendNotification',
    componentDid: 'z8iZ...', // Replace with the actual component DID
    input: {
      userDid: 'z1...', // Replace with the recipient's DID
      message: 'Hello from MCP Service!'
    }
  };

  try {
    const response = await fetch('/.well-known/service/mcp/tools', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(toolPayload),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    console.log('Tool execution result:', result);
    return result;
  } catch (error) {
    console.error('Failed to call tool:', error);
  }
}

callMcpTool();
```

<strong>Example Response</strong>

The response will contain the output from the tool execution. The structure of the response depends on the tool's implementation.

**Example Tool Call Response**

```json
{
  "status": "success",
  "notificationId": "nt_12345"
}
```

## Security and Permissions

When you implement an MCP tool, you can define an access policy to control who can execute it. The permission check is handled by the Blocklet Service, ensuring that only authorized users can access your tools.

The access policy can include `allow` and `deny` rules based on the user's DID, role (e.g., `owner`, `admin`, `member`), or authentication provider.

### Access Policy Structure

- **allow** `object` — Rules to permit access. If `allow` is defined, a user must match at least one rule to be granted access.
  - **dids** `string[]` — A list of user DIDs that are allowed.
  - **roles** `string[]` — A list of roles that are allowed (e.g., 'owner', 'admin').
  - **providers** `string[]` — A list of authentication providers that are allowed.
- **deny** `object` — Rules to deny access. If a user matches any `deny` rule, access is denied, even if they match an `allow` rule.
  - **dids** `string[]` — A list of user DIDs that are denied.
  - **roles** `string[]` — A list of roles that are denied.
  - **providers** `string[]` — A list of authentication providers that are denied.

### Example: Role-Based Access

For example, to restrict a tool to only be callable by blocklet owners and administrators, you would define the following policy:

**Access Policy Example**

```javascript
const policy = {
  allow: {
    roles: ['owner', 'admin'],
  },
};
```

This policy ensures that any attempt to call the tool by users with other roles (or unauthenticated users) will be rejected with an "Unauthorized" error.

## Summary

The MCP Service provides a powerful framework for extending your blocklet's functionality with AI-driven tools. By exposing your features through the Model Context Protocol, you enable seamless integration with AI agents and other applications, creating a more intelligent and interconnected ecosystem. Remember to secure your tools with appropriate access policies to ensure they are used safely and correctly.

For more information on user authentication, please refer to the [Authentication Service](/en/docs/blocklet-service/developer-guide-authentication-4f480d/) documentation.

---

## Notification Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-notification-4f480d/

The Blocklet Service provides a robust, multi-channel Notification Service designed to streamline communication with your users. Instead of building and maintaining separate integrations for different delivery methods, you can use a single, unified API to send notifications through various channels, including DID Wallet messages, emails, and push notifications via PushKit.

This service is built for reliability, using a queuing system to process notifications asynchronously. This ensures that delivery attempts are retried in case of transient failures and that the system remains responsive under load.

## Overview

The notification process is initiated when your blocklet makes a secure API call to the Notification Service. The service then validates the request and queues a job to deliver the message to the specified users across the selected channels. The following diagram illustrates the high-level architecture:

![Notification Service](https://media.arcblock.io/lib/0a/0a0591ea58afef51.w1600.webp)

## API Usage

### Send Notification

This is the primary endpoint for sending a notification to one or more users. It accepts a detailed payload specifying the sender, receivers, content, and desired delivery channels.

#### Endpoint

`POST /.well-known/service/api/send-to-user`

#### Parameters

The request body is a JSON object that includes sender information, a list of recipients, the notification payload, and sending options.

- **sender** `object` *(required)* — Information about the application sending the notification. This is typically populated automatically when using the helper function.
  - **appDid** `string` *(required)* — The DID of the blocklet sending the notification.
  - **appSk** `string` *(required)* — The secret key of the blocklet for signing the request.
- **receiver** `string | string[]` *(required)* — The DID of the user or an array of user DIDs to receive the notification.
- **notification** `object` *(required)* — The content of the notification. The structure should conform to the notification schema.
  - **type** `string` (default: `notification`) — The type of the notification. Common values include 'notification', 'passthrough', 'hi', 'connect'.
  - **title** `string` *(required)* — The title of the notification.
  - **body** `string` *(required)* — The main content or message body of the notification.
  - **actions** `array` — An array of action objects that can be presented to the user.
  - **attachments** `array` — An array of attachment objects.
- **options** `object` — Additional options to control the delivery.
  - **channels** `string[]` (default: `["app", "email", "webhook", "push"]`) — An array of channels to send the notification through. Possible values are app (DID Wallet), email, webhook, and push (PushKit).
  - **keepForOfflineUser** `boolean` (default: `true`) — If true, messages for offline users will be stored and delivered upon their next connection.

#### Code Example

The most straightforward way to send a notification is by using the `sendToUser` helper function from within your blocklet's backend code. This function handles the necessary authentication and API call structure.

**Send a notification to a user**

```javascript
const Notification = require('@blocklet/sdk/lib/util/send-notification');

async function sendWelcomeNotification(userDid) {
  const { wallet } = await req.getBlockletInfo();

  const notification = {
    title: 'Welcome!',
    body: 'Thank you for joining our application.',
    actions: [
      {
        type: 'link',
        name: 'Get Started',
        url: 'https://example.com/getting-started',
      },
    ],
  };

  try {
    const result = await Notification.sendToUser(
      userDid,
      notification,
      {
        appDid: wallet.address,
        appSk: wallet.secretKey,
      },
      process.env.ABT_NODE_SERVICE_PORT
    );
    console.log('Notification queued successfully:', result);
  } catch (error) {
    console.error('Failed to send notification:', error.message);
  }
}
```

This example defines a simple welcome notification and sends it to a specified user DID. The `getBlockletInfo` method retrieves the necessary credentials to authenticate the request.

### Channel-Specific Behavior

- <strong>DID Wallet</strong>: If a user is online, the message is delivered instantly via WebSocket. If the user is offline, the message is cached and delivered the next time they connect, provided `keepForOfflineUser` is `true`.
- <strong>Email</strong>: The system uses predefined templates to render the notification content into an HTML email. This requires the Email Service to be properly configured by the administrator in the dashboard.
- <strong>Push Notifications</strong>: The service retrieves the user's device token from their session data and forwards the notification to a configured PushKit blocklet, which then handles the platform-specific delivery to APNs (iOS) or FCM (Android).
- <strong>WebHooks</strong>: The service sends the notification payload to all webhook URLs configured by the user in their profile settings.

### Responses

- <strong>200 OK</strong>: The notification has been successfully queued for delivery. The response body contains the created notification object(s) with their unique IDs.
- <strong>400 Bad Request</strong>: The request is malformed. This could be due to an invalid sender token, a notification object that fails validation, or an invalid receiver DID. The response body will contain a descriptive error message.

#### Example Response (Success)

**Example Success Response**

```json
[
  {
    "id": "z8iZp8d7a9E5fG3bC1hJ2kL4mN6oP8qR0tV",
    "receiver": "z1...",
    "componentDid": "z2...",
    "teamDid": "z3...",
    "type": "notification",
    "status": "pending",
    "title": "Welcome!",
    "body": "Thank you for joining our application.",
    "createdAt": "2023-10-27T10:00:00.000Z",
    "updatedAt": "2023-10-27T10:00:00.000Z"
  }
]
```

## Summary

The Notification Service provides a powerful and flexible way to engage with your users. By leveraging its multi-channel capabilities, you can ensure that your messages reach users on their preferred platform, enhancing the overall user experience of your application. For administrative tasks such as viewing notification history and configuring channels, please see the [Notifications User Guide](/en/docs/blocklet-service/user-guide-operations-notifications-4f480d/).

---

## OAuth Service

URL: https://www.arcblock.io/en/docs/blocklet-service/developer-guide-oauth-4f480d/

The OAuth Service enables developers to integrate third-party authentication providers and to expose a standard OAuth 2.0 interface for their own applications. This service facilitates federated login, allowing users to sign in with accounts from providers like Google, GitHub, Apple, and Twitter, and also allows your Blocklet Service to function as a centralized authentication authority for other applications.

This guide is intended for developers and covers the technical details of configuring and using the OAuth Service APIs. For administrative configuration through the UI, please refer to the [OAuth Apps](/en/docs/blocklet-service/user-guide-did-connect-oauth-apps-4f480d/) section in the User Guide.

## Overview

The OAuth Service has a dual role:

::::steps
:::step{title="OAuth Client"}
It acts as a client to external OAuth providers. When a user chooses to log in with a third-party service, the Blocklet Service handles the redirects, token exchanges, and profile retrieval required to authenticate the user.
:::

:::step{title="OAuth Server"}
It functions as a fully-featured OAuth 2.0 and OpenID Connect (OIDC) provider. This allows external or third-party applications to delegate authentication to your service, providing a secure method for them to access user data with proper consent.
:::
::::

### Authentication Flow (Authorization Code Grant)

The service primarily uses the OAuth 2.0 Authorization Code Grant flow, which is a secure and widely adopted standard for web applications. The process involves the user, the client application (your blocklet or a third-party app), the authorization server (this OAuth Service), and the resource server.

The following diagram illustrates the sequence of interactions in this flow:

![OAuth Service](https://media.arcblock.io/lib/06/060c81ad2bd9bea7.w1600.webp)

## Integrating Third-Party Providers (Client)

You can enable users to log in to your application using their existing accounts from various providers.

### Configuration

Configuration for each provider is managed within the blocklet's settings. You will need to obtain credentials (e.g., Client ID and Client Secret) from the developer console of each provider you wish to integrate.

The following providers are supported:

::::card-group
::link-card{title="Google" description="Uses OpenID Connect for authentication. Requires a Client ID and Client Secret from the Google Cloud Console." icon="globe"}
::link-card{title="GitHub" description="Uses OAuth 2.0. Requires a Client ID and Client Secret from your GitHub Developer settings." icon="github"}
::link-card{title="Apple" description="Uses Sign in with Apple. Requires a Service ID, Team ID, Key ID, and private key." icon="globe"}
::link-card{title="Twitter (X)" description="Uses OAuth 2.0. Requires a Client ID and Client Secret from the X Developer Portal." icon="twitter"}
::::

### Client-Side API Flow

The client-side flow for initiating a third-party login and handling the callback is as follows:

::::steps
:::step{title="Initiate Login"}
Redirect the user to the login endpoint for the desired provider.
:::

:::step{title="Handle Callback"}
After the user authenticates with the third-party provider, they are redirected back to your application. The callback URL will contain an authorization `code`.
:::

:::step{title="Finalize Login"}
Your application sends this `code` to the backend API to exchange it for a session token.
:::
::::

#### GET /.well-known/service/oauth/login/:provider

Redirects the user to the selected provider's authentication page. The `referrer` header is required and must match a trusted domain configured in the service.

<strong>Parameters</strong>

- **provider** `string` *(required)* — The name of the OAuth provider (e.g., `google`, `github`).

#### POST /.well-known/service/api/oauth/login

After the user is redirected back from the provider, use this endpoint to exchange the authorization code for a session token.

<strong>Parameters</strong>

- **provider** `string` *(required)* — The name of the OAuth provider.
- **code** `string` *(required)* — The authorization code received from the provider's callback.

<strong>Returns</strong>

- **sessionToken** `string` — A JWT session token for the authenticated user.
- **refreshToken** `string` — A token that can be used to obtain a new session token.
- **visitorId** `string` — A unique identifier for the user's device/browser.

### User Profile Data

When a user authenticates, the service retrieves their profile from the provider. The structure of this profile is normalized but may contain provider-specific data in an `extraData` field.

#### Standard Profile Structure

- **sub** `string` *(required)* — A unique subject identifier for the user, prefixed with the provider name (e.g., `google-oauth2|...
- **name** `string` *(required)* — The user's full name.
- **email** `string` *(required)* — The user's primary email address.
- **picture** `string` — URL of the user's profile picture.
- **emailVerified** `boolean` — Indicates if the user's email has been verified by the provider.
- **extraData** `object` — Contains additional, provider-specific user data.

## Acting as an OAuth 2.0 Provider (Server)

The Blocklet Service can also function as a standard OAuth 2.0 and OIDC provider, allowing third-party applications to authenticate your users and access protected resources on their behalf.

### Standard Endpoints

The service exposes the following standard endpoints, all prefixed with `/.well-known/service/oauth`.

| Endpoint  | Path  | Description  |
|---|---|---|
| <strong>Authorization</strong>  | `/authorize`  | Starts the authorization process by redirecting the user for login and consent.  |
| <strong>Token</strong>  | `/token`  | Exchanges authorization codes or refresh tokens for access tokens.  |
| <strong>Client Registration</strong>  | `/register`  | Allows dynamic registration of new client applications.  |
| <strong>User Info</strong>  | `/userinfo`  | Retrieves profile information for the authenticated user using an access token.  |
| <strong>Token Revocation</strong>  | `/revoke`  | Invalidates an access or refresh token.  |
| <strong>JSON Web Key Set</strong>  | `/jwks.json`  | Provides the public keys used to verify JWT signatures.  |

### API Details

#### Authorization Endpoint

`GET /.well-known/service/oauth/authorize`

This endpoint initiates the login and consent flow.

<strong>Query Parameters</strong>

- **response_type** `string` *(required)* — Must be `code`.
- **client_id** `string` *(required)* — The client ID of the application.
- **redirect_uri** `string` *(required)* — The URL to redirect to after authorization.
- **scope** `string` *(required)* — A space-separated list of requested permissions (e.g., `profile:read`).
- **state** `string` — An opaque value used to maintain state between the request and callback.
- **code_challenge** `string` — The PKCE code challenge.
- **code_challenge_method** `string` — The PKCE challenge method, typically `S256`.

#### Token Endpoint

`POST /.well-known/service/oauth/token`

This endpoint is used to exchange an authorization code or refresh token for an access token.

<strong>Request Body (Authorization Code Grant)</strong>

- **grant_type** `string` *(required)* — Must be `authorization_code`.
- **code** `string` *(required)* — The authorization code received from the authorization endpoint.
- **redirect_uri** `string` *(required)* — The same redirect URI used in the authorization request.
- **client_id** `string` *(required)* — The client ID of the application.
- **code_verifier** `string` — The PKCE code verifier.

<strong>Request Body (Refresh Token Grant)</strong>

- **grant_type** `string` *(required)* — Must be `refresh_token`.
- **refresh_token** `string` *(required)* — The refresh token.
- **client_id** `string` *(required)* — The client ID of the application.

<strong>Successful Response</strong>

**Token Response**

```json
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "scope": "profile:read",
  "expires_in": 3600
}
```

#### UserInfo Endpoint

`GET /.well-known/service/oauth/userinfo`

Retrieves the authenticated user's profile information. Requires a valid `access_token` in the `Authorization` header.

<strong>Successful Response</strong>

**UserInfo Response**

```json
{
  "sub": "z2...",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "picture": "https://example.com/avatar.png",
  "preferred_username": "John Doe",
  "email_verified": true
}
```

## Summary

The OAuth Service is a powerful component for managing user authentication. By supporting both client integrations with major identity providers and acting as a standard OAuth 2.0 server, it provides a flexible and secure foundation for identity management in your applications.

For more information on the underlying protocols, please refer to the official documentation:

- [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-service/overview-4f480d/

Blocklet Service is a foundational layer that provides a suite of ready-to-use, reusable services for blocklets. It is designed to run within a Blocklet Server environment and acts as a central hub for common functionalities that applications often require. By offering these services out-of-the-box, it accelerates development, ensures consistency, and reduces the redundant work of building essential features from scratch.

This documentation is structured to guide two primary types of users: administrators who manage blocklets through a web interface, and developers who build applications on the platform. The following diagram illustrates the relationship between these users, the Blocklet Service, and the overall environment:

![Overview](https://media.arcblock.io/lib/6e/6ef9d745443893d1.w1600.webp)

## Core Functionalities

Blocklet Service provides a wide range of services that can be categorized as follows:

::::card-group
::link-card{title="Authentication Service" description="Manages user identity, login, and session management using Decentralized Identifiers (DID). It also supports third-party OAuth providers." icon="key" href="/en/docs/blocklet-service/developer-guide-authentication-4f480d/"}
::link-card{title="Notification Service" description="Enables sending multi-channel notifications to users, including wallet messages, emails, and push notifications." icon="bell" href="/en/docs/blocklet-service/developer-guide-notification-4f480d/"}
::link-card{title="Image Service" description="Provides on-the-fly image processing, such as resizing, cropping, and format conversion." icon="image" href="/en/docs/blocklet-service/developer-guide-image-4f480d/"}
::link-card{title="MCP Service" description="Allows blocklets to interact with the Model Context Protocol (MCP) server for integrating AI-powered features." icon="bot" href="/en/docs/blocklet-service/developer-guide-mcp-4f480d/"}
::link-card{title="EventBus Service" description="Facilitates communication between different blocklets and the core system through a publish-subscribe model." icon="routes" href="/en/docs/blocklet-service/developer-guide-eventbus-4f480d/"}
::link-card{title="KYC Service" description="Integrates Know Your Customer (KYC) processes for user identity verification." icon="shield-check" href="/en/docs/blocklet-service/developer-guide-kyc-4f480d/"}
::link-card{title="Discovery & SEO Services" description="Enhances discoverability through services like Open Graph, oEmbed, and automatic sitemap generation." icon="search" href="/en/docs/blocklet-service/developer-guide-discovery-seo-4f480d/"}
::link-card{title="OAuth Service" description="Integrates third-party authentication providers like Google and GitHub for federated login." icon="lock" href="/en/docs/blocklet-service/developer-guide-oauth-4f480d/"}
::::

## How This Documentation is Organized

To cater to different needs, this documentation is divided into two main parts, ensuring that both administrators and developers can find the information relevant to their tasks efficiently.

### For Administrators: User Guide

The [<strong>User Guide</strong>](/en/docs/blocklet-service/user-guide-4f480d/) is intended for non-technical users and system administrators. It provides clear, step-by-step instructions for configuring and managing the various features of Blocklet Service through the web dashboard. This guide focuses on practical application management, monitoring, and customization without requiring any knowledge of coding.

### For Developers: Developer Guide

The [<strong>Developer Guide</strong>](/en/docs/blocklet-service/developer-guide-4f480d/) is a comprehensive resource for software developers. It contains detailed technical information, API references, code snippets, and integration workflows necessary to programmatically utilize the reusable services provided by Blocklet Service in custom applications. This guide is designed to help developers build, extend, and integrate their blocklets with the platform's core functionalities.

---

## User Guide

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-4f480d/

This guide is for administrators and non-technical users, providing step-by-step instructions for configuring and managing the Blocklet Service through its web dashboard. It covers all major functional areas, from initial setup to advanced operations.

## Main Sections

The Blocklet Service dashboard is organized into several key sections, each dedicated to a specific area of management and configuration. The following diagram shows the main components of the dashboard. For detailed information, please refer to the corresponding sub-documents.

![User Guide](https://media.arcblock.io/lib/46/46e5dedb4aaf7bf1.w1600.webp)

::::card-group
::link-card{title="Dashboard" description="The central hub for managing your blocklets, monitoring system status, and accessing frequently used functions." icon="layout" href="/en/docs/blocklet-service/user-guide-dashboard-4f480d/"}
::link-card{title="DID Connect" description="A comprehensive user and identity management center for handling members, passports, and authentication settings." icon="users" href="/en/docs/blocklet-service/user-guide-did-connect-4f480d/"}
::link-card{title="AIGNE Hub" description="Manage AI capabilities and monitor account balances for all your blocklets through the AIGNE Hub integration." icon="brain" href="/en/docs/blocklet-service/user-guide-aigne-hub-4f480d/"}
::link-card{title="Website" description="Manage your website's presentation, branding, and navigation to customize its appearance and user experience." icon="layout" href="/en/docs/blocklet-service/user-guide-website-4f480d/"}
::link-card{title="Operations" description="Access aggregated operational functions for production management, including notifications, audit logs, and analytics." icon="server" href="/en/docs/blocklet-service/user-guide-operations-4f480d/"}
::link-card{title="Integrations" description="Manage integrations with external systems and control programmatic API access." icon="zap" href="/en/docs/blocklet-service/user-guide-integrations-4f480d/"}
::link-card{title="Developer Tools" description="Access developer-focused tools for logging, performance monitoring, and viewing embedded documentation." icon="code" href="/en/docs/blocklet-service/user-guide-developer-tools-4f480d/"}
::link-card{title="DID Spaces" description="Manage decentralized storage, backups, and file management using DID Spaces integration." icon="database" href="/en/docs/blocklet-service/user-guide-did-spaces-4f480d/"}
::link-card{title="Blocklet Studio" description="Use the no-code platform to create, manage, and publish new blocklets from templates." icon="box" href="/en/docs/blocklet-service/user-guide-blocklet-studio-4f480d/"}
::::

## Summary

This user guide provides a comprehensive overview of the Blocklet Service dashboard's functionalities. Each section is designed to give you control over different aspects of your application, from user management to website branding and operational monitoring.

For developers looking to integrate with Blocklet Service programmatically, please refer to the [Developer Guide](/en/docs/blocklet-service/developer-guide-4f480d/).

---

## AIGNE Hub

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-aigne-hub-4f480d/

The AIGNE Hub acts as a centralized control panel for integrating and managing AI capabilities across all your blocklets. It simplifies the administration of AI services by providing a single point for monitoring usage, managing accounts, and controlling access to large language models (LLMs). By connecting your blocklets to the AIGNE Hub, you can seamlessly infuse them with advanced AI-powered features.

This guide provides an overview of the AIGNE Hub's features and how to configure them.

![AIGNE Hub](https://media.arcblock.io/lib/e0/e0dcb0edd1329bda.w1600.webp)

## Key Features

The AIGNE Hub integration offers several key functionalities for administrators:

- <strong>Centralized Account Management</strong>: Connect to a single AIGNE Hub account to manage AI services for all associated blocklets. You can easily view the connected account's DID and switch between users if necessary.
- <strong>Credit Monitoring</strong>: Keep track of your AI service consumption by monitoring your AIGNE Hub Credits directly from the dashboard. This allows for effective budget management and ensures uninterrupted service.
- <strong>Unified Service Access</strong>: Provides a streamlined way for all your blocklets to access powerful AI models without requiring individual configurations for each one.

## Configuration and Management

The AIGNE Hub interface provides a straightforward way to manage your AI service integration.

![AIGNE Hub Interface](https://media.arcblock.io/lib/73/732e9d036588e838.w1600.webp)

### Account Information

Once connected, the dashboard displays the AIGNE Hub URL and the DID of the currently linked account.

- <strong>Switch User</strong>: This function allows you to change the AIGNE Hub account that is connected to your Blocklet Service instance, providing flexibility for different administrative needs.

### Balance and Transactions

This section provides a clear view of your available AIGNE Hub Credits, which are consumed when your blocklets utilize AI services.

- <strong>AIGNE Hub Credits</strong>: Displays the current balance of credits.
- <strong>Buy Credits</strong>: A direct link to purchase additional credits to replenish your account.
- <strong>Transactions</strong>: Navigates to a detailed history of your credit usage and purchases, allowing for precise tracking of expenditures.

## Summary

The AIGNE Hub integration simplifies the management of AI capabilities for your blocklets. By providing a central point for account management and credit monitoring, it enables administrators to efficiently deploy and maintain AI-powered features across their applications.

---

## Blocklet Studio

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-blocklet-studio-4f480d/

Blocklet Studio is a no-code platform designed for administrators to create, manage, and publish new blocklets using pre-built templates. It streamlines the development cycle, enabling the creation of applications without requiring direct code manipulation.

## Key Features

Blocklet Studio provides a comprehensive set of tools to facilitate a no-code development experience.

- <strong>Template-Based Creation</strong>: Initiate new projects by selecting from a library of available blocklet templates, providing a functional baseline for further customization.
- <strong>Visual Builder</strong>: Utilize a graphical user interface to assemble and configure blocklet components, manage settings, and define application behavior.
- <strong>Simplified Publishing</strong>: Follow a structured workflow to publish completed blocklets, making them available for deployment or distribution via the Blocklet Store.
- <strong>Lifecycle Management</strong>: Access a centralized dashboard to oversee all created blocklets, including viewing detailed information, editing configurations, and performing administrative actions.

## Development Workflow

The process of creating and deploying a blocklet using the Studio follows a clear, sequential path from conception to publication. The diagram below illustrates the key stages involved.

![Blocklet Studio](https://media.arcblock.io/lib/d1/d17772f0af8f2fa9.w1600.webp)

## Interface Overview

The Blocklet Studio dashboard serves as the central hub for managing all your blocklet projects. It presents a comprehensive list of blocklets, providing key details and management actions in a clear, tabular format.

![Blocklet Studio Dashboard](https://media.arcblock.io/lib/47/471564f3068bfff3.w1600.webp)

The main components of the interface are:

- <strong>New Blocklet Button</strong>: Located in the top-right corner, this button initiates the creation workflow for a new blocklet.
- <strong>Blocklet List</strong>: The central area of the dashboard displays a table of all existing blocklets. Each row contains the following information:
-
  - <strong>Name</strong>: The user-defined name of the blocklet.
  - <strong>Version</strong>: The current version number of the blocklet.
  - <strong>DID</strong>: The unique Decentralized Identifier (DID) for the blocklet.
  - <strong>Last Updated</strong>: A timestamp indicating the most recent modification.
- <strong>Action Icons</strong>: Each entry in the list includes a set of icons for performing common tasks, such as adding the blocklet to a project, copying its DID, or deleting it.

## Summary

In summary, Blocklet Studio provides a structured, no-code environment for administrators to efficiently build, manage, and publish blocklets. By leveraging templates and a visual editor, it lowers the barrier to application creation and simplifies the overall development and deployment lifecycle.

---

## Dashboard

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-dashboard-4f480d/

The Dashboard is the central administrative interface for your Blocklet Service. It functions as the primary hub for managing blocklets, monitoring the overall system status, and provides quick access to essential, frequently used functions.

## Overview

Upon logging in, the Dashboard presents a comprehensive overview, acting as the command center for all administrative tasks. Its design prioritizes efficiency, allowing for immediate access to critical system information and management tools. From this central point, you can control your installed blocklets, navigate to user and identity management, customize your website's branding and appearance, and monitor key operational metrics.

![Dashboard](https://media.arcblock.io/lib/dd/dd4a8191735d5f8a.w1600.webp)

## Blocklet Management

A primary feature of the Dashboard is the direct management of all installed blocklets. This section provides a streamlined interface for the complete lifecycle management of your applications.

![Blocklet Management Overview](https://media.arcblock.io/lib/22/22abdd12ac3b06be.w1600.webp)

Key management actions include:

- <strong>Lifecycle Control</strong>: Start, stop, restart, and remove blocklets as needed.
- <strong>Updates</strong>: View notifications for available updates and apply them with a single click to keep your services current.
- <strong>Configuration</strong>: Manage environment variables and adjust blocklet-specific preferences.
- <strong>Installation</strong>: Add new blocklets directly from the Blocklet Store.

![Blocklet Environment Configuration](https://media.arcblock.io/lib/83/8318a6935edaeb0f.w1600.webp)

## Navigation Hub

The Dashboard serves as the main navigation hub, providing access to all other administrative sections. The side navigation panel is logically organized to ensure you can locate the required tools quickly and efficiently.

::::card-group
::link-card{title="DID Connect" description="Manage users, groups, passports, and authentication settings." icon="users" href="/en/docs/blocklet-service/user-guide-did-connect-4f480d/"}
::link-card{title="AIGNE Hub" description="Integrate AI capabilities and monitor account balances." icon="cpu" href="/en/docs/blocklet-service/user-guide-aigne-hub-4f480d/"}
::link-card{title="Website" description="Customize your site's domains, branding, and navigation." icon="layout" href="/en/docs/blocklet-service/user-guide-website-4f480d/"}
::link-card{title="Operations" description="Access notifications, audit logs, analytics, and advanced settings." icon="bar-chart" href="/en/docs/blocklet-service/user-guide-operations-4f480d/"}
::link-card{title="Integrations" description="Configure WebHooks and manage API access keys for external systems." icon="power" href="/en/docs/blocklet-service/user-guide-integrations-4f480d/"}
::link-card{title="Developers" description="Access logs, performance metrics, and embedded documentation." icon="code" href="/en/docs/blocklet-service/user-guide-developer-tools-4f480d/"}
::link-card{title="DID Spaces" description="Manage decentralized storage, backups, and files." icon="cloud" href="/en/docs/blocklet-service/user-guide-did-spaces-4f480d/"}
::link-card{title="Blocklet Studio" description="A no-code platform to create and publish new blocklets from templates." icon="box" href="/en/docs/blocklet-service/user-guide-blocklet-studio-4f480d/"}
::::

## Summary

In summary, the Dashboard is the essential starting point for any administrative task. It provides a high-level status overview and consolidates all management functionalities into a single, accessible interface, ensuring a streamlined and efficient administrative experience. From here, you can proceed to more specialized sections like [DID Connect](/en/docs/blocklet-service/user-guide-did-connect-4f480d/) for user management or the [Website](/en/docs/blocklet-service/user-guide-website-4f480d/) section to configure your site's appearance.

---

## Developers

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-developer-tools-4f480d/

The Developer Tools section provides administrators with access to a suite of powerful tools for monitoring, debugging, and understanding the inner workings of your blocklets. These utilities offer deep insights into application behavior, resource consumption, and provide direct access to relevant documentation, streamlining troubleshooting and operational management.

While these tools are technical in nature, they are designed to be accessible to administrators responsible for maintaining the health and stability of the service. This section can be hidden by default in advanced settings to simplify the interface for non-technical users.

::::card-group
::link-card{title="Logs" description="Access real-time and historical application logs for debugging and monitoring system events." icon="book" href="/en/docs/blocklet-service/user-guide-developer-tools-logs-4f480d/"}
::link-card{title="Performance" description="Monitor runtime performance metrics, including CPU and memory utilization, to ensure optimal operation." icon="activity" href="/en/docs/blocklet-service/user-guide-developer-tools-performance-4f480d/"}
::::

## Key Features

This section is divided into several key areas, each providing a specific set of functionalities to aid in the management and maintenance of your blocklet service.

### Logs

The Logs interface provides a centralized location to view and analyze log data generated by your blocklets. This is an essential tool for debugging issues, tracking application activity, and understanding system behavior over time. You can view logs in real-time as they are generated or browse through historical log files. The interface includes powerful filtering and search capabilities to help you quickly locate specific log entries.

![Developer Logs Viewer](https://media.arcblock.io/lib/5d/5dbccb8a6694ee5a.w1600.webp)

For more detailed information, please see the [Logs](/en/docs/blocklet-service/user-guide-developer-tools-logs-4f480d/) documentation.

### Performance

The Performance dashboard offers a visual representation of your blocklet's runtime metrics. It allows you to monitor critical resource utilization, such as CPU and memory usage, over various time periods. By observing these performance graphs, you can identify potential bottlenecks, diagnose performance degradation, and ensure your service is running efficiently.

![Performance Monitoring Dashboard showing CPU utilization graphs.](https://media.arcblock.io/lib/4a/4aef07594475f82e.w1600.webp)

For a deeper dive into monitoring, refer to the [Performance](/en/docs/blocklet-service/user-guide-developer-tools-performance-4f480d/) section.

### Docs

The embedded documentation portal provides convenient access to developer guides, API references, and other essential documentation directly within the Blocklet Service dashboard. This feature ensures that you have the information you need right at your fingertips, without having to navigate to external websites, facilitating a more efficient workflow when you need to look up technical details.

## Summary

The Developer Tools section equips administrators with the necessary utilities to effectively monitor, diagnose, and manage their blocklet services. By providing direct access to logs, performance metrics, and documentation, it empowers users to maintain a stable and reliable application environment.

---

## Logs

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-developer-tools-logs-4f480d/

The Logs section provides administrators with direct access to real-time and historical log data generated by the blocklet. This tool is essential for debugging issues, monitoring application behavior, and gaining insights into operational activities. A systematic review of logs can help identify errors, track user actions, and ensure the system is functioning as expected.

![The Logs interface, showing a real-time view of access logs with filtering options.](https://media.arcblock.io/lib/5d/5dbccb8a6694ee5a.w1600.webp)

## Log Data Flow

The following diagram illustrates the process by which log data is generated, collected, and made available for viewing and analysis within the Developer Tools.

generateDiagram(documentContent='# Logs

The Logs section provides administrators with direct access to real-time and historical log data generated by the blocklet. This tool is essential for debugging issues, monitoring application behavior, and gaining insights into operational activities. A systematic review of logs can help identify errors, track user actions, and ensure the system is functioning as expected.

![The Logs interface, showing a real-time view of access logs with filtering options.](https://media.arcblock.io/lib/5d/5dbccb8a6694ee5a.w1600.webp)

## Log Data Flow

The following diagram illustrates the process by which log data is generated, collected, and made available for viewing and analysis within the Developer Tools. ', locale='en')

## Key Features

The Logs interface is designed to provide comprehensive access to your blocklet's logs with several key functionalities.

### Real-Time Log Streaming

View logs as they are generated in real-time. The live-streaming feature is invaluable for monitoring the immediate effects of actions or diagnosing active problems within the application. The latest log entries automatically appear at the top of the view, providing an up-to-the-minute account of system activity.

### Historical Log Access

Beyond real-time monitoring, you can browse and inspect historical log files. This allows for post-mortem analysis of incidents, auditing of past activities, and understanding trends over time. The system archives logs, making them available for review long after they were initially generated.

### Filtering and Searching

To efficiently navigate through large volumes of log data, the Logs tool includes powerful filtering and search capabilities. You can isolate specific log entries based on their severity level or content.

- <strong>Filter by Level</strong>: Narrow down the log entries by type, such as `Error`, `Info`, and `Access`. This helps in quickly identifying critical issues or focusing on specific categories of events.
- <strong>Search</strong>: Use the search bar to find logs containing specific keywords, user IDs, request URLs, or error messages. This is crucial for tracing a specific transaction or debugging a particular feature.

## How to Use the Log Viewer

::::steps
:::step{title="Navigate to Logs"}
From the main dashboard, select <strong>Developers</strong> in the sidebar, and then click on the <strong>Logs</strong> tab.
:::

:::step{title="Select a Component"}
If your service consists of multiple blocklets or components, use the dropdown menu at the top to select the specific component whose logs you wish to view.
:::

:::step{title="View Real-Time Logs"}
By default, the log viewer streams logs in real-time. Observe the entries as they appear.
:::

:::step{title="Apply Filters"}
To narrow the results, click on the filter buttons (e.g., `Error`, `Info`). The view will update to show only the logs matching the selected level.
:::

:::step{title="Search Logs"}
Enter a search term into the search box and press Enter. The log display will be filtered to show only entries that contain your search query.
:::

:::step{title="Inspect Log Details"}
Each log entry typically contains a timestamp, the log level, and the message. Click on an entry if additional details are available for inspection.
:::
::::

## Summary

The Logs section is a critical tool for administrators responsible for maintaining the health and stability of a blocklet. It provides the necessary visibility to diagnose problems, monitor system behavior, and ensure a reliable service. By leveraging real-time streaming, historical access, and powerful search filters, you can effectively manage and troubleshoot your application.

---

## Performance

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-developer-tools-performance-4f480d/

The Performance section provides administrators with essential tools to monitor the runtime health and resource utilization of blocklets. Consistent monitoring is a key practice for maintaining application stability, identifying potential bottlenecks, and ensuring efficient operation. This area is located within the "Developers" tools, offering a clear view of how system resources are being consumed.

## Performance Dashboard

The primary interface for performance monitoring is a dashboard that visualizes key metrics over time. It presents a series of graphs, allowing for a quick assessment of a blocklet's operational status. Administrators can observe trends, identify anomalies, and correlate performance spikes with specific events or time periods.

![Performance monitoring dashboard displaying CPU usage graphs for various services.](https://media.arcblock.io/lib/4a/4aef07594475f82e.w1600.webp)

The dashboard typically displays metrics such as:

- <strong>CPU Utilization</strong>: Shows the percentage of CPU resources being used by a blocklet or its components. Sustained high CPU usage may indicate an inefficient process or a need for resource scaling.
- <strong>Memory Usage</strong>: Tracks the amount of memory (RAM) a blocklet is consuming. Monitoring this metric is crucial for detecting memory leaks and preventing application crashes due to resource exhaustion.

## Monitoring Architecture

The performance monitoring system is designed to collect, store, and display metrics with minimal overhead. The process involves a metrics collector that periodically gathers data from the blocklet's runtime environment. This data is then stored and made available to the dashboard for visualization.

![Performance](https://media.arcblock.io/lib/d8/d83667da076ed82a.w1600.webp)

This architecture ensures that administrators have access to timely and accurate performance data to make informed decisions about their applications.

## Summary

By utilizing the Performance dashboard, administrators can proactively manage the health of their blocklets. Regular monitoring of CPU and memory usage helps in diagnosing issues, planning for future capacity, and maintaining a smooth and reliable user experience. For real-time issue diagnosis and debugging, this tool should be used in conjunction with the [Logs](/en/docs/blocklet-service/user-guide-developer-tools-logs-4f480d/) viewer.

---

## DID Connect

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-connect-4f480d/

DID Connect is a comprehensive user and identity management center designed for administrators. It provides a centralized suite of tools for managing members, handling digital passports, and configuring all authentication-related settings for your application. This service is fundamental for controlling user access, customizing the login experience, and ensuring application security.

The following diagram illustrates the key components of DID Connect and how an administrator interacts with the system:

![DID Connect](https://media.arcblock.io/lib/41/415befecf19ed722.w1600.webp)

## Features Overview

DID Connect is organized into several distinct sections, each tailored to a specific aspect of identity and access management. Below is an overview of the key components. For detailed information, please refer to the specific sub-document for each feature.

::::card-group
::link-card{title="Members" description="View, search, and manage user profiles and groups. You can also invite new members to your application." icon="users" href="/en/docs/blocklet-service/user-guide-did-connect-members-4f480d/"}
::link-card{title="Passports" description="Manage the complete lifecycle of user passports, including issuing new passports, managing templates, and tracking usage history." icon="user" href="/en/docs/blocklet-service/user-guide-did-connect-passports-4f480d/"}
::link-card{title="Settings" description="Configure various authentication settings, such as login session duration, KYC requirements, and federated login options." icon="settings" href="/en/docs/blocklet-service/user-guide-did-connect-settings-4f480d/"}
::link-card{title="Security" description="Define advanced security rules, access control policies, and response handling to enhance your application's security." icon="shield" href="/en/docs/blocklet-service/user-guide-did-connect-security-4f480d/"}
::link-card{title="OAuth Apps" description="Manage third-party applications that use your service as an OAuth provider for authentication and authorization." icon="key" href="/en/docs/blocklet-service/user-guide-did-connect-oauth-apps-4f480d/"}
::::

## Summary

DID Connect centralizes all the necessary tools for robust user and identity management. By exploring the sections linked above, you can effectively manage your user base, secure your application, and customize the authentication processes to fit your specific needs.

---

## Members

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-connect-members-4f480d/

The Members section within DID Connect serves as the central administrative hub for user management. It provides a comprehensive interface for viewing, searching, and managing all user profiles and groups associated with your application. Additionally, it contains the tools necessary to invite new members, facilitating the expansion of your user base.

![Members Management Interface](https://media.arcblock.io/lib/93/93c284a8b832b8bd.w1600.webp)

## User and Group Management

This area provides a detailed overview of all registered users, allowing for efficient administration and organization.

### Member List

The main view is a comprehensive table that lists all members, providing key information at a glance. The table is sortable and searchable, enabling administrators to quickly locate specific users. The columns typically include:

- <strong>Type</strong>: The role or status of the member within the application (e.g., Owner, Admin, Guest).
- <strong>Name</strong>: The full name of the user.
- <strong>DID</strong>: The user's Decentralized Identifier (DID) address.
- <strong>Last Login</strong>: The timestamp of the user's most recent login activity.
- <strong>Source</strong>: The method used for registration or the last login, such as a DID Wallet, Google, or another OAuth provider.

### User Profiles

By selecting a member from the list, administrators can access their detailed profile page. This page contains comprehensive information about the user, including their registration details, assigned passports, and activity history.

### Managing Roles

The "Type" column indicates the user's role. Administrators can manage these roles, assigning different levels of permissions and access rights to various users or groups, ensuring proper governance and security within the application.

## Inviting New Members

Administrators can invite new users to join the application directly from this interface. The invitation system is designed to be straightforward and secure.

### Invitation Process

::::steps
:::step{title="Initiate Invitation"}
The administrator starts the process by selecting the "Invite" option.
:::

:::step{title="Enter Details"}
The administrator provides the necessary details for the invitee, typically an email address.
:::

:::step{title="Send Invitation"}
The system sends a secure invitation link or code to the prospective user.
:::

:::step{title="User Registration"}
The user clicks the link, completes the registration process, and is added to the member list with a pre-assigned role if specified during the invitation.
:::
::::

This streamlined process simplifies onboarding new users while maintaining administrative control over who can join the application.

## Summary

The Members section is an essential tool for administrators, providing all the necessary functions for effective user lifecycle management. From here, you can monitor user activity, organize users into groups, and control the growth of your user community. For more on user identity and access, refer to the [Passports](/en/docs/blocklet-service/user-guide-did-connect-passports-4f480d/) and [Settings](/en/docs/blocklet-service/user-guide-did-connect-settings-4f480d/) sections.

---

## OAuth Apps

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-connect-oauth-apps-4f480d/

OAuth Apps functionality allows your service to act as an OAuth 2.0 provider. This enables third-party applications to securely access user data through a standardized authorization process, without exposing the user's primary login credentials. As an administrator, you can register and manage these third-party applications, controlling which applications can connect to your service and what level of access they are granted.

This is commonly used for "Login with..." features, where users can use their accounts on your service to sign in to other applications.

## How the OAuth Flow Works

The OAuth 2.0 Authorization Code Grant is the primary flow used. It is a secure, multi-step process that ensures users explicitly consent to the access requested by a third-party application.

The process involves four main parties:

- <strong>Resource Owner</strong>: The end-user who owns the data.
- <strong>Client Application</strong>: The third-party application requesting access to the user's data.
- <strong>Authorization Server</strong>: Your Blocklet Service, which authenticates the user and obtains their consent.
- <strong>Resource Server</strong>: Your Blocklet Service, which hosts the user's data and provides it to the Client Application upon successful authorization.

![OAuth Apps](https://media.arcblock.io/lib/c6/c64df7f1fb4a1660.w1600.webp)

Here is a simplified step-by-step breakdown of the flow:

::::steps
:::step{title="Authorization Request"}
The user initiates an action in the Client Application (e.g., clicking "Login with My Service"). The Client Application redirects the user to your service's Authorization Server with a request for specific permissions (scopes).
:::

:::step{title="User Authentication & Consent"}
The Authorization Server authenticates the user (if not already logged in) and displays a consent screen detailing the permissions the Client Application is requesting.
:::

:::step{title="Granting Authorization Code"}
If the user approves the request, the Authorization Server redirects the user back to the Client Application, providing a single-use Authorization Code.
:::

:::step{title="Exchanging Code for Tokens"}
The Client Application sends the Authorization Code to the Authorization Server in a secure, back-channel request.
:::

:::step{title="Token Issuance"}
The Authorization Server validates the code and, if valid, issues an Access Token and an optional Refresh Token to the Client Application.
:::

:::step{title="Accessing Resources"}
The Client Application uses the Access Token to make API calls to the Resource Server to retrieve the user's data, limited to the scopes the user approved.
:::
::::

This flow ensures that the user's credentials are never shared directly with the third-party application.

## Managing OAuth Applications

From the DID Connect dashboard, you can register new third-party applications and manage existing ones. This gives you full control over which external services can integrate with your user base.

![OAuth Apps Management Interface](https://media.arcblock.io/lib/48/4898112e15630594.w1600.webp)

### Creating a New OAuth App

To allow a new third-party application to use your service for authentication, you must first register it.

1. Navigate to <strong>DID Connect > OAuth Apps</strong>.
2. Click the <strong>Create</strong> button.
3. Fill in the required application details:
4.
  - <strong>App Name</strong>: A user-friendly name for the application that will be displayed on the consent screen.
  - <strong>Redirect URIs</strong>: A list of one or more URLs where the user will be redirected after they authorize the application. This is a critical security measure to prevent authorization codes from being intercepted.
  - <strong>Scopes</strong>: The specific permissions the application can request (e.g., `profile:read`). This defines what user data the application is allowed to access.

After creation, the system will generate a <strong>Client ID</strong> and a <strong>Client Secret</strong>. These credentials are used by the third-party application to identify itself to your service. The Client Secret should be stored securely by the application developer and never exposed in client-side code.

### Viewing and Managing Existing Apps

The OAuth Apps page displays a list of all registered applications. For each application, you can see:

- <strong>Name</strong>: The application's display name.
- <strong>Client ID</strong>: The unique public identifier for the application.
- <strong>Scopes</strong>: The permissions granted to the application.
- <strong>Created At</strong>: The date the application was registered.
- <strong>Created By</strong>: The user or process that registered the application.

From this list, you can select an application to view its full details, edit its configuration (e.g., add or remove Redirect URIs), or revoke its access by deleting it.

## Summary

The OAuth Apps feature transforms your Blocklet Service into a secure and centralized identity provider. By managing client applications and their permissions, you can enable a seamless and secure integration ecosystem, allowing users to connect their accounts to trusted third-party services without compromising their credentials. This enhances user convenience and extends the reach of your platform.

---

## Passports

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-connect-passports-4f480d/

A Passport is a verifiable digital credential issued to a user, serving as proof of identity or authorization within your application. As a fundamental component of the DID Connect system, Passports enable secure and structured access control. This section provides administrators with the tools to manage the entire lifecycle of user Passports, including issuance, monitoring, and revocation.

## Passport Lifecycle

The lifecycle of a Passport follows a distinct and manageable process, ensuring that user credentials are systematically controlled from creation to expiration. The key stages are illustrated below:

![Passports](https://media.arcblock.io/lib/9f/9fc9fe7fbb91a35a.w1600.webp)

The process unfolds as follows:

::::steps
:::step{title="Template Creation"}
An administrator designs and configures a passport template, defining its claims, validity period, and other relevant attributes.
:::

:::step{title="Issuance"}
Based on a selected template, a new Passport is issued to a specific user's DID.
:::

:::step{title="User Acceptance"}
The user receives a notification and accepts the issued Passport in their DID Wallet.
:::

:::step{title="Verification"}
The user presents the Passport to the application to gain access. The application verifies its authenticity and confirms it is still valid.
:::

:::step{title="Expiration/Revocation"}
The Passport becomes invalid either when its predefined expiration date is reached or if an administrator manually revokes it.
:::
::::

## Key Features

The Passports section offers a centralized interface for comprehensive management of all user credentials.

- <strong>Issued Passport Registry</strong>: Access a complete list of all Passports issued to users. The registry provides essential details such as the passport type, owner's DID, issuance date, and current status.
- <strong>Usage History</strong>: Monitor when and how Passports are used to access the application. This functionality is critical for security audits and analyzing user activity patterns.
- <strong>Template Management</strong>: Create, edit, and manage templates for various types of Passports. Templates standardize the information and permissions associated with each credential, which simplifies and accelerates the issuance process.
- <strong>Issue New Passports</strong>: Manually issue new Passports to individual users as needed, which is particularly useful for granting specific permissions or onboarding new members.
- <strong>Custom Passport Types</strong>: For advanced use cases, you can define custom Passport types that are tailored to the unique requirements of your application, providing flexibility beyond the standard templates.

## Managing Passports

The Passports dashboard presents a detailed table of all issued credentials, designed for efficient administration and oversight.

![A screenshot of the Passports management interface in DID Connect, showing a table with passport details like type, owner, status, last login, and source.](https://media.arcblock.io/lib/b8/b89fc66111fbdf05.w1600.webp)

The table contains the following columns:

| Column  | Description  |
|---|---|
| <strong>Type</strong>  | The category or template from which the Passport was issued.  |
| <strong>Owner</strong>  | The user to whom the Passport was issued, identified by their name and DID.  |
| <strong>Status</strong>  | The current state of the Passport (e.g., `Valid`, `Expired`).  |
| <strong>Last Login</strong>  | The timestamp of the user's most recent login session using this Passport.  |
| <strong>Source</strong>  | The method or authority through which the Passport was originally issued.  |

From this interface, administrators can select any Passport to view its detailed information, verify its status, or perform management actions such as revocation.

## Summary

Systematic management of Passports is essential for maintaining a secure and orderly application environment. The tools provided in this section allow you to control, monitor, and audit user access throughout its entire lifecycle. For details on managing the users who hold these Passports, please proceed to the [Members](/en/docs/blocklet-service/user-guide-did-connect-members-4f480d/) section.

---

## Security

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-connect-security-4f480d/

For administrators, the Security section is where you define advanced security rules, access policies, and response handling to protect your application. It provides a centralized console to manage who can access your resources and how browsers should handle your content to mitigate common web vulnerabilities.

## Overview

The Security section within DID Connect provides administrators with powerful tools to safeguard their applications. By defining a granular set of rules and policies, you can control who can access your application, what they can do, and how the application responds to requests. This ensures a secure and robust environment for your users and data.

The security model is built on three core components that work together:

- <strong>Security Rules</strong>: The entry point for incoming requests. Each rule matches a specific URL path pattern and links it to an Access Policy and a Response Policy.
- <strong>Access Policies</strong>: These policies determine whether a user is authorized to access a resource. Examples include allowing public access, requiring a login, or restricting access to invitees only.
- <strong>Response Policies</strong>: These define the HTTP security headers sent back to the client, enhancing protection against common web vulnerabilities like cross-site scripting (XSS) and clickjacking.

The following diagram illustrates how an incoming request is processed through the security framework:

![Security](https://media.arcblock.io/lib/1f/1f6c01913dc8deb4.w1600.webp)

## Security Rules

Security Rules are the foundation of your application's access control. They act as a router, evaluating incoming requests against defined URL path patterns and applying the corresponding access and response policies. You can create multiple rules to handle different parts of your application with varying levels of security.

For example, you could have a rule that makes your marketing pages (`/about`, `/features`) public, another that requires users to be logged in to see their dashboard (`/app/*`), and a third that restricts access to an admin panel (`/admin/**`) to a specific user group.

The main management interface allows you to:

- <strong>Create New Rules</strong>: Define new path patterns and link them to policies.
- <strong>Order Rules</strong>: The order is critical. Rules are evaluated from top to bottom, and the first matching rule is applied. You can drag and drop rules to set the correct priority.
- <strong>Enable/Disable Rules</strong>: Temporarily turn rules on or off without deleting them.
- <strong>Edit and Delete Rules</strong>: Modify existing rules as your application's needs change.

![Security Rule Management Interface](https://media.arcblock.io/lib/66/66717f619a31bf88.w1600.webp)

### Configuration Fields

When creating or editing a Security Rule, you will configure the following:

- <strong>Path Pattern</strong>: A URL pattern to match incoming requests (e.g., `/app/*`, `/api/v1/**`, `/`). Standard path-matching syntax is supported.
- <strong>Access Policy</strong>: The access policy to apply if the path matches.
- <strong>Response Policy</strong>: The set of response headers to apply if the path matches.

## Access Policies

Access Policies define the authentication and authorization requirements for a request. They specify <em>who</em> is allowed to access a particular resource. The system includes several built-in policies that cover common use cases.

### Common Access Policies

| Policy Name  | Description  |
|---|---|
| <strong>Public</strong>  | Allows access to anyone, without requiring authentication. Ideal for landing pages, blogs, or public content.  |
| <strong>Any Logged-in User</strong>  | Requires the user to be authenticated. Any user with a valid session can access the resource.  |
| <strong>Invite Only</strong>  | Restricts access to users who have been explicitly invited to the application. This is useful for private betas or exclusive communities.  |
| <strong>Admin Only</strong>  | Restricts access to users with administrative privileges.  |

You can assign one of these policies to each Security Rule to enforce the desired level of access control across your application.

## Response Policies

Response Policies control the HTTP security headers that your application sends back to the browser. These headers are a crucial part of a defense-in-depth security strategy, helping to mitigate client-side attacks.

By configuring these policies, you can instruct browsers on how to handle your content securely.

### Common Security Headers

- <strong>Content-Security-Policy (CSP)</strong>: Helps prevent cross-site scripting (XSS) and other code injection attacks by specifying which dynamic resources are allowed to load.
- <strong>X-Frame-Options</strong>: Protects against clickjacking attacks by controlling whether your site can be embedded in an `<iframe>`, `<frame>`, `<embed>`, or `<object>`.
- <strong>Strict-Transport-Security (HSTS)</strong>: Forces browsers to communicate with your server only over HTTPS, preventing downgrade attacks.
- <strong>X-Content-Type-Options</strong>: Prevents browsers from MIME-sniffing a response away from the declared content type, which can help prevent certain types of attacks.

You can create different sets of response policies (e.g., a strict policy for authenticated application areas and a more lenient one for public pages) and associate them with your Security Rules.

## Summary

The Security section provides a flexible and powerful framework for protecting your application. By combining Security Rules, Access Policies, and Response Policies, you can create a tailored security posture that meets the specific needs of your application, ensuring that your resources are only accessible to authorized users and that your application is hardened against common web threats.

---

## Settings

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-connect-settings-4f480d/

The Settings section within DID Connect is the central control panel for administrators to configure authentication policies, user verification processes, and login methods. Proper configuration in this area is essential for balancing security, user convenience, and data completeness for your application.

This guide provides a detailed overview of each configuration area: Login Settings, KYC Settings, OAuth Settings, and Federated Login Settings.

The following diagram illustrates the relationship between the administrator and the different configuration areas within the DID Connect Settings.

![Settings](https://media.arcblock.io/lib/85/8522e0497485ddd0.w1600.webp)

## Login Settings

This area allows you to customize the user login experience and define data requirements for user profiles.

![DID Connect Settings page showing session validity and profile requirements](https://media.arcblock.io/lib/a6/a66b098da19c153a.w1600.webp)

### Session Duration

The session duration setting determines how long a user's session remains active after they log in. Shorter durations enhance security by requiring users to re-authenticate more frequently, while longer durations offer greater convenience.

- <strong>Functionality</strong>: Use the slider to set the session validity period (e.g., from 1 day to 30 days).
- <strong>Use Case</strong>: For applications handling sensitive data, a shorter session duration (e.g., 1-3 days) is recommended. For general-purpose sites, a longer duration (e.g., 14-30 days) improves user experience by reducing login frequency.

### User Profile Requirements

Define which information fields are mandatory for a user's profile to be considered complete. This ensures that you collect essential data from your users upon registration or their first login.

- <strong>Available Fields</strong>: You can require users to provide their full name, email address, and phone number.
- <strong>Configuration</strong>: Use the toggle switches next to each field to enable or disable the requirement.

## KYC Settings

KYC (Know Your Customer) settings are used to establish and manage identity verification processes. This is critical for applications that must adhere to regulatory compliance or wish to add a layer of trust and security by verifying user identities.

- <strong>Verification Methods</strong>: Configure requirements for users to verify their identity through various channels, such as email validation or phone number confirmation.
- <strong>Use Case</strong>: Financial applications may use KYC to comply with anti-money laundering (AML) regulations. Online communities might use email verification to reduce spam and fake accounts.

## OAuth Settings

OAuth settings enable you to integrate third-party authentication providers, allowing users to sign in with their existing social or professional accounts (e.g., Google, GitHub). This simplifies the registration and login process, which can lead to higher user adoption.

- <strong>Provider Configuration</strong>: Add, configure, and manage credentials for each external OAuth provider you wish to support.
- <strong>Channel Management</strong>: You can enable or disable specific login methods and customize the order in which they appear on the login page to prioritize certain providers.

## Federated Login Settings

Federated login establishes a trust relationship between multiple independent websites, creating a single sign-on (SSO) experience for users across all sites in the federation. When a user logs into one site, they are automatically authenticated on all other participating sites.

- <strong>Functionality</strong>: Configure a "master" site that manages authentication for a group of "member" sites.
- <strong>Use Case</strong>: An organization with multiple web properties (e.g., a main website, a blog, and a support portal) can use federated login to provide a seamless user experience, eliminating the need for users to log in separately to each property.

### Summary

The Settings section provides administrators with powerful tools to tailor the authentication and user management aspects of their application. By carefully configuring these options, you can create a secure, compliant, and user-friendly environment. For more advanced access control, please refer to the [Security](/en/docs/blocklet-service/user-guide-did-connect-security-4f480d/) section.

---

## DID Spaces

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-spaces-4f480d/

DID Spaces provides a decentralized and secure storage solution integrated directly into your Blocklet Service. It allows administrators to manage application data, perform automated backups, and monitor storage usage, all leveraging a personal, user-controlled storage space. This ensures data sovereignty and enhances security by separating the application environment from its persistent data.

The primary functions managed through this section are:

- <strong>Data Backups</strong>: Configure and automate the backup of your blocklet's critical data to your DID Space. This includes scheduling, viewing backup history, and restoring data when needed.
- <strong>File Storage</strong>: Monitor the storage quota and usage of your connected DID Space. It provides an interface for managing the files and data your blocklet stores.

This integrated approach simplifies data management, providing a reliable and secure way to protect and handle your application's information.

![DID Spaces](https://media.arcblock.io/lib/03/033bb0eb265ceb32.w1600.webp)

## Key Features

DID Spaces is divided into two main areas, each addressing a critical aspect of data management.

![DID Spaces backup management interface](https://media.arcblock.io/lib/e7/e7abf6fccecae365.w1600.webp)

::::card-group
::link-card{title="Backups" description="Establish a robust data protection strategy by configuring automated backup schedules and restoring data from specific points in time." icon="archive" href="/en/docs/blocklet-service/user-guide-did-spaces-backups-4f480d/"}
::link-card{title="Storage" description="Monitor your storage quota, track usage patterns, and manage files to ensure you have adequate space for your application's data." icon="database" href="/en/docs/blocklet-service/user-guide-did-spaces-storage-4f480d/"}
::::

## Summary

DID Spaces offers a seamless and secure method for managing your blocklet's data. By integrating decentralized storage, it enhances data security, provides reliable backup and recovery options, and gives administrators clear visibility into storage consumption. This ensures that your application's data is both safe and efficiently managed.

For more detailed information, please proceed to the [Backups](/en/docs/blocklet-service/user-guide-did-spaces-backups-4f480d/) and [Storage](/en/docs/blocklet-service/user-guide-did-spaces-storage-4f480d/) sections.

---

## Backups

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-spaces-backups-4f480d/

The Backups feature, integrated with DID Spaces, provides a robust solution for safeguarding your application's data. It allows administrators to establish and manage a comprehensive data protection strategy, ensuring that critical information can be recovered in case of data loss. This section details how to configure automated backup schedules, view the history of all backup activities, and restore your service to a previous state from a selected backup file.

## Key Features

The backup management interface is designed to be straightforward and efficient, offering several key functionalities:

- <strong>DID Spaces Integration</strong>: Before initiating any backup, you must connect to a DID Space. This decentralized storage solution serves as the secure, remote location for all your backup archives.
- <strong>Automated Backups</strong>: Configure a "fire and forget" backup strategy by enabling the auto-backup feature. The system will automatically perform backups according to a predefined schedule, ensuring consistent data protection without manual intervention.
- <strong>Backup History</strong>: A detailed log of all backup attempts is maintained and displayed in a clear, tabular format. This allows administrators to quickly verify the status of each backup, including start and end times, and confirm whether it succeeded.
- <strong>Backup Restoration</strong>: In the event of data corruption or accidental deletion, you can easily restore your application to a stable state. The interface allows you to select a specific backup from the history and initiate the restoration process.

## Managing Backups

The main dashboard for managing backups provides a centralized view of all related activities.

![Backup management interface in DID Spaces](https://media.arcblock.io/lib/e7/e7abf6fccecae365.w1600.webp)

As shown in the interface:

::::steps
:::step{title="Connection Status"}
The top section displays the currently connected DID Spaces, confirming where your backups are being stored.
:::

:::step{title="Auto Backup Toggle"}
A simple toggle switch allows you to enable or disable the automated backup strategy for your service.
:::

:::step{title="Activity Heatmap"}
A calendar-style heatmap offers a visual representation of your backup frequency and consistency over the past several months. Days with successful backups are color-coded, making it easy to spot any gaps in your backup schedule.
:::

:::step{title="Backup Records"}
The table at the bottom lists each individual backup record. Key details such as the destination DID Space, backup strategy (e.g., automated, manual), start and end times, and final status (`Succeeded`, `Failed`) are clearly presented for quick review and action.
:::
::::

## Backup and Restore Process

The process involves securely packaging your application data, transferring it to your DID Space for storage, and retrieving it when a restore operation is needed. This ensures that your data is always available for recovery. The following diagram illustrates this process:

![Backups](https://media.arcblock.io/lib/b7/b7fe37bdb5fcb654.w1600.webp)

## Summary

Regularly backing up your Blocklet Service is a critical administrative task for data protection and disaster recovery. The Backups feature simplifies this process by integrating with decentralized DID Spaces, offering both automated and manual control over creating and restoring data. By leveraging this tool, administrators can ensure the integrity and availability of their service.

---

## Storage

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-did-spaces-storage-4f480d/

The Storage section, part of the DID Spaces service, provides administrators with essential tools for monitoring and managing the storage resources allocated to their Blocklet Service. This interface offers a clear view of storage consumption, including total quota and current usage, enabling proactive resource management. It also includes a file management interface to browse and handle files stored within your decentralized DID Space.

This guide covers the primary functions of the Storage section: monitoring usage and managing files.

![Storage](https://media.arcblock.io/lib/d6/d6227f21a888692f.w1600.webp)

## Key Features

### Storage Monitoring

Maintaining awareness of your storage consumption is critical for uninterrupted service. The Storage section provides a straightforward view of your allocated resources.

- <strong>Storage Quota:</strong> This represents the total amount of storage space available to your DID Space. It is the upper limit of data you can store.
- <strong>Storage Usage:</strong> This metric shows the current amount of storage space being actively used by your files and data. A visual indicator, such as a progress bar, typically accompanies this figure to provide a quick assessment of your consumption relative to the total quota.

Regularly monitoring these metrics helps in planning for future storage needs and preventing service disruptions due to exhausted space.

### File Management

Beyond monitoring, the Storage section includes a file management interface that allows for direct interaction with the data stored in your DID Space. This integrated file browser provides a user-friendly way to:

- Navigate through the directory structure of your storage.
- View a list of all stored files and folders.
- Access details about individual files, such as size and modification date.

This functionality is essential for administrative tasks such as verifying backups, locating specific files, or cleaning up obsolete data to free up space.

### Storage Configuration

The interface also provides access to configuration settings related to your DID Space storage. These settings allow you to manage the connection to your DID Space and adjust parameters as needed to suit your application's requirements.

## Summary

The Storage section is a vital tool for any administrator responsible for managing a Blocklet Service. It provides the necessary visibility and control over decentralized storage resources, combining essential monitoring capabilities with practical file management tools. By leveraging this section, you can ensure your service operates smoothly with well-managed and optimized storage. For information on configuring automated backups, please see the [Backups](/en/docs/blocklet-service/user-guide-did-spaces-backups-4f480d/) documentation.

---

## Integrations

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-integrations-4f480d/

The Integrations section provides the tools necessary to connect your Blocklet Service with external systems and to manage programmatic access via the API. This is essential for automating workflows, enabling third-party services to interact with your blocklet, and building custom applications.

The following diagram illustrates the relationship between the Blocklet Service and various external systems:

![Integrations](https://media.arcblock.io/lib/7e/7e872146a281d39f.w1600.webp)

This section is divided into the following key areas:

::::card-group
::link-card{title="WebHooks" description="Configure WebHooks to send automated messages from your blocklet to other applications when specific events occur, enabling real-time notifications and data synchronization." icon="link" href="/en/docs/blocklet-service/user-guide-integrations-webhooks-4f480d/"}
::link-card{title="Access Keys" description="Generate and manage secure API keys for applications or scripts that need to interact with your blocklet's API programmatically." icon="key" href="/en/docs/blocklet-service/user-guide-integrations-access-keys-4f480d/"}
::link-card{title="MCP Servers" description="Discover and manage connections to Model Context Protocol (MCP) servers, which are used for building AI-powered features within your blocklets." icon="server" href="/en/docs/blocklet-service/user-guide-integrations-mcp-servers-4f480d/"}
::::

For detailed instructions on how to use these features, please refer to the specific documentation for each section.

---

## Access Keys

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-integrations-access-keys-4f480d/

Access Keys provide a method for granting programmatic access to your blocklet's services. They are used by applications, scripts, or external services to authenticate and interact with your blocklet's API without requiring manual user login. Each access key consists of an App ID and an App Secret, which function similarly to a username and password.

This administrative function is essential for integrating external services or automating tasks that require interaction with your blocklet's backend.

## Access Key Workflow

The following diagram illustrates the workflow for creating a new access key and its subsequent use for API authentication.

![Access Keys](https://media.arcblock.io/lib/dc/dc65e8a373f324d6.w1600.webp)

## Key Concepts

- <strong>App ID</strong>: A unique public identifier for the access key. It is included in each API request and is safe to expose publicly.
- <strong>App Secret</strong>: A confidential token used to sign requests, proving the identity of the application. The App Secret must be stored securely and must never be exposed in client-side applications or public code repositories.

## Managing Access Keys

The Access Keys dashboard provides a centralized location for managing all API credentials.

![Access Keys Management Interface](https://media.arcblock.io/lib/5e/5e88e9d0570ed922.w1600.webp)

### Creating an Access Key

To generate a new set of API credentials, follow these steps:

1. Navigate to the <strong>Integrations</strong> section in the administration sidebar.
2. Select the <strong>Access Keys</strong> tab.
3. Click the <strong>Create</strong> button to open the new key configuration form.
4. Provide a descriptive name for the key to easily identify its purpose (e.g., "CI/CD Script" or "External Analytics Service").
5. Assign an appropriate role that grants only the necessary permissions required by the application.
6. Upon creation, the App ID and App Secret will be displayed.
7. <strong>Important</strong>: The App Secret is displayed only once at the time of creation. You must copy it immediately and store it in a secure location, such as a password manager or an encrypted secrets store.

### Using an Access Key

When making an API request, your application must include the App ID and a signature generated with the App Secret in the request headers for authentication. The specific implementation details for generating the signature can be found in the [Developer Guide](/en/docs/blocklet-service/developer-guide-4f480d/).

### Revoking an Access Key

If an access key is compromised or no longer needed, it should be revoked immediately.

1. Navigate to the <strong>Access Keys</strong> list.
2. Locate the key you wish to disable.
3. Click the corresponding action to revoke the key.

This action is irreversible and will permanently block any application using that key from accessing your blocklet's services.

## Summary

Access keys are a powerful tool for enabling programmatic access to your blocklet. Proper management is critical for security. Always adhere to the principle of least privilege by assigning roles with the minimum necessary permissions, and ensure that App Secrets are stored securely at all times. For detailed information on API integration, please refer to the [Developer Guide](/en/docs/blocklet-service/developer-guide-4f480d/).

---

## MCP Servers

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-integrations-mcp-servers-4f480d/

The Model Context Protocol (MCP) provides a standardized framework that allows the main blocklet and its components to expose and consume AI-powered tools and services. The MCP Servers page serves as a central registry for administrators to discover and view all available MCP servers within their blocklet ecosystem.

This feature gives you a clear, real-time overview of all active AI services, their specific endpoints, and their security status, which helps in managing and integrating these capabilities across your application.

## MCP Discovery and Architecture

The Blocklet Service employs an automated discovery mechanism to identify and list all MCP-enabled services. This creates a decoupled architecture where a central service can interact with various specialized tools provided by different components without hardcoded configurations.

The discovery process is systematic and ensures the list of servers is always current. The following diagram illustrates this process:

![MCP Servers](https://media.arcblock.io/lib/c8/c8be4dd79c4b1fb5.w1600.webp)

Here is a step-by-step breakdown of the process:

::::steps
:::step{title="Initiation"}
When an administrator navigates to the <strong>Integrations > MCP Servers</strong> page, the Blocklet Service begins a discovery scan.
:::

:::step{title="Self-Identification"}
The service first identifies and lists its own built-in MCP server.
:::

:::step{title="Component Scan"}
It then iterates through all installed child components (blocklets).
:::

:::step{title="Capability Check"}
For each component, the service inspects its metadata to verify if the `capabilities.mcp` flag is enabled, indicating support for the protocol.
:::

:::step{title="Data Retrieval"}
If a component supports MCP, the service retrieves its essential details, including its name, DID, version, and specific MCP endpoint.
:::

:::step{title="Security Assessment"}
The service checks the security rules associated with the component to determine if its MCP server is public or protected.
:::

:::step{title="Aggregation"}
Finally, the Blocklet Service compiles a complete list of its own server and all discovered component servers and displays it on the page.
:::
::::

## Available MCP Servers

The MCP Servers page presents the discovered services in a clear and organized list. This allows administrators to quickly assess the available AI tools within their application.

![MCP Servers List](https://media.arcblock.io/lib/43/43d234a816a5b9c0.w1600.webp)

The table provides the following information for each server:

| Column  | Description  |
|---|---|
| <strong>Name</strong>  | The human-readable name of the blocklet or component providing the MCP server.  |
| <strong>DID</strong>  | The decentralized identifier (DID) of the server, which uniquely identifies it within the ecosystem.  |
| <strong>Endpoint</strong>  | The full URL endpoint where the MCP server can be accessed by clients.  |
| <strong>Protected</strong>  | A status indicating whether the server requires authentication. `True` means access is restricted and controlled by [Security Rules](/en/docs/blocklet-service/user-guide-did-connect-security-4f480d/). `False` means the endpoint is publicly accessible.  |
| <strong>Version</strong>  | The version number of the blocklet or component.  |
| <strong>Logo</strong>  | The icon associated with the blocklet or component for easy visual identification.  |

## Summary

The MCP Servers page is an essential tool for administrators, providing a centralized and automated inventory of all AI services available within the blocklet environment. By presenting key details like endpoints and security status, it simplifies the management and integration of AI-powered features, ensuring that you have a clear and accurate view of your application's capabilities at all times.

---

## WebHooks

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-integrations-webhooks-4f480d/

WebHooks provide a mechanism for your Blocklet Service to send real-time notifications to external services. By subscribing to specific system events, you can automate workflows and integrate your blocklet with other applications. When a subscribed event is triggered, the service sends an HTTP POST request containing event data to a URL you specify.

This guide explains how to configure and manage WebHooks within your Blocklet Service dashboard. For developer-focused information on event types and payload structures, please see the [EventBus Service](/en/docs/blocklet-service/developer-guide-eventbus-4f480d/) documentation.

## How WebHooks Work

The WebHook process is straightforward:

::::steps
:::step{title="Event Occurs:"}
An action takes place within the system, such as a new user registering or content being published.
:::

:::step{title="Trigger:"}
The system identifies that this action corresponds to a specific event (e.g., `user.created`).
:::

:::step{title="Notification:"}
The Blocklet Service checks for any active WebHook subscriptions for that event.
:::

:::step{title="HTTP POST:"}
For each subscription, the service sends an HTTP POST request with a JSON payload to the pre-configured URL of the external service.
:::

:::step{title="External Action:"}
The external service receives the data and can execute a corresponding action, such as updating a database, sending a notification, or starting a CI/CD pipeline.
:::
::::

The following diagram illustrates this workflow:flowchart TD A[Event Occurs in Blocklet Service] --> B{Check for Subscribed WebHooks}; B -- Yes --> C[Prepare JSON Payload]; C --> D[Send HTTP POST to External URL]; D --> E[External Service Receives Data]; E --> F[Action is Performed]; B -- No --> G[End Process];

## Configuring WebHooks

You can manage all your WebHooks from the Integrations section of the dashboard.

![WebHooks Management Page](https://media.arcblock.io/lib/08/08caf5f52183762b.w1600.webp)

### Creating a WebHook

To create a new WebHook, follow these steps:

1. Navigate to <strong>Integrations</strong> from the main menu.
2. Select the <strong>WebHooks</strong> tab.
3. Click the <strong>+ Create</strong> button to open the configuration form.
4. Enter the required details for your WebHook:
5.
  - <strong>Payload URL:</strong> The endpoint URL of your external service that will receive the POST requests.
  - <strong>Secret (Optional):</strong> A secret token used to secure your WebHook. The service will use this secret to generate a signature for each request, allowing your endpoint to verify the sender's authenticity.
  - <strong>Events:</strong> Select the specific events you want to subscribe to from the provided list. You can subscribe to one or more events.
6. Ensure the <strong>Enable</strong> checkbox is checked if you want the WebHook to be active immediately.
7. Click <strong>Save</strong> to create the WebHook.

### Managing Existing WebHooks

The WebHooks table provides a complete overview of all configured endpoints. From this list, you can:

- <strong>View Details:</strong> See the URL, subscribed events, and creation date for each WebHook.
- <strong>Enable/Disable:</strong> Use the toggle switch in the "Status" column to activate or deactivate a WebHook without deleting it. A disabled WebHook will not receive any event notifications.
- <strong>Edit:</strong> Click the edit action to modify the Payload URL, secret, or subscribed events.
- <strong>Delete:</strong> Permanently remove a WebHook and all its subscriptions. This action cannot be undone.

## Event Types and Payloads

The Blocklet Service emits various events related to system activities. When creating a WebHook, you can choose from a list of available events. The payload sent to your URL is a JSON object containing details about the event that occurred.

A typical payload structure includes:

- `event`: The name of the event (e.g., `Bookmark.Published`).
- `payload`: An object containing the data relevant to the event.
- `timestamp`: The time the event occurred.

### Example Payload

Here is an example of a JSON payload that might be sent for a `Bookmark.Published` event:

**WebHook Payload Example**

```json
{
  "event": "Bookmark.Published",
  "payload": {
    "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "url": "https://www.arcblock.io",
    "title": "ArcBlock Home",
    "author": "did:abt:z123...abc",
    "publishedAt": "2023-10-27T10:00:00Z"
  },
  "timestamp": "2023-10-27T10:00:05Z"
}
```

## Security

To ensure that your endpoint only processes requests sent from your Blocklet Service, you can configure a <strong>secret</strong> for your WebHook. When a secret is set, the service includes an `X-Hub-Signature-256` header in each POST request.

This header contains a SHA256 HMAC hex digest of the request body, generated using your secret as the key. You should validate this signature on your receiving server to confirm the request's integrity and authenticity.

## Summary

WebHooks are a powerful tool for creating automated, event-driven integrations between your Blocklet Service and other systems. By configuring WebHooks, you can extend the functionality of your blocklet and streamline your operational workflows without needing to poll for changes continuously.

---

## Operations

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-operations-4f480d/

The Operations section provides a centralized suite of tools for administrators to manage and monitor the production environment of their blocklets. It aggregates key functions related to system notifications, activity logging, performance analytics, and advanced administrative tasks.

This area is essential for maintaining system health, ensuring security, and gaining insights into application usage. By offering a consolidated view of operational data, it simplifies the process of managing a live application.

![Operations](https://media.arcblock.io/lib/0f/0f9e8bf8b278f917.w1600.webp)

The Operations section is divided into the following key areas, each providing specialized tools for effective production management. For detailed information, please refer to the specific sub-sections linked below.

::::card-group
::link-card{title="Notifications" description="View notification history, manage retries, and configure multi-channel notification settings like Email and PushKit." icon="bell" href="/en/docs/blocklet-service/user-guide-operations-notifications-4f480d/"}
::link-card{title="Audit Logs" description="Review a comprehensive audit trail of all system activities, with advanced filtering and search capabilities." icon="clock" href="/en/docs/blocklet-service/user-guide-operations-audit-logs-4f480d/"}
::link-card{title="Analytics" description="Analyze traffic, view visitor statistics, and monitor the performance of your blocklet." icon="chart" href="/en/docs/blocklet-service/user-guide-operations-analytics-4f480d/"}
::link-card{title="Advanced" description="Perform low-frequency administrative tasks such as ownership transfer, vault configuration, and cache management." icon="settings" href="/en/docs/blocklet-service/user-guide-operations-advanced-4f480d/"}
::::

By leveraging these tools, administrators can ensure their applications run smoothly, securely, and efficiently.

---

## Advanced

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-operations-advanced-4f480d/

The Advanced settings section provides administrators with access to powerful, low-frequency administrative functions. These tools are intended for critical system-level tasks and should be used with a clear understanding of their impact. This area centralizes configurations for ownership, security, and data management.

![Advanced Settings](https://media.arcblock.io/lib/fb/fb4e2bb4ad3ee83c.w1600.webp)

### Key Functions

This section consolidates several critical administrative capabilities that were previously located in what was known as the "danger zone." Each function is designed to give you precise control over the core aspects of your Blocklet Service instance.

::::card-group
::link-card{title="Ownership Transfer" description="Allows the current owner to transfer complete control and ownership of the service to another DID. This is a permanent action that reassigns all administrative privileges." icon="user"}
::link-card{title="Vault Configuration" description="Manage the configuration of the underlying data vault. This may include settings related to data storage, encryption, and access policies for sensitive information." icon="archive"}
::link-card{title="DID Rotation" description="Facilitates the process of rotating the Decentralized Identifier (DID) associated with the service. This is a critical security practice to mitigate risks associated with key compromise." icon="refresh"}
::link-card{title="Cache Management" description="Provides tools to clear or purge system caches. This is useful for ensuring configuration changes are applied immediately or for resolving potential data consistency issues." icon="cpu"}
::link-card{title="Deletion Protection" description="A safety feature that, when enabled, prevents the accidental or unauthorized deletion of the entire service instance. It acts as a safeguard against irreversible data loss." icon="shield-check"}
::::

### Summary

The Advanced settings panel is a vital tool for administrators responsible for the long-term health and security of the Blocklet Service. It offers direct control over fundamental aspects of the service's identity, data, and lifecycle. Due to the critical nature of these functions, it is imperative to exercise caution and ensure you have a complete understanding of the consequences before making any changes.

---

## Analytics

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-operations-analytics-4f480d/

The Analytics section provides essential tools for understanding your blocklet's performance and user engagement. It allows administrators to monitor web traffic, analyze visitor statistics, and gain insights into the overall operational health of their service. These metrics are crucial for making informed decisions, optimizing resources, and identifying potential issues before they impact users.

## Key Features

The Analytics dashboard visualizes key performance indicators (KPIs) through a series of time-based graphs, offering a clear and concise overview of your blocklet's activity.

- <strong>Traffic Analysis</strong>: Track the total number of requests your blocklet receives over a selected period. This helps in understanding peak usage times and overall traffic patterns.
- <strong>Visitor Statistics</strong>: Monitor the number of unique visitors to your application. This metric is vital for gauging user growth and reach.
- <strong>Performance Monitoring</strong>: Keep an eye on important operational metrics such as the rate of failed requests and the total log size. This data can help you proactively identify and address performance bottlenecks or errors.

![The Analytics dashboard displays key metrics in a grid of graphs.](https://media.arcblock.io/lib/e7/e74fc0b3cd5eb4a8.w1600.webp)

## How It Works

The analytics functionality is designed for services running in a production environment to ensure the data reflects real-world usage. When an administrator selects a specific date in the Analytics dashboard, the system performs the following steps:

::::steps
:::step{title="Verifies Environment"}
It first checks if the blocklet is running in 'production' mode. Analytics data is not available for development environments.
:::

:::step{title="Locates Report"}
The system looks for a pre-generated daily report file corresponding to the selected date. These reports are compiled periodically from server logs.
:::

:::step{title="Renders Data"}
If the report for the specified date exists, it is retrieved and displayed to the administrator in the form of charts and statistics. If no report is found, or if the blocklet is not in production, a notification is displayed instead.
:::
::::

This process ensures that you get an accurate and persistent record of your blocklet's performance for any given day.

![Analytics](https://media.arcblock.io/lib/2c/2c5f3d6ba021846b.w1600.webp)

---

## Audit Logs

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-operations-audit-logs-4f480d/

The Audit Logs service provides administrators with a comprehensive and chronological record of all activities that occur within the system. This feature is essential for maintaining security, ensuring compliance, and troubleshooting operational issues. By tracking events such as user logins, configuration changes, and other significant actions, the audit trail offers a clear and searchable history of system usage.

## Navigating to Audit Logs

To access the audit trail, navigate to the main dashboard of your Blocklet Service and follow these steps:

1. Select <strong>Operations</strong> from the primary navigation menu.
2. Click on the <strong>Audit Logs</strong> sub-menu item.

This will take you to the main Audit Logs page, where all recorded system events are displayed.

## Understanding the Audit Log Interface

The Audit Logs interface is designed to provide a clear and detailed view of system activities. The main component is a table that lists all log entries in reverse chronological order, with the most recent events appearing at the top.

![The Audit Logs interface displaying a list of user login events.](https://media.arcblock.io/lib/8e/8e649118f1f58b8a.w1600.webp)

Each entry in the audit log table contains key information to help you understand the event:

- <strong>User:</strong> The user or system process that performed the action.
- <strong>Action:</strong> A description of the event that occurred (e.g., "User logged in").
- <strong>Timestamp:</strong> The exact date and time when the event was recorded.

## Key Features

The Audit Logs service includes powerful tools to help you efficiently navigate and analyze the data.

### Advanced Filtering and Search

To quickly locate specific events, you can use the filtering and search capabilities. This allows you to narrow down the log entries based on various criteria, such as:

- <strong>Date Range:</strong> Filter logs to view events that occurred within a specific period.
- <strong>User:</strong> Isolate all activities performed by a particular user.
- <strong>Action Type:</strong> Search for specific types of events, such as logins, updates, or deletions.

### Detailed Log Inspection

For a more in-depth understanding of an event, you can inspect the details of any log entry. Clicking on a specific log in the table will open a detailed view, providing additional context and data related to the event. This can include information like the user's IP address, the specific resource that was affected, and the before-and-after state of any changes.

## Common Use Cases

Administrators can leverage the Audit Logs for several critical operational tasks:

- <strong>Security Monitoring:</strong> Actively monitor for suspicious activities, such as multiple failed login attempts or unauthorized access to sensitive areas.
- <strong>Compliance and Auditing:</strong> Generate reports and provide evidence of system activity to meet internal policies or external regulatory requirements.
- <strong>Troubleshooting:</strong> Investigate issues by reconstructing the sequence of events that led to a problem, helping to identify the root cause more quickly.
- <strong>User Activity Review:</strong> Track actions performed by specific users to ensure they are complying with established protocols and permissions.

## Summary

The Audit Logs feature is an indispensable tool for administrators responsible for the security and stability of the Blocklet Service. It provides a transparent and searchable record of all system activities, enabling effective monitoring, streamlined troubleshooting, and rigorous compliance. Regularly reviewing audit logs is a best practice for maintaining a secure and well-managed operational environment.

---

## Notifications

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-operations-notifications-4f480d/

## Overview

The Notifications section provides a centralized interface for administrators to monitor and manage all outgoing communications from the system. It allows you to track the delivery status of messages across multiple channels, review historical data, and manage notification settings to ensure reliable communication with your users. This is essential for operational oversight and for diagnosing any issues related to message delivery.

From this dashboard, you can view a comprehensive history of all notifications sent, check whether they were successfully delivered via channels such as DID Wallet, Email, or PushKit, and retry sending any messages that may have failed.

The following diagram illustrates the notification workflow from the administrator to the end-user:

![Notifications](https://media.arcblock.io/lib/b9/b96be948a99091a4.w1600.webp)

## Notification History

The main view of the Notifications section is a detailed log of all notifications that have been sent. This historical list provides transparency and allows you to audit communications effectively.

![The Notifications section displays a history of all sent notifications, detailing the sender, receiver, delivery channels, a preview of the message, its severity, and the creation time.](https://media.arcblock.io/lib/4c/4c9bbd1e264cadeb.w1600.webp)

The notification list is presented in a table with the following columns:

| Column  | Description  |
|---|---|
| <strong>FROM</strong>  | Indicates the sender of the notification, which is typically a system component or a specific blocklet.  |
| <strong>TO</strong>  | The intended recipient of the notification, identified by their name or DID.  |
| <strong>CHANNELS</strong>  | Shows the delivery status across the different configured channels (e.g., Wallet, Push, Email). Icons indicate success, failure, or pending status for each channel.  |
| <strong>PREVIEW</strong>  | A short snippet of the notification content, allowing you to quickly understand the message's purpose.  |
| <strong>SEVERITY</strong>  | The priority level of the notification, such as `info`, `warning`, or `error`, which helps in categorizing and filtering messages.  |
| <strong>CREATED</strong>  | The exact date and time when the notification was generated.  |

You can use the date filter at the top of the page to narrow down the list and find notifications sent within a specific time frame.

## Multi-Channel Delivery

The Blocklet Service is equipped with a multi-channel notification system to ensure messages reach users effectively. A single event can trigger notifications across several channels simultaneously. The primary channels include:

- <strong>DID Wallet</strong>: Sends a direct message to the user's ABT Wallet. This is the most common and reliable method for users who have connected their wallet.
- <strong>Email</strong>: Delivers a notification to the user's registered email address. This requires an email service to be configured in the system settings.
- <strong>PushKit</strong>: Sends a push notification to a user's mobile device via services like Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM). This is effective for engaging users of mobile applications.

The system intelligently routes messages based on user preferences and available contact information, and the <strong>CHANNELS</strong> column in the history log provides a clear status for each delivery attempt.

## Managing Notifications

In addition to viewing history, the Notifications section provides tools for managing message delivery. If a notification fails to send on a particular channel, you will have the option to <strong>retry</strong> the delivery. This is particularly useful for transient network issues or temporary service unavailability.

## Summary

The Notifications section is a vital tool for administrators responsible for operational management. It offers a clear and detailed overview of all user-facing communications, supports reliable multi-channel delivery, and provides the necessary tools to manage and troubleshoot notification issues.

---

## Website

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-website-4f480d/

The Website service provides a centralized control panel for administrators to manage all aspects of a site's public-facing presentation. This includes configuring custom domains, customizing branding elements like logos and metadata, defining visual themes with specific color palettes and typography, and structuring the site's navigation menus. By consolidating these settings, the service simplifies the process of creating a consistent and professional user experience that aligns with your brand identity.

![Website](https://media.arcblock.io/lib/0f/0f63b95335aef594.w1600.webp)

The Website service is organized into four main areas, each dedicated to a specific aspect of your site's appearance and accessibility. For detailed instructions on each area, please refer to the corresponding sub-document.

::::card-group
::link-card{title="Domains" description="Configure custom domains, manage URL mapping, and set up routing rules to ensure users can access your services through a professional web address." icon="globe" href="/en/docs/blocklet-service/user-guide-website-domains-4f480d/"}
::link-card{title="Branding" description="Customize your application's title, description, logo, and OpenGraph metadata to establish a strong brand identity." icon="star" href="/en/docs/blocklet-service/user-guide-website-branding-4f480d/"}
::link-card{title="Theming" description="Adjust typography and color schemes to create a consistent and visually appealing design that matches your brand's aesthetic." icon="palette" href="/en/docs/blocklet-service/user-guide-website-theming-4f480d/"}
::link-card{title="Navigation" description="Configure the primary and footer navigation menus for your site, using a real-time live preview to test and verify changes instantly." icon="navigation" href="/en/docs/blocklet-service/user-guide-website-navigation-4f480d/"}
::::

## Summary

Effectively managing your website's presentation is crucial for building trust and engaging users. The tools within this section allow you to control every aspect of your site's appearance, from its domain and branding to its visual theme and navigation structure.

For more detailed guides on each function, please proceed to the relevant sections:

- [<strong>Domains</strong>](/en/docs/blocklet-service/user-guide-website-domains-4f480d/)
- [<strong>Branding</strong>](/en/docs/blocklet-service/user-guide-website-branding-4f480d/)
- [<strong>Theming</strong>](/en/docs/blocklet-service/user-guide-website-theming-4f480d/)
- [<strong>Navigation</strong>](/en/docs/blocklet-service/user-guide-website-navigation-4f480d/)

---

## Branding

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-website-branding-4f480d/

The Branding section allows administrators to customize the application's visual identity to align with their brand. Proper branding ensures a consistent and professional user experience across the application. This includes setting the application's name, description, logos, and the metadata used when sharing links on social media.

This guide provides a step-by-step process for configuring your application's branding settings.

![A screenshot of the Branding settings page, showing fields for App Name, Description, URL, Copyright, and logos for light and dark modes.](https://media.arcblock.io/lib/51/51c9613bfd8be845.w1600.webp)

## Basic Information

This area is for defining the core identity of your application.

- **App Name** `string` *(required)* — The official name of your application, displayed in the browser tab, title bars, and throughout the user interface.
- **Description** `string` — A brief summary of your application's purpose. This description is often used by search engines and may be displayed in search results.
- **URL** `string` *(required)* — The primary web address for your application.
- **Copyright** `string` — The copyright notice, which typically includes the year and the name of the organization. This is usually displayed in the site's footer.
- **Supported Languages** `array` — Configure the languages available to users. You can set a default language and add others to provide a localized experience for a global audience.

## Logo Configuration

Logos are a critical component of your brand's visual identity. You can upload different versions of your logo to ensure it looks great in various contexts.

- <strong>App Logo (Light Mode)</strong>: Upload the version of your logo that is designed to be displayed on light or white backgrounds.
- <strong>App Logo (Dark Mode)</strong>: Upload a version of your logo that is optimized for dark or black backgrounds. This ensures visibility and aesthetic consistency when users enable a dark theme.

The interface provides a preview for both light and dark modes, allowing you to see how the logo will appear before saving the changes.

## OpenGraph Metadata

OpenGraph is a protocol that enables any web page to become a rich object in a social graph. When a user shares a link from your application on platforms like Facebook, X (formerly Twitter), or LinkedIn, the platform uses OpenGraph metadata to display a preview card with a title, description, and image.

- **OG Title** `string` — The title that will be displayed in the social media preview card. If left blank, the application's name is typically used as a fallback.
- **OG Description** `string` — The description that will appear in the preview card. It should be a concise and compelling summary to encourage clicks.
- **OG Background Image** `string` — Upload an image that will be displayed in the preview card. This image should be visually appealing and relevant to your brand or the content being shared.

## Summary

By carefully configuring these branding settings, you can create a polished and professional appearance for your application. This not only reinforces your brand identity but also improves user trust and provides a better experience when your application's links are shared across the web.

---

## Domains

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-website-domains-4f480d/

Proper domain configuration is fundamental to establishing your website's brand identity and ensuring users can easily access your services. This section allows you to manage the domains associated with your site, from using automatically assigned default domains to connecting your own custom domains and defining specific URL routing rules.

## How Domain Routing Works

When a user visits your domain, the request is first directed to the Blocklet Service gateway. The gateway then consults the URL mapping and routing rules you have configured. Based on these rules, it forwards the request to the appropriate blocklet that is responsible for handling that specific URL path.

![Domains](https://media.arcblock.io/lib/5c/5c7cae89e1f9c268.w1600.webp)

## Domain Management

The Domains management interface provides a centralized location for all domain-related configurations.

![Domain management interface in Blocklet Service](https://media.arcblock.io/lib/c5/c52a24fb5209311c.w1600.webp)

### Key Features

- <strong>Default Domains</strong>: Every site is automatically assigned a default domain upon creation. This allows you to access and test your site immediately without needing to configure a custom domain first.
- <strong>Custom Domains</strong>: To create a professional and branded presence, you can connect your own domains. This involves updating your domain's DNS records to point to the Blocklet Service.
- <strong>URL Mapping</strong>: This powerful feature allows you to direct traffic from specific URL paths to different blocklets. For example, you can route `your-domain.com/blog` to your blogging blocklet and `your-domain.com/shop` to your e-commerce blocklet, all under a single, unified domain.

## How to Configure a Custom Domain

Follow these steps to connect a domain you own to your site:

::::steps
:::step{title="Navigate to Domains"}
From the sidebar, select <strong>Website</strong>, then click on <strong>Domains</strong>.
:::

:::step{title="Add Domain"}
Click the "Configure Domain" or a similar button to start the process.
:::

:::step{title="Enter Your Domain"}
Input the domain name you wish to add (e.g., `www.your-company.com`).
:::

:::step{title="Update DNS Records"}
The system will provide you with the necessary DNS information (typically a CNAME or A record). You must log in to your domain registrar's control panel (e.g., GoDaddy, Namecheap, Cloudflare) and add this record.
:::

:::step{title="Verification"}
After you save the DNS record, it may take some time for the changes to propagate across the internet. Blocklet Service will periodically check for the record and, once found, will mark your domain as "Verified."
:::
::::

## How to Set Up URL Mapping

Once your domain is verified, you can create specific routing rules:

1. <strong>Select a Domain</strong>: In the domain list, find the domain you want to configure.
2. <strong>Access Routing Rules</strong>: Click on the domain or a "Manage" button to find the "URL Mapping" or "Routing Rules" section.
3. <strong>Create a New Rule</strong>: Click the "Add Rule" button.
4. <strong>Define the Rule</strong>:
5.
  - <strong>Source Path</strong>: Enter the incoming URL path you want to match (e.g., `/blog`, `/store/products`).
  - <strong>Destination</strong>: From the dropdown list, select the blocklet that should handle requests for that path.
6. <strong>Save the Rule</strong>: Save your changes to activate the new routing rule. All subsequent requests matching the source path will be directed to the selected blocklet.

## Summary

Managing your domains and URL mappings effectively is essential for structuring your website, improving user navigation, and building a strong brand. The tools provided in this section give you complete control over how users access the different services and blocklets that make up your application.

---

## Navigation

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-website-navigation-4f480d/

The Navigation section provides administrators with the tools to configure and manage the navigation menus for the website. This includes creating, editing, and organizing menu items that appear in locations such as the site header and footer. A key feature is the live preview, which allows for real-time testing of any changes before they are published to the live site.

## Key Features

- <strong>Menu Configuration</strong>: Add, edit, reorder, and delete navigation links.
- <strong>Live Preview</strong>: Instantly visualize changes to the navigation structure as you make them.
- <strong>Support for Multiple Menus</strong>: Manage different navigation areas, such as main navigation and footer social links, independently.

## Configuring Navigation Menus

The navigation management interface is designed for clarity and ease of use. Administrators can modify the structure and content of various menus directly from the dashboard.

The process for configuring a navigation menu is as follows:

1. <strong>Navigate to the Section</strong>: Access the navigation settings by selecting <strong>Website > Navigation</strong> from the main dashboard menu.
2. <strong>Select a Menu</strong>: Choose the specific menu you wish to edit from the available options (e.g., "Footer Social").
3. <strong>Modify Menu Items</strong>:
4.
  - <strong>To Add a New Link</strong>: Click the "Add" or "Create" button to open a form for a new menu item. You will typically need to provide a label (the text that is displayed) and a URL (the destination link).
  - <strong>To Edit an Existing Link</strong>: Select the item you wish to change. The editing interface will allow you to modify its label, URL, or other properties.
  - <strong>To Reorder Links</strong>: Use drag-and-drop functionality or reordering arrows to change the position of a menu item.
5. <strong>Preview Changes</strong>: As you make modifications, the live preview pane, located alongside the configuration options, will update in real-time to reflect the new structure. This allows for immediate visual confirmation of your changes.
6. <strong>Save Configuration</strong>: Once you are satisfied with the changes as shown in the preview, click the "Save Changes" button to apply them to your website.

The following image shows the configuration interface for the "Footer Social" menu, where an administrator can manage links to social media platforms.

![Screenshot of the Navigation settings interface, showing the configuration for footer social media links.](https://media.arcblock.io/lib/fc/fc5e1182f976b101.w1600.webp)

## Navigation Configuration Workflow

The diagram below illustrates the standard workflow for updating a website navigation menu, from accessing the settings to publishing the final changes. This process ensures that modifications can be reviewed for accuracy before going live.

![Navigation](https://media.arcblock.io/lib/cc/ccd9d72d314f06ec.w1600.webp)

This diagram shows a standard workflow for updating a website navigation menu. It starts with accessing the navigation settings, followed by selecting and modifying a menu. The user then reviews these changes in a live preview. If the changes are satisfactory, they are saved and published; otherwise, the user can return to modify the menu items until they are correct. This iterative process ensures that all changes are verified before going live.

---

## Theming

URL: https://www.arcblock.io/en/docs/blocklet-service/user-guide-website-theming-4f480d/

The Theming section provides administrators with granular control over the visual appearance of their website, ensuring a consistent and on-brand user experience. By adjusting typography, color schemes, and other stylistic elements, you can tailor the site's design to match your organization's identity precisely.

This guide will walk you through the various customization options available on the Theming page.

![Theming configuration page, showing color palette, typography, and border radius settings with a live preview pane.](https://media.arcblock.io/lib/ca/ca1f71cd55c8022c.w1600.webp)

## Color Palette

A consistent color palette is fundamental to your website's design. The system allows you to define a comprehensive set of colors that will be applied globally across the user interface.

The color palette is organized into logical groups:

- <strong>Neutrals</strong>: A grayscale range from pure white to black, used for backgrounds, borders, and text.
- <strong>Semantic Colors</strong>: Colors that carry specific meanings to the user.
-
  - <strong>Primary</strong>: The main brand color, used for primary buttons, links, and important interface elements.
  - <strong>Secondary</strong>: An accent color used to complement the primary color.
  - <strong>Success</strong>: Indicates a successful operation (e.g., a confirmation message).
  - <strong>Warning</strong>: Alerts users to potential issues or actions that require caution.
  - <strong>Error</strong>: Signals that an error has occurred.
  - <strong>Info</strong>: Used for informational messages or alerts.

To customize a color, simply click on the color swatch and enter a valid hexadecimal (hex) color code (e.g., `#007BFF`).

## Typography

Typography settings control the appearance of all text on your website, ensuring readability and brand alignment. You can set distinct font families for different text elements.

- <strong>Headings Font</strong>: The font used for all heading levels (e.g., H1, H2, H3). This is typically a more stylized or bold font to create a visual hierarchy.
- <strong>Body Font</strong>: The font used for paragraphs, labels, and other general text content. This font should be optimized for readability.

Select your desired fonts from the dropdown menus provided.

## Border Radius

Border radius settings allow you to control the roundness of corners on various UI elements like buttons, cards, and input fields. This subtle detail can significantly impact the overall look and feel of your site, from sharp and modern (a small radius) to soft and friendly (a larger radius). You can select a predefined radius style that best fits your design aesthetic.

## Live Preview

To facilitate the design process, a real-time live preview pane is displayed on the right side of the settings panel. As you modify colors, fonts, or border radii, the preview pane instantly updates to reflect your changes. This allows you to experiment with different styles and see the immediate impact on your website's appearance before committing to and saving the changes.

---

## Blocklet Spec

URL: https://www.arcblock.io/en/docs/blocklet-spec/

---

## API Reference

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-988441/

The `@blocklet/meta` library provides a comprehensive suite of utility functions for programmatically interacting with `blocklet.yml` metadata. These helpers streamline common tasks such as parsing, validation, data manipulation, and security operations. Whether you are building development tools, custom blocklet runtimes, or applications that interact with the Blocklet ecosystem, these APIs provide the necessary building blocks.

This section serves as a detailed reference for all exported functions, grouped by their core functionality. For a complete understanding of the metadata structure these functions operate on, please refer to the [Blocklet Specification (blocklet.yml)](/en/docs/blocklet-spec/spec-988441/).

Explore the categories below to find the specific functions you need. Each section provides detailed explanations, parameters, and usage examples to help you get started quickly.

::::card-group
::link-card{title="Parsing & Validation" description="Functions for reading, parsing, and validating `blocklet.yml` files. Includes `parse`, `validateMeta`, `fixAndValidateService`, and other validation helpers." icon="search" href="/en/docs/blocklet-spec/api-parsing-validation-988441/"}
::link-card{title="Metadata Helpers" description="Utilities for fetching and processing blocklet metadata from remote URLs. Includes `getBlockletMetaByUrl` and `getSourceUrlsFromConfig`." icon="file" href="/en/docs/blocklet-spec/api-metadata-helpers-988441/"}
::link-card{title="Component & State Utilities" description="A collection of helper functions for working with blocklet state objects, such as traversing component trees, finding specific components, and extracting information." icon="box" href="/en/docs/blocklet-spec/api-component-state-utilities-988441/"}
::link-card{title="DID & Wallet Utilities" description="Functions for handling DIDs and wallets within the blocklet context, including creating blocklet-specific DIDs, generating wallets, and extracting user information." icon="wallet" href="/en/docs/blocklet-spec/api-did-wallet-utilities-988441/"}
::link-card{title="Security Utilities" description="Functions for cryptographic operations, such as signing responses, verifying signatures, and managing multi-signature verification for metadata." icon="shield-check" href="/en/docs/blocklet-spec/api-security-utilities-988441/"}
::link-card{title="Navigation Utilities" description="Functions for parsing and processing the `navigation` property from a blocklet's metadata and state to build dynamic user interfaces." icon="navigation" href="/en/docs/blocklet-spec/api-navigation-utilities-988441/"}
::link-card{title="URL & Path Utilities" description="Helpers for creating URL-friendly strings and validating URL paths, useful for generating clean and valid routes." icon="link" href="/en/docs/blocklet-spec/api-url-path-utilities-988441/"}
::link-card{title="File Utilities" description="Low-level functions for reading, writing, and locating `blocklet.yml` files on the filesystem, and custom Joi extensions for file validation." icon="file" href="/en/docs/blocklet-spec/api-file-utilities-988441/"}
::link-card{title="Miscellaneous Utilities" description="A collection of other useful utilities, including communication channel helpers and identity icon (Blockies) generation." icon="box" href="/en/docs/blocklet-spec/api-misc-utilities-988441/"}
::::

---

## Component & State Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-component-state-utilities-988441/

The `@blocklet/meta` library provides a comprehensive suite of utility functions designed to simplify interaction with the `BlockletState` object. Blocklets, especially composite ones, are represented as a tree of components. These utilities offer powerful and efficient ways to traverse this tree, find specific components, check their status, and extract critical information for runtime operations, UI rendering, and administrative tasks.

This section covers functions for tree traversal, component searching, status checking, configuration management, and information extraction.

## Tree Traversal

These functions allow you to iterate over the component tree of a blocklet application. They are fundamental for applying operations to every component or for aggregating data.

### forEachBlocklet & forEachBlockletSync

The core traversal functions. `forEachBlocklet` is asynchronous and can run in serial (default) or parallel, while `forEachBlockletSync` is its synchronous counterpart.

**Function Signature**

```typescript
function forEachBlocklet(
  blocklet: TComponentPro,
  cb: (blocklet: TComponentPro, context: object) => any,
  options?: {
    parallel?: boolean;
    concurrencyLimit?: number;
    sync?: boolean;
  }
): Promise<any> | null;

function forEachBlockletSync(
  blocklet: any,
  cb: Function
): void;
```

The callback function `cb` receives the current component and a context object containing `{ parent, root, level, ancestors, id }`.

<strong>Example: Collecting all component DIDs</strong>

```javascript
import { forEachBlockletSync } from '@blocklet/meta/lib/util';

const appState = {
  meta: { did: 'z1' },
  children: [
    { meta: { did: 'z2' } },
    {
      meta: { did: 'z3' },
      children: [{ meta: { did: 'z4' } }],
    },
  ],
};

const allDids = [];
forEachBlockletSync(appState, (component) => {
  if (component.meta?.did) {
    allDids.push(component.meta.did);
  }
});

console.log(allDids);
// Output: ['z1', 'z2', 'z3', 'z4']
```

### forEachChild & forEachChildSync

These are wrappers around `forEachBlocklet` that conveniently iterate over all descendants of a blocklet, skipping the root blocklet itself (where `level > 0`).

## Finding & Filtering Components

Locating specific components within the state tree is a common requirement. These functions provide various ways to find one or more components based on different criteria.

### findComponent

A generic search function that traverses the component tree and returns the first component that satisfies the provided predicate function.

**Function Signature**

```typescript
function findComponent(
  blocklet: TComponent,
  isEqualFn: (component: TComponent, context: { ancestors: Array<TComponent> }) => boolean
): TComponent | null;
```

<strong>Example: Find a component by its</strong> <strong>`bundleName`</strong>

```javascript
import { findComponent } from '@blocklet/meta/lib/util';

const appState = {
  meta: { did: 'z1', bundleName: 'app' },
  children: [
    { meta: { did: 'z2', bundleName: 'component-a' } },
    { meta: { did: 'z3', bundleName: 'component-b' } },
  ],
};

const componentB = findComponent(
  appState,
  (component) => component.meta?.bundleName === 'component-b'
);

console.log(componentB.meta.did);
// Output: 'z3'
```

### findComponentById

A specialized version of `findComponent` that finds a component by its unique composite ID (e.g., `app-did/component-did`).

**Function Signature**

```typescript
function findComponentById(
  blocklet: TComponent,
  componentId: string | string[]
): TComponent | null;
```

### filterComponentsV2

Iterates over the direct children of an app and returns an array of all components that satisfy the predicate function.

## Identity & Naming

These utilities help in generating and retrieving various identifiers and names for components within the application state.

| Function  | Description  |
|---|---|
| `getComponentId`  | Constructs a unique, path-based ID for a component using its ancestors' DIDs (e.g., `root_did/child_did`).  |
| `getComponentName`  | Constructs a unique, path-based name for a component using its ancestors' names.  |
| `getParentComponentName`  | Extracts the parent component's name from a given component name path.  |
| `getAppName`  | Retrieves the display name of a blocklet, prioritizing the `BLOCKLET_APP_NAME` environment variable over metadata.  |
| `getAppDescription`  | Retrieves the description of a blocklet, prioritizing `BLOCKLET_APP_DESCRIPTION`.  |
| `getComponentProcessId`  | Generates a filesystem-safe process ID for a component, using MD5 hashing for long names to prevent filesystem errors.  |

## Configuration & State Management

Managing configuration, especially in composite blocklets where settings can be shared, is crucial. These helpers simplify the process.

### getSharedConfigObj

Calculates the shared configuration object for a specific component within an application. It intelligently merges configurations from the parent application and sibling components that are marked as `shared: true`.

### getAppMissingConfigs & getComponentMissingConfigs

These functions are vital for validation. They scan an application or a single component and return a list of all configurations that are marked as `required: true` but have not been assigned a value, either directly or through the shared configuration mechanism.

<strong>Example: Checking for missing configurations</strong>

```javascript
import { getAppMissingConfigs } from '@blocklet/meta/lib/util';

const appWithMissingConfig = {
  meta: { did: 'z1' },
  children: [
    {
      meta: { did: 'z2' },
      configs: [
        { key: 'API_KEY', required: true, value: null, description: 'Service API Key' },
      ],
    },
  ],
};

const missing = getAppMissingConfigs(appWithMissingConfig);

console.log(missing);
// Output: [{ did: 'z2', key: 'API_KEY', description: 'Service API Key' }]
```

### wipeSensitiveData

A security-focused utility that creates a deep clone of a blocklet state object and redacts all sensitive information. It replaces values of fields marked `secure: true` and certain sensitive environment variables (like `BLOCKLET_APP_SK`) with `__encrypted__`.

## Status Checks

These boolean functions provide a simple way to check the current status of a blocklet or component without needing to handle the raw status codes directly.

| Function  | Description  | Corresponding Statuses  |
|---|---|---|
| `isRunning`  | Checks if the component is in a stable, running state.  | `running`  |
| `isInProgress`  | Checks if the component is in a transitional state.  | `downloading`, `installing`, `starting`, `stopping`, `upgrading`, etc.  |
| `isBeforeInstalled`  | Checks if the component has not yet completed its first installation.  | `added`, `waiting`, `downloading`, `installing`  |
| `isAccessible`  | Checks if the component's web interface might be accessible.  | `running`, `waiting`, `downloading`  |

## Interface & Service Discovery

Utilities for finding interfaces and services defined in a blocklet's metadata.

| Function  | Description  |
|---|---|
| `findWebInterface`  | Finds the first interface of type `web` in a component's metadata.  |
| `findDockerInterface`  | Finds the first interface of type `docker` in a component's metadata.  |
| `findWebInterfacePort`  | Retrieves the host port mapped to the component's web interface.  |
| `getBlockletServices`  | Returns a flattened list of all services defined across all components in a blocklet, including their name, protocol, and port details.  |

## Information Extraction

These functions extract specific, processed information from the raw blocklet state.

### getComponentsInternalInfo

This function traverses a blocklet application and returns a structured array containing key internal details for each component. This is extremely useful for system management and inter-service communication.

<strong>Returns</strong>

- **components** `array` — An array of internal component information objects.
  - **title** `string` — The display title of the component.
  - **did** `string` — The unique DID of the component.
  - **name** `string` — The machine-readable name of the component.
  - **version** `string` — The version of the component.
  - **mountPoint** `string` — The URL path where the component is mounted.
  - **status** `number` — The numerical status code of the component.
  - **port** `number` — The host port assigned to the component's web interface.
  - **containerPort** `string` — The internal container port for the web interface.
  - **resourcesV2** `array` — A list of resource assets bundled with the component.
    - **path** `string` — The absolute path to the resource.
    - **public** `boolean` — Indicates if the resource is publicly accessible.
  - **group** `string` — The functional group of the component (e.g., 'gateway', 'dapp').

### getMountPoints

Scans the entire component tree and returns a structured list of all components that have a mount point, making it easy to build navigation or routing tables.

### getAppUrl

Determines the primary, user-facing URL for a blocklet application by analyzing its `site.domainAliases`. It intelligently sorts the domains to prioritize accessible, non-protected URLs.

## Miscellaneous Utilities

A collection of other useful checks and helpers.

| Function  | Description  |
|---|---|
| `isFreeBlocklet`  | Checks if a blocklet has a payment price of zero.  |
| `isDeletableBlocklet`  | Checks if a blocklet is allowed to be deleted based on the `BLOCKLET_DELETABLE` environment variable.  |
| `hasRunnableComponent`  | Determines if the application contains any non-gateway components that can be run.  |
| `isExternalBlocklet`  | Checks if the blocklet is managed by an external controller.  |
| `isGatewayBlocklet`  | Checks if the component's group is `gateway`.  |
| `isPackBlocklet`  | Checks if the component's group is `pack`.  |
| `hasStartEngine`  | Checks if the component's metadata defines a startable engine (e.g., `main` or `docker.image`).  |
| `hasMountPoint`  | Determines if a component should have a mount point based on its configuration.  |
| `getBlockletChainInfo`  | Extracts and consolidates chain configuration (type, id, host) from the blocklet and its children.  |
| `checkPublicAccess`  | Checks if the blocklet's security configuration allows for public access.  |

---

## DID & Wallet Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-did-wallet-utilities-988441/

This section provides a detailed reference for utility functions related to Decentralized Identifiers (DIDs) and cryptographic wallets. These helpers are essential for managing a Blocklet's identity, generating application-specific wallets, and extracting identity information from user sessions.

## Blocklet Identity & Wallet Generation

These functions are used to create and manage the core identity and cryptographic wallet of the Blocklet itself.

### toBlockletDid

Converts a string or a Buffer into a valid Blocklet DID. If the input is already a valid DID, it is returned as is. Otherwise, it generates a DID of type `ROLE_ANY` from the input.

<strong>Parameters</strong>

- **name** `string | Buffer` *(required)* — The string or buffer to be converted into a DID.

<strong>Returns</strong>

- **did** `string` — A valid DID.

<strong>Example</strong>

**toBlockletDid Example**

```javascript
import toBlockletDid from '@blocklet/meta/lib/did';

// Generate a DID from a string name
const blockletName = 'my-awesome-blocklet';
const did = toBlockletDid(blockletName);

console.log(did); // e.g., 'z8ia1m4f5z3a...'

// It also works with existing valid DIDs
const existingDid = 'z8iZge7d4a4s9d5z...';
const result = toBlockletDid(existingDid);

console.log(result === existingDid); // true
```

### getApplicationWallet

Generates a wallet object for the Blocklet. This is a critical function for any operation that requires signing, such as authenticating with other services or creating verifiable credentials. The wallet can be derived either from the Blocklet's DID in combination with the node's secret key or directly from a custom secret key provided as an environment variable.

<strong>Parameters</strong>

- **didOrSk** `string` *(required)* — The Blocklet's DID or a custom secret key. If it's not a valid DID, it's treated as a secret key.
- **nodeSk** `string` — Required if didOrSk is a DID. The secret key of the underlying Blocklet Server node.
- **type** `DIDType | 'default' | 'eth' | 'ethereum'` — The type of wallet to generate. Supports 'ethereum' or 'eth' for Ethereum-compatible wallets. Defaults to the standard ArcBlock type.
- **index** `number` (default: `0`) — The derivation index, used when generating the wallet from a DID and node SK.

<strong>Returns</strong>

- **wallet** `WalletObject` — An OCAP wallet object with address, publicKey, secretKey, and signing methods.

<strong>Example: Generating from DID and Node SK</strong>

**Generating from DID**

```javascript
import getApplicationWallet from '@blocklet/meta/lib/wallet';

const blockletDid = 'z8iZ...'; // The Blocklet's DID from its metadata
const nodeSk = '...'; // The secret key of the Blocklet Server node

const wallet = getApplicationWallet(blockletDid, nodeSk);

console.log('Wallet Address:', wallet.address);
console.log('Wallet Type:', wallet.type);
```

<strong>Example: Generating from a Custom SK</strong>

**Generating from Custom SK**

```javascript
import getApplicationWallet from '@blocklet/meta/lib/wallet';

// Typically loaded from process.env.BLOCKLET_APP_SK
const customSk = '...';
const wallet = getApplicationWallet(customSk);

console.log('Wallet Address:', wallet.address);
```

### getBlockletInfo

This is a high-level utility that parses a Blocklet's state object to extract a comprehensive set of metadata and, optionally, generate its wallet. It consolidates information from `blocklet.yml`, environment variables, and server configurations.

<strong>Parameters</strong>

- **state** `BlockletState` *(required)* — The Blocklet's state object, typically available in a Blocklet's backend hooks or routes.
- **nodeSk** `string` — The secret key of the Blocklet Server node. Required if returnWallet is true and a custom SK is not set in the environment.
- **options** `object` — Configuration options.
  - **returnWallet** `boolean` (default: `true`) — If true, the function will generate and include the wallet and permanentWallet objects.

<strong>Returns</strong>

- **info** `object` — An object containing the Blocklet's information.
  - **did** `string` — Blocklet's DID from meta.did.
  - **name** `string` — Display name of the Blocklet.
  - **version** `string` — Blocklet version.
  - **description** `string` — Blocklet description.
  - **appUrl** `string` — The configured application URL.
  - **secret** `string` — A derived secret hash for session management.
  - **wallet** `WalletObject | null` — The primary application wallet (null if returnWallet is false).
  - **permanentWallet** `WalletObject | null` — A permanent wallet if BLOCKLET_APP_PSK is set, otherwise same as wallet.
  - **passportColor** `string` — Color scheme for the passport.
  - **tenantMode** `string` — The tenant mode of the application.

<strong>Example</strong>

**getBlockletInfo Example**

```javascript
import getBlockletInfo from '@blocklet/meta/lib/info';

// Assuming 'blockletState' and 'nodeSk' are available in your context

try {
  const info = getBlockletInfo(blockletState, nodeSk);

  console.log(`Blocklet Name: ${info.name}`);
  console.log(`Blocklet DID: ${info.did}`);
  console.log(`App Wallet Address: ${info.wallet.address}`);

  // When wallet is not needed
  const infoWithoutWallet = getBlockletInfo(blockletState, nodeSk, { returnWallet: false });
  console.log(infoWithoutWallet.wallet); // null
} catch (error) {
  console.error('Failed to get Blocklet info:', error.message);
}
```

## User Identity & Account Helpers

These utility functions are designed to easily extract DID and account information from a `UserInfo` object, which is typically available in `req.user` within an authenticated route in a Blocklet.

### User Info Utility Functions

A collection of helpers to access different parts of a user's identity profile.

| Function  | Description  |
|---|---|
| `getPermanentDid(user)`  | Returns the user's primary, permanent DID.  |
| `getConnectedAccounts(user)`  | Returns an array of all accounts connected to the user's profile.  |
| `getConnectedDids(user)`  | Returns an array of DIDs from all connected accounts.  |
| `getWallet(user)`  | Finds and returns the user's connected wallet account object.  |
| `getWalletDid(user)`  | A convenience function to get the DID of the user's connected wallet.  |
| `getSourceProvider(user)`  | Returns the provider the user used for the current session (e.g., `wallet`).  |
| `getSourceProviders(user)`  | Returns an array of all providers the user has connected.  |

<strong>Example</strong>

**User Info Helpers**

```javascript
import {
  getPermanentDid,
  getConnectedDids,
  getWalletDid,
  getSourceProvider,
} from '@blocklet/meta/lib/did-utils';

// Mock UserInfo object (in a real app, this would be req.user)
const mockUser = {
  did: 'z...userPermanentDid',
  sourceProvider: 'wallet',
  connectedAccounts: [
    {
      provider: 'wallet',
      did: 'z...userWalletDid',
      // ... other wallet account details
    },
    {
      provider: 'github',
      did: 'z...userGithubDid',
      // ... other github account details
    },
  ],
  // ... other UserInfo properties
};

const permanentDid = getPermanentDid(mockUser);
console.log('Permanent DID:', permanentDid); // 'z...userPermanentDid'

const walletDid = getWalletDid(mockUser);
console.log('Wallet DID:', walletDid); // 'z...userWalletDid'

const allDids = getConnectedDids(mockUser);
console.log('All Connected DIDs:', allDids); // ['z...userWalletDid', 'z...userGithubDid']

const loginProvider = getSourceProvider(mockUser);
console.log('Logged in with:', loginProvider); // 'wallet'
```

These utilities provide the fundamental building blocks for managing identity and security within your Blocklet. To learn how to use these wallets for signing and verifying data, proceed to the [Security Utilities](/en/docs/blocklet-spec/api-security-utilities-988441/) section.

---

## File Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-file-utilities-988441/

This module provides a set of low-level functions for interacting with `blocklet.yml` files on the filesystem. It includes utilities for locating, reading, and writing metadata files, as well as custom [Joi](https://joi.dev/) extensions to streamline validation for file paths and DIDs.

## blocklet.yml File Handlers

These functions are the core building blocks for any tool that needs to programmatically read or modify a blocklet's metadata file.

### select(dir, options?)

The `select` function intelligently locates the correct `blocklet.yml` or `blocklet.yaml` file within a specified directory.

<strong>Parameters</strong>

- **dir** `string` *(required)* — The absolute path to the directory where the blocklet metadata file is located.
- **options** `object` — Configuration options for the select function.
  - **throwOnError** `boolean` (default: `true`) — If true, an error will be thrown if no metadata file is found. If false, it returns an empty string.

<strong>Returns</strong>

- **metaFilePath** `string` — The full, absolute path to the found metadata file, or an empty string if not found and `throwOnError` is false.

<strong>Example</strong>

**Locating the metadata file**

```javascript
import { select } from '@blocklet/meta';

const blockletDir = '/path/to/your/blocklet';

try {
  const metaFile = select(blockletDir);
  console.log(`Found metadata file at: ${metaFile}`);
} catch (error) {
  console.error(error.message); // e.g., 'blocklet.yml not found...'
}
```

### read(file)

Once you have the file path, the `read` function parses the YAML content into a JavaScript object.

<strong>Parameters</strong>

- **file** `string` *(required)* — The path to the blocklet.yml file to be read.

<strong>Returns</strong>

- **meta** `object` — The parsed content of the YAML file as a JavaScript object.

<strong>Example</strong>

**Reading the metadata file**

```javascript
import { select, read } from '@blocklet/meta';

const metaFile = select('/path/to/your/blocklet');
const meta = read(metaFile);
console.log(`Blocklet name: ${meta.name}`);
```

### update(file, meta, options?)

The `update` function serializes a metadata object back into a YAML file. By default, it cleans the metadata by removing properties that are only relevant at runtime (e.g., `path`, `stats`, `signatures`) before writing.

<strong>Parameters</strong>

- **file** `string` *(required)* — The path to the blocklet.yml file to be updated.
- **meta** `TBlockletMeta` *(required)* — The metadata object to write to the file.
- **options** `object` — Configuration options for the update function.
  - **fix** `boolean` (default: `true`) — If true, cleans the metadata object before writing (e.g., removes `path`, `stats`, `signatures`). If false, writes the object as-is.

<strong>Returns</strong>

This function does not return a value (`void`).

<strong>Example</strong>

**Updating the metadata file**

```javascript
import { select, read, update } from '@blocklet/meta';

const metaFile = select('/path/to/your/blocklet');
let meta = read(metaFile);

// Modify the description
meta.description = 'An updated description for my blocklet.';

// Write the changes back to the file with cleanup
update(metaFile, meta);
console.log('blocklet.yml has been updated.');
```

### list

A simple constant array that contains the potential names for the blocklet metadata file, which `select` uses internally.

<strong>Example</strong>

```javascript
import { list } from '@blocklet/meta';

console.log(list); // Outputs: ['blocklet.yml', 'blocklet.yaml']
```

## Custom Joi Extensions

These extensions integrate with the Joi validation library to provide custom validation types for common Blocklet-related data, such as file paths and DIDs.

### fileExtension

Provides a custom `file()` type for Joi schemas, enabling powerful file-system-aware validations.

<strong>Usage</strong>

First, extend a Joi instance with the `fileExtension`. Then, you can use the `file()` type and its rules in your schemas.

**Joi Schema with fileExtension**

```javascript
import Joi from 'joi';
import path from 'path';
import { fileExtension } from '@blocklet/meta';

// Create a Joi instance extended with our custom types
const customJoi = Joi.extend(fileExtension);

const schema = customJoi.object({
  // Validates that 'logo.png' exists within the project directory
  logoPath: customJoi.file().exists({ baseDir: __dirname }),
});

const { error } = schema.validate({ logoPath: 'logo.png' });
if (error) {
  console.log(error.message); // e.g., 'file "logo.png" does not exist'
}
```

### didExtension

Provides a custom `DID()` type for Joi to validate ArcBlock Decentralized Identifiers.

<strong>Usage</strong>

Extend Joi with `didExtension` to add the `DID()` validation type.

**Joi Schema with didExtension**

```javascript
import Joi from 'joi';
import { didExtension } from '@blocklet/meta';

const customJoi = Joi.extend(didExtension);

const schema = customJoi.object({
  author: customJoi.DID().required(),
});

// Example with an invalid DID
const { error } = schema.validate({ author: 'z123...invalid_did' });
if (error) {
  console.log(error.message); // 'did "z123...invalid_did" is not valid'
}

// Example with a valid DID
const { value } = schema.validate({ author: 'z8iZpbpJ4Yy2LzG1cqK9rC9pZ8r1Yq2Z3t4a' });
console.log(value); // { author: 'z8iZpbpJ4Yy2LzG1cqK9rC9pZ8r1Yq2Z3t4a' }
```

These file utilities form the foundation for many higher-level operations within the Blocklet ecosystem. For more advanced metadata handling, proceed to the [Parsing & Validation](/en/docs/blocklet-spec/api-parsing-validation-988441/) documentation.

---

## Metadata Helpers

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-metadata-helpers-988441/

These utility functions are your toolkit for fetching, processing, and validating Blocklet metadata from remote sources. Whether you're resolving a Blocklet from a store URL or a local file path, these helpers are crucial for any tool or application—like launchers, development tools, or registry services—that needs to interact with Blocklets that aren't available locally.

They are designed to handle the complexities of network requests, caching, validation, and even provide fault tolerance when multiple sources are available.

## Core Fetching Functions

These functions are central to retrieving Blocklet metadata from one or more URLs.

### getBlockletMetaByUrl

This is a foundational function for fetching the raw `blocklet.json` content from a single URL. It supports both `http(s)://` and `file://` protocols. To enhance performance, the results of successful fetches are cached in memory using an LRU cache.

<strong>Parameters</strong>

- **url** `string` *(required)* — The URL (http, https, or file) pointing to the blocklet.json file.

<strong>Returns</strong>

- **** `Promise<TBlockletMeta>` — A promise that resolves to the parsed Blocklet metadata object (TBlockletMeta). It throws an error if the URL is inaccessible or the content is not valid JSON.

<strong>Example</strong>

**Fetching Raw Metadata**

```javascript
import { getBlockletMetaByUrl } from '@blocklet/meta';

async function fetchMeta() {
  const metaUrl = 'https://store.blocklet.dev/api/blocklets/z8ia2vL3A9ACu4p2f2iF9yQWc9BvCzaWwx57p/blocklet.json';
  try {
    const meta = await getBlockletMetaByUrl(metaUrl);
    console.log(`Successfully fetched metadata for: ${meta.name}`);
    return meta;
  } catch (error) {
    console.error('Failed to fetch metadata:', error.message);
  }
}

fetchMeta();
```

### getBlockletMetaFromUrl

This is a higher-level, more robust utility that builds upon `getBlockletMetaByUrl`. It not only fetches the metadata but also performs validation, cleans up the data (e.g., removes `htmlAst`), and optionally ensures the associated `dist.tarball` URL is valid and accessible. This is the recommended function for most use cases.

<strong>Parameters</strong>

- **url** `string` *(required)* — The URL of the blocklet.json file.
- **options** `object` — An optional configuration object.
  - **validateFn** `Function` (default: `validateBlockletMeta`) — A custom function to validate the fetched metadata.
  - **returnUrl** `boolean` (default: `false`) — If true, the function returns an object { meta, url }.
  - **ensureTarball** `boolean` (default: `true`) — If true, the function validates the dist.tarball URL by making a HEAD request.
  - **logger** `object` — A logger instance (e.g., console) for debugging purposes.

<strong>Returns</strong>

- **** `Promise<any>` — A promise that resolves to the validated TBlockletMeta object. If returnUrl is true, it resolves to { meta: TBlockletMeta, url: string }.

<strong>Example</strong>

**Fetching and Validating Metadata**

```javascript
import { getBlockletMetaFromUrl } from '@blocklet/meta';

async function fetchAndValidateMeta() {
  const metaUrl = 'https://store.blocklet.dev/api/blocklets/z8ia2vL3A9ACu4p2f2iF9yQWc9BvCzaWwx57p/blocklet.json';
  try {
    const meta = await getBlockletMetaFromUrl(metaUrl, { ensureTarball: true });
    console.log(`Successfully validated metadata for: ${meta.name}`);
    console.log(`Tarball URL is valid: ${meta.dist.tarball}`);
  } catch (error) {
    console.error('Failed to fetch or validate metadata:', error.message);
  }
}

fetchAndValidateMeta();
```

### getBlockletMetaFromUrls

This function provides fault tolerance by accepting an array of URLs. It attempts to fetch metadata from each URL concurrently and returns the result from the first one that succeeds, leveraging `Promise.any`. This is useful when a Blocklet's metadata might be hosted in multiple locations, such as a primary and a backup registry.

<strong>Parameters</strong>

- **urls** `string[]` *(required)* — An array of URLs to attempt fetching from.
- **options** `object` — The same options object as getBlockletMetaFromUrl.

<strong>Returns</strong>

- **** `Promise<any>` — A promise that resolves with the result from the first successful fetch. If all URLs fail, the promise is rejected with an aggregate error containing the reasons for each failure.

<strong>Example</strong>

**Fetching with Redundancy**

```javascript
import { getBlockletMetaFromUrls } from '@blocklet/meta';

async function fetchWithFallback() {
  const metaUrls = [
    'https://invalid-registry.com/blocklet.json', // This will fail
    'https://store.blocklet.dev/api/blocklets/z8ia2vL3A9ACu4p2f2iF9yQWc9BvCzaWwx57p/blocklet.json' // This will succeed
  ];

  try {
    const { meta, url } = await getBlockletMetaFromUrls(metaUrls, { returnUrl: true });
    console.log(`Successfully fetched metadata for ${meta.name} from ${url}`);
  } catch (error) {
    console.error('All URLs failed:', error.message);
  }
}

fetchWithFallback();
```

## Composition Helpers

These helpers are used for resolving metadata for child Blocklets within a composite application.

### getSourceUrlsFromConfig

This utility is essential for Blocklet composition. When a Blocklet defines `components`, this function parses a component's configuration to generate a list of potential `blocklet.json` URLs. It can interpret various source declarations, including direct URLs, Blocklet Store identifiers, and resolved URLs.

<strong>Parameters</strong>

- **config** `object` *(required)* — A component configuration object from the components section of a blocklet.yml file.

<strong>Returns</strong>

- **** `string[]` — An array of potential metadata URLs for the specified component.

<strong>Example</strong>

**Resolving Component Metadata URLs**

```javascript
import { getSourceUrlsFromConfig } from '@blocklet/meta';

// Example component config from a parent blocklet's metadata
const componentConfig = {
  name: 'my-child-blocklet',
  source: {
    store: ['https://store.blocklet.dev/api', 'https://backup-store.com/api'],
    version: '1.2.0'
  }
};

const urls = getSourceUrlsFromConfig(componentConfig);

console.log(urls);
/* Output (DID is derived from the name):
[
  'https://store.blocklet.dev/api/blocklets/z2qa.../1.2.0/blocklet.json',
  'https://backup-store.com/api/blocklets/z2qa.../1.2.0/blocklet.json'
]
*/
```

## Validation Utilities

This section includes lower-level utilities used by the core fetching functions.

### validateUrl

This is a general-purpose utility to check if a URL is valid and accessible. It supports `file://` by checking for file existence and `http(s)://` by making a `HEAD` request to verify accessibility and, optionally, the `content-type` header. This function's results are also cached.

<strong>Parameters</strong>

- **url** `string` *(required)* — The URL to validate.
- **expectedHttpResTypes** `string[]` (default: `['application/json', 'text/plain']`) — An array of acceptable content-type values for HTTP requests.

<strong>Returns</strong>

- **** `Promise<boolean>` — A promise that resolves to true if the URL is valid. It throws an error if validation fails (e.g., file not found, network error, unexpected content type).

<strong>Example</strong>

**Validating a Remote Asset**

```javascript
import { validateUrl } from '@blocklet/meta';

async function checkTarball(url) {
  try {
    await validateUrl(url, ['application/octet-stream', 'application/x-gzip']);
    console.log(`Tarball URL is valid and has the correct content type: ${url}`);
    return true;
  } catch (error) {
    console.error(`Tarball URL validation failed: ${error.message}`);
    return false;
  }
}

checkTarball('https://some-cdn.com/blocklet.tar.gz');
```

---

## Miscellaneous Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-misc-utilities-988441/

This section covers a collection of specialized helper functions provided by `@blocklet/meta`. These utilities handle tasks such as parsing and creating communication channel strings and generating unique, visually identifiable icons (Blockies) from addresses.

## Channel Utilities

Channel utilities provide a standardized way to create and parse channel strings used for real-time communication and event handling within the Blocklet ecosystem. This ensures that components, applications, and services can reliably identify communication endpoints.

### parseChannel(channel)

Parses a given channel string and returns a structured object containing its type and relevant identifiers.

<strong>Parameters</strong>

- **channel** `string` *(required)* — The channel string to be parsed.

<strong>Returns</strong>

An object with a `type` property and other properties depending on the channel format (e.g., `appDid`, `componentDid`, `topic`). Throws an error if the channel string is empty or has an invalid format.

<strong>Example</strong>

**Parsing Various Channels**

```javascript
import { parseChannel, CHANNEL_TYPE } from '@blocklet/meta/lib/util';

const componentChannel = 'component:z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g:z8iX9g5e3ubm5x6iG7xDxwK5N4b2kL1h2h2h';
const relayChannel = 'relay:z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g:news';
const didChannel = 'z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g';

try {
  const parsedComponent = parseChannel(componentChannel);
  console.log(parsedComponent);

  const parsedRelay = parseChannel(relayChannel);
  console.log(parsedRelay);

  const parsedDid = parseChannel(didChannel);
  console.log(parsedDid);
} catch (error) {
  console.error(error.message);
}
```

<strong>Example Response</strong>

**Response for parsedComponent**

```json
{
  "type": "COMPONENT",
  "appDid": "z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g",
  "componentDid": "z8iX9g5e3ubm5x6iG7xDxwK5N4b2kL1h2h2h"
}
```

**Response for parsedRelay**

```json
{
  "type": "RELAY",
  "appDid": "z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g",
  "topic": "news"
}
```

**Response for parsedDid**

```json
{
  "type": "DID"
}
```

### Channel Creation Functions

These helper functions generate valid channel strings based on the provided identifiers.

| Function  | Description  |
|---|---|
| `getAppPublicChannel(appDid)`  | Creates a public channel string for an application.  |
| `getComponentChannel(appDid, componentDid)`  | Creates a channel string for a specific component.  |
| `getRelayChannel(appDid, topic)`  | Creates a topic-based relay channel string for an application.  |
| `getEventBusChannel(appDid)`  | Creates an event bus channel string for an application.  |

<strong>Example</strong>

**Creating Channels**

```javascript
import {
  getAppPublicChannel,
  getComponentChannel,
  getRelayChannel,
  getEventBusChannel,
} from '@blocklet/meta/lib/util';

const appDid = 'z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g';
const componentDid = 'z8iX9g5e3ubm5x6iG7xDxwK5N4b2kL1h2h2h';
const topic = 'user-updates';

console.log('App Public:', getAppPublicChannel(appDid));
console.log('Component:', getComponentChannel(appDid, componentDid));
console.log('Relay:', getRelayChannel(appDid, topic));
console.log('Event Bus:', getEventBusChannel(appDid));
```

<strong>Example Output</strong>

```text
App Public: app:z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g:public
Component: component:z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g:z8iX9g5e3ubm5x6iG7xDxwK5N4b2kL1h2h2h
Relay: relay:z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g:user-updates
Event Bus: app:z2qaVo5e3ubm5x6iG7xDxwK5N4b2kL1g1g1g:eventbus
```

### CHANNEL_TYPE

An enum-like object that defines the possible channel types returned by `parseChannel`.

- `DID`: A raw DID address.
- `APP`: A public channel for an application.
- `COMPONENT`: A channel for a specific component.
- `RELAY`: A topic-based relay channel.
- `EVENT_BUS`: An application's internal event bus channel.

## Blockies Generation

Blockies are visual, pixelated icons generated from a seed string, typically a DID address. They provide a simple and recognizable visual identifier for users and entities. These utilities allow you to generate Blockies icons in SVG format.

### createBlockiesSvg(address, size, caseSensitive, scale)

Generates a complete SVG string for a blocky icon based on an input address or seed string.

<strong>Parameters</strong>

| Name  | Type  | Description  | Default  |
|---|---|---|---|
| `address`  | `string`  | <strong>Required.</strong> The seed string used to generate the icon (e.g., a DID address).  |  |
| `size`  | `number`  | The number of blocks per side for the icon's grid. For example, 8 creates an 8x8 grid.  | `8`  |
| `caseSensitive`  | `boolean`  | Determines if the seed string should be treated as case-sensitive.  | `false`  |
| `scale`  | `number`  | The size in pixels for each individual block. The final SVG width and height will be `size * scale`.  | `10`  |

<strong>Returns</strong>

A string containing the complete SVG markup for the generated Blockie icon.

<strong>Example</strong>

**Generating a Blockie**

```javascript
import { createBlockiesSvg } from '@blocklet/meta/lib/util';

const didAddress = 'z1S8B6n2E7gGzX2mY3c4V5b6N7m8P9q1A2b';

// Generate a 100x100px icon (10 blocks * 10 scale)
const svgString = createBlockiesSvg(didAddress, 10, false, 10);

console.log(svgString);
```

<strong>Example Response (SVG String)</strong>

**Blockie SVG Output**

```xml
<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
	<rect width="100" height="100" fill="hsl(13,67.4%,57.2%)" />
	<g fill="hsl(247,42.4%,53.4%)">
		<rect width="10" height="10" x="20" y="0" />
                <rect width="10" height="10" x="70" y="0" />
                <rect width="10" height="10" x="30" y="10" />
                <!-- ... more rect elements ... -->
	</g>
	<g fill="hsl(22,96.5%,48.6%)">
		<rect width="10" height="10" x="40" y="50" />
                <!-- ... more rect elements for spot color ... -->
	</g>
</svg>
```

This SVG can be directly embedded in HTML or used in other image contexts.

---

## Navigation Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-navigation-utilities-988441/

These functions are the engine behind building dynamic user interfaces in a Blocklet-based application. They parse and process the `navigation` property from a blocklet's metadata (`blocklet.yml`) and its current state, aggregating navigation items from the main blocklet and all its child components into a unified, ready-to-render structure.

The core challenge these utilities solve is complexity management. In a composite application, each component can declare its own navigation items. These utilities intelligently merge these declarations, resolve path prefixes based on each component's mount point, handle internationalization (i18n), filter out duplicates or inaccessible items, and organize everything into logical sections (like `header`, `footer`, `userCenter`).

## Core Processing Flow

The following diagram illustrates the high-level process of how raw navigation metadata from various sources is transformed into a final, structured list for the UI.

![Navigation Utilities](https://media.arcblock.io/lib/f9/f93660285c16a173.w1600.webp)

## Main Function

### parseNavigation(blocklet, options)

This is the primary function for processing navigation data. It orchestrates the entire workflow, from parsing built-in navigation from `blocklet.yml` files to merging them with user-defined customizations stored in the database.

<strong>Parameters</strong>

- **blocklet** `object` *(required)* — The full blocklet state object, including `meta`, `children`, and `settings.navigations`.
- **options** `object` — Optional configuration for the parsing process.
  - **beforeProcess** `(data: any) => any` — An optional function to preprocess the built-in navigation list before it's compacted and patched.

<strong>Returns</strong>

An object containing the processed navigation data:

- **navigationList** `NavigationItem[]` — The final, merged, and cleaned list of navigation items, ready for rendering. This is the primary output.
- **components** `ComponentItem[]` — An array of all child components that declare navigation, including their name, link, and title.
- **builtinList** `NavigationItem[]` — The processed list of navigation items derived purely from `blocklet.yml` files, before merging with custom navigation from settings.

<strong>Example Usage</strong>

**Basic Usage**

```javascript
import { parseNavigation } from '@blocklet/meta/lib/navigation';

// A simplified blocklet state object
const blockletState = {
  did: 'z1...',
  meta: {
    name: 'my-app',
    title: 'My App',
    navigation: [
      { id: 'home', title: 'Home', link: '/' },
      { id: 'dashboard', title: 'Dashboard', component: 'dashboard-blocklet' },
    ],
  },
  children: [
    {
      did: 'z2...',
      mountPoint: '/dashboard',
      meta: {
        name: 'dashboard-blocklet',
        title: 'Dashboard',
        navigation: [
          { id: 'overview', title: 'Overview', link: '/overview' },
        ],
      },
    },
  ],
  settings: {
    // Custom navigation items from a database
    navigations: [
      {
        id: 'external-link',
        title: 'External Site',
        link: 'https://example.com',
        section: 'header',
        from: 'db',
        visible: true,
      },
    ],
  },
};

const { navigationList, components } = parseNavigation(blockletState);

console.log(navigationList);
/*
Outputs a structured array like:
[
  { id: '/home', title: 'Home', link: '/', ... },
  {
    id: '/dashboard/overview',
    title: 'Overview',
    link: '/dashboard/overview',
    component: 'dashboard-blocklet',
    ...
  },
  { id: 'external-link', title: 'External Site', ... }
]
*/
console.log(components);
/*
Outputs component info:
[
  {
    did: 'z2...',
    name: 'dashboard-blocklet',
    link: '/dashboard',
    title: 'Dashboard',
    ...
  }
]
*/
```

## Helper Functions

While `parseNavigation` is the all-in-one solution, the library also exports several underlying helper functions. These are useful for advanced use cases where you might need to perform custom manipulations on navigation data.

::::card-group
::link-card{title="deepWalk" description="A generic utility for recursively traversing a tree-like object, applying a callback to each node." icon="git-commit"}
::link-card{title="flattenNavigation" description="Transforms a nested navigation tree into a flat array, optionally to a specified depth." icon="git-merge"}
::link-card{title="nestNavigationList" description="Reconstructs a nested navigation tree from a flat array where items have a `parent` ID property." icon="git-branch"}
::link-card{title="splitNavigationBySection" description="Deconstructs navigation items that belong to multiple sections into separate items for each section." icon="columns"}
::link-card{title="filterNavigation" description="Filters a navigation list by removing items marked as `visible: false` or those whose components are missing." icon="filter"}
::link-card{title="joinLink" description="Intelligently combines a parent's link with a child's link, correctly handling prefixes and absolute URLs." icon="link"}
::::

### flattenNavigation(list, options)

This function takes a tree of navigation items and flattens it into a single-level array. It's particularly useful for preparing navigation data for display in menus that don't support deep nesting or for easier processing.

<strong>Parameters</strong>

- **list** `NavigationItem[]` *(required)* — The tree-structured navigation list.
- **options** `object` — Configuration options for flattening.
  - **depth** `number` (default: `1`) — The depth to which the tree should be flattened. A depth of 1 means full flattening.
  - **transform** `(current, parent) => any` — A function to transform each item as it's being flattened.

<strong>Example</strong>

**Flattening a Navigation Tree**

```javascript
const nestedNav = [
  {
    id: 'parent1',
    title: 'Parent 1',
    items: [
      { id: 'child1a', title: 'Child 1a' },
      { id: 'child1b', title: 'Child 1b' },
    ],
  },
];

const flatNav = flattenNavigation(nestedNav, { depth: 2 }); // Flatten up to 2 levels

console.log(flatNav);
/*
[
  { id: 'parent1', title: 'Parent 1' },
  { id: 'child1a', title: 'Child 1a' },
  { id: 'child1b', title: 'Child 1b' }
]
*/
```

### nestNavigationList(list)

The inverse of `flattenNavigation`. This function takes a flat array of navigation items, where children reference their parent via a `parent` ID, and reconstructs the original tree structure.

<strong>Parameters</strong>

- **list** `NavigationItem[]` *(required)* — A flat array of navigation items with `id` and `parent` properties.

<strong>Example</strong>

**Building a Tree from a Flat List**

```javascript
const flatNav = [
  { id: 'parent1', title: 'Parent 1', section: 'header' },
  { id: 'child1a', title: 'Child 1a', parent: 'parent1', section: 'header' },
  { id: 'root2', title: 'Root 2', section: 'header' },
];

const nestedNav = nestNavigationList(flatNav);

console.log(nestedNav);
/*
[
  {
    id: 'parent1',
    title: 'Parent 1',
    section: 'header',
    items: [ { id: 'child1a', title: 'Child 1a', ... } ],
  },
  { id: 'root2', title: 'Root 2', section: 'header' },
]
*/
```

These utilities provide a comprehensive toolkit for managing navigation in complex, component-based applications. To understand how to format the URLs and paths used within these navigation items, proceed to the [URL & Path Utilities](/en/docs/blocklet-spec/api-url-path-utilities-988441/) documentation.

---

## Parsing & Validation

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-parsing-validation-988441/

This section provides a detailed reference for the functions used to read, parse, and validate `blocklet.yml` files. These utilities are the programmatic interface for working with the [Blocklet Specification](/en/docs/blocklet-spec/spec-988441/), ensuring that your blocklet's metadata is correct, complete, and ready for use by Blocklet Server and other tooling.

These functions are essential for building tools that interact with blocklets, validating configurations in CI/CD pipelines, or programmatically reading blocklet metadata.

## parse

The `parse` function is the primary utility for reading a blocklet's metadata from the filesystem. It locates the `blocklet.yml` (or `blocklet.yaml`) file in a given directory, reads its content, applies a series of compatibility fixes, and validates the final object against the official schema.

### Workflow

The parsing process follows several key steps to ensure a valid and consistent metadata object is produced. The following diagram illustrates this workflow:

![Parsing & Validation](https://media.arcblock.io/lib/2a/2a30216c2e177dd7.w1600.webp)

### Signature

```typescript
function parse(
  dir: string,
  options?: {
    ensureFiles?: boolean;
    ensureDist?: boolean;
    ensureComponentStore?: boolean;
    extraRawAttrs?: any;
    schemaOptions?: any;
    defaultStoreUrl?: string | ((component: TComponent) => string);
    fix?: boolean;
  }
): TBlockletMeta;
```

### Parameters

- **dir** `string` *(required)* — The path to the blocklet directory containing the blocklet.yml file.
- **options** `object` — An optional configuration object.
  - **ensureFiles** `boolean` (default: `false`) — If true, verifies that files listed in the `logo` and `files` fields actually exist on the filesystem.
  - **ensureDist** `boolean` (default: `false`) — If true, requires the `dist` field to be present and valid in the metadata.
  - **ensureComponentStore** `boolean` (default: `true`) — If true, ensures that any components sourced from a store have a `source.store` URL defined.
  - **extraRawAttrs** `object` — An object with extra attributes to be merged into the metadata before validation. Useful for augmenting metadata, for example in a registry.
  - **schemaOptions** `object` — Additional options to pass to the underlying Joi schema validator.
  - **defaultStoreUrl** `string | function` — A URL to be used as the default store for components that don't specify one. Can be a static string or a function that returns a string.
  - **fix** `boolean` (default: `true`) — If true, applies automatic fixes to the metadata (e.g., for `person`, `repository`, `keywords`).

### Returns

Returns a validated `TBlockletMeta` object. If the `blocklet.yml` file is not found, is invalid YAML, or fails schema validation, the function will throw an `Error` with a descriptive message.

### Example Usage

**parse-example.js**

```javascript
import path from 'path';
import parse from '@blocklet/meta/lib/parse';

const blockletDir = path.join(__dirname, 'my-blocklet');

try {
  const meta = parse(blockletDir, {
    ensureFiles: true, // Make sure the logo exists
  });
  console.log('Successfully parsed blocklet:', meta.name, meta.version);
} catch (error) {
  console.error('Failed to parse blocklet.yml:', error.message);
}
```

## validateMeta

Use `validateMeta` when you already have a blocklet metadata object (e.g., from a database or an API response) and need to validate it against the blocklet schema without reading from the filesystem.

### Signature

```typescript
function validateMeta(
  meta: any,
  options?: {
    ensureFiles?: boolean;
    ensureDist?: boolean;
    ensureComponentStore?: boolean;
    ensureName?: boolean;
    skipValidateDidName?: boolean;
    schemaOptions?: any;
  }
): TBlockletMeta;
```

### Parameters

- **meta** `any` *(required)* — The raw blocklet metadata object to validate.
- **options** `object` — An optional configuration object, similar to parse.
  - **ensureFiles** `boolean` (default: `false`) — If true, verifies that files listed in the `logo` and `files` fields actually exist on the filesystem.
  - **ensureDist** `boolean` (default: `false`) — If true, requires the `dist` field to be present and valid in the metadata.
  - **ensureComponentStore** `boolean` (default: `true`) — If true, ensures that any components sourced from a store have a `source.store` URL defined.
  - **ensureName** `boolean` (default: `false`) — If true, requires the `name` field to be present.
  - **skipValidateDidName** `boolean` (default: `false`) — If true, and the blocklet name is in a DID format, it will skip the DID type validation.
  - **schemaOptions** `object` — Additional options to pass to the underlying Joi schema validator.

### Returns

Returns the validated and cleaned `TBlockletMeta` object. It throws an `Error` if the metadata object fails validation.

### Example Usage

**validate-example.js**

```javascript
import validateMeta from '@blocklet/meta/lib/validate';

const rawMeta = {
  name: 'my-first-blocklet',
  version: '1.0.0',
  description: 'A simple blocklet.',
  did: 'z8iZpA529j4Jk1iA...',
  // ... other properties
};

try {
  const validatedMeta = validateMeta(rawMeta, { ensureName: true });
  console.log('Metadata is valid:', validatedMeta.title);
} catch (error) {
  console.error('Invalid blocklet meta:', error.message);
}
```

## fixAndValidateService

This is a specialized helper function for validating the `services` configuration within each entry of the `interfaces` array in the metadata. The main `parse` and `validateMeta` functions call this internally, but it's exported for cases where you might need to process service configurations in isolation.

### Signature

```typescript
function fixAndValidateService(meta: TBlockletMeta): TBlockletMeta;
```

### Parameters

- **meta** `TBlockletMeta` *(required)* — The blocklet metadata object containing the service configurations to validate.

### Returns

Returns the input `TBlockletMeta` object with its service configurations validated and potentially modified with default values. It throws an `Error` if any service configuration is invalid.

### Example Usage

**service-validate-example.js**

```javascript
import { fixAndValidateService } from '@blocklet/meta/lib/validate';

const meta = {
  // ... other meta properties
  interfaces: [
    {
      type: 'web',
      name: 'publicUrl',
      path: '/',
      services: [
        {
          name: '@blocklet/service-auth',
          config: {
            // auth service config
          },
        },
      ],
    },
  ],
};

try {
  const metaWithValidatedServices = fixAndValidateService(meta);
  console.log('Service configuration is valid.');
} catch (error) {
  console.error('Invalid service config:', error.message);
}
```

## validateBlockletEntry

This utility function validates a blocklet's entry point (`main` property) to ensure it's correctly configured for its group type (`dapp` or `static`). For `dapp`s, it checks for the existence of required files or a valid `engine` configuration. For `static` blocklets, it ensures the `main` directory exists. This is a crucial check to perform after parsing to confirm a blocklet is executable.

### Signature

```typescript
function validateBlockletEntry(dir: string, meta: TBlockletMeta): void;
```

### Parameters

- **dir** `string` *(required)* — The root directory of the blocklet bundle.
- **meta** `TBlockletMeta` *(required)* — The parsed and validated blocklet metadata object.

### Returns

This function does not return a value. It will throw an `Error` if the entry point validation fails, with a message explaining the issue.

### Example Usage

**entry-validate-example.js**

```javascript
import path from 'path';
import parse from '@blocklet/meta/lib/parse';
import validateBlockletEntry from '@blocklet/meta/lib/entry';

const blockletDir = path.join(__dirname, 'my-dapp');

try {
  const meta = parse(blockletDir);
  validateBlockletEntry(blockletDir, meta);
  console.log('Blocklet entry point is valid.');
} catch (error) {
  console.error('Validation failed:', error.message);
}
```

Now that you understand how to parse and validate metadata, you may want to explore helpers for fetching metadata from remote sources. Proceed to the [Metadata Helpers](/en/docs/blocklet-spec/api-metadata-helpers-988441/) section to learn more.

---

## Security Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-security-utilities-988441/

The `@blocklet/meta` library provides a suite of security utilities for handling cryptographic operations. These functions are essential for ensuring the integrity and authenticity of data, particularly for signing and verifying Blocklet metadata and API responses. They form the backbone of trust within the Blocklet ecosystem.

This section covers functions for simple request/response signing, as well as more complex multi-signature and chained-trust verification schemes.

## signResponse

Adds a cryptographic signature to any JSON-serializable object. This function uses a stable stringification method (`json-stable-stringify`) to ensure the payload is consistent before signing it with the provided wallet object. The resulting signature is added to the object under the `$signature` key, making it easy to verify.

### Parameters

- **data** `T extends Record<string, any>` *(required)* — The data object to be signed.
- **wallet** `WalletObject` *(required)* — An `@ocap/wallet` instance used to generate the signature.

### Returns

- **T & { $signature: string }** `object` — The original object augmented with a `$signature` property containing the cryptographic signature string.

### Example

**Sign a Data Object**

```javascript
import { signResponse } from '@blocklet/meta';
import { fromRandom } from '@ocap/wallet';

// Create a new wallet for signing
const wallet = fromRandom();

const myData = {
  user: wallet.did,
  action: 'updateProfile',
  timestamp: Date.now(),
};

const signedData = signResponse(myData, wallet);

console.log(signedData);
/*
Output:
{
  user: 'z...',
  action: 'updateProfile',
  timestamp: 1678886400000,
  $signature: '...'
}
*/
```

## verifyResponse

Verifies the signature of an object that was previously signed, typically using `signResponse`. It automatically isolates the payload from the `$signature` property, recalculates the payload hash using the same stable stringification method, and verifies it against the signature using the provided wallet's public key.

### Parameters

- **signed** `T & { $signature?: string }` *(required)* — The data object containing the `$signature` to be verified.
- **wallet** `WalletObject` *(required)* — An `@ocap/wallet` instance corresponding to the key pair that was used for signing.

### Returns

- **Promise<boolean>** `Promise<boolean>` — A promise that resolves to `true` if the signature is valid, and `false` otherwise.

### Example

**Verify a Signed Object**

```javascript
import { signResponse, verifyResponse } from '@blocklet/meta';
import { fromRandom } from '@ocap/wallet';

async function main() {
  const wallet = fromRandom();
  const myData = { user: wallet.did, action: 'updateProfile' };

  // 1. Sign the data
  const signedData = signResponse(myData, wallet);
  console.log('Signed Data:', signedData);

  // 2. Verify the valid signature
  const isValid = await verifyResponse(signedData, wallet);
  console.log(`Signature is valid: ${isValid}`); // Expected: true

  // 3. Tamper with the data and try to verify again
  const tamperedData = { ...signedData, action: 'grantAdminAccess' };
  const isTamperedValid = await verifyResponse(tamperedData, wallet);
  console.log(`Tampered signature is valid: ${isTamperedValid}`); // Expected: false
}

main();
```

## verifyMultiSig

A sophisticated utility for verifying blocklet metadata (`blocklet.yml`) that has been signed by multiple parties. It processes signatures sequentially, respecting `excludes` and `appended` fields from each signature to correctly reconstruct the exact payload that each party signed. This allows for a collaborative and auditable metadata authoring process where different actors (e.g., developer, publisher, marketplace) can contribute to and sign off on the metadata.

The function also handles delegated signatures, where one DID authorizes another to sign on its behalf via a JWT (`delegation` field in the signature object).

### Multi-Signature Verification Flow

![Security Utilities](https://media.arcblock.io/lib/54/5400a54ffe2d3ccf.w1600.webp)

### Parameters

- **blockletMeta** `TBlockletMeta` *(required)* — The full blocklet metadata object, including the `signatures` array.

### Returns

- **Promise<boolean>** `Promise<boolean>` — A promise that resolves to `true` if all signatures in the chain are valid according to the multi-sig rules, and `false` otherwise.

### Example

**Verify Blocklet Metadata with Multiple Signatures**

```javascript
import verifyMultiSig from '@blocklet/meta/lib/verify-multi-sig';

async function verifyMetadata() {
  const blockletMeta = {
    name: 'my-multi-sig-blocklet',
    version: '1.0.0',
    description: 'A blocklet with multiple authors.',
    author: 'did:abt:z1...',
    signatures: [
      {
        // Developer's signature
        signer: 'did:abt:z1...',
        pk: '...',
        sig: '...',
        // The first signer signs the content *before* `signatures` and `publisherInfo` are added.
        excludes: ['signatures', 'publisherInfo'],
      },
      {
        // Publisher's signature, who might add their own field.
        signer: 'did:abt:z2...',
        pk: '...',
        sig: '...',
        // The publisher added this field before signing.
        appended: ['publisherInfo'],
      },
    ],
    publisherInfo: {
      name: 'Blocklet Store',
      did: 'did:abt:z2...',
    },
  };

  const isValid = await verifyMultiSig(blockletMeta);
  console.log(`Multi-signature metadata is valid: ${isValid}`);
}

verifyMetadata();
```

## verifyVault

Verifies a chain of trust for a "vault," which represents a sequence of ownership or control changes for a specific application context. Each entry in the vault must be chronologically ordered and cryptographically signed. For entries after the first, the signature must be approved by the previous owner, creating an unbroken, verifiable chain. This mechanism is crucial for features like secure, DID-based ownership transfer of assets or administrative roles.

### Vault Chain of Trust

**Vault Verification Process**

```d2
direction: down

initial-approver: {
  label: "Initial Approver\n(e.g., App DID)"
  shape: c4-person
}

vault-1: {
  label: "Vault 1\nOwner: User A"
  shape: rectangle
}

vault-2: {
  label: "Vault 2\nOwner: User B"
  shape: rectangle
}

vault-3: {
  label: "Vault 3\nOwner: User C"
  shape: rectangle
}

initial-approver -> vault-1: "1. Approves User A as first owner"
vault-1 -> vault-2: "2. User A approves User B as next owner"
vault-2 -> vault-3: "3. User B approves User C as final owner"
```

### Parameters

- **vaults** `VaultRecord[]` *(required)* — An array of vault records, sorted chronologically by the `at` timestamp.
- **appPid** `string` *(required)* — The application's DID or a unique identifier for the vault's context.
- **throwOnError** `boolean` (default: `false`) — If `true`, the function will throw an error on verification failure instead of returning an empty string.

### Returns

- **Promise<string>** `Promise<string>` — A promise that resolves to the DID of the final valid owner in the chain. It returns an empty string on failure unless `throwOnError` is `true`.

### Example

**Verify an Ownership Vault**

```javascript
import { verifyVault } from '@blocklet/meta';

// A simplified example of a vault chain for an application
async function checkVault() {
  const vaults = [
    {
      pk: 'pk_user1',
      did: 'did:abt:user1',
      at: 1672531200,
      sig: 'sig_user1_commit',
      approverPk: 'pk_app',
      approverDid: 'did:abt:app',
      approverSig: 'sig_app_approve_user1',
    },
    {
      pk: 'pk_user2',
      did: 'did:abt:user2',
      at: 1672534800,
      sig: 'sig_user2_commit',
      // Approved by the previous owner (user1)
      approverSig: 'sig_user1_approve_user2',
    },
  ];
  const appDid = 'did:abt:app';

  try {
    const finalOwnerDid = await verifyVault(vaults, appDid);
    if (finalOwnerDid) {
      console.log(`Vault is valid. Final owner: ${finalOwnerDid}`);
      // Expected: Vault is valid. Final owner: did:abt:user2
    } else {
      console.error('Vault verification failed.');
    }
  } catch (error) {
    console.error('Vault verification threw an error:', error.message);
  }
}

checkVault();
```

---

## URL & Path Utilities

URL: https://www.arcblock.io/en/docs/blocklet-spec/api-url-path-utilities-988441/

This section provides a set of helper functions for creating URL-friendly strings and validating URL paths. These utilities are essential for generating clean, valid, and consistent routes and links within your blocklet applications.

## Recommended Utilities

The following functions are provided in the `url-path-friendly.ts` module and are the recommended choice for handling URL paths.

### urlPathFriendly(name, [options])

Converts a string into a URL path-friendly format by replacing non-standard characters with hyphens and cleaning up consecutive special characters.

<strong>Parameters</strong>

- **name** `string` *(required)* — The input string to be converted.
- **options** `object` — Optional configuration object.
  - **keepSlash** `boolean` (default: `true`) — If `true` (default), slashes (`/`) are preserved. If `false`, leading and trailing slashes are removed.

<strong>Returns</strong>

- `string`: The URL path-friendly string.

<strong>Example</strong>

```javascript
import urlPathFriendly from '@blocklet/meta/lib/url-path-friendly';

// Basic usage
const messyString = '  My Awesome/Blocklet!!_v1.0.  ';
const cleanPath = urlPathFriendly(messyString);
// Result: 'My-Awesome/Blocklet-v1.0.'

// Handling consecutive characters
const withExtras = 'path///with...multiple---separators';
const cleanedExtras = urlPathFriendly(withExtras);
// Result: 'path/with.multiple-separators'

// Without keeping slashes
const fullPath = '/my/blocklet/path/';
const noSlashes = urlPathFriendly(fullPath, { keepSlash: false });
// Result: 'my/blocklet/path'
```

### isValidUrlPath(name)

Checks if a given string is a valid URL path segment. It verifies that the string contains only ASCII characters, matches the pattern `^[a-z0-9/\-._]*$`, and does not contain consecutive slashes (`//`).

<strong>Parameters</strong>

- **name** `string` *(required)* — The path string to validate.

<strong>Returns</strong>

- `boolean`: `true` if the path is valid, otherwise `false`.

<strong>Example</strong>

```javascript
import { isValidUrlPath } from '@blocklet/meta/lib/url-path-friendly';

console.log(isValidUrlPath('valid-path/sub-path_1.0')); // true
console.log(isValidUrlPath('/another/valid/path')); // true

console.log(isValidUrlPath('invalid//path')); // false (consecutive slashes)
console.log(isValidUrlPath('path-with-emojis-😀')); // false (non-ASCII characters)
console.log(isValidUrlPath('invalid path')); // false (contains space)
```

### checkLink(value)

Determines if a string is either a valid absolute URL or a valid relative URL path suitable for linking.

<strong>Parameters</strong>

- **value** `string` *(required)* — The URL or path to check.

<strong>Returns</strong>

- `boolean`: `true` if the link is valid, otherwise `false`.

<strong>Example</strong>

```javascript
import { checkLink } from '@blocklet/meta/lib/url-path-friendly';

// Absolute URLs
console.log(checkLink('https://www.arcblock.io')); // true
console.log(checkLink('ftp://example.com')); // true

// Valid relative paths
console.log(checkLink('/my-page')); // true
console.log(checkLink('/docs/getting-started/')); // true

// Invalid paths
console.log(checkLink('not-a-link')); // false
console.log(checkLink('/invalid//path')); // false
```

### checkUrlPath(value)

A stricter check specifically for URL paths used in concatenation. It validates that a path starts with a slash and does not contain consecutive slashes.

<strong>Parameters</strong>

- **value** `string` *(required)* — The URL path to check.

<strong>Returns</strong>

- `boolean`: `true` if the path is a valid concatenation path, otherwise `false`.

<strong>Example</strong>

```javascript
import { checkUrlPath } from '@blocklet/meta/lib/url-path-friendly';

console.log(checkUrlPath('/abc')); // true
console.log(checkUrlPath('/abc/bcd')); // true
console.log(checkUrlPath('/abc/bcd/')); // true

console.log(checkUrlPath('abc')); // false (does not start with '/')
console.log(checkUrlPath('/abc//bcd')); // false (contains consecutive slashes)
```

## Deprecated Utilities

> ⚠️ <strong>Warning:</strong> The following functions from the `url-friendly.ts` module are deprecated. Please use the utilities from `url-path-friendly.ts` instead for better handling of URL paths.
>

### urlFriendly(name, [options])

> <strong>Deprecated:</strong> Use `urlPathFriendly` instead.
>

Converts a string to a URL-friendly format using `slugify`.

<strong>Parameters</strong>

- **name** `string` *(required)* — The input string.
- **options** `object` — Optional configuration object.
  - **keepSlash** `boolean` (default: `true`) — If `true` (default), slashes (`/`) are preserved. If `false`, slashes are converted to hyphens.

<strong>Example</strong>

```javascript
import urlFriendly from '@blocklet/meta/lib/url-friendly';

// With slashes kept
const result1 = urlFriendly('my/awesome_blocklet');
// Result: 'my/awesome-blocklet'

// With slashes replaced
const result2 = urlFriendly('my/awesome_blocklet', { keepSlash: false });
// Result: 'my-awesome-blocklet'
```

### isValidUrl(name)

> <strong>Deprecated:</strong> Use `isValidUrlPath` or `checkLink` instead.
>

Checks if a string contains characters that are typically problematic in URLs, such as spaces and various symbols.

<strong>Example</strong>

```javascript
import { isValidUrl } from '@blocklet/meta/lib/url-friendly';

console.log(isValidUrl('valid-name')); // true
console.log(isValidUrl('invalid name')); // false
console.log(isValidUrl('another$invalid')); // false
```

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-spec/getting-started-988441/

This guide provides a quick introduction to using the `@blocklet/meta` library. You'll learn how to install the package and perform the most common task: parsing a `blocklet.yml` file to access its metadata within your application.

### Prerequisites

Before you begin, ensure you have:

1. A Node.js development environment.
2. A Blocklet project directory that contains a `blocklet.yml` file.

For this guide, let's assume you have a project directory named `my-blocklet` with the following `blocklet.yml` file inside:

**my-blocklet/blocklet.yml**

```yaml
name: my-awesome-blocklet
version: 0.1.0
title: My Awesome Blocklet
description: A simple blocklet to demonstrate parsing.
author: 'Jane Doe <jane.doe@example.com>'
```

### Step 1: Installation

Add the `@blocklet/meta` package to your project dependencies using either Yarn or npm.

**yarn**

```shell
yarn add @blocklet/meta
```

Or with npm:

**npm**

```shell
npm install @blocklet/meta
```

### Step 2: Parse Blocklet Metadata

The core function of the library is `parse`. It reads the `blocklet.yml` (or `blocklet.yaml`) from a given directory, validates its contents against the Blocklet Specification, applies necessary fixes (like standardizing person fields), and returns a clean JavaScript object.

Create a file named `index.js` next to your `my-blocklet` directory and add the following code:

**index.js**

```javascript
const path = require('path');
const { parse } = require('@blocklet/meta');

// Define the path to your blocklet's root directory
const blockletDir = path.join(__dirname, 'my-blocklet');

try {
  // Parse the metadata
  const meta = parse(blockletDir);

  // Print the parsed metadata object
  console.log('Successfully parsed blocklet meta:', meta);
} catch (error) {
  console.error('Failed to parse blocklet.yml:', error.message);
}
```

When you run this script (`node index.js`), it will output the parsed metadata object.

### Expected Output

The `parse` function not only reads the YAML file but also camelCases the keys and formats complex fields like `author` into structured objects.

**Output**

```json
{
  "name": "my-awesome-blocklet",
  "version": "0.1.0",
  "title": "My Awesome Blocklet",
  "description": "A simple blocklet to demonstrate parsing.",
  "author": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "specVersion": "1.0.0",
  "path": "/path/to/your/project/my-blocklet"
}
```

### What's Next?

You've successfully installed `@blocklet/meta` and parsed your first `blocklet.yml`. Now you can explore more advanced topics.

::::card-group
::link-card{title="Blocklet Specification (blocklet.yml)" description="Learn about all the available fields and their meanings to fully configure your blocklet's behavior and appearance." icon="file-text" href="/en/docs/blocklet-spec/spec-988441/"}
::link-card{title="API Reference" description="Dive into the full API documentation to discover other utilities for validation, file handling, and security." icon="book-open" href="/en/docs/blocklet-spec/api-988441/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-spec/overview-988441/

`@blocklet/meta` is a foundational library within the Blocklet ecosystem, serving as the definitive toolkit for managing blocklet metadata. It establishes the formal specification for the `blocklet.yml` manifest file and provides a comprehensive suite of utility functions to parse, validate, fix, and interact with this metadata programmatically.

At its core, the library ensures that every blocklet is described in a consistent, reliable, and machine-readable way. This standardization is what powers the entire Blocklet ecosystem, from the Blocklet Server that runs your application to the developer tools that help you build it.

The following diagram illustrates the core workflow within the Blocklet ecosystem:

![Overview](https://media.arcblock.io/lib/a6/a676c5c51d99892e.w1600.webp)

This documentation is divided into two main parts, mirroring the dual purpose of the library itself.

## The Blocklet Specification: blocklet.yml

The `blocklet.yml` file is the blueprint of a blocklet. It's a declarative manifest where you define every aspect of your application. The `@blocklet/meta` library contains the formal schema that validates this file, ensuring that the Blocklet platform can correctly install, configure, run, and manage your application. Key aspects you can define include:

- <strong>Core Identity</strong>: `name`, `version`, and the blocklet's unique Decentralized ID (`did`).
- <strong>Presentation</strong>: `title`, `description`, `logo`, and screenshots for display in app stores.
- <strong>Execution Environment</strong>: The runtime `engine` (e.g., Node.js), lifecycle `scripts` (like `pre-start`), and required `environments` variables.
- <strong>Networking & Services</strong>: Exposed web `interfaces`, internal services, and required ports.
- <strong>Composition</strong>: A list of other blocklets to be included as `components`, enabling modular application design.
- <strong>User Interface</strong>: `navigation` links to integrate with a dashboard and `theme` settings for visual consistency.
- <strong>Monetization</strong>: `payment` details for setting prices and revenue sharing.
- <strong>Security</strong>: Cryptographic `signatures` to verify the integrity and authorship of the metadata.

## The Utility Toolkit: Programmatic Access

Beyond just defining a specification, `@blocklet/meta` provides a rich set of JavaScript/TypeScript functions for developers to work with blocklet metadata and state. This toolkit is essential for building custom tooling, plugins, or complex applications that interact with the Blocklet ecosystem.

The utilities can be grouped into several key categories:

- <strong>Parsing & Validation</strong>: Functions like `parse` and `validateMeta` allow you to read a `blocklet.yml` file from the disk and verify its contents against the official schema.
- <strong>Metadata Helpers</strong>: A collection of functions to automatically fix common formatting issues, format person objects, resolve repository URLs, and more.
- <strong>Component & State Utilities</strong>: A powerful set of helpers (`forEachBlocklet`, `findComponent`, `getAppUrl`, etc.) for traversing the state of a running blocklet and its components, which is crucial for building admin dashboards and dynamic applications.
- <strong>DID & Wallet Utilities</strong>: Functions for handling Decentralized Identifiers (DIDs) and cryptographic wallets associated with a blocklet, such as `toBlockletDid` and `getBlockletWallet`.
- <strong>Security</strong>: Tools like `signResponse` and `verifyResponse` for signing and verifying data to ensure integrity and authenticity.

## What's Next?

::::card-group
::link-card{title="Getting Started" description="Install the library and parse your first `blocklet.yml` file in minutes." icon="rocket" href="/en/docs/blocklet-spec/getting-started-988441/"}
::link-card{title="Blocklet Specification (blocklet.yml)" description="Dive deep into the comprehensive reference for every field in the `blocklet.yml` manifest." icon="book-open" href="/en/docs/blocklet-spec/spec-988441/"}
::link-card{title="API Reference" description="Explore the detailed documentation for all the utility functions available in the library." icon="code-2" href="/en/docs/blocklet-spec/api-988441/"}
::::

---

## Blocklet Specification (blocklet.yml)

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-988441/

The `blocklet.yml` file is the heart of every Blocklet. It's a YAML manifest that defines all the essential metadata about your application, serving as the single source of truth for the Blocklet Server and other tools in the ecosystem.

Think of it as the equivalent of `package.json` in the Node.js world, but expanded to encompass the full lifecycle and configuration of a decentralized application. It details everything from the Blocklet's identity and version to how it runs, what web interfaces it exposes, its dependencies on other Blocklets, and how it integrates with the user interface.

This specification is the definitive reference for every field available in `blocklet.yml`. Whether you are building a simple static website or a complex, multi-service application, a well-formed `blocklet.yml` is the first step to ensuring it runs correctly and predictably.

### Basic Example

Here is a minimal `blocklet.yml` file to illustrate its basic structure. Each field is explained in detail in the sections below.

**blocklet.yml**

```yaml
# Core identity of the Blocklet
did: z8iZpA63mBCy9j82Vf9aL3a8u9b5c7d9e1f2
name: my-awesome-blocklet
version: 1.0.0

# Human-readable metadata
title: My Awesome Blocklet
description: A simple Blocklet to demonstrate the core concepts.

# How the Blocklet is executed
main: api/index.js

# How the Blocklet is exposed to the web
interfaces:
  - type: web
    name: publicUrl
    path: /
    prefix: '*'
    port: BLOCKLET_PORT
    protocol: http

# System requirements
requirements:
  server: ">=1.16.0"
  os: "*"
  cpu: "*"
```

### Specification Sections

The `blocklet.yml` specification is organized into logical groups of properties. Explore the sections below for a comprehensive guide to each field, its purpose, and valid values.

::::card-group
::link-card{title="Core Metadata" description="Fundamental properties like name, DID, version, and description that define your blocklet's identity." icon="package" href="/en/docs/blocklet-spec/spec-core-metadata-988441/"}
::link-card{title="People & Ownership" description="Specify the author, contributors, and maintainers of the blocklet." icon="users" href="/en/docs/blocklet-spec/spec-people-ownership-988441/"}
::link-card{title="Distribution & Links" description="Fields for the distribution package, source code repository, homepage, and documentation links." icon="link" href="/en/docs/blocklet-spec/spec-distribution-links-988441/"}
::link-card{title="Execution & Environment" description="Configure the runtime engine, system requirements, environment variables, and lifecycle scripts." icon="terminal" href="/en/docs/blocklet-spec/spec-execution-environment-988441/"}
::link-card{title="Interfaces & Services" description="Define how your blocklet exposes web pages, APIs, and other endpoints to the outside world." icon="routes" href="/en/docs/blocklet-spec/spec-interfaces-services-988441/"}
::link-card{title="Composition (Components)" description="Build complex applications by composing your blocklet from other blocklets as components." icon="box" href="/en/docs/blocklet-spec/spec-composition-988441/"}
::link-card{title="UI & Theming" description="Define navigation items and theme settings to integrate your blocklet's UI seamlessly." icon="palette" href="/en/docs/blocklet-spec/spec-ui-theming-988441/"}
::link-card{title="Monetization" description="Configure pricing, revenue sharing, and NFT-based purchases for your blocklet." icon="dollar-sign" href="/en/docs/blocklet-spec/spec-monetization-988441/"}
::link-card{title="Security & Resources" description="Ensure metadata integrity with signatures and define shared assets using the resource field." icon="shield" href="/en/docs/blocklet-spec/spec-security-resources-988441/"}
::::

Now that you have an overview of the `blocklet.yml` structure, dive into the specific sections above to find the details you need. For programmatic interaction with this metadata, see the [API Reference](/en/docs/blocklet-spec/api-988441/).

---

## Composition (Components)

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-composition-988441/

Blocklet composition is a powerful feature that allows you to build complex, modular applications by assembling smaller, independent blocklets. This approach promotes reusability, separation of concerns, and easier maintenance. The `components` property in the `blocklet.yml` file is the cornerstone of this feature, defining the dependencies a blocklet has on other blocklets.

## Core Concept: Parent-Child Relationship

At its heart, composition establishes a parent-child relationship. A primary blocklet (the parent) can declare a list of other blocklets (the children or components) that it needs to function. When a user installs the parent blocklet, the Blocklet Server automatically resolves, fetches, and installs all its required components, creating a single, cohesive application from multiple parts.

The following diagram illustrates this parent-child relationship, showing how a parent blocklet defines its child components within its configuration:

![Composition (Components)](https://media.arcblock.io/lib/30/30ddc645854a9cc7.w1600.webp)

## The components Property Specification

The `components` property is an array of objects, where each object defines a single child blocklet. Here are the key fields for each component object:

- **source** `object` *(required)* — Specifies where to find the component. It contains either a url or a store and name.
- **required** `boolean` — If true, the parent blocklet cannot be installed or started without this component. Defaults to false.
- **title** `string` — A suggested display title for the component during the installation process. The user can override this value.
- **description** `string` — A suggested description for the component during installation.
- **mountPoint** `string` — A suggested URL path prefix where the component should be mounted. For example, /api for a backend service. The user can change this during setup.
- **name** `string` *(deprecated)* — A legacy field for backward compatibility. It's recommended to rely on the name within the source object.

### Defining the Component source

The `source` object is mandatory and tells the Blocklet Server how to locate and download the component. It has two primary forms:

1. <strong>From a Blocklet Store (Recommended)</strong>: This is the standard method. You specify the store's URL, the component's name, and a version range. - **store** `string` *(required)* — The URL of the Blocklet Store API. - **name** `string` *(required)* — The unique name of the component blocklet. - **version** `string` (default: `latest`) — A semantic version range (e.g., ^1.2.3, ~2.0.0, latest).
2. <strong>From a direct URL</strong>: This allows you to link directly to a component's manifest (`blocklet.yml` or `blocklet.json`) or its tarball package. - **url** `string | string[]` *(required)* — A single URL string or an array of URL strings for redundancy. - **version** `string` — A semantic version range to validate against the version specified in the linked manifest.

### Example blocklet.yml Configuration

Here is a snippet demonstrating how to declare components in your `blocklet.yml` file.

**blocklet.yml**

```yaml
name: 'my-composite-blog'
did: 'z8iZexampleDidForCompositeBlog'
version: '1.0.0'
title: 'My Composite Blog'
description: 'A blog application built from several smaller blocklets.'

# ... other properties

components:
  # Component fetched from a Blocklet Store (recommended)
  - name: 'blog-api-service' # backward compatible name
    required: true
    title: 'Blog API Service'
    description: 'Handles all backend logic and database interactions.'
    mountPoint: '/api/blog'
    source:
      store: 'https://store.blocklet.dev/api/blocklets'
      name: 'blog-api-service'
      version: '^1.0.0'

  # Component fetched from a direct URL
  - name: 'blog-frontend-ui'
    required: true
    title: 'Blog User Interface'
    mountPoint: '/'
    source:
      url: 'https://github.com/me/blog-frontend/releases/download/v2.1.0/blocklet.yml'
      version: '2.1.0'
```

This configuration defines a blog application that depends on two other blocklets: a backend API service and a frontend UI. Both are marked as `required`.

## Dependency Resolution

Blocklet composition can be nested; a component can have its own components. To manage this complexity, the system needs to resolve the entire dependency tree to determine the correct installation order. The `@blocklet/meta` library provides a utility function for this purpose.

### getRequiredComponentsLayers()

This function traverses the dependency graph and returns a two-dimensional array representing the dependency layers. The arrays are ordered from the lowest-level dependency to the highest, ensuring that foundational components are installed before the components that depend on them.

<strong>Usage Example</strong>

**Resolving Dependency Order**

```javascript
import { getRequiredComponentsLayers } from '@blocklet/meta';

// A simplified list of all available blocklets and their dependencies
const allBlocklets = [
  {
    meta: { did: 'did:app:parent' },
    dependencies: [{ did: 'did:app:child', required: true }],
  },
  {
    meta: { did: 'did:app:child' },
    dependencies: [{ did: 'did:app:grandchild', required: true }],
  },
  {
    meta: { did: 'did:app:grandchild' },
    dependencies: [],
  },
  {
    meta: { did: 'did:app:optional_component' },
    dependencies: [],
  },
];

const layers = getRequiredComponentsLayers({
  targetDid: 'did:app:parent',
  children: allBlocklets,
});

console.log(layers);
// Expected Output: [['did:app:grandchild'], ['did:app:child']]
// This means 'grandchild' must be installed first, followed by 'child'.
```

This utility is critical for ensuring a stable and predictable installation process for complex, multi-layered applications.

---

## Core Metadata

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-core-metadata-988441/

Core metadata fields establish the fundamental identity of a Blocklet. They provide essential, at-a-glance information for identification, versioning, and discoverability within the Blocklet ecosystem. Every `blocklet.yml` file must define these foundational properties to be considered valid.

## Identity & Versioning

These fields uniquely identify your Blocklet and track its evolution.

### did (Decentralized Identifier)

The `did` is the globally unique and immutable identifier for the Blocklet. It serves as its primary key across the entire ArcBlock ecosystem, ensuring that every Blocklet can be securely and unambiguously referenced.

- **did** `string` *(required)* — A valid Decentralized Identifier. The DID's type information must specify RoleType.ROLE_BLOCKLET.

#### Validation Rules

The system validates that the provided DID is not just syntactically correct but also has the appropriate role type (`ROLE_BLOCKLET`), which is a critical security and integrity feature.

**blocklet.yml**

```yaml
did: z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ
```

### name

The `name` is a human-readable identifier for the Blocklet. While the `did` is the canonical identifier for machines, the `name` provides a convenient, memorable alias for developers and users. In legacy configurations, it was also used to derive the Blocklet's DID.

- **name** `string` *(required)* — A unique name that follows npm package naming conventions and does not exceed 32 characters.

#### Relationship Between name and did

It's crucial to understand how `name` and `did` interact:

::::steps
:::step{title="DID-First (Recommended)"}
You provide a valid, pre-registered Blocklet DID. This is the modern and most robust approach.
:::

:::step{title="Name-First (Legacy Support)"}
If you provide a `name`, the system can derive a DID from it. For the metadata to be valid, the `did` field in your `blocklet.yml` <strong>must</strong> match the expected DID generated from the `name`. An inconsistency will result in a validation error.
:::
::::

**blocklet.yml**

```yaml
# This name is used for display and can be used to derive the DID
name: 'my-awesome-blocklet'

# This DID must be a valid Blocklet DID. If using the name-first approach,
# it must match the DID derived from 'my-awesome-blocklet'.
did: z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ
```

### version

The `version` field tracks the release version of the Blocklet, enabling proper dependency management and version control for users and other Blocklets.

- **version** `string` *(required)* — The Blocklet version, which must adhere to the Semantic Versioning 2.0.0 specification (e.g., 1.2.3, 2.0.0-beta.1).

**blocklet.yml**

```yaml
version: '1.0.0'
```

### specVersion

This field specifies the version of the `blocklet.yml` specification that your metadata file adheres to. This allows Blocklet runtimes and tools to correctly parse and interpret the file's contents, ensuring forward compatibility.

- **specVersion** `string` — A valid SemVer string indicating the specification version, which must be 1.0.0 or greater.

**blocklet.yml**

```yaml
specVersion: '1.2.0'
```

## Presentation & Classification

These fields define how your Blocklet is presented in user interfaces and how it's categorized.

### title

The `title` is a display-friendly name for the Blocklet. It is used in user interfaces such as the Blocklet Store, dashboards, and launchpads where a more descriptive or branded name is preferable to the short `name`.

- **title** `string` — A short, human-readable title. Its length is calculated with CJK character awareness and must not exceed a predefined limit (MAX_TITLE_LENGTH). For more details, see cjk-length.

**blocklet.yml**

```yaml
title: 'My Awesome Blocklet'
```

### description

The `description` provides a concise summary of the Blocklet's purpose and functionality. It is heavily used in search results and UI previews to help users quickly understand what the Blocklet does.

- **description** `string` *(required)* — A brief summary of the Blocklet, between 3 and 160 characters long.

**blocklet.yml**

```yaml
description: 'A Blocklet that provides amazing data visualization tools for your DID Space.'
```

### logo

This field specifies the path or URL to the Blocklet's logo. The logo is used for branding in the Blocklet Store, on dashboards, and in other user interfaces.

- **logo** `string` — A relative path or an absolute HTTP(S) URL to the logo image. It should not point to the well-known logo path (/.well-known/blocklet/logo) used internally by the system.

**blocklet.yml**

```yaml
# Using a relative path within the Blocklet bundle
logo: 'images/logo.png'

# Or using an absolute URL
# logo: 'https://cdn.example.com/blocklet-logo.svg'
```

### group

The `group` field categorizes the Blocklet, which helps with organization and discoverability in registries and marketplaces.

- **group** `string` — The category of the Blocklet. Must be one of the predefined values.

Valid values for `group` include:

| Value  | Description  |
|---|---|
| `dapp`  | A decentralized application.  |
| `static`  | A static website or single-page application.  |
| `service`  | A backend service or API.  |
| `component`  | A reusable component designed to be composed within other Blocklets.  |

**blocklet.yml**

```yaml
# Categorizes this Blocklet as a decentralized application.
group: 'dapp'
```

## Complete Example

Here is a snippet showing all the core metadata fields working together in a `blocklet.yml` file.

**blocklet.yml**

```yaml
name: 'data-visualizer'
did: z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ # Corresponds to 'data-visualizer'
version: '1.2.0'
specVersion: '1.2.0'
title: 'Data Visualizer'
description: 'A Blocklet that provides amazing data visualization tools for your DID Space.'
logo: 'images/logo.svg'
group: 'dapp'
```

Now that you understand the core identity of a Blocklet, the next section will cover how to specify its creators and maintainers.

:::action-card{title="Next: People & Ownership" description="Learn how to specify the author, contributors, and maintainers of your Blocklet." icon="users"}
::action{label="Read More" href="/en/docs/blocklet-spec/spec-people-ownership-988441/" variant="primary"}
:::

---

## Distribution & Links

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-distribution-links-988441/

This section covers the fields in `blocklet.yml` that define how your blocklet is packaged for distribution and provide essential links to its source code, homepage, documentation, and other resources. Properly configuring these fields is crucial for discoverability, user trust, and integration into the Blocklet ecosystem.

## Distribution Package (dist)

The `dist` object contains information about the blocklet's bundled package. This data is typically generated and added automatically by the `blocklet publish` command and is used by the Blocklet Store to download and verify the blocklet.

It ensures the integrity and authenticity of the blocklet package that users install.

### Schema

- **dist** `object` — Contains information about the blocklet's bundled package.
  - **tarball** `string` *(required)* — The URL where the compressed blocklet bundle (.tar.gz) can be downloaded.
  - **integrity** `string` *(required)* — A subresource integrity string (e.g., a SHA-512 hash) to verify the downloaded package's contents.
  - **size** `number` — The size of the tarball in bytes.

### Example

**blocklet.yml**

```yaml
# This field is usually auto-generated during the publish process
dist:
  tarball: https://store.blocklet.dev/uploads/z123abc.tar.gz
  integrity: sha512-Vbf...Q==
  size: 1234567
```

## Source Code Repository (repository)

The `repository` field specifies the location of your blocklet's source code. This is highly recommended as it allows users and contributors to review the code, report issues, and contribute.

You can provide a simple URL string or a more detailed object.

### Schema

- **repository** `string | object` — Specifies the location of the blocklet's source code.
  - **type** `string` *(required)* — The version control system type (e.g., 'git', 'https', 'svn').
  - **url** `string` *(required)* — The URL of the repository.
  - **directory** `string` — The path to the blocklet's package within a monorepo.

### Example: Simple URL

If you provide a string, it will be automatically parsed to determine the repository type.

**blocklet.yml**

```yaml
repository: https://github.com/arcblock/blocklet-spec.git
```

### Example: Object Format

Using the object format is useful for monorepos or when you need to be more explicit.

**blocklet.yml**

```yaml
repository:
  type: git
  url: https://github.com/arcblock/blocklet-framework.git
  directory: packages/blocklet-spec
```

## Web Links & Support

These fields provide direct links to important external resources, enhancing user support and community engagement.

- **homepage** `string` — The official homepage or marketing page for the blocklet.
- **documentation** `string` — A link to the blocklet's detailed documentation site.
- **community** `string` — A link to a community forum, Discord server, or other discussion platforms.
- **support** `string` — A URL or email address for users to get help.

### Example

**blocklet.yml**

```yaml
homepage: https://www.arcblock.io/
documentation: https://docs.arcblock.io/
community: https://community.arcblock.io/
support: support@arcblock.io
```

## Promotional Assets

These fields are used to showcase your blocklet in the Blocklet Store, providing users with a visual preview of its features and functionality.

- **screenshots** `string[]` — An array of URLs pointing to images that showcase the blocklet's UI or features.
- **videos** `string[]` — An array of up to 3 URLs for promotional videos. Only YouTube and Vimeo links are supported.
- **logoUrl** `string` — A direct URL to the blocklet's logo. This is often generated and uploaded by the publishing process.

### Example

**blocklet.yml**

```yaml
screenshots:
  - https://meta.blocklet.dev/screenshots/1.png
  - https://meta.blocklet.dev/screenshots/2.png
videos:
  - https://www.youtube.com/watch?v=xxxxxxxx
logoUrl: https://meta.blocklet.dev/logo.png
```

## Usage Statistics (stats)

The `stats` object contains usage metrics for the blocklet. Like the `dist` field, this is typically managed by the Blocklet Store and should not be set manually.

### Schema

- **stats** `object` — Contains usage metrics for the blocklet, managed by the Blocklet Store.
  - **downloads** `number` — The total number of times the blocklet has been downloaded.
  - **star** `number` (default: `0`) — The number of stars or upvotes the blocklet has received.
  - **purchases** `number` (default: `0`) — The number of times the blocklet has been purchased.

### Example

**blocklet.yml**

```yaml
# This field is managed by the Blocklet Store
stats:
  downloads: 10500
  star: 250
  purchases: 120
```

With these fields configured, your blocklet is ready for distribution. The next step is to define how it runs.

:::action-card{title="Next: Execution & Environment" description="Learn how to configure the blocklet's engine, runtime requirements, environment variables, and startup scripts." icon="terminal"}
::action{label="Read More" href="/en/docs/blocklet-spec/spec-execution-environment-988441/" variant="primary"}
:::

---

## Execution & Environment

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-execution-environment-988441/

The execution and environment configuration within your `blocklet.yml` is the blueprint for how your Blocklet runs. It specifies the necessary runtime, defines system requirements, exposes configuration options to users, and hooks into the Blocklet's lifecycle. Getting this section right is crucial for creating a portable, robust, and user-friendly application.

This section covers five key areas: `engine`, `docker`, `requirements`, `environments`, `scripts`, and `timeout`.

## Engine (engine)

This property specifies the execution engine for your blocklet, defining the runtime and how it should be started. For most JavaScript-based blocklets, you'll specify `node` as the interpreter, and the `main` property (defined at the root of `blocklet.yml`) will serve as the entry point.

**A Simple Node.js Engine**

```yaml
name: my-node-blocklet
main: build/index.js
engine:
  interpreter: node
```

You can also provide an array of engine configurations to support multiple platforms, which is ideal for binary distributions.

**Multi-Platform Engine Configuration**

```yaml
# ... other properties
engine:
  - platform: linux
    interpreter: binary
    source: ./bin/server-linux
  - platform: darwin
    interpreter: binary
    source: ./bin/server-macos
  - platform: win32
    interpreter: binary
    source: ./bin/server-win.exe
```

### Engine Properties

- **interpreter** `string` (default: `node`) — The runtime to execute the blocklet. Valid values: node, blocklet, binary, bun.
- **platform** `string` — Optional OS platform. Used when engine is an array to specify configurations for different OSs (e.g., linux, darwin, win32).
- **source** `string | object` — The source of the engine if the interpreter is blocklet. Can be a URL string, or an object referencing a URL or the Blocklet Store.
- **args** `string[]` (default: `[]`) — An array of command-line arguments to pass to the executable.

## Docker (docker)

As an alternative to the `engine` property, you can use `docker` to run your blocklet in a containerized environment. This is ideal for applications with complex dependencies or non-JavaScript runtimes. You must provide either an `image` or a `dockerfile`.

**Using a Pre-built Docker Image**

```yaml
docker:
  image: 'nginx:latest'
  egress: true
```

When using a `dockerfile`, you must also include its path in the root `files` array.

**Building from a Dockerfile**

```yaml
docker:
  dockerfile: 'Dockerfile.prod'
files:
  - 'Dockerfile.prod'
```

### Docker Properties

- **image** `string` — The name of the Docker image to use.
- **dockerfile** `string` — The path to the Dockerfile to build the image. You cannot use image and dockerfile at the same time.
- **egress** `boolean` (default: `true`) — Whether the blocklet can access the external network.

## Runtime Requirements (requirements)

This object defines the environment constraints necessary for the blocklet to run correctly. The system will check these requirements before installation to ensure compatibility.

**Example Requirements**

```yaml
requirements:
  server: '>=1.16.0'
  os: '*'
  cpu: 'x64'
  nodejs: '>=18.0.0'
```

### Requirement Properties

- **server** `string` — A valid SemVer range for the required Blocklet Server version. Defaults to the latest stable version.
- **os** `string | string[]` (default: `*`) — The compatible operating system(s). Use * for any. Can be a single string or an array (e.g., ['linux', 'darwin']). Valid platforms include aix, darwin, freebsd, linux, openbsd, sunos, win32.
- **cpu** `string | string[]` (default: `*`) — The compatible CPU architecture(s). Use * for any. Can be a single string or an array (e.g., ['x64', 'arm64']). Valid architectures include arm, arm64, ia32, mips, mipsel, ppc, ppc64, s390, s390x, x32, x64.
- **nodejs** `string` (default: `*`) — A valid SemVer range for the required Node.js version.
- **fuels** `array` — Specifies a list of required assets (tokens) in a connected wallet for certain operations.
- **aigne** `boolean` — If true, indicates the blocklet requires an AI Engine to be available.

## Environment Variables (environments)

The `environments` array allows you to define custom configuration variables. These are presented to the user during installation or on the blocklet's configuration page, allowing them to securely input API keys, set feature flags, or customize behavior.

**Environment Variable Definitions**

```yaml
environments:
  - name: 'API_KEY'
    description: 'Your secret API key for the external service.'
    required: true
    secure: true
  - name: 'FEATURE_FLAG_BETA'
    description: 'Enable the beta feature for this blocklet.'
    required: false
    default: 'false'
    validation: '^(true|false)$'
```

<strong>Key Naming Rules:</strong>

- Names must not start with the reserved prefixes `BLOCKLET_`, `COMPONENT_`, or `ABTNODE_`.
- Names can only contain letters, numbers, and underscores (`_`).

### Environment Properties

- **name** `string` *(required)* — The name of the environment variable.
- **description** `string` *(required)* — A user-friendly description of what this variable is for.
- **default** `string` — An optional default value. Cannot be used if secure is true.
- **required** `boolean` (default: `false`) — Whether the user must provide a value for this variable.
- **secure** `boolean` (default: `false`) — If true, the value is treated as sensitive data (e.g., passwords, API keys), stored encrypted, and hidden in the UI.
- **validation** `string` — An optional regex string to validate the user's input.
- **shared** `boolean` — If true, this variable can be shared among components. Defaults to false if secure is true.

## Lifecycle Scripts (scripts)

Scripts are shell commands that hook into the blocklet's lifecycle, allowing you to perform automated tasks at specific stages like installation, startup, or uninstallation. The following diagram illustrates when the installation and startup hooks are executed:

![Execution & Environment](https://media.arcblock.io/lib/90/90176f135a8df069.w1600.webp)

**Script Hook Examples**

```yaml
scripts:
  pre-install: 'npm install --production'
  post-start: 'node ./scripts/post-start.js'
  pre-stop: 'echo "Shutting down..."'
```

### Available Hooks

| Hook (`kebab-case`)  | When It Runs  |
|---|---|
| `dev`  | The command to run the blocklet in development mode.  |
| `e2eDev`  | The command to run for end-to-end testing in a development environment.  |
| `pre-flight`  | Before the installation process begins, for initial checks.  |
| `pre-install`  | Before the blocklet files are copied to their final destination.  |
| `post-install`  | After the blocklet has been successfully installed.  |
| `pre-start`  | Before the blocklet's main process is started.  |
| `post-start`  | After the blocklet has successfully started.  |
| `pre-stop`  | Before the blocklet is stopped.  |
| `pre-uninstall`  | Before the blocklet is uninstalled.  |
| `pre-config`  | Before the configuration user interface is displayed to the user.  |

## Timeouts (timeout)

This object allows you to configure maximum wait times for critical lifecycle operations to prevent processes from hanging indefinitely.

**Timeout Configuration**

```yaml
timeout:
  start: 120  # Wait up to 120 seconds for the blocklet to start
  script: 600 # Allow scripts to run for up to 10 minutes
```

### Timeout Properties

- **start** `number` (default: `60`) — The maximum time in seconds to wait for the blocklet to start. Must be between 10 and 600.
- **script** `number` — The maximum time in seconds for any lifecycle script to run. Must be between 1 and 1800.

With the execution environment configured, the next step is to define how your blocklet communicates with the outside world. Proceed to the [Interfaces & Services](/en/docs/blocklet-spec/spec-interfaces-services-988441/) section to learn how to expose web pages and API endpoints.

---

## Interfaces & Services

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-interfaces-services-988441/

Blocklets interact with the outside world through `interfaces` and are enhanced with powerful, reusable functionalities via `services`. The `interfaces` property in `blocklet.yml` is the cornerstone for exposing your application's web pages, APIs, and other endpoints. `services`, such as the built-in authentication service, can then be attached to these interfaces to provide common features without extra boilerplate code.

This section details how to configure both, enabling you to define clear entry points for your blocklet and integrate it seamlessly into the broader ecosystem.

## Interfaces

The `interfaces` array defines all the public-facing entry points for your blocklet. Each object in the array represents a single interface, specifying its type, location, and behavior.

### Interface Schema

Each interface object is defined by the following properties:

- **type** `string` *(required)* — The type of interface. Valid values include web, well-known, api, health, etc. A blocklet can only declare one web interface.
- **name** `string` *(required)* — A unique, human-readable name for the interface (e.g., `publicUrl`, `adminApi`).
- **path** `string` (default: `/`) — The internal path within the blocklet that serves this interface.
- **prefix** `string` (default: `*`) — The path prefix where this interface is mounted publicly. A value of * (BLOCKLET_DYNAMIC_PATH_PREFIX) allows the user to mount it at any path.
- **protocol** `string` (default: `http`) — The communication protocol. Valid values are http, https, tcp, udp.
- **port** `string | object` (default: `PORT`) — Defines the port mapping. It can be a string referencing an environment variable (e.g., PORT), or an object with internal (env var name) and external (port number) keys for fixed mappings.
- **containerPort** `number` — The port number inside the container.
- **hostIP** `string` — Binds the interface to a specific IP on the host machine.
- **services** `array` (default: `[]`) — A list of services to attach to this interface. See the Services section below for details.
- **endpoints** `array` (default: `[]`) — Defines specific API endpoints with metadata for discoverability and interaction.
- **cacheable** `array` (default: `[]`) — A list of relative paths under this interface that can be cached by upstream services.
- **proxyBehavior** `string` (default: `service`) — Defines how requests are proxied. service routes through Blocklet Server's service layer, while direct bypasses it.
- **pageGroups** `array` (default: `[]`) — A list of page group identifiers.

### Special Interface Types

- <strong>`web`</strong>: This is the primary user-facing interface for a blocklet. A blocklet can declare <strong>at most one</strong> interface of type `web`.
- <strong>`well-known`</strong>: This type is for standardized resource discovery paths (e.g., `/.well-known/did.json`). Any interface of this type must have a `prefix` that starts with `/.well-known`.

### Example: Defining Interfaces

Here is an example of a `blocklet.yml` defining both a primary web interface and a separate API interface.

**blocklet.yml**

```yaml
name: my-awesome-app
did: z8iZpky2Vd3i2bE8z9f6c7g8h9j0k1m2n3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d
version: 1.2.0
description: An awesome app with a web UI and an API.

interfaces:
  # The main web interface, accessible by users
  - type: web
    name: publicUrl
    path: /
    prefix: /
    protocol: http
    port: PORT

  # A dedicated API interface
  - type: api
    name: dataApi
    path: /api
    prefix: /api
    protocol: http
    port: PORT
```

## Services

Services are pre-built, configurable functionalities provided by the Blocklet Server environment. You can attach them to an interface to add features like authentication, authorization, and more, simply by declaring them in the `services` array of an interface.

### Service Schema

A service object has two main properties:

- **name** `string` *(required)* — The name of the service to attach (e.g., `auth`).
- **config** `object` (default: `{}`) — A configuration object specific to that service.

### Built-in Service: auth

The `auth` service provides a complete user authentication and authorization solution for your blocklet. It handles user login, profile management, and access control.

#### auth Service Configuration

When you add the `auth` service, you can customize its behavior using the `config` object. Here are the available options:

- **whoCanAccess** `string` (default: `all`) — Defines who can access the interface. Valid values: owner (only the DID Space owner), invited (owner and invited users), or all (any authenticated user).
- **profileFields** `array` (default: `["fullName", "email", "avatar"]`) — The user profile information your app requests upon login. Valid fields are fullName, email, avatar, and phone.
- **allowSwitchProfile** `boolean` (default: `true`) — Determines if users can switch between different profiles within your application.
- **blockUnauthenticated** `boolean` (default: `false`) — If `true`, the service automatically blocks any request that is not authenticated.
- **blockUnauthorized** `boolean` (default: `false`) — If true, the service blocks authenticated users who do not meet the whoCanAccess criteria.
- **ignoreUrls** `array` (default: `[]`) — A list of URL paths or patterns (e.g., /public/**) that should be excluded from authentication checks.

### Example: Attaching the auth Service

This example shows how to secure the `web` interface from the previous example using the `auth` service.

**blocklet.yml**

```yaml
interfaces:
  - type: web
    name: publicUrl
    path: /
    prefix: /
    protocol: http
    port: PORT
    services:
      - name: auth
        config:
          whoCanAccess: invited
          blockUnauthenticated: true
          profileFields:
            - fullName
            - email
          ignoreUrls:
            - /assets/**
            - /login
```

In this configuration, all paths under the web interface are protected except for `/assets/**` and `/login`. Only the DID Space owner and invited users will be able to access the protected pages after logging in, and they will be prompted to share their full name and email.

## Endpoints

The `endpoints` array within an interface allows for the explicit definition of API endpoints, enhancing discoverability and enabling automated interactions.

### Endpoint Schema

- **type** `string` *(required)* — A unique identifier for the endpoint type.
- **path** `string` *(required)* — The path to the endpoint, relative to the interface's path.
- **meta** `object` — An object containing metadata about the endpoint.
  - **vcType** `string` — The type of Verifiable Credential associated with the endpoint.
  - **payable** `boolean` — Indicates if the endpoint involves a payment.
  - **params** `array` — An array describing the parameters the endpoint accepts.
    - **name** `string` *(required)* — The name of the parameter.
    - **description** `string` *(required)* — A description of the parameter.

By combining interfaces and services, you can clearly define how your blocklet is exposed and secure it with powerful, built-in features. To learn how to build more complex applications by combining multiple blocklets, see the next section on composition.

[Next: Composition (Components)](/en/docs/blocklet-spec/spec-composition-988441/)

---

## Monetization

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-monetization-988441/

Blocklet developers can monetize their work through a built-in payment system powered by OCAP (Open Capability Access Protocol) and NFTs. When a user purchases a blocklet, they receive a unique NFT (a `BlockletPurchaseCredential`) that serves as proof of ownership. This entire process is defined within the `blocklet.yml` metadata, primarily through the `payment` object.

This section details the configuration fields that enable you to set prices, define revenue-sharing models, and understand how the underlying NFT factory works.

## The payment Object

The `payment` object is the central hub for all monetization configurations. It allows you to specify the price, how the revenue should be shared, and how much to charge when your blocklet is used as a component by other blocklets.

Here is the high-level structure of the `payment` object:

**blocklet.yml**

```yaml
payment:
  price: []
  share: []
  componentPrice: []
```

### payment.price

This property defines the cost for a user to purchase the blocklet. The price is specified in a specific token. Currently, only a single token price is supported.

- **value** `number` *(required)* — The cost of the blocklet. Must be greater than 0.
- **address** `string` *(required)* — The DID address of the token used for payment.

**Example: Setting a Price**

```yaml
# blocklet.yml
payment:
  price:
    - value: 10
      address: 'z2de...'
```

### payment.share

This property enables automatic revenue sharing. When a blocklet is purchased, the funds can be distributed among multiple beneficiaries according to predefined shares. This is useful for teams of developers or for paying royalties.

<strong>Constraints:</strong>

- A maximum of 4 beneficiaries can be specified.
- The sum of all `value` fields in the `share` array must equal `1` (representing 100%).

- **name** `string` *(required)* — A human-readable name for the beneficiary (e.g., 'Lead Developer', 'Designer').
- **address** `string` *(required)* — The DID address of the beneficiary who will receive the funds.
- **value** `number` *(required)* — The portion of the revenue this beneficiary receives. Must be a value between 0 and 1.

**Example: 70/30 Revenue Split**

```yaml
# blocklet.yml
payment:
  price:
    - value: 10
      address: 'z2de...'
  share:
    - name: 'Developer'
      address: 'z1dev...'
      value: 0.7
    - name: 'Designer'
      address: 'z1design...'
      value: 0.3
```

In this example, for every 10-token purchase, the developer receives 7 tokens and the designer receives 3 tokens automatically.

### payment.componentPrice

This property defines the pricing model for your blocklet when it is used as a component within another, larger blocklet. This allows you to earn revenue when your work is part of a bigger application.

- **parentPriceRange** `[number, number]` — Optional. A two-element array specifying the price range of the parent blocklet for this rule to apply. e.g., [0, 100] applies to parents costing up to 100.
- **type** `string` *(required)* — The pricing type. Can be 'fixed' or 'percentage'.
- **value** `number` *(required)* — The price value. For 'fixed', it's a specific amount. For 'percentage', it's a value between 0 and 1 (e.g., 0.1 for 10%).

**Example: Component Pricing**

```yaml
# blocklet.yml
payment:
  componentPrice:
    # For parent blocklets priced between 0 and 50 tokens, charge a fixed fee of 5 tokens.
    - parentPriceRange: [0, 50]
      type: 'fixed'
      value: 5

    # For parent blocklets priced above 50 tokens, charge 10% of the parent's price.
    - parentPriceRange: [50.01, 99999]
      type: 'percentage'
      value: 0.1
```

## nftFactory Field

The `nftFactory` field holds the DID address of the OCAP NFT Factory responsible for minting the `BlockletPurchaseCredential` when a user buys your blocklet.

<strong>Important:</strong> You do not need to set this field manually. It is automatically generated and populated by the `blocklet publish` command when you publish your blocklet to a Blocklet Store. The store uses your `payment` configuration to create a unique, secure NFT factory and writes its address to this field in the final metadata.

## How the Payment Flow Works

Understanding the monetization flow helps clarify how these fields work together. The process is designed to be secure, transparent, and automated.

![Monetization](https://media.arcblock.io/lib/d8/d809cf23991d4176.w1600.webp)

This diagram illustrates the end-to-end process:

1. The user initiates a purchase from a Blocklet Store.
2. The store presents a transaction to the user's DID Wallet.
3. Upon user approval, the wallet interacts with the `nftFactory` specified in the blocklet's metadata.
4. The factory executes its `mint` function, which triggers the internal share contract.
5. Funds are automatically distributed to the beneficiaries defined in the `payment.share` array.
6. A purchase NFT is minted and sent to the user's wallet, serving as a perpetual receipt and license.
7. The Blocklet Store verifies the NFT ownership and grants the user access to install and use the blocklet.

### Advanced: Composite Blocklet Payments

When a blocklet is composed of other paid components, the payment system ensures that all creators in the dependency chain are compensated fairly and securely. This is achieved through a `paymentIntegrity` hash and cross-store signatures.

Before publishing a composite blocklet, the developer's CLI tool analyzes the entire component tree, calculates the final revenue sharing contract, and generates a unique hash of this payment logic (`paymentIntegrity`). It then requests a cryptographic signature for this hash from every Blocklet Store that hosts a paid component in the tree. These signatures are bundled into the final NFT Factory, creating a tamper-proof chain of trust that guarantees the payment logic has been verified and approved by all participating stores.

**Composite Blocklet Publish & Payment Integrity**

```d2
shape: sequence_diagram

Developer-CLI: "Developer CLI"
Store-A: "Store A"
Store-B: "Store B"

Developer-CLI -> Developer-CLI: "1. Analyze composite blocklet & components"
Developer-CLI -> Store-A: "2. Fetch meta for Component A"
Store-A -> Developer-CLI: "3. Return meta"
Developer-CLI -> Store-B: "4. Fetch meta for Component B"
Store-B -> Developer-CLI: "5. Return meta"
Developer-CLI -> Developer-CLI: "6. Calculate final share contract & paymentIntegrity hash"
Developer-CLI -> Store-A: "7. Request signature for paymentIntegrity"
Store-A -> Store-A: "8. Verify integrity"
Store-A -> Developer-CLI: "9. Return signature"
Developer-CLI -> Store-B: "10. Request signature for paymentIntegrity"
Store-B -> Store-B: "11. Verify integrity"
Store-B -> Developer-CLI: "12. Return signature"
Developer-CLI -> Developer-CLI: "13. Bundle signatures into NFT Factory"
Developer-CLI -> Store-A: "14. Publish final composite blocklet metadata"
```

With monetization configured, the next step is to ensure your blocklet's metadata is secure and its resources are properly defined. Continue to the [Security & Resources](/en/docs/blocklet-spec/spec-security-resources-988441/) section to learn about signing your metadata and managing bundled assets.

---

## People & Ownership

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-people-ownership-988441/

Properly attributing authorship and defining roles for contribution and maintenance is crucial for a healthy open-source ecosystem. In `blocklet.yml`, you can specify the people involved in your project using three distinct fields: `author`, `contributors`, and `maintainers`. All of these fields use a common `person` schema.

## The Person Schema

Each person involved in the blocklet is represented by a standardized object, ensuring consistency across all people-related fields in the metadata. The `@blocklet/meta` library also provides helper functions to parse and format this information.

Here is the formal definition for a person object:

- **name** `string` *(required)* — The person's full name or nickname.
- **email** `string` — The person's email address.
- **url** `string` — A URL to the person's website, blog, or social media profile.

### String Shorthand

For convenience, you can also specify a person as a single string in the format `"Name <email@example.com> (http://example.com)"`. The `@blocklet/meta` library automatically parses this string into the structured object format. The email and URL parts are optional.

**String Shorthand Example**

```yaml
author: 'Satoshi Nakamoto <satoshi@gmx.com> (https://bitcoin.org)'
```

## author

The `author` field designates the primary creator or owner of the blocklet. It should be a single person object or a string that can be parsed into one.

<strong>Schema:</strong> `personSchema`

<strong>Example:</strong>

**blocklet.yml**

```yaml
author:
  name: Jane Doe
  email: jane.doe@example.com
  url: https://github.com/janedoe
```

## contributors

The `contributors` field is an array of people who have contributed to the development of the blocklet. Each item in the array can be either a person object or a string.

<strong>Schema:</strong> `Joi.array().items(personSchema)`

<strong>Example:</strong>

**blocklet.yml**

```yaml
contributors:
  - name: John Smith
    email: john.smith@example.com
  - name: Alice Johnson
    url: https://alicej.dev
  - 'Bob Williams <bob@williams.io>'
```

## maintainers

The `maintainers` field is an array of people who are currently responsible for maintaining the blocklet, including responding to issues and reviewing contributions.

<strong>Schema:</strong> `Joi.array().items(personSchema)`

<strong>Example:</strong>

**blocklet.yml**

```yaml
maintainers:
  - name: Jane Doe
    email: jane.doe@example.com
  - name: Admin Team
    email: admin@example.com
    url: https://example.com/team
```

By clearly defining these roles, you provide transparency and make it easier for users and other developers to know who to contact for different purposes.

Next, let's look at how to specify where your blocklet can be found and downloaded.

:::action-card{title="Next: Distribution & Links" description="Learn about the `dist`, `repository`, and various URL fields to link your blocklet to its package and source code." icon="package"}
::action{label="Read More" href="/en/docs/blocklet-spec/spec-distribution-links-988441/" variant="primary"}
:::

---

## Security & Resources

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-security-resources-988441/

Security and resource management are crucial for creating trustworthy and interoperable Blocklets. The `blocklet.yml` specification provides two key fields for this purpose: `signatures` to ensure the integrity and authenticity of the metadata, and `resource` to define and bundle shared assets for composition with other Blocklets.

This section covers the specification for these fields and introduces the utility functions provided by `@blocklet/meta` to work with them.

## Signatures

The `signatures` field contains an array of digital signatures that create a verifiable chain of trust for the Blocklet's metadata. This mechanism prevents unauthorized modifications and confirms the identity of the publishers, such as the developer and the Blocklet Store. Each signature in the chain cryptographically signs the core metadata along with any subsequent signatures, ensuring that the entire history of modifications is tamper-proof.

### Multi-Signature Process Flow

The typical multi-signature workflow during the publishing process involves the developer signing the initial metadata, followed by the Blocklet Store verifying it, adding distribution information, and appending its own signature.

![Security & Resources](https://media.arcblock.io/lib/e1/e1f455135f03fd57.w1600.webp)

### Specification

The `signatures` field is an array of signature objects. Each object has the following structure:

**blocklet.yml**

```yaml
signatures:
  - type: 'ED25519'
    name: 'dev'
    signer: 'z8qa...'
    pk: 'z28n...'
    created: '2023-10-27T10:00:00.000Z'
    sig: 'z24e...'
    excludes: []
  - type: 'ED25519'
    name: 'store'
    signer: 'z8qR...'
    pk: 'z29c...'
    created: '2023-10-27T10:05:00.000Z'
    sig: 'z25a...'
    appended:
      - 'dist'
      - 'stats'
```

- **type** `string` *(required)* — The cryptographic algorithm used for the signature (e.g., 'ED25519').
- **name** `string` *(required)* — A human-readable name for the signature's role (e.g., 'dev', 'store').
- **signer** `string` *(required)* — The DID of the entity that created the signature.
- **pk** `string` *(required)* — The public key corresponding to the signer's DID.
- **created** `string` *(required)* — The ISO 8601 timestamp when the signature was created.
- **sig** `string` *(required)* — The base58-encoded signature string.
- **excludes** `string[]` — An array of top-level field names to exclude from the metadata before signing.
- **appended** `string[]` — An array of top-level field names that were added to the metadata by this signer. This is used by the next signer to correctly verify the previous signature.
- **delegatee** `string` — The DID of the delegatee if the signature was made through delegation.
- **delegateePk** `string` — The public key of the delegatee.
- **delegation** `string` — The delegation token (JWT) authorizing the `delegatee` to sign on behalf of the `signer`.

## Resource Management

The `resource` field allows a Blocklet to declare shared data types it can export and to bundle resources from other Blocklets. This is fundamental to enabling a composable and interoperable ecosystem where Blocklets can share data and functionality seamlessly.

### Specification

**blocklet.yml**

```yaml
resource:
  exportApi: '/api/resources'
  types:
    - type: 'posts'
      description: 'A collection of blog posts.'
    - type: 'images'
      description: 'A gallery of images.'
  bundles:
    - did: 'z2qa...'
      type: 'user-profiles'
      public: true
```

- **resource** `object` — Contains properties for defining exportable types and bundled resources.
  - **exportApi** `string` — A path to an API endpoint that other Blocklets can call to fetch exported resources.
  - **types** `object[]` — An array of resource types that this Blocklet can export. Limited to a maximum of 10 types.
    - **type** `string` *(required)* — The unique identifier for the resource type (e.g., 'posts', 'products').
    - **description** `string` — A human-readable description of the resource type.
  - **bundles** `object[]` — An array of resource bundles imported from other Blocklets.
    - **did** `string` *(required)* — The DID of the resource bundle to include.
    - **type** `string` *(required)* — The specific resource type to bundle from the source.
    - **public** `boolean` — If `true`, indicates that the bundled resource is publicly accessible.

## Related API Utilities

The `@blocklet/meta` library provides a suite of functions to handle the security aspects of a Blocklet's metadata and communications. For full details, see the [Security Utilities API Reference](/en/docs/blocklet-spec/api-security-utilities-988441/).

### Verifying Metadata Signatures

The `verifyMultiSig` function is the primary tool for ensuring the integrity of a `blocklet.yml` file. It processes the `signatures` array, verifying each signature in the chain to confirm that the metadata has not been tampered with and was signed by the declared entities.

**verifyMultiSig Example**

```javascript
import verifyMultiSig from '@blocklet/meta/lib/verify-multi-sig';
import { TBlockletMeta } from '@blocklet/meta/lib/types';

async function checkMetadata(meta: TBlockletMeta) {
  const isValid = await verifyMultiSig(meta);
  if (isValid) {
    console.log('Blocklet metadata is authentic and untampered.');
  } else {
    console.error('WARNING: Blocklet metadata verification failed!');
  }
}
```

### Signing and Verifying API Responses

For securing communications between Blocklets or between a Blocklet and a client, you can use the `signResponse` and `verifyResponse` functions. These helpers use a wallet object to cryptographically sign and verify any JSON-serializable data, ensuring data integrity and sender authenticity.

**signResponse Example**

```javascript
import { signResponse, verifyResponse } from '@blocklet/meta/lib/security';
import { fromRandom } from '@ocap/wallet';

async function secureCommunicate() {
  const wallet = fromRandom(); // Your Blocklet's wallet
  const data = { message: 'hello world', timestamp: Date.now() };

  // Signing
  const signedData = signResponse(data, wallet);
  console.log('Signed Data:', signedData);

  // Verifying
  const isVerified = await verifyResponse(signedData, wallet);
  console.log('Verification result:', isVerified); // true
}
```

---

## UI & Theming

URL: https://www.arcblock.io/en/docs/blocklet-spec/spec-ui-theming-988441/

This section details the `navigation` and `theme` properties within the `blocklet.yml` file. These properties are instrumental in defining a blocklet's contribution to the user interface, controlling how it appears in menus, and specifying its look and feel to ensure a cohesive user experience.

Proper configuration of these fields allows a blocklet to integrate seamlessly into a larger application, providing clear navigation paths for users and adhering to established visual guidelines.

## Navigation

The `navigation` property is an array of objects that defines the blocklet's user-facing menu structure. It allows you to specify navigation links that will be merged into the parent application's navigation, such as headers, footers, or dashboards. This system is composable, meaning a parent blocklet can reference a child component, and the child's navigation items will be intelligently integrated into the parent's structure.

### Navigation Item Properties

Each item in the `navigation` array is an object that can contain the following fields:

- **id** `string` — A unique identifier for the navigation item. While optional, providing an id is best practice, especially for items that might be referenced or extended by other blocklets. The ID must conform to JavaScript variable naming rules.
- **title** `string | object` *(required)* — The text displayed for the navigation item. This can be a simple string or an object for internationalization (i18n), where keys are locale codes (e.g., en, zh).
- **description** `string | object` — A tooltip or supplementary text for the navigation item. It also supports i18n in the same way as title.
- **link** `string | object` — The destination URL for the navigation item. This can be a relative path (e.g., /profile) which will be resolved against the blocklet's mount point, or an absolute URL (e.g., https://www.arcblock.io). It also supports i18n.
- **component** `string` — The name or DID of a child component blocklet. When specified, this navigation item acts as a container for the child's own navigation entries, which will be nested under it.
- **section** `string | array` — Specifies where the navigation item should appear in the UI. A single item can belong to multiple sections. Valid values include: header, footer, bottom, social, dashboard, sessionManager, userCenter, and bottomNavigation.
- **role** `string | array` — Defines roles that are permitted to see this navigation item, enabling role-based access control (RBAC) for the UI.
- **icon** `string` — An identifier for an icon to be displayed next to the navigation item's title.
- **visible** `boolean` (default: `true`) — Controls the default visibility of the navigation item.
- **private** `boolean` (default: `false`) — If true, this item will only be visible when a user is viewing their own profile or user center, not when viewing another user's.
- **items** `array` — An array of nested navigation item objects, allowing for the creation of dropdowns or sub-menus.

### Example: Basic Navigation

Here is an example of a `navigation` configuration that defines a main link to the blocklet's home page and an external link in the footer.

**blocklet.yml**

```yaml
name: 'my-blocklet'
did: 'z8iZuf...s92'
version: '1.0.0'
title: 'My Blocklet'

interfaces:
  - type: 'web'
    name: 'publicUrl'
    path: '/'
    prefix: '*'
    port: 'BLOCKLET_PORT'

navigation:
  - title: 'Home'
    link: '/'
    section: 'header'
  - title:
      en: 'My Account'
      zh: '我的账户'
    link: '/profile'
    section: 'userCenter'
    role: ['guest', 'user']
    private: true
  - title: 'About Us'
    link: 'https://www.arcblock.io'
    section: 'footer'
    icon: 'mdi:info-outline'
```

### Example: Composable Navigation

This example demonstrates how a parent blocklet can compose its navigation with a child component. The "Dashboard" entry will automatically pull in and nest the navigation items defined within the `my-dashboard-component`.

**Parent Blocklet (blocklet.yml)**

```yaml
# ... (parent blocklet metadata)

components:
  - name: 'my-dashboard-component'
    source:
      store: 'https://store.arcblock.io/api'
      name: 'my-dashboard-component'

navigation:
  - title: 'Home'
    link: '/'
    section: 'header'
  - title: 'Dashboard'
    component: 'my-dashboard-component' # References the child component
    section: 'dashboard'
```

**Child Component (my-dashboard-component/blocklet.yml)**

```yaml
# ... (child component metadata)

navigation:
  - title: 'Overview'
    link: '/overview'
  - title: 'Settings'
    link: '/settings'
```

The final, merged navigation structure would result in a "Dashboard" menu with "Overview" and "Settings" as sub-items.

## Theming

The `theme` property allows a blocklet to define basic visual styles, such as background colors or images, that can be applied by the host application. This ensures that the blocklet's UI aligns with the overall aesthetic.

### Theme Properties

- **background** `string | object` — Specifies the background for different UI areas. It can be a single string (URL or color value) to be used as a default, or an object to define backgrounds for specific sections.
  - **header** `string` — Background for the header section.
  - **footer** `string` — Background for the footer section.
  - **default** `string` — Default background for other areas.

### Example: Theme Configuration

This example sets a default background color and a specific image for the header.

**blocklet.yml**

```yaml
name: 'my-themed-blocklet'
did: 'z8iZuf...s92'
version: '1.0.0'
title: 'My Themed Blocklet'

theme:
  background:
    default: '#F5F5F5'
    header: 'url(/assets/header-background.png)'
    footer: '#333333'
```

By leveraging the `navigation` and `theme` properties, developers can create blocklets that are not only functional but also deeply integrated into the end-user's application environment, providing a consistent and intuitive experience.

---

## Blocklet Store

URL: https://www.arcblock.io/en/docs/blocklet-store/

---

## Best practice

URL: https://www.arcblock.io/en/docs/blocklet-store/best-practice/

> NOTE: this page is in draft and is subject to change.
>

This page has advice on how you should implement your blocklet and list it in the store. As the store matures and we learn from developers' experiences, these recommendations will be updated.

## Design a high-quality blocklet

We encourage you to develop blocklets that are of high quality. High-quality blocklets conform to standards of performance, security, and user experience, as summarized by the following guidelines:

- <strong>Security</strong>: Is the blocklet safe for users? Make sure your blocklet does not pose security threats and does not use deceptive usage tactics.
- <strong>User privacy</strong>: Make sure that your blocklet handles user data appropriately and conforms to data privacy requirements.
- <strong>Performance</strong>: Does the blocklet function at an outstanding level? High-quality blocklets don't just perform their intended action, they do so while using as few system resources as possible.
- <strong>User experience</strong>: Is the blocklet a joy to use? The blocklet itself should provide a good-looking, intuitive, and seamless user experience while also respecting the end user's privacy.
- <strong>Store listing</strong>: The blocklet's listing should set the user's expectations and clearly communicate what the blocklet does. All image assets (icon, tile, marquee, and screenshots) should be provided. Images should not be blurry or too busy. Privacy information (permissions justifications, the blocklet's privacy policy, data use disclosures, etc.) must be accurate and up to date.

## Support DID

If your blocklet requires user login, we recommend that you provide at least some support for [DID Connect](https://didconnect.io/). DID Connect can help you provide a better user experience: users won't have to set up and remember username and password, they just need to review and confirm information requested by your blocklet on their [DID Wallet](https://didwallet.io/).

If you already have a login system, consider correlating the DID to the user account in your system.

## Create a compelling store listing

The better your blocklet's listing in the store, the more users will find and try your blocklet. When choosing your blocklet's name, writing its description, and designing its logo, keep in mind our guidelines.

### Provide great images

See [Supplying Images](/en/docs/blocklet-store/supplying-images/) for guidelines on the images you should supply to the store.

### Provide concise information

See [Listing information](/en/docs/blocklet-store/listing-information/) for guidelines on information you should supply to the store.

---

## Blocklet Detail Page

URL: https://www.arcblock.io/en/docs/blocklet-store/blocklet-detail-page/

Instructions on obtaining a meticulously configured blocklet detail page.

- [Listing information](/en/docs/blocklet-store/listing-information/)

- [Supplying images](/en/docs/blocklet-store/supplying-images/)

- [Choose License](/en/docs/blocklet-store/choose-license/)

---

## Frequently asked questions

URL: https://www.arcblock.io/en/docs/blocklet-store/blocklet-store-frequently-asked-questions/

#### Q：How to create a blocklet from scratch?

[Create Blocklet](/en/docs/blocklet-developer/create-blocklet/#creating-a-blocklet-project-based-on-an-existing-project)


#### Q：How to create a blocklet from existing project?

[Create Blocklet](/en/docs/blocklet-developer/create-blocklet/#creating-a-blocklet-project-based-on-an-existing-project)

---

## Publish your blocklet

URL: https://www.arcblock.io/en/docs/blocklet-store/blocklet-store-publish-your-blocklet/

> TODO: this page is not yet complete
>

This page describes how you publish a new blocklet to the Blocklet Store.

Before you publish an blocklet, you need to bundle, deploy and test it locally to make sure that it runs correctly and that all its functionality works as you intend.

To publish your blocklet to the Blocklet Store, follow these steps:

- Get your developer passport either through [invitation](/en/docs/blocklet-store/get-your-developer-passport/) or staking.
- Connect your Blocklet Studio or Development environment to the Blocklet Store with `blocklet connect`.
- Create your blocklet bundle with [blocklet bundle](/en/docs/blocklet-developer/welcome/)
- Upload your blocklet with [blocklet upload](/en/docs/blocklet-developer/welcome/)
- Publish your blocklet from the [developer dashboard](https://store.blocklet.dev/developer/blocklets)

We'll go into detail about each step below.

---

## Choose License

URL: https://www.arcblock.io/en/docs/blocklet-store/choose-license/

> TODO: this page need to be updated

---

## Request Entity too large

URL: https://www.arcblock.io/en/docs/blocklet-store/CS63EXGmCLEMhG-KTtwtWP-G/

Blocklet Store limit blocklet bundle size within a certain range for efficiency considerations, since larger bundles takes much more time to download and expand.

The default limit for blocklet bundle is 500M, if you upload bundle larger than that size, Blocklet Store will throw an Error.

If you want to increase the default bundle size limit, you need to take following steps:

- Update Blocklet Server Settings:  [Request Entity too Large](/en/docs/blocklet-developer/07ns0Nj6haMOsyrsTdyAjlps/)
- Update Blocklet Store Settings in Blocklet Dashboard -> Configuration -> Preferences -> Blocklet Store -> Blocklets -> Max Bundle Size

---

## Developer Program Policies

URL: https://www.arcblock.io/en/docs/blocklet-store/developer-policies/

<strong>Effective Date: 2024-06-01</strong>

Welcome to the Blocklet Store Developer Program. The following policies are designed to ensure a safe, trustworthy, and efficient environment for all users and developers. By participating in the Blocklet Store Developer Program, you agree to comply with these policies.

## 1. General Requirements

### 1.1 Developer Passports

All developers must get their developer passports (either through invitation or staking a small amount of ABT) to submit blocklets to the Blocklet Store. Accounts must be maintained with accurate and up-to-date information. ArcBlock reserves the right to verify this information and take appropriate actions on accounts found to be inaccurate or misleading.

### 1.2 Blocklet Requirements

Blocklets submitted to the Blocklet Store must:

- Be compatible with the Blocklet Store’s operational parameters and security measures.
- Not infringe on intellectual property rights.
- Not include malware, spyware, or any malicious code.
- Provide clear and truthful information about their functionality and data usage.

### 1.3 Privacy and Data Handling

Developers must:

- Adhere to all applicable laws and regulations regarding privacy and data protection.
- Provide a privacy policy that details how user data is collected, used, and protected.
- Obtain explicit consent from users before collecting or using their data.

## 2. Prohibited Actions

### 2.1 Misrepresentation

Developers may not misrepresent their identity or the purpose and functionality of their blocklets. Impersonation and misleading claims are strictly prohibited.

### 2.2 Manipulative Practices

Any attempt to manipulate ratings, reviews, or the functionality of the Blocklet Store is forbidden. This includes, but is not limited to, the use of bots, buying reviews, or other deceptive behaviors.

### 2.3 Illegal Activities

Blocklets must not facilitate or promote illegal activities. This includes the distribution of illegal content or the promotion of activities that violate local or international laws.

## 3. Content Policies

Blocklets must adhere to content guidelines that prohibit:

- Explicit or violent content.
- Hate speech, harassment, and bullying.
- Content that promotes discrimination based on race, gender, religion, nationality, disability, sexual orientation, or age.

## 4. Enforcement and Penalties

ArcBlock reserves the right to enforce these policies at its discretion. Actions may include, but are not limited to:

- Removal of blocklets from the Blocklet Store, and slashing of staked ABT when publishing blocklets (if any).
- Suspension or termination of developer accounts, and slashing of staked ABT when get developer passports (if any).
- Legal action against individuals or entities violating these policies.

## 5. Changes to Policies

ArcBlock may update these policies at any time. Developers will be notified of any significant changes. Continued participation in the program following any changes indicates acceptance of the new terms.

## 6. Contact Information

For questions or more information about these policies, please contact [blocklet@arcblock.io](mailto:blocklet@arcblock.io).

---

## Get your developer passport

URL: https://www.arcblock.io/en/docs/blocklet-store/get-your-developer-passport/

If we want to publish an application to the Blocklet Store, we need the Blocklet Store to issue a Developer certificate to us.

Because Blocklet Store is decentralized, anyone can create their own app store. If you are not an administrator of Blocklet Store, you can also create your own app store.

### Create your own app store

Visit the official Blocklet Store of ArcBlock.

[Blocklet Store](https://store.blocklet.dev/)

We search for Blocklet Store in the app store, install it, and then have our own Blocklet Store:

![image.png](https://media.arcblock.io/lib/f6/f6be289853e14d38dc4deb6813970ad9.w1600.webp)

### Blocklet Store administrators issue Developer Passports

First, have the administrator of the Blocklet Store issue passports on the Member page:

![image.png](https://media.arcblock.io/lib/38/387267180b47d3aad1cc0de9601bbd2d.w1600.webp)

Certificate type selection Developer:

![image.png](https://media.arcblock.io/lib/65/65cfb5fea73853e6eaef121029a2a1b4.w1600.webp)

Copy this certificate address and send it to the Blocklet developer:

![image.png](https://media.arcblock.io/lib/fb/fb8ea5dbe99f00fb85b526dae0e3b72f.w1600.webp)

### Blocklet developers receive Passports

Blocklet developers open the invite link and click on DID Connect to associate the passport:

![image.png](https://media.arcblock.io/lib/f9/f962160e7cf3ff3e39bdd6ec18174704.w1600.webp)

Once the acceptance is successful, this user will become the developer of this Blocklet Store, and will be able to upload and publish subsequent Blocklets.

---

## Internationalize your blocklet

URL: https://www.arcblock.io/en/docs/blocklet-store/internationalize-your-blocklet/

This page describes how to support multiple languages of an blocklet in the Blocklet Store.

Unless your blocklet is strictly local in scope, you should internationalize it, making it easy to adapt to various languages and regions. You can then localize it—translate and otherwise adapt it so that it works well in a particular locale.

The word internationalization is often abbreviated to i18n, referring to the 18 letters between the letters i and n. Localization is sometimes abbreviated to l10n.

You can follow these steps to internationalize and localize an blocklet to be published in the Blocklet Store:

- Decide which locales you want to support.
- Internationalize and localize the blocklet's UI with any available i18n libraries.
- Localize your blocklet's title, description in `blocklet.yml`.
- Localize your blocklet's introduction in `blocklet.md`.
- Upload your blocklet using the [Developer Dashboard](https://store.blocklet.dev/developer/blocklets).

---

## Listing information

URL: https://www.arcblock.io/en/docs/blocklet-store/listing-information/

Welcome to the Blocklet Development Guide. This document is designed to provide all developers with a complete l<strong>ist</strong> <strong>of steps</strong> to develop blocklets, helping you pass the blocklet review smoothly.

### Title

Provide a title for your blocklet in `blocklet.yml` or Blocklet Studio. The requirements are as follows:

- Language: English (preferred)
- Length: No more than 40 characters; try to stay within one line and avoid line breaks. If it is in other languages such as Chinese, Japanese, or Korean, no more than 20 characters (English is preferred);
- Content: Be concise and specific. Your content can be combined with application functions, homophones, visual names, innovative nouns, etc;

### Logo

See details at [Providing Image](/en/docs/blocklet-store/supplying-images/#blocklet-logo).

### Description

Describe your blocklet briefly in `blocklet.yml` or Blocklet Studio. The requirements are as follows:

- Language: English or Chinese;
- Length: no more than 160 characters, and if it is in other languages such as Chinese, Japanese, or Korean, no more than 80 characters (English is preferred);
- Content: Provide additional explanations or descriptions of keywords in the title, focusing on the description of core functions.

### Screenshot

See details at [Providing Image](/en/docs/blocklet-store/supplying-images/#blocklet-screenshot).

### Details

Provide a detailed introduction to your blocklet in `blocklet.md`; Focus on introducing the type of application you are building (entertainment, learning, store, tools, etc.), usage scenarios, purposes, methods, etc. For example, if you create a game, you can briefly introduce the game rules, operation buttons, etc. (Note: English is preferred). If you are creating a game in as second language such as Chinese, you must include an introduction in Chinese and English.

### Installation and Running

No complex configuration is required; it can be started and run normally.

### Other Instructions

You can include any optional links related to your blocklet. For example:

- Add a homepage address: To provide a more detailed explanation of how your Blocklet works; you can give a direct link to the Blocklet website by setting the homepage field in `blocklet.yml` or Blocklet Studio;
- Provide support address: The Blocklet Store provides a built-in user support experience under the "Support" tab of Blocklets, but you can use a dedicated support website by including a link in the community field of `blocklet.yml` or Blocklet Studio;
- Provide source code address: If your Blocklet is open-source, you can set the repository field in `blocklet.yml` or Blocklet Studio; to the actual repository address.

### Specific Descriptions Refer To The Following Illustrations:

![英文.png](https://media.arcblock.io/lib/b9/b959351c14afac3f14f12713292a89db.w1600.webp)

---

## How to fix logo and screenshot ratio?

URL: https://www.arcblock.io/en/docs/blocklet-store/LMo49mG9oAyDYRZT8aNsIS3h/

To guarantee the effective presentation of the Blocklet detail page, we require Blocklet developers to submit images that adhere to certain specifications. For further information:
[Supplying images](/en/docs/blocklet-store/c5294249-5d2b-4f66-9bf2-dab8134e21cc/)


Blocklet Studio offers user-friendly tools that help developers automatically crop logos and screenshots to meet the necessary aspect ratio and size requirements. The following are detailed instructions on how to utilize these tools:

### Building and publishing with Blocklet Studio？

If you are using Blocklet Studio to build and release applications, updating those already published is straightforward: simply create a new release and upload the logo and screenshots, then publish your new release on Blocklet Store.

### <video src="https://media.arcblock.io/lib/b9/b93d70581e2436f423cc35a1e069a4dd.mp4" controls></video>
Building with Blocklet CLI？

Developers creating applications through coding can update their logos and screenshots using the following steps, regardless of whether the application has been launched. Begin by confirming that you are using the latest official version, as this feature is only available in that version.

```javascript
npm install -g @blocklet/cli@beta
blocklet server start​
```

Next, run the following command in your Blocklet development directory:

```javascript
blocklet dev studio​
```

Next, navigate to the "Branding Images" page where you can update the Logo and screenshots.

<video src="https://media.arcblock.io/lib/8b/8b047689621bc97fcf99b44a5b3168ff.mp4" controls></video>
Once all changes have been made, you are required to upload and publish the updated version. If you have already enabled automatic publishing for your application, manual publication will not be necessary.

---

## Manage your blocklet

URL: https://www.arcblock.io/en/docs/blocklet-store/manage-your-blocklet/

> TODO: this page need to be updated, topics to be covered: auto publish, private publish

---

## Prepare your Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-store/prepare-your-blocklet/

- [Best practice](/en/docs/blocklet-store/best-practice/)
- [Internationalize your blocklet](/en/docs/blocklet-store/internationalize-your-blocklet/)

---

## Error: Bundles with the same did cannot in different stores

URL: https://www.arcblock.io/en/docs/blocklet-store/publish-error-same-did-cannot-in-different-store/

If you encounter the above error when publishing your blocklet to the blocklet store, like the following screenshot

![Screenshot 2024-01-26 at 05.49.07.png](https://media.arcblock.io/lib/1e/1ee78606283ebbbe8a87a986315663a3.w1600.webp)

All you need is to update your GitHub Actions Workflow:

```javascript
      - name: Upload to Blocklet Store
        uses: blocklet/action-workflow@v1
        env:

// update this according to your setup
          COMPONENT_STORE_URL: "https://test.store.blocklet.dev"
        with:
          skip-deps: true
          skip-upload: false
          skip-deploy: true
          skip-release: true
          bundle-command: yarn bundle
          working-directory: blocklets/enterprise
          store-endpoint: ${{ secrets.STORE_ENDPOINT_TEST }}
          store-access-token: ${{ secrets.STORE_ACCESS_TOKEN_TEST }}
          slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
```

---

## Publish your Blocklet

URL: https://www.arcblock.io/en/docs/blocklet-store/publish-your-blocklet/

- [Register as developer](/en/docs/blocklet-store/register-as-developer/)
- [Publish your blocklet](/en/docs/blocklet-store/blocklet-store-publish-your-blocklet/)
- [Manage your blocklet](/en/docs/blocklet-store/manage-your-blocklet/)

---

## Permission Modes

URL: https://www.arcblock.io/en/docs/blocklet-store/store-permision-modes/

At the heart of permission models of  Blocklet Store is the [DID](https://www.arcblock.io/content/collections/en/did) and [Verifiable Credential](https://www.arcblock.io/content/collections/en/verifiable-credential)-based <strong>developer passport</strong> mechanism, an advanced system for authorization and access control across the ArcBlock Platform. This mechanism allows for precise management of who can publish and manage blocklets on the store, using passports that can be issued/revoked by site masters and stored/presented via [DID Wallet](https://www.didwallet.io/).

### Invitation-Based Model: Excellence Through Exclusivity

The default setting in our revamped permission scheme is the invitation-based model. This model is designed for those who wish to maintain a curated and quality-controlled environment. Here’s how it works:

- <strong>Controlled Access</strong>: Store owers can extend invitations to developers whose skills and reliability are well-known, thus ensuring that only high-quality Blocklets are made available on the store.
- <strong>Unrestricted Publishing</strong>: Once invited, developers can publish their Blocklets without limitations, fostering an environment rich with trusted applications.

This model is perfect for maintaining a high standard of offerings in the store, ensuring every Blocklet adds value to the user's experience.

![image.png](https://media.arcblock.io/lib/ea/eac207c240614807784d379f42756598.w1600.webp)

### Staking-Based Model: Openness With Accountability

For those who prefer a more open ecosystem, we introduce the staking-based permission model. This model democratizes the publishing process by allowing anyone to participate, provided they meet certain criteria:

- <strong>Stake to Participate</strong>: Developers can gain their developer passport by staking a certain amount of ABT (ArcBlock Token). This stake is a pledge of good behavior and quality in the Blocklet development process.
- <strong>Further Staking for Publishing</strong>: To publish a Blocklet, developers must stake additional ABT. This serves as an assurance of their commitment to maintaining high standards in their offerings.
- <strong>Accountability Measures</strong>: If a developer acts maliciously or violates the store policies, they risk being blocked and may have their staked ABT slashed as a penalty.

This model is designed to encourage a broader participation by lowering barriers to entry while ensuring that developers are accountable for their contributions.

![image.png](https://media.arcblock.io/lib/81/819f22cb2dfe9cb63234f84685580b2d.w1600.webp)

A side note: if you made any changes to your Blocklet Store, please remember to restart your store to make those changes loaded in the runtime.

---

## Supplying images

URL: https://www.arcblock.io/en/docs/blocklet-store/supplying-images/

Welcome to the Blocklet Development Guide. This document is designed to help developers understand what images are required and how to add them to your Blocklet.

You need to provide the following two types of images for use in the Blocklet Store: Blocklet Logo and Screen Screenshots. Be sure to use high quality images to help increase use engagement and the overall experience for your Blocklet.

### Blocklet Logo

You must provide the Blocklet Logo image in the Bundle file of the Blocklet. Here are the requirements:

- Size: Greater than or equal to 256 x 256;
- Format: PNG;
- Size: Less than 500KB;
- Other suggestions:
-
  - The Logo should be unique and recognizable, use symbolic elements, and focus on color, simplicity, and font consistency.
  - Try to avoid adding borders around the image, as the UI may add edges;
  - The Logo should be clear and recognizable in both light mode and dark mode;
  - If most of your Logos are dark in color, consider adding a subtle white outer glow so that it will look good on a dark background;
  - Avoiding large shadows, UI may add shadows; using small shadows for comparison is acceptable;
  - Make the Logo face the audience rather than having an embedded perspective; subtle angle adjustments can give a tangible feel, but avoid dramatic angles;
  - Ensure that the Logo does not contain sensitive content or elements that do not comply with community standards (such as violence, pornography, illegal symbols, etc.).

### Blocklet Screenshot

Use screenshots to convey the appearance, type, functionality, and experience of the application in the Blocklet store. Here are some requirements for screenshots:

- Number of images: You must add at least 1, but no more than 5 images to your listing. (In some cases, we allow for exceptions such as a single display page, where 1-2 may be provided depending on the actual situation);
- Image Aspect Ratio and Dimensions: 16:9. The recommended dimensions are 1600 x 900, 1280 x 720, 800 x 450, 640 x 360, etc.;
- Format: PNG / JPG / JPEG / WEBP / GIF are all acceptable;
- Size: less than 5MB;
- Other suggestions:

-
  - The first screenshot will be used as the cover image on the store recommendation page, so it is recommended to be more distinctive and aesthetically pleasing;
  - Screenshots should showcase the actual user experience, focusing on core functionalities and content so that users can have a general idea about the blocklet;
  - Composition Best Practices: show key features in first 2-3 screenshots, keep text brief and readable, use consistent branding and style, ensure screenshots are high resolution, avoid cluttered interfaces
  - Content Strategy: tell a story through screenshot sequence, highlight unique selling points, include call-to-action text, show real app content, not placeholders, consider localization needs
- You can use [https://shots.so/](https://shots.so/) to produce more slick images.

---

## How to upload/update different links and videos on the Blocklet page?

URL: https://www.arcblock.io/en/docs/blocklet-store/update-blocklet-links-videos/

### How to create a new Blocklet and upload various links and videos:

- To create a Blocklet, navigate to the Blocklet Studio page and click the “+ New Blocklet” button in the upper right corner. Select the “Brand” field and fill in the necessary information as guided by the prompts on the page. Each field is closely linked to the details on the Blocklet page, so you can complete the link upload by following the instructions.
- The relationship between specific page link fields and Blocklet page details is outlined as follows:

![image.png](https://team.arcblock.io/comment/uploads/eded4b13b3c07a74b393738fd9e8d569.png)

- Keep scrolling down on this page until you find and click the "Video" button. Please note, that it's necessary to have your video uploaded beforehand to YouTube or Vimeo. Afterward, submit the video link on this page and click the "Confirm" button. The system will automatically embed the video into the details section of the current application page, displayed as follows:

![image.png](https://team.arcblock.io/comment/uploads/90f309abe6a694b120ab83fd3323659c.png)

![image.png](https://team.arcblock.io/comment/uploads/b29eaeb97eadfc79bfaf6a54dc91c2ae.png)

### How to update existing Blocklet links and videos:

- Open the Blocklet Studio page, select the Blocklet you wish to update, and click its name to navigate to the blocklet page. Click the “+ Create Version” button in the upper right corner to enter the modification page, where you can select the appropriate fields to make updates.
- Select the "Brand" field and update the associated page link accordingly.

![image.png](https://team.arcblock.io/comment/uploads/f6f95438ddae100d5c5903cc05e06a3d.png)

- Select the "Video" section to remove an existing video or add a new one according to your needs.

![image.png](https://team.arcblock.io/comment/uploads/94fe00788096ed523f0663bc13e37788.png)

---

## Terms and Policies

URL: https://www.arcblock.io/en/docs/blocklet-store/wCaylsbKprnq9BRN0KLeKgyO/

- [Developer Program Policies](/en/docs/blocklet-store/developer-policies/)

---

## What is blocklet store

URL: https://www.arcblock.io/en/docs/blocklet-store/what-is-blocklet-store/

> NOTE: this page is in draft and is subject to change.

## What is Blocklet Store?

Blocklet Store is a decentralized marketplace where developers publish decentralized apps (blocklets) and users can easily find, purchase and use them.

A published blocklet can be free, or the developer can charge for it using any payment method supported, including cryptocurrency.

To upload and publish items, use the [Blocklet Store Developer Dashboard](https://store.blocklet.dev/developer/blocklets).

## Why should I use Blocklet Store?

Publishing your blocklet in the Blocklet Store lets you reach more people, and earn revenue.

## How do I start?

- Learn more about [Blocklet Platform](https://www.blocklet.io/) and from [Blocklet Developer](/en/docs/blocklet-developer/welcome/)
- Publish your first blocklet by following the steps in [Publish in the Blocklet Store](/en/docs/blocklet-store/blocklet-store-publish-your-blocklet/).
- For addition help, check the [Blocklet Store FAQs](/en/docs/blocklet-store/blocklet-store-frequently-asked-questions/)

---

## How to create high-quality screenshot?

URL: https://www.arcblock.io/en/docs/blocklet-store/YVZZRV0_7Celkr5F7xrk_C77/

Blocklet Store has always been committed to providing developers and users with an excellent experience. To further improve the display effect of blocklets and reduce the cost of image production, we are about to usher in an important update!

### Update Details

Since November 13, 2024, the blocklet screenshots in Blocklet Store will be uniformly adjusted to a ratio of 16:9. We provide multiple recommended sizes, including 1600 x 900, 1280 x 720, 800 x 450, and 640 x 360, to ensure the best effect on different devices and platforms.

### The Processing Method Has Been Uploaded

For applications already online on the Blocklet Store, developers do not need to update. However, when updating applications in the future, screenshots need to be replaced with images that comply with the latest aspect ratios.

### Recommended Tool - [Shots](https://shots.so/)

To help developers easily adjust the screenshot size, we strongly recommend using the  [Shots](https://shots.so/) tool. The specific operation steps are as follows:

![Shots英文.png](https://team.arcblock.io/comment/uploads/1705eb1c0c6b0b544e579bf53073dee4.png)

Apart from the above requirements, developers can also unlock [Shots](https://shots.so/) more usage by themselves.

- <strong>Multiple models, free creation:</strong> Developers can freely choose from multiple models in Shots and start creating with simple drag and drop;
- <strong>Quick customization:</strong> provides quick customization options to adjust the appearance and layout of the model, making your photos more personalized;
- <strong>Rich background package:</strong> containing rich backgrounds such as gradients and images, further enhancing visual effects;
- <strong>Pre-set borders, perfect pixels:</strong> Pre-set borders are generated based on selected social media to ensure perfect pixel export of images.

We believe that the update of this screenshot ratio will bring developers and users a more high-quality and professional experience.

Let's work together to improve the overall presentation of the application!

Looking forward to developers actively participating together to create a more exciting Blocklet Store!

---

## Blocklet UI (React)

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/

---

## Components

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-9e3990/

This section provides a comprehensive reference for all available UI components in the Blocklet UI React library. Each component is documented with its properties (props), practical usage examples, and best practices to ensure seamless integration into your application.

The components are organized into logical categories to facilitate navigation and discovery. Select a category below to explore the components within it.

::::card-group
::link-card{title="Layout" description="Primary components like Header, Footer, and Dashboard that form the main structure of a blocklet application." icon="layout" href="/en/docs/blocklet-ui-react/components-layout-9e3990/"}
::link-card{title="User Management" description="A suite of components for handling user profiles, session management, and organization switching." icon="users" href="/en/docs/blocklet-ui-react/components-user-management-9e3990/"}
::link-card{title="Component Management" description="Tools for dynamically installing, publishing, and managing blocklet components within an application." icon="package" href="/en/docs/blocklet-ui-react/components-component-management-9e3990/"}
::link-card{title="Notifications" description="Provides components and utilities for implementing a real-time user notification system." icon="bell" href="/en/docs/blocklet-ui-react/components-notifications-9e3990/"}
::link-card{title="Utilities" description="A collection of helper components and utilities, such as a versatile Icon component and theme providers." icon="wrench" href="/en/docs/blocklet-ui-react/components-utilities-9e3990/"}
::::

To begin building your application's structure, proceed to the [Layout Components](/en/docs/blocklet-ui-react/components-layout-9e3990/) section.

---

## Component Management

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-component-management-9e3990/

Component management provides a suite of tools for dynamically installing, publishing, and managing blocklet components within a running application. This capability allows applications to be modular and extensible, enabling administrators and developers to add or update features without requiring a full redeployment of the core application.

These tools are essential for creating flexible systems where functionality can be composed and updated on the fly. For example, you can ensure that an application has all its necessary dependencies at runtime or provide an integrated interface for developers to publish new resources.

The primary components for managing this lifecycle are `ComponentInstaller` and `BlockletStudio`.

![Component Management](https://media.arcblock.io/lib/5a/5ad969a90b9fbb1e.w1600.webp)

## Core Tools

This section provides a brief overview of the available component management tools. For detailed documentation and usage examples, please refer to the specific sub-pages.

::::card-group
::link-card{title="ComponentInstaller" description="A utility component that verifies if all required dependent components are installed and provides a simple, role-protected interface for administrators to install any missing ones." icon="package" href="/en/docs/blocklet-ui-react/components-component-management-component-installer-9e3990/"}
::link-card{title="BlockletStudio" description="An embeddable iframe-based interface that provides a comprehensive studio for publishing, versioning, and managing components and their associated resources directly within your application." icon="box" href="/en/docs/blocklet-ui-react/components-component-management-blocklet-studio-9e3990/"}
::::

## Summary

By leveraging `ComponentInstaller` and `BlockletStudio`, developers can build robust applications that are easy to maintain and extend. `ComponentInstaller` ensures application health by managing dependencies, while `BlockletStudio` provides a powerful interface for content and feature management.

For more information on the underlying principles, see the [Core Concepts](/en/docs/blocklet-ui-react/core-concepts-9e3990/) documentation.

---

## BlockletStudio

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-component-management-blocklet-studio-9e3990/

The `BlockletStudio` component provides a streamlined, embeddable user interface for publishing and managing blocklet resources. It operates by rendering a full-page `iframe` that loads a dedicated publishing interface from a specified blocklet service. This allows your application to offer a consistent and powerful resource management experience without needing to build the UI from scratch.

Communication between the host application and the `BlockletStudio` iframe is handled securely using the `window.postMessage` API, enabling callbacks for events like uploads, releases, and connections.

## Usage Example

To integrate `BlockletStudio`, you need to manage its visibility state (e.g., with `useState`). Since the iframe may take a moment to load, it is recommended to display a loading indicator to the user. The `onOpened` callback can be used to signal that the iframe content is ready, at which point the loading indicator can be hidden.

The following example demonstrates how to implement a button that opens the `BlockletStudio` dialog and manages a loading state.

**Exporter.tsx**

```tsx
import { Icon } from '@iconify-icon/react';
import ArrowUp from '@iconify-icons/tabler/arrow-big-up-line';
import { Box, IconButton, CircularProgress as Spinner, svgIconClasses } from '@mui/material';
import { useState } from 'react';
import { BlockletStudio } from '@arcblock/ux-react';

// The DID of the blocklet that provides the studio service.
const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9';

export default function Exporter() {
  const [showCreateResource, setShowCreateResource] = useState(false);
  const [opening, setOpening] = useState(false);

  const handleShowDialog = () => {
    setOpening(true);
    setShowCreateResource(true);
  };

  return (
    <>
      <IconButton
        sx={{
          position: 'relative',
          minWidth: 40,
          minHeight: 40,
          borderRadius: '100%',
          [`.${svgIconClasses.root}`]: {
            color: 'text.secondary',
          },
        }}
        onClick={handleShowDialog}>
        {opening ? <Spinner size={16} /> : <Box component={Icon} icon={ArrowUp} style={{ fontSize: 24 }} />}
      </IconButton>
      <BlockletStudio
        open={showCreateResource}
        setOpen={setShowCreateResource}
        onOpened={() => setOpening(false)}
        componentDid={AI_STUDIO_COMPONENT_DID}
        mode="dialog"
        title="Demo Project"
        description="This is a demo project for the 'aigne' blocklet."
        note='Please review all resources and components before publishing.'
        introduction="Welcome to the resource publisher."
        tenantScope="test-tenant-scope-id-2"
        resourcesParams={{ name: 'test-project', extra: true }}
        dependentComponentsMode="readonly"
        componentsTitle="Required Components"
        resourcesTitle="Add Project Files"
        onConnected={() => alert('Connected')}
        onUploaded={() => alert('Uploaded')}
        onReleased={() => alert('Released')}
        components={[
          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
        ]}
        resources={{
          'z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB': [
            'template-448698592710885376',
            'template-448696391418511360',
          ],
        }}
      />
    </>
  );
}
```

## Props

The `BlockletStudio` component accepts the following props to control its behavior and appearance.

- **open** `boolean` *(required)* — Controls the visibility of the BlockletStudio iframe. Set to true to display it, and false to hide it.
- **setOpen** `(open: boolean) => void` *(required)* — A callback function used by BlockletStudio to request being closed. Typically, this function will set the state variable associated with the open prop to false.
- **componentDid** `string` *(required)* — The Decentralized Identifier (DID) of the blocklet that provides the resource publishing service. This determines which studio interface is loaded.
- **onOpened** `() => void` — An optional callback function that is executed when the BlockletStudio iframe has finished loading and is ready for user interaction.
- **onUploaded** `(data: unknown) => void` — An optional callback function that is triggered after a user successfully uploads a new resource. The data parameter contains metadata about the uploaded item.
- **onReleased** `(data: unknown) => void` — An optional callback function that is triggered after a user publishes a new release of a component. The data parameter contains information about the new release.
- **onConnected** `(data: unknown) => void` — An optional callback function that is triggered after a user connects a resource or component.
- **tenantScope** `string` — An optional string to scope the resources to a specific tenant. This can be used to ensure data isolation in a multi-tenant environment.
- **resourcesParams** `Record<string, any>` (default: `{}`) — An object containing query parameters to be passed to the blocklet's resource-fetching API endpoint. This allows for dynamic filtering of resources.
- **mode** `string` (default: `"dialog"`) — Determines the display mode of the studio interface. The default is 'dialog'.
- **title** `string` — An optional title to be displayed at the top of the studio interface.
- **logo** `string` — An optional URL for a logo to be displayed in the studio interface.
- **description** `string` — An optional string providing a short description, displayed in the studio UI.
- **introduction** `string` — An optional string for a more detailed introduction, displayed in the studio UI.
- **note** `string` — An optional string to display a note or important message to the user.
- **componentsTitle** `string` — An optional string to customize the title of the components section.
- **resourcesTitle** `string` — An optional string to customize the title of the resources section.
- **components** `Record<string, unknown>[]` (default: `[]`) — An array of objects representing components that should be pre-selected by default in the studio.
- **resources** `Record<string, unknown>` (default: `{}`) — An object representing resources that should be pre-selected by default in the studio.
- **dependentComponentsMode** `'auto' | 'readonly'` — Controls the behavior of dependent components. In 'readonly' mode, users cannot deselect components that are automatically included as dependencies of a selected resource.
- **style** `React.CSSProperties` (default: `{}`) — An object for applying custom CSS styles to the iframe element.
- **zIndex** `number` (default: `9999`) — The z-index CSS property for the iframe element, controlling its stacking order.

## Dependent Components

Blocklets that provide a resource API for the `BlockletStudio` can specify component dependencies directly within the resource data. When a user selects a resource that lists `dependentComponents`, the `BlockletStudio` will automatically select those components in the UI.

This feature simplifies the user experience by ensuring that all necessary dependencies are included automatically.

To implement this, your blocklet's resource API should return a `dependentComponents` array containing the DIDs of the required components.

### API Response Example

Here is an example of a JSON response from a resource API endpoint. The "Application" and "Tool" resources declare their component dependencies.

**API Response with Dependencies**

```json
{
  "resources": [
    {
      "id": "application-448698592710885376",
      "name": "My App (as Application)",
      "dependentComponents": [
        "error-did",
        "z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9",
        "z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ",
        "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"
      ]
    },
    {
      "id": "tool-448698592710885376",
      "name": "My App (as Tool)",
      "dependentComponents": ["error-did", "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"]
    },
    {
      "id": "template-448698592710885376",
      "name": "My App (as Template)"
    }
  ]
}
```

## Summary

The `BlockletStudio` component offers a powerful and convenient way to integrate resource and component management directly into your application. By leveraging an `iframe` and a clear set of props, it provides a consistent user experience while simplifying development. For related functionalities regarding dependency management, you may also want to review the [ComponentInstaller](/en/docs/blocklet-ui-react/components-component-management-component-installer-9e3990/) documentation.

---

## ComponentInstaller

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-component-management-component-installer-9e3990/

The `ComponentInstaller` is a utility component that acts as a gatekeeper for features that depend on other blocklets. It verifies whether specified component dependencies are installed. If they are not, it provides a user-friendly interface for administrators (`owner` or `admin` roles by default) to install them directly. If the user lacks the necessary permissions, it displays a message advising them to contact an administrator.

This component is essential for creating robust applications that can gracefully handle missing optional dependencies, improving the user experience by guiding administrators through the installation process.

## How It Works

The component's logic follows a clear, sequential process to ensure dependencies are met before rendering its child components.

![ComponentInstaller](https://media.arcblock.io/lib/10/102f4e3f1737f854.w1600.webp)

1. <strong>Dependency Check</strong>: It reads the `did` prop and checks against the blocklet's metadata (`window.blocklet.optionalComponents`) to determine if the required components are installed.
2. <strong>Permission Check</strong>: If any components are missing, it uses the `SessionPermission` component to verify if the current user's role matches those specified in the `roles` prop.
3. <strong>Conditional Rendering</strong>:
4.
  - If all dependencies are installed, it renders its `children`.
  - If dependencies are missing and the user has permission, it displays a pop-up installation panel.
  - If dependencies are missing and the user lacks permission, it either shows a suggestion to contact an admin or renders a `fallback` component if `noPermissionMute` is enabled.

## Basic Usage

Wrap any component or feature that relies on an optional blocklet with `ComponentInstaller`. Provide the DID of the required component.

**"MyFeature.jsx"**

```jsx
import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
import MyDependentComponent from './MyDependentComponent';

export default function MyFeature() {
  // Replace with the actual DID of the required component
  const requiredComponentDid = 'z8ia2427634f1e909a304e2b963715a18';

  return (
    <ComponentInstaller did={requiredComponentDid}>
      {/* This component will only be rendered if the dependency is met */}
      <MyDependentComponent />
    </ComponentInstaller>
  );
}
```

## Props

The `ComponentInstaller` accepts the following props to customize its behavior.

- **did** `string | string[]` *(required)* — The DID (or an array of DIDs) of the component dependencies to check. This is the primary identifier for the blocklet(s) you need.
- **children** `any` *(required)* — The content to render once all dependencies are confirmed to be installed. Can be a standard React node or a render function.
- **roles** `string[]` (default: `["owner", "admin"]`) — An array of user roles that are permitted to see the installation UI and install missing components.
- **fallback** `React.ReactNode` — A fallback component to display while checking for dependencies or when noPermissionMute is active for a user without installation rights.
- **noPermissionMute** `boolean` (default: `false`) — If true, users without permission will see the fallback component (or nothing) instead of the "contact admin" message.
- **disabled** `boolean` (default: `false`) — If true, the component bypasses all checks and immediately renders its children.
- **onInstalled** `function` — A callback function that is triggered after the dependency check is complete. It receives the list of installed components.
- **onError** `function` — A callback function that is triggered if an error occurs during the dependency check. It receives the list of components that caused the error.
- **onClose** `function` — A callback function invoked when the installation pop-up is closed.
- **closeByOutSize** `boolean` (default: `false`) — If true, the installation pop-up will close when the user clicks outside of it.
- **warnIcon** `React.ReactNode` — A custom React node to replace the default warning icon in the installation pop-up.

## Advanced Usage

### Checking Multiple Components

You can pass an array of DIDs to the `did` prop to check for multiple dependencies at once. The children will only render if all specified components are installed.

**"MyDashboard.jsx"**

```jsx
import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
import AnalyticsWidget from './AnalyticsWidget';
import CmsWidget from './CmsWidget';

export default function MyDashboard() {
  const requiredDids = [
    'z8ia2427634f1e909a304e2b963715a18', // Analytics Service
    'z8ia3c1f2e4b8e6a1b2c3d4e5f6a7b8c9', // CMS Service
  ];

  return (
    <ComponentInstaller did={requiredDids}>
      <AnalyticsWidget />
      <CmsWidget />
    </ComponentInstaller>
  );
}
```

### Using a Fallback for Loading States

Provide a `fallback` component to improve the user experience while the dependency check is in progress. This is also useful with `noPermissionMute` to display a placeholder for unauthorized users.

**"FeatureWithLoading.jsx"**

```jsx
import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
import CircularProgress from '@mui/material/CircularProgress';
import Box from '@mui/material/Box';
import MyDependentComponent from './MyDependentComponent';

export default function FeatureWithLoading() {
  const LoadingSpinner = (
    <Box sx={{ display: 'flex', justifyContent: 'center', p: 4 }}>
      <CircularProgress />
    </Box>
  );

  return (
    <ComponentInstaller
      did="z8ia2427634f1e909a304e2b963715a18"
      fallback={LoadingSpinner}
      noPermissionMute={true}
    >
      <MyDependentComponent />
    </ComponentInstaller>
  );
}
```

### Custom UI with Render Props

For full control over the UI, you can pass a function as `children`. This function receives an object with `hasPermission`, `optComponents`, and `installStatus`, allowing you to build a completely custom installation interface.

**"CustomInstallerButton.jsx"**

```jsx
import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
import Button from '@mui/material/Button';

export default function CustomInstallerButton() {
  const requiredDid = 'z8ia2427634f1e909a304e2b963715a18';

  return (
    <ComponentInstaller did={requiredDid}>
      {({ hasPermission, optComponents, installStatus }) => {
        const isMissing = optComponents.length > 0;
        const status = installStatus[requiredDid] || 'not_installed';

        if (!isMissing) {
          return <p>Feature is ready to use!</p>;
        }

        if (!hasPermission) {
          return <p>Please ask an admin to install the required component.</p>;
        }

        return (
          <Button
            variant="contained"
            disabled={status !== 'not_installed'}
            onClick={() => window.open(optComponents[0].installUrl, '_blank')}
          >
            {status === 'not_installed' ? `Install ${optComponents[0].meta.title}` : `Installing... (${status})`}
          </Button>
        );
      }}
    </ComponentInstaller>
  );
}
```

## Summary

The `ComponentInstaller` is a powerful component for managing optional dependencies within a blocklet application. It provides a structured and user-friendly way to ensure that required components are available, guiding administrators through the installation process when necessary. By using this component, you can build more resilient and feature-rich applications that adapt to the user's environment.

For further details on managing components, you may also be interested in the [BlockletStudio](/en/docs/blocklet-ui-react/components-component-management-blocklet-studio-9e3990/) component, which offers a more comprehensive interface for resource and component management.

---

## Layout

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-layout-9e3990/

Layout components are the foundational building blocks for structuring your blocklet application's user interface. They provide a consistent and predictable framework, including the main header, footer, and content areas. By leveraging these components, you can ensure a professional and cohesive user experience across your entire application, as they automatically adapt based on your blocklet's metadata.

These components form the primary visual structure of an application, as illustrated below:

![Layout](https://media.arcblock.io/lib/a1/a1d3a91af7858e95.w1600.webp)

This section provides an overview of the primary layout components available. For detailed implementation guides and API references, please refer to the specific documentation for each component.

::::card-group
::link-card{title="Header" description="Provides a responsive and customizable header, automatically populated with navigation links and user session controls from the blocklet's metadata." icon="navigation" href="/en/docs/blocklet-ui-react/components-layout-header-9e3990/"}
::link-card{title="Footer" description="Renders a consistent footer for your application, including branding, copyright information, social media links, and additional navigation." icon="book" href="/en/docs/blocklet-ui-react/components-layout-footer-9e3990/"}
::link-card{title="Dashboard" description="A pre-built dashboard layout with a sidebar, header, and content area, designed for admin interfaces and user-centric views." icon="layout" href="/en/docs/blocklet-ui-react/components-layout-dashboard-9e3990/"}
::::

## Summary

The layout components are designed to work together seamlessly, pulling configuration directly from your blocklet's metadata (`blocklet.yml`) to minimize boilerplate code and accelerate development.

To continue, please explore the detailed documentation for each component to understand their specific props, usage patterns, and customization options.

- <strong>Next</strong>: Learn about the [Header component](/en/docs/blocklet-ui-react/components-layout-header-9e3990/).

---

## Dashboard

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-layout-dashboard-9e3990/

The `Dashboard` component provides a pre-built, responsive layout for blocklet applications, typically used for administrative interfaces or user-centric views. It automatically constructs a standard dashboard with a sidebar, header, and main content area by interpreting your blocklet's metadata. This component significantly reduces boilerplate code for building common application structures.

The layout is composed of three primary sections: a persistent sidebar for navigation, a header for global actions and user information, and a main content area where the page-specific content is rendered.

The following diagram illustrates the component's structure and its relationship with the blocklet metadata:

![Dashboard](https://media.arcblock.io/lib/7c/7c37afd0b8bc889f.w1600.webp)

## Basic Usage

To use the `Dashboard` component, simply wrap your page's content with it. The component will automatically render the header and sidebar around your content.

**MyDashboard.jsx**

```javascript
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';

export default function MyDashboardPage() {
  return (
    <Dashboard>
      <h1>Welcome to the Dashboard</h1>
      <p>This is your main content area.</p>
    </Dashboard>
  );
}
```

The children passed to the `Dashboard` component will be displayed in the main content area.

## Props

The `Dashboard` component accepts the following props to customize its behavior and appearance.

- **children** `React.ReactNode` *(required)* — The content to be rendered within the main content area of the dashboard layout.
- **meta** `object` — A blocklet metadata object. If provided, it will be merged with and override the default window.blocklet metadata. This is useful for testing or dynamically altering blocklet information.
- **fallbackUrl** `string` (default: `publicPath`) — The URL to redirect to if the current authenticated user has no access to any navigation links based on their role. Set to null to disable this automatic redirection.
- **invalidPathFallback** `function` — A callback function that is executed when the current URL path does not match any of the available navigation links. The default behavior is to redirect to the first available link.
- **headerAddons** `React.ReactNode | function` — Allows for customization of the header's right-side addons. If a node is provided, it replaces all default addons. If a function is provided, it receives the default addons array as an argument, allowing you to add, remove, or reorder them.
- **sessionManagerProps** `object` — Props to be passed directly to the underlying SessionUser component in the header. This allows for customization of the user session menu, such as showRole or defining a custom onLogout handler.
- **links** `array | function` — Allows for programmatic modification of the sidebar navigation links. If an array is provided, its items are appended to the links generated from metadata. If a function is provided, it receives the metadata-generated links as an argument and should return a new array of links.
- **showDomainWarningDialog** `boolean` (default: `true`) — If true, displays a warning dialog if the application is accessed from an untrusted domain.

## How It Works

The `Dashboard` component is designed to be "configuration-driven," deriving its structure and content primarily from the blocklet's metadata file (`blocklet.yml`).

### Navigation from Metadata

The sidebar navigation is automatically generated from the `navigation` array in your `blocklet.yml`. The component specifically looks for navigation items that include `dashboard` in their `section` property.

Here is an example of how to define dashboard navigation:

**blocklet.yml**

```yaml
navigation:
  - title: 'Home'
    link: '/'
    section: 'dashboard'
    icon: 'mdi:home'
    role: ['owner', 'admin', 'guest']
  - title: 'Analytics'
    link: '/analytics'
    section: 'dashboard'
    icon: 'mdi:chart-bar'
    role: ['owner', 'admin']
  - title: 'Settings'
    link: '/settings'
    section: 'dashboard'
    icon: 'mdi:cog'
    role: ['owner']
    items:
      - title: 'Profile'
        link: '/settings/profile'
      - title: 'Billing'
        link: '/settings/billing'
```

### Role-Based Access Control

The `Dashboard` component enforces role-based access control (RBAC) on navigation links. Each navigation item can have a `role` property, which is an array of roles that are permitted to see the link.

- If a navigation item does not have a `role` property, it is visible to everyone.
- If the current user is not authenticated, they can only see items that include the `guest` role.
- If the current user is authenticated, the component compares their `user.role` with the `role` array of each navigation item. The item is only displayed if there is a match.
- A parent navigation item is only visible if at least one of its children is visible.

Using the `blocklet.yml` example above:

- A user with the `guest` role will only see the "Home" link.
- A user with the `admin` role will see "Home" and "Analytics".
- A user with the `owner` role will see all links, including the nested "Profile" and "Billing" links under "Settings".

### Icons

The `icon` property for a navigation item should be a string that corresponds to an icon name from the [Iconify](https://icon-sets.iconify.design/) library (e.g., `mdi:home`). You can also provide a full URL to an image file.

## Customization

While the `Dashboard` is designed to work out-of-the-box with metadata, it offers several props for more advanced customization.

### Customizing Header Addons

You can modify the default header addons (e.g., Theme Toggle, Locale Selector, Session Manager) using the `headerAddons` prop. By passing a function, you can add new elements or rearrange the existing ones.

**CustomHeader.jsx**

```javascript
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Button from '@mui/material/Button';

function MyCustomButton() {
  return <Button color="inherit" onClick={() => alert('Help!')}>Help</Button>;
}

export default function CustomDashboard() {
  return (
    <Dashboard
      headerAddons={(existingAddons) => {
        const customAddon = <MyCustomButton key="custom-help" />;
        // Add the custom button before the other addons
        return [customAddon, ...existingAddons];
      }}
    >
      <p>Dashboard with a custom header button.</p>
    </Dashboard>
  );
}
```

### Programmatically Adding Links

The `links` prop allows you to add or modify sidebar navigation links dynamically from your code. This is useful for links that depend on application state.

**DynamicLinks.jsx**

```javascript
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Icon from '@arcblock/ux/lib/Icon';

const useFeatureFlag = () => {
  // In a real app, this would check a feature flag service
  return true;
};

export default function DynamicDashboard() {
  const isBetaFeatureEnabled = useFeatureFlag();

  return (
    <Dashboard
      links={(existingLinks) => {
        if (isBetaFeatureEnabled) {
          const betaLink = {
            id: 'beta-feature',
            title: 'Beta Feature',
            url: '/beta',
            icon: <Icon name="mdi:test-tube" />,
            external: true, // Required for client-side routing
          };
          return [...existingLinks, betaLink];
        }
        return existingLinks;
      }}
    >
      <p>This dashboard may have dynamic links.</p>
    </Dashboard>
  );
}
```

## Summary

The `Dashboard` component is a powerful tool for quickly scaffolding application layouts. By leveraging blocklet metadata, it provides a structured, role-aware navigation system out of the box. For more foundational layout components, see the documentation for [Header](/en/docs/blocklet-ui-react/components-layout-header-9e3990/) and [Footer](/en/docs/blocklet-ui-react/components-layout-footer-9e3990/).

---

## Footer

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-layout-footer-9e3990/

The `Footer` component provides a standardized, responsive footer for your application. It automatically populates its content—including branding, navigation links, social media icons, and copyright information—by reading your blocklet's metadata. This data-driven approach ensures consistency and simplifies configuration.

The component is designed to be responsive, adapting its layout for different screen sizes. It also includes built-in logic to hide itself when the application is running in an embedded mode, ensuring a clean user interface in integrations.

## Basic Usage

To add a footer to your application, simply import and render the `Footer` component. It requires no props for basic use, as it automatically sources data from the global `window.blocklet` object.

**Usage Example**

```jsx
import React from 'react';
import { Footer } from '@blocklet/ui-react';

export default function App() {
  return (
    <div style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
      <main style={{ flex: 1 }}>
        {/* Your application content goes here */}
      </main>
      <Footer />
    </div>
  );
}
```

## Props

The `Footer` component can be customized through the following props.

- **meta** `object` — An object containing blocklet metadata. Use this prop to override the default window.blocklet configuration or to provide data in environments where the global object is not available. The structure should match the blocklet metadata format.
- **theme** `object` — A theme object to customize the footer's appearance. This object is deeply merged with the application's default theme, allowing you to override specific styles like colors, fonts, and spacing.

## Metadata Configuration

The content of the `Footer` is primarily configured through the blocklet's metadata file (`blocklet.yml`). The component reads specific fields from this file to render its different sections.

Below is an example of a `blocklet.yml` configuration that populates all sections of the footer.

**blocklet.yml**

```yaml
name: my-app
title: My App
description: A detailed description of my application that appears in the footer.
copyright: 'My Company Inc.'

# Navigation links are structured into groups
navigation:
  # Main footer navigation, supports two levels for grouping
  footer:
    - title: 'Products'
      items:
        - title: 'Product A'
          link: '/products/a'
        - title: 'Product B'
          link: '/products/b'
    - title: 'Resources'
      items:
        - title: 'Documentation'
          link: '/docs'
        - title: 'Blog'
          link: '/blog'

  # Social media links
  social:
    - title: 'twitter' # Icon is inferred from the title (e.g., 'twitter', 'github')
      link: 'https://twitter.com/your-handle'
    - title: 'github'
      icon: 'mdi:github' # You can also specify an Iconify icon name
      link: 'https://github.com/your-org'

  # Bottom links, typically for legal and privacy information
  bottom:
    - title: 'Privacy Policy'
      link: '/privacy'
    - title: 'Terms of Service'
      link: '/terms'
```

### Data Structure

The `navigation` object in your metadata defines the links displayed in the footer. It is organized into three distinct sections: `footer`, `social`, and `bottom`.

- **navigation** `object` — Contains all navigation structures for the application.
  - **footer** `array` — An array of link groups for the main footer navigation area. Supports a two-level hierarchy.
    - **[].title** `string` *(required)* — The title of the navigation group (e.g., 'Products').
    - **[].link** `string` — An optional link for the group title itself.
    - **[].items** `array` — An array of child navigation links.
      - **[].title** `string` *(required)* — The display text for the link.
      - **[].link** `string` *(required)* — The URL for the navigation link.
  - **social** `array` — An array of links to social media profiles.
    - **[].title** `string` *(required)* — The name of the social media platform, used to infer the icon (e.g., 'twitter').
    - **[].icon** `string` — Explicitly specify an icon using an Iconify string (e.g., `mdi:github`). Overrides the inferred icon.
    - **[].link** `string` *(required)* — The URL to the social media profile.
  - **bottom** `array` — An array of links displayed at the very bottom of the footer, typically for legal notices.
    - **[].title** `string` *(required)* — The display text for the link (e.g., 'Privacy Policy').
    - **[].link** `string` *(required)* — The URL for the link.

## Layouts

The `Footer` component intelligently selects the most appropriate layout based on the provided data. This ensures a clean and functional presentation across different use cases.

- <strong>Standard Layout</strong>: This layout is automatically activated when `footer` navigation links or `social` media links are defined in your metadata. It features a multi-section design that elegantly organizes the brand information, social icons, and navigation columns. On mobile devices, the navigation groups become collapsible accordions for a better user experience.
- <strong>Plain Layout</strong>: If no `footer` or `social` links are provided, the component falls back to a simplified, single-row layout. This is ideal for applications that only require a copyright notice and a few essential links, such as "Terms of Service" or "Privacy Policy".

## Theming

You can customize the footer's appearance by passing a `theme` object. This object is deeply merged with the existing theme, allowing for targeted overrides.

**Custom Theme Example**

```jsx
import { Footer } from '@blocklet/ui-react';

const customTheme = {
  palette: {
    background: {
      default: '#2c3e50', // A darker background for the footer
    },
    text: {
      primary: '#ecf0f1',
      secondary: '#bdc3c7',
    },
    divider: '#34495e',
  },
};

// ... in your component's render method
<Footer theme={customTheme} bordered />;
```

## Behavior in Embedded Mode

The `Footer` component is wrapped in a higher-order component (`withHideWhenEmbed`) that automatically hides it when the application is rendered in an embedded context. This behavior is controlled by a session storage key, `EMBED_MODE_KEY`. If this key is set to `1`, the footer will not be rendered. This is useful for preventing redundant footers when your blocklet is displayed inside another application.

For information on the header component, which is also configured via blocklet metadata, please see the [Header documentation](/en/docs/blocklet-ui-react/components-layout-header-9e3990/).

---

## Header

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-layout-header-9e3990/

The `Header` component provides a responsive and customizable header for a Blocklet application. It automatically populates navigation links, the application logo, and user session controls by reading metadata directly from the blocklet's configuration (`blocklet.yml`). This component is designed to create a consistent and feature-rich header with minimal configuration.

## Overview

The `Header` component serves as a primary navigation and branding element. It is built on top of `@arcblock/ux` components, including `ResponsiveHeader` and `NavMenu`, and integrates seamlessly with the DID Connect session context for user authentication.

Key features include:

- <strong>Automatic Configuration</strong>: Populates the app logo, title, and navigation links from `blocklet.yml`.
- <strong>Responsive Design</strong>: Adapts automatically to different screen sizes, providing a mobile-friendly navigation menu.
- <strong>Session Management</strong>: Integrates with DID Connect to display user information, profile menus, and login/logout buttons.
- <strong>Customizable Addons</strong>: Allows for the injection of custom components or modification of default elements like the theme toggle and locale selector.
- <strong>Organization Switching</strong>: Automatically includes an organization switcher if the blocklet has organization support enabled.
- <strong>Domain Warnings</strong>: Notifies administrators and users when accessing the application via a temporary domain to encourage custom domain configuration for better security.

### How It Works

The diagram below illustrates the data flow and component composition of the `Header`. It reads configuration from the `blocklet.yml` file, processes it, and renders the appropriate UI elements, including the logo, navigation links, and user session controls.

![Header](https://media.arcblock.io/lib/cd/cdc29d2826e1d718.w1600.webp)

## Basic Usage

To use the `Header`, import it and place it in your application's layout. It requires the blocklet's metadata, which is typically available globally via `window.blocklet`.

**"App.js"**

```javascript
import Header from '@blocklet/ui-react/lib/Header';

function App() {
  // The meta object is usually sourced from window.blocklet
  const blockletMeta = window.blocklet || {};

  return (
    <div>
      <Header meta={blockletMeta} />
      <main>
        {/* Your application content */}
      </main>
    </div>
  );
}

export default App;
```

## Props

The `Header` component accepts several props for customization.

- **meta** `BlockletMetaProps` — The blocklet's metadata object, typically from window.blocklet. It contains information like name, logo, and navigation that the component uses for rendering.
- **addons** `Function | React.ReactNode` — Custom elements to be added to the right side of the header. If a function is provided, it receives the built-in addons as an argument, allowing you to modify, reorder, or supplement them. If a node is provided, it replaces all built-in addons.
- **sessionManagerProps** `SessionManagerProps` (default: `{ "showRole": true }`) — Props passed directly to the underlying SessionUser component to control the display of user session information, such as showing the user's role.
- **homeLink** `string | Function` (default: `publicPath`) — The URL for the home link, which is typically triggered by clicking the logo or brand name. It defaults to the blocklet's public path (/). Can also be a function that returns a JSX element.
- **theme** `object` — A Material-UI theme object to merge with the default theme, allowing for deep customization of colors, typography, and other styles.
- **hideNavMenu** `boolean` (default: `false`) — If true, the navigation menu generated from blocklet.yml will be hidden, even if navigation data exists.
- **bordered** `boolean` (default: `false`) — If true, a bottom border will be applied to the header for visual separation.
- **logo** `React.ReactNode` — A custom logo element to override the one from the blocklet metadata.
- **brand** `React.ReactNode` — A custom brand element (e.g., text or an image) to display next to the logo.
- **showDomainWarningDialog** `boolean` (default: `true`) — If false, the dialog warning about temporary domains will not be shown.

## Features

### Automatic Navigation from Metadata

The `Header` automatically generates its navigation menu from the `navigation` array in your `blocklet.yml` file. The component parses this configuration to create primary navigation links and nested dropdown menus.

Here is an example of a `navigation` configuration in `blocklet.yml`:

**"blocklet.yml"**

```yaml
navigation:
  - title: Features
    link: /features
    icon: 'mdi:star'
  - title: Docs
    link: /docs
    icon: 'mdi:book-open'
  - title: More
    items:
      - title: About Us
        link: /about
        description: Learn more about our mission.
      - title: Community
        link: https://community.example.com
        description: Join our community forum.
```

The `parseNavigation` utility processes this structure, handles localization for `title` and `description`, and determines the active link based on the current URL path.

### Session Management and Addons

The right side of the header contains "addons," which are a collection of controls for session management and application settings. By default, these include:

- <strong>Organization Switcher</strong>: Appears if the blocklet has organization support enabled.
- <strong>Notification Center</strong>: Appears if the blocklet includes a notifications page.
- <strong>Locale Selector</strong>: Appears if multiple languages are configured.
- <strong>Theme Mode Toggle</strong>: Switches between light and dark modes.
- <strong>Session Controls</strong>: Displays the logged-in user's avatar and a menu with links for profile, settings, and logout. For guests, it shows a "Connect Wallet" button.

#### Customizing Addons

You can customize these addons using the `addons` prop.

<strong>Example: Appending a custom button</strong>

Provide a function to the `addons` prop. This function receives an array of the default addon elements, allowing you to add your own.

**"HeaderWithCustomAddon.js"**

```javascript
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button';

function HeaderWithCustomAddon() {
  return (
    <Header
      meta={window.blocklet}
      addons={(builtInAddons) => (
        <>
          {builtInAddons}
          <Button variant="contained" color="primary" sx={{ ml: 1 }}>
            Upgrade
          </Button>
        </>
      )}
    />
  );
}
```

<strong>Example: Replacing all addons</strong>

Provide a React node or an array of nodes to replace the default addons entirely.

**"HeaderWithReplacedAddons.js"**

```javascript
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button';

function HeaderWithReplacedAddons() {
  return (
    <Header
      meta={window.blocklet}
      addons={[
        <Button key="feedback" variant="outlined" sx={{ ml: 1 }}>
          Feedback
        </Button>,
      ]}
    />
  );
}
```

### Hiding in Embedded Mode

The `Header` is wrapped with the `withHideWhenEmbed` higher-order component. It will automatically be hidden when the application is rendered in an embedded context (e.g., within an iframe where `sessionStorage` contains `EMBED_MODE_KEY: 1`). This is useful for providing a cleaner UI when your blocklet is integrated into another application.

## Summary

The `Header` component is a powerful tool for establishing consistent branding and navigation across a Blocklet application. By leveraging blocklet metadata, it simplifies development while offering extensive customization through props.

For related layout components, please see the documentation for the [Footer](/en/docs/blocklet-ui-react/components-layout-footer-9e3990/).

---

## Notifications

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-notifications-9e3990/

This section provides a detailed guide to the components and utilities available for implementing a real-time user notification system. The system is designed to deliver timely updates to users through a dedicated UI component and toast messages.

The core of the notification system is built around a WebSocket connection, enabling the server to push updates to the client instantly. This ensures that users are always informed of important events without needing to refresh the application.

## Architecture Overview

The notification system follows a straightforward, event-driven architecture. When a notable event occurs in the backend, a notification is generated and broadcasted through a WebSocket channel. The frontend client listens on this channel, receives the notification, and updates the UI accordingly.

![Notifications](https://media.arcblock.io/lib/21/21d414d5397a71a8.w1600.webp)

## Core Components

The notification system is primarily composed of two React components: `NotificationAddon` and `NotificationSnackbar`.

### NotificationAddon

The `NotificationAddon` component serves as the main user interface element for notifications. It renders a bell icon that displays a badge indicating the number of unread notifications.

#### Features

- <strong>Unread Count</strong>: Displays a real-time count of unread notifications.
- <strong>WebSocket Integration</strong>: Automatically connects to the notification WebSocket channel and listens for incoming messages.
- <strong>Toast Notifications</strong>: Triggers toast messages for new component-level notifications.
- <strong>Direct Navigation</strong>: Functions as a link to the main notifications page.

#### Usage

To use this component, import it and place it within a layout component, such as an application header. It requires a `session` object, typically obtained from a session context, to function correctly.

**Example:**

```javascript
import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
import { useSessionContext } from '@arcblock/did-connect-react';

export default function AppHeader() {
  const { session } = useSessionContext();

  return (
    <header>
      {/* Other header content */}
      <NotificationAddon session={session} />
    </header>
  );
}
```

<strong>Important</strong>: For the toast notifications to work, your application must be wrapped in a `SnackbarProvider` from the `notistack` library.

**Example:**

```javascript
import { SnackbarProvider } from 'notistack';
import App from './App';

function Root() {
  return (
    <SnackbarProvider maxSnack={3}>
      <App />
    </SnackbarProvider>
  );
}
```

#### Props

- **session** `object` *(required)* — The session object containing user and notification data. The component relies on session.user, session.unReadCount, and session.setUnReadCount.

### NotificationSnackbar

This component provides a rich, standardized UI for toast notifications. It is used internally by `NotificationAddon` via `notistack`'s `enqueueSnackbar` function and is not intended for direct use.

#### Features

- <strong>Severity-Based Styling</strong>: The appearance of the snackbar changes based on the notification's severity level (`success`, `info`, `warning`, `error`).
- <strong>Rich Content Display</strong>: Capable of displaying structured activity notifications (e.g., "User X liked your post") in addition to simple titles and descriptions.
- <strong>Interactive Links</strong>: Automatically converts recognized patterns in the description (like user DIDs or DApp addresses) into clickable links.
- <strong>Click-to-Open</strong>: Clicking the snackbar navigates the user to the detailed notification view.

## WebSocket Integration

Real-time functionality is powered by a WebSocket client managed by the `useListenWsClient` hook. This hook establishes a connection for the logged-in user and listens for specific events.

### useListenWsClient Hook

This hook abstracts the complexity of creating and managing the WebSocket connection. It retrieves the current user session and initializes a client connected to a specified endpoint.

**Hook**

```javascript
const wsClient = useListenWsClient('user');
```

### Events

The `NotificationAddon` component subscribes to the following events on the `user` channel:

| Event Name  | Description  |
|---|---|
| `notification:blocklet:create`  | Fired when a new notification is created for the user. The component increments the unread count and may display a toast message.  |
| `notification:blocklet:read`  | Fired when one or more notifications have been read. The component decrements the unread count by the number of notifications that were read.  |

The full event name is dynamically constructed using the blocklet's DID and the user's DID, for example: `{blocklet.did}/{user.did}/notification:blocklet:create`.

## Key Utilities

Several utility functions support the notification system by processing and formatting notification data.

### mergeAdjacentNotifications

This function groups consecutive, similar notifications into a single, aggregated entry. For example, if a user receives multiple "like" notifications in a row from different users, this function can merge them into a single notification like "Alice, Bob, and 2 others liked your post."

### toClickableSpan

This utility is responsible for enhancing notification descriptions by converting plain text into rich, interactive content. It parses the input string, identifies special entities like user DIDs or DApp addresses, and transforms them into clickable HTML `<a>` tags. This allows users to navigate directly to a user's profile or a DApp's page from within a notification.

### sanitize

A wrapper around `DOMPurify` that cleans and sanitizes HTML content before it is rendered. This is a security measure to prevent cross-site scripting (XSS) attacks when displaying notification content that may contain user-generated data.

## Summary

The notification system provides a robust and real-time solution for keeping users informed. By leveraging the `NotificationAddon` component and ensuring your application is configured with the `SnackbarProvider`, you can easily integrate a full-featured notification center into your blocklet. The underlying WebSocket architecture ensures that updates are delivered instantly, creating a dynamic and responsive user experience.

---

## User Management

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-user-management-9e3990/

The User Management suite provides a collection of pre-built React components designed to handle essential user-related functionalities. These components simplify the implementation of user profiles, session management, and organization switching within your application, ensuring a consistent and reliable user experience.

This section provides an overview of the main components available in the suite. The following diagram illustrates how a user interacts with the different components of the application:

![User Management](https://media.arcblock.io/lib/60/6081516d3917600c.w1600.webp)

For detailed implementation guides and API references, please refer to the specific component documentation linked below.

## Core Components

The suite is composed of several key components, each addressing a specific aspect of user management.

::::card-group
::link-card{title="UserCenter" description="A comprehensive component for displaying and managing user profiles. It includes features for handling user settings, passport management, and social interactions like following other users." icon="user" href="/en/docs/blocklet-ui-react/components-user-management-user-center-9e3990/"}
::link-card{title="UserSessions" description="A security-focused component that allows users to view and manage their active and past login sessions across different devices, enhancing account security." icon="smartphone" href="/en/docs/blocklet-ui-react/components-user-management-user-sessions-9e3990/"}
::::

### Organization Switching

The `OrgsSwitch` component provides a dropdown menu interface for users who belong to multiple organizations. It allows for seamless context switching, which is critical for applications with team-based or multi-tenant features.

<strong>Key Features:</strong>

- <strong>Current Organization Display:</strong> Clearly shows the user's current organizational context.
- <strong>Organization List:</strong> Lists all available organizations a user can switch to, complete with infinite scrolling for performance.
- <strong>Search Functionality:</strong> Includes a search bar to quickly filter and find a specific organization.
- <strong>Creation and Navigation:</strong> Provides options to create a new organization and a link to a dedicated page for managing all organizations.

### Hooks for User Interaction

To facilitate the development of social features, the library also includes custom hooks and contexts that abstract away complex logic.

- <strong>`useFollow`</strong> <strong>hook</strong>: This hook manages the complete logic for following and unfollowing other users. It handles the API requests and state changes, returning the current follow status (`followed`) and functions to `followUser` and `unfollowUser`.
- <strong>`UserFollowersProvider`</strong> <strong>context</strong>: For applications where follow status needs to be accessible across multiple components, this provider wraps a section of your component tree and makes the follow state and actions available via the `useUserFollowersContext` hook.

## Summary

This suite of components provides the necessary building blocks for robust user management in any application built with the library. By using these components, you can accelerate development and ensure your application follows best practices for user account management and security.

For detailed implementation guides, please proceed to the specific component documentation.

- <strong>Next:</strong> [UserCenter](/en/docs/blocklet-ui-react/components-user-management-user-center-9e3990/)
- <strong>See Also:</strong> [UserSessions](/en/docs/blocklet-ui-react/components-user-management-user-sessions-9e3990/)

---

## UserCenter

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-user-management-user-center-9e3990/

The `UserCenter` component is a comprehensive, pre-built interface that provides a complete user profile and settings management page. It integrates various functionalities, including user information display, passport management, privacy controls, notification settings, and DID storage management, offering a centralized hub for users.

This component is designed to be highly extensible, allowing developers to add custom tabs and content through the blocklet's metadata, ensuring a consistent user experience across different applications.

![UserCenter](https://media.arcblock.io/lib/13/13ebd2b3a250c2d2.w1600.webp)

## Basic Usage

To use the `UserCenter`, you need to provide the `currentTab` prop, which determines which section is active. This is typically derived from the application's router.

**UserCenter Example**

```javascript
import React from 'react';
import { UserCenter } from '@blocklet/ui-react';

export default function ProfilePage() {
  // In a real application, you would get this value from your router.
  // For example, if the URL is /profile/settings, currentTab would be '/profile/settings'.
  const currentTab = '/profile/nfts';

  return <UserCenter currentTab={currentTab} />;
}
```

## Props

The `UserCenter` component accepts several props to customize its behavior and appearance.

- **children** `React.ReactNode` — Used to render content for custom tabs defined in the blocklet's navigation settings. The UserCenter will display the children when currentTab matches a custom tab's URL.
- **currentTab** `string` *(required)* — The value of the currently active tab. This should match the value property of one of the available tabs (either default or custom). It is used to highlight the correct tab and display its corresponding content.
- **userDid** `string` — The DID of the user whose profile is to be displayed. If omitted, the component will attempt to get the DID from the URL query parameter (?did=...) or default to the currently logged-in user.
- **embed** `boolean` (default: `false`) — If set to true, the component renders in an embedded mode without the main Header and Footer, making it suitable for integration within other layouts or pages.
- **onlyProfile** `boolean` (default: `false`) — If set to true, only the UserBasicInfo profile card is displayed, without any tabs or content sections. This is useful for contexts where only a compact user profile is needed.
- **hideFooter** `boolean` (default: `false`) — If set to true, the Footer component will not be rendered.
- **headerProps** `object` — Props to be passed down to the underlying Header component for customization.
- **footerProps** `object` — Props to be passed down to the underlying Footer component for customization.
- **onDestroySelf** `() => void` — A callback function that is triggered when a non-owner user initiates the account deletion process from the "Danger Zone" in the settings.
- **notLoginContent** `React.ReactNode` — Custom content to display when no user is logged in and no userDid is provided. If not set, a default login prompt is shown.

## Core Features

The `UserCenter` is composed of several key sections and components that provide a rich user experience out of the box.

### Default Tabs

By default, the `UserCenter` includes the following tabs for every user:

| Tab  | Description  | Visibility  |
|---|---|---|
| <strong>NFTs</strong>  | Displays the user's NFT collections.  | Public  |
| <strong>Social Activity</strong>  | Shows the user's followers and following lists if social features are enabled.  | Public  |
| <strong>Settings</strong>  | Access to profile, privacy, notification, and session management.  | Owner Only  |
| <strong>Storage</strong>  | Interface for managing connections to DID Spaces for decentralized storage.  | Owner Only  |

### User Profile (UserBasicInfo)

The `UserBasicInfo` component is a dedicated section (typically a sidebar on desktop) that displays essential user details:

- <strong>Avatar and Name</strong>: Shows the user's profile picture and full name. The owner can click the avatar to open the profile switcher.
- <strong>DID</strong>: Displays the user's Decentralized Identifier, with options to copy it or view its QR code.
- <strong>Social Actions</strong>: For public profiles, it shows "Follow" or "Unfollow" buttons.
- <strong>Metadata</strong>: Displays user-provided information such as bio, location, and social links.
- <strong>Private Information</strong>: For the owner, it shows private details like email and phone number.

### Passport Management

On the main profile tab (NFTs), the currently logged-in user will see a section dedicated to their DID Passports. This area lists all associated passports, indicating their status (e.g., active, revoked) and highlighting the one currently in use.

### Settings

The "Settings" tab is a comprehensive panel available only to the user who owns the profile. It is organized into several sub-sections:

- <strong>Common Settings</strong>: Allows users to update their public profile information like name, bio, and social links.
- <strong>Notification Management</strong>: Configure how to receive notifications (Wallet, Email, Push) and manage webhooks.
- <strong>Third-Party Login</strong>: Manage connections to other identity providers like Google, GitHub, or Passkeys.
- <strong>Privacy Management</strong>: Control the visibility of different tabs on the user profile, making them public or private.
- <strong>Session Management</strong>: View and revoke active login sessions across different devices.
- <strong>Danger Zone</strong>: For non-owner roles, provides an option to delete their own account.

## Customization

You can extend the `UserCenter` by adding new tabs through your blocklet's configuration.

1. <strong>Define Custom Tabs in</strong> <strong>`blocklet.yml`</strong> Add entries to the `navigation.userCenter` array in your `blocklet.yml` file. Each entry represents a new tab. **blocklet.yml**  ```yaml navigation:   - title: User Center     role: guest     userCenter:       - title: My Activity         link: /profile/activity         icon: 'material-symbols:history'         # Set to true if this tab should only be visible to the profile owner         private: false ```
2. <strong>Render Content for the Custom Tab</strong> In your component, pass a child element that will be rendered when the `currentTab` prop matches the `link` you defined. **MyActivity.js**  ```javascript import React from 'react'; import { UserCenter } from '@blocklet/ui-react';  function MyActivityComponent() {   return <div>This is the custom activity content.</div>; }  export default function ProfilePageWithActivity() {   // This value would come from your router, e.g., '/profile/activity'   const currentTab = '/profile/activity';    return (     <UserCenter currentTab={currentTab}>{currentTab === '/profile/activity' && <MyActivityComponent />}</UserCenter>   ); } ```

This approach allows you to seamlessly integrate application-specific pages into the standard `UserCenter` layout.

---

## UserSessions

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-user-management-user-sessions-9e3990/

The `UserSessions` component renders a comprehensive data table for displaying and managing a user's login sessions. It provides a clear overview of all active, expired, and offline sessions across various devices, giving users control over their account security.

The component is designed to be a plug-and-play solution for developers needing to implement session management features. It handles data fetching, pagination, UI rendering, and actions like logging out of specific sessions.

## Features

- <strong>Session Filtering:</strong> Users can easily filter sessions by their status: `online`, `expired`, or `offline`.
- <strong>Detailed Information:</strong> Each session entry displays parsed user-agent data, including the operating system, device type (browser), and wallet OS.
- <strong>IP Geolocation:</strong> Automatically resolves and displays the geographical region based on the last login IP address.
- <strong>Session Termination:</strong> Allows users to terminate any session except the current one.
- <strong>Bulk Actions:</strong> Includes a "Logout All" feature to terminate all sessions of a specific status.
- <strong>Responsive Design:</strong> Adapts to different screen sizes, ensuring a consistent user experience on both desktop and mobile devices.

## How It Works

The `UserSessions` component operates by requesting session data from a developer-provided function. This design decouples the component from any specific backend implementation, offering greater flexibility.

The following diagram illustrates the interaction between the user, the component, and the application backend:

![UserSessions](https://media.arcblock.io/lib/c0/c08d27da68b9a4ab.w1600.webp)

## Usage

To use the `UserSessions` component, you must provide a `user` object and a `getUserSessions` function. The `getUserSessions` function is responsible for fetching the session data from your backend service.

**Integration Example**

```javascript
import { UserSessions } from '@arcblock/blocklet-ui-react';
import { client } from './libs/client'; // Your API client instance

// The user object for whom sessions are being displayed.
const currentUser = {
  did: 'z1...',
  name: 'Alice',
  // other user properties
};

/**
 * This function fetches session data from your backend.
 * The UserSessions component will call this function whenever it needs new data.
 *
 * @param {object} params - The query parameters.
 * @param {number} params.page - The current page number.
 * @param {number} params.pageSize - The number of items per page.
 * @param {string} params.status - The session status to filter by ('online', 'expired', 'offline').
 * @returns {Promise<{ list: UserSession[], paging: { total: number } }>} A promise that resolves to the session data.
 */
const fetchUserSessions = async ({ page, pageSize, status }) => {
  const response = await client.user.getSessions({
    page,
    pageSize,
    status,
  });

  // Ensure the return format matches the component's requirements
  return {
    list: response?.list || [],
    paging: {
      total: response?.paging?.total || 0,
    },
  };
};

export default function MyAccountSessionsPage() {
  return (
    <div>
      <h2>Manage Your Login Sessions</h2>
      <UserSessions
        user={currentUser}
        getUserSessions={fetchUserSessions}
      />
    </div>
  );
}
```

## Props

The `UserSessions` component accepts the following props to customize its behavior and appearance.

- **user** `User` *(required)* — The user object for whom the sessions are being displayed. The component requires this to provide context for the session list.
- **getUserSessions** `function` *(required)* — An asynchronous function responsible for fetching paginated session data from your backend. It receives an object with page, pageSize, and status and must return a Promise that resolves to an object with the shape { list: UserSession[], paging: { total: number } }.
- **showAction** `boolean` (default: `true`) — Controls the visibility of the "Actions" column, which contains the logout buttons. Set to false to create a read-only view.
- **showUser** `boolean` (default: `true`) — Controls the visibility of the "User" column. This is useful in multi-user or administrative contexts where identifying the user for each session is necessary.
- **showOffline** `boolean` (default: `false`) — Determines whether the "Offline" filter option is available in the UI. Offline sessions typically represent long-lived sessions that are not currently active.
- **showAppPid** `boolean` (default: `false`) — Controls the visibility of the "App Pid" column, which can display a Blocklet's Program ID associated with the session.

## Displayed Information

The component renders the following information for each session in the data table:

| Column  | Description  |
|---|---|
| <strong>Platform</strong>  | The operating system and version derived from the session's user-agent string (e.g., `Windows/10`).  |
| <strong>Device Type</strong>  | The browser or application used for the session (e.g., `Chrome/108.0.0`).  |
| <strong>Wallet OS</strong>  | The operating system of the connected DID wallet, if available.  |
| <strong>App Pid</strong>  | The Program ID of the Blocklet that created the session. (Visible if `showAppPid` is `true`).  |
| <strong>User</strong>  | The user associated with the session. (Visible if `showUser` is `true`).  |
| <strong>Created At</strong>  | The timestamp when the session was initially created.  |
| <strong>Last Active</strong>  | The timestamp of the last activity. For expired sessions, this column shows "Expired".  |
| <strong>Last Login IP</strong>  | The last known IP address for the session, along with its resolved geographical region.  |
| <strong>Actions</strong>  | Provides a button to log out of the session. (Visible if `showAction` is `true`).  |

For a complete user management interface, consider using the `UserSessions` component within the [UserCenter](/en/docs/blocklet-ui-react/components-user-management-user-center-9e3990/) component.

---

## Utilities

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-utilities-9e3990/

This section provides documentation for a collection of helper components, Higher-Order Components (HOCs), and utility functions. These tools are designed to simplify common development tasks, manage application themes, and handle complex data structures.

The primary utilities available are:

::::card-group
::link-card{title="Icon Component" description="A versatile component for displaying icons from various sources, including Iconify, image URLs, or as letter avatars." icon="image" href="/en/docs/blocklet-ui-react/components-utilities-icon-9e3990/"}
::link-card{title="OverridableThemeProvider" description="A theme provider that allows developers to supply their own theme object to override the default Blocklet UI theme." icon="palette"}
::link-card{title="withHideWhenEmbed HOC" description="A Higher-Order Component that conditionally renders a component, hiding it when the application is in an embedded mode." icon="eye-off"}
::link-card{title="JavaScript Helpers" description="A suite of standalone functions for tasks such as recursive array manipulation, URL validation, and path matching." icon="code"}
::::

For a detailed guide on the `Icon` component, please see its dedicated documentation page. The other utilities are documented below.

## OverridableThemeProvider

This component is a wrapper around Material-UI's `ThemeProvider`. It allows you to apply a consistent theme to its child components. By default, it uses the standard Blocklet UI theme, but you can provide a custom theme object via the `theme` prop to override the default styles.

### Usage

To apply a custom theme, pass a theme object to the `theme` prop. The component will merge your overrides with the default theme.

**Theme Provider Example**

```javascript
import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
import { Button } from '@mui/material';

const customTheme = {
  palette: {
    primary: {
      main: '#ff5722',
    },
  },
};

function App() {
  return (
    <OverridableThemeProvider theme={customTheme}>
      <Button color="primary" variant="contained">
        Custom Themed Button
      </Button>
    </OverridableThemeProvider>
  );
}
```

## withHideWhenEmbed

`withHideWhenEmbed` is a Higher-Order Component (HOC) that prevents a component from rendering if the application is in "embed mode." It checks a session storage key (`EMBED_MODE_KEY`) to determine the current mode. If the value is `1`, the wrapped component will return `null`.

This is useful for hiding elements like headers or footers in an embedded context where they are not needed.

### Usage

Wrap the component you wish to conditionally hide with the `withHideWhenEmbed` HOC.

**HOC Example**

```javascript
import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';

function PageHeader() {
  return (
    <header>
      <h1>My Application</h1>
    </header>
  );
}

const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);

function App() {
  return (
    <div>
      <MaybeHiddenHeader />
      <main>
        {/* Main content goes here */}
      </main>
    </div>
  );
}
```

## Helper Functions

A set of pure JavaScript functions are available for common data manipulation and validation tasks. These can be imported directly from the library's utility module.

### Array Manipulation

These functions are designed to work with arrays of nested objects, such as navigation menus or file trees.

| Function  | Description  |
|---|---|
| `mapRecursive(array, fn, childrenKey = 'children')`  | Recursively applies a function to each item in a nested array.  |
| `flatRecursive(array, childrenKey = 'children')`  | Flattens a nested array into a single-level array.  |
| `countRecursive(array, childrenKey = 'children')`  | Counts the total number of items in a nested array.  |
| `filterRecursive(array, predicate, childrenKey = 'children')`  | Recursively filters a nested array based on a predicate function, preserving parent structure if children match.  |

### String & URL Validation

Simple helpers for checking string formats.

| Function  | Description  |
|---|---|
| `isUrl(str)`  | Returns `true` if the string starts with `http://` or `https://`.  |
| `isMailProtocol(str)`  | Returns `true` if the string starts with `mailto:`.  |

### Routing

Utilities to assist with client-side routing logic.

| Function  | Description  |
|---|---|
| `matchPath(path)`  | Checks if a given path matches the current `window.location.pathname`.  |
| `matchPaths(paths)`  | Finds the best matching path from an array of paths against the current location.  |

### Layout

| Function  | Description  |
|---|---|
| `splitNavColumns(items, options)`  | Splits a list of navigation items into a specified number of columns, useful for creating mega menus.  |

### Summary

This section provided an overview of the general-purpose utilities included in the library. For more powerful, specialized functionality, proceed to the detailed documentation for individual components.

For a comprehensive guide on using the flexible `Icon` component, please refer to the next section.

- [<strong>Icon</strong>](/en/docs/blocklet-ui-react/components-utilities-icon-9e3990/)

---

## Icon

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/components-utilities-icon-9e3990/

The `Icon` component is a flexible utility built upon Material-UI's `Avatar` component. It is designed to render icons from multiple sources, including [Iconify](https://iconify.design/) icon strings, image URLs, and character-based "letter avatars". This versatility makes it a standardized component for handling most icon and avatar display needs within an application.

## Props

The `Icon` component accepts the following props:

- **icon** `string` *(required)* — The primary identifier for the icon. The component intelligently determines how to render it based on the string's format. It can be an Iconify string (e.g., mdi:home), a direct image URL, or a simple string to generate a letter avatar (e.g., "U").
- **size** `number` — Sets a uniform width and height for the icon container in pixels.
- **sx** `BoxProps['sx']` — The sx prop for custom styling, consistent with Material-UI's system.
- **...** `AvatarProps` — The component also accepts any other props supported by the Material-UI Avatar component, such as variant, alt, and onClick.

## Usage Examples

Here are practical examples demonstrating the different ways to use the `Icon` component.

### Iconify Icon

To display an icon from the Iconify ecosystem, provide its unique string identifier to the `icon` prop. The component will dynamically load and render the corresponding SVG.

**Displaying an Iconify icon**

```jsx
import Icon from '@blocklet/ui-react/lib/Icon';

export default function IconifyExample() {
  return <Icon icon="mdi:react" size={48} />;
}
```

This example renders the "react" icon from the Material Design Icons collection.

### Image URL

You can render an image directly by passing its URL to the `icon` prop. The component will detect the URL format and use it as the `src` for an `<img>` tag within the Avatar.

**Rendering an icon from a URL**

```jsx
import Icon from '@blocklet/ui-react/lib/Icon';

export default function ImageUrlExample() {
  return <Icon icon="https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg" size={48} />;
}
```

### Letter Avatar

If the `icon` prop receives a string that is neither a valid Iconify icon nor a URL, it will render a letter avatar using the first character of the string. This is useful for user profile placeholders.

**Creating a letter avatar**

```jsx
import Icon from '@blocklet/ui-react/lib/Icon';

export default function LetterAvatarExample() {
  return <Icon icon="Blocklet" size={48} variant="rounded" sx={{ bgcolor: 'primary.main', color: 'primary.contrastText' }} />;
}
```

In this case, the component will display the letter "B". Note the use of the `variant` and `sx` props, which are passed directly to the underlying Material-UI Avatar.

### Custom Size

The `size` prop provides a convenient way to control the icon's dimensions.

**Adjusting the icon size**

```jsx
import Icon from '@blocklet/ui-react/lib/Icon';

export default function SizingExample() {
  return (
    <div>
      <Icon icon="mdi:home" size={24} />
      <Icon icon="mdi:home" size={32} />
      <Icon icon="mdi:home" size={48} />
    </div>
  );
}
```

This example shows the same icon rendered at three different sizes.

### Using Avatar Props

Since the `Icon` component is a wrapper around Material-UI's `Avatar`, you can use any `Avatar` prop to customize its appearance. For instance, you can change the shape using the `variant` prop.

**Customizing with Avatar props**

```jsx
import Icon from '@blocklet/ui-react/lib/Icon';

export default function AvatarPropsExample() {
  return (
    <div>
      <Icon icon="B" variant="circular" size={48} sx={{ bgcolor: 'secondary.main' }} />
      <Icon icon="L" variant="rounded" size={48} sx={{ bgcolor: 'success.main' }} />
      <Icon icon="T" variant="square" size={48} sx={{ bgcolor: 'info.main' }} />
    </div>
  );
}
```

This demonstrates how to create circular, rounded, and square avatars.

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/core-concepts-9e3990/

This document explains the fundamental principles of the Blocklet UI React library. The core design philosophy is a <strong>metadata-driven approach</strong>, where UI components such as the `Header`, `Footer`, and `Dashboard` are automatically configured and rendered based on the blocklet's metadata. This strategy ensures consistency, reduces boilerplate code, and enables dynamic UIs that adapt to user roles and language preferences.

The central idea is that a single configuration file, typically `blocklet.yml`, serves as the single source of truth for the application's overall structure and appearance. The library reads this metadata, processes it, and uses it to construct the appropriate UI elements.

## The Metadata-Driven Principle

The library's operation can be visualized as a simple data flow: the blocklet metadata is provided as input to the library, which then processes it through a pipeline to produce fully rendered UI components. This eliminates the need for developers to manually build and configure common layout elements for each application.

The following diagram illustrates this data flow:

![Core Concepts](https://media.arcblock.io/lib/0d/0d4f4f87db0b8137.w1600.webp)

This automated process relies on a well-defined metadata structure, which is detailed in the following section.

## Anatomy of Blocklet Metadata

The library expects a specific object structure, referred to as `BlockletMetaProps`, which contains all the necessary information for rendering the UI. Below is a detailed breakdown of this structure.

- **appName** `string` — The name of the application, typically displayed in the Header.
- **appLogo** `React.ReactNode` — A React node for the application's logo, also displayed in the Header.
- **enableConnect** `boolean` — Determines whether to display a DID Connect button.
- **enableLocale** `boolean` — Determines whether to display the language selection component.
- **theme** `object` — Defines the color scheme for the application layout.
  - **background** `string` — Sets the background color for layout components like the Header and Footer.
- **navigation** `array` — An array of navigation item objects that define the links and menus throughout the application.
  - **title** `string | object` *(required)* — The display text for the navigation item. Can be an object for i18n.
  - **link** `string | object` — The URL for the navigation item. Can be an object for i18n.
  - **icon** `string` — An Iconify-compatible string for an icon to display next to the title.
  - **section** `string | array` — Specifies where the item should appear, e.g., 'header', 'footer', 'dashboard'.
  - **role** `string | array` — Defines which user roles can see this item, e.g., 'admin', 'guest'.
  - **items** `array` — An array of nested navigation items to create dropdown menus or sub-menus.

### Navigation Configuration Example

The `navigation` array is the most critical part of the metadata. It provides a structured way to define all links, menus, and their placement.

**Navigation Configuration in blocklet.yml**

```yaml
# blocklet.yml
navigation:
  - title: Features
    link: /features
  - title:
      en: About Us
      zh: 关于我们
    link:
      en: /about
      zh: /about-us
    section: footer
  - title: Admin Dashboard
    link: /admin
    section: dashboard
    role: admin
  - title: Social
    section: social
    items:
      - title: Twitter
        link: https://twitter.com/arcblock
        icon: mdi:twitter
      - title: GitHub
        link: https://github.com/arcblock
        icon: mdi:github
```

This example illustrates several key features:

- A simple header link ("Features").
- A multi-language footer link ("About Us").
- An admin-only link for the dashboard.
- A group of social media links intended for the footer.

## The Data Processing Pipeline

Before rendering, the library processes the raw metadata through a series of steps to prepare it for the UI components.

### 1. Parsing and Sectioning

The first step is to parse the `navigation` array and group items based on their `section` property. A single navigation item can be assigned to multiple sections by using an array for the `section` value.

The `parseNavigation` utility categorizes each item into predefined sections:

- `header`: For the main application header.
- `footer`: For primary links in the footer.
- `social`: For social media icons, typically in the footer.
- `bottom`: For legal or secondary links at the very bottom of the footer.
- `dashboard`: For the sidebar navigation in a dashboard layout.
- `sessionManager`: For menus within the user session component.
- `userCenter`: For tabs or links within the user profile area.

If an item has no `section` property, it defaults to `header`.

### 2. Internationalization (i18n)

The library provides built-in support for multiple languages. If a `title` or `link` property in a navigation item is an object with language keys (e.g., `en`, `zh`), the `getLocalizedNavigation` function automatically selects the correct string based on the user's current locale.

**i18n Object Example**

```javascript
// A navigation item with multi-language support
{
  title: {
    en: 'Home',
    zh: '首页'
  },
  link: {
    en: '/home',
    zh: '/zh/home'
  }
}
```

### 3. Role-Based Filtering

To create a dynamic user experience, navigation items can be restricted to specific user roles. The `filterNavByRole` function filters the navigation list by comparing the `role` property of each item against the `user.role` from the current session.

- If an item has no `role` property, it is visible to everyone.
- If an item has a `role` property (e.g., `['admin', 'editor']`), it is only visible to users whose role is in that array.
- The `guest` role is a special value that applies to unauthenticated users.

This mechanism allows you to define a comprehensive navigation structure in your metadata and have the UI automatically adapt based on the logged-in user's permissions.

## Summary

The core concept of the Blocklet UI React library is to leverage a centralized metadata object to drive the configuration and rendering of common UI components. This metadata-driven approach offers several advantages:

- <strong>Single Source of Truth</strong>: Application structure, branding, and navigation are defined in one place.
- <strong>Consistency</strong>: Ensures a consistent look and feel across different parts of the application.
- <strong>Reduced Boilerplate</strong>: Eliminates the need to manually code common layout elements like headers and footers.
- <strong>Dynamic UI</strong>: Natively supports internationalization and role-based access control, allowing the UI to adapt dynamically to the user and their permissions.

With a clear understanding of these principles, you can effectively utilize the library's components. For more information on specific components and their usage, please refer to the [Components](/en/docs/blocklet-ui-react/components-9e3990/) section.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/getting-started-9e3990/

This guide provides a step-by-step walkthrough to install the `@blocklet/ui-react` library and render your first components. The objective is to have a functional `Header` and `Footer` within your application in a minimal amount of time.

## Prerequisites

Before proceeding, ensure you have the following installed in your development environment:

- A functional React project.
- Node.js and a package manager (npm or yarn).

## Installation

To begin, add the `@blocklet/ui-react` package to your project using your preferred package manager.

With npm:

**npm**

```bash
npm install @blocklet/ui-react
```

With yarn:

**yarn**

```bash
yarn add @blocklet/ui-react
```

## Basic Usage: Header and Footer

The `Header` and `Footer` components are designed for simplicity and can be rendered without any initial configuration. They automatically source their data from the blocklet's metadata.

1. Import the `Header` and `Footer` components into your main application file (e.g., `App.js`).
2. Place them at the top and bottom of your application's layout, respectively.

**App.js**

```jsx
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

function App() {
  return (
    <div>
      <Header />
      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
        {/* Your application content goes here */}
        <h1>Welcome to My Blocklet</h1>
      </main>
      <Footer />
    </div>
  );
}

export default App;
```

The components automatically retrieve configuration details—such as the application name, logo, and navigation links—from the `window.blocklet` metadata object, which is injected by the Blocklet Server environment.

Furthermore, the `Header` component will intelligently render additional controls:

- A <strong>user session manager</strong> is displayed if a `SessionContext` is available.
- A <strong>language selector</strong> is displayed if a `LocaleContext` is available.

## Manual Configuration

For development, testing, or cases where you need to override the default metadata, you can pass a configuration object directly to the components using the `blockletMeta` prop.

**App.js**

```jsx
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';

const customBlockletMeta = {
  appName: 'My Custom App',
  appLogo: 'https://path.to/your/logo.png',
  navigation: [
    {
      title: 'Home',
      link: '/',
    },
    {
      title: 'Documentation',
      link: '/docs',
    },
  ],
};

function App() {
  return (
    <div>
      <Header blockletMeta={customBlockletMeta} />
      {/* ... rest of your app */}
    </div>
  );
}
```

This approach gives you precise control over the component's appearance and behavior by overriding any data provided by the global `window.blocklet` object.

## Customizing the Header

The `Header` component includes an `addons` area on the right side, which you can customize to include your own components, such as action buttons or custom links.

The `addons` prop accepts a function that receives the default addon components as an argument. This allows you to prepend, append, or completely replace them.

**CustomHeader.js**

```jsx
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button'; // Example using Material-UI

function CustomHeader() {
  return (
    <Header
      addons={existingAddons => {
        return [
          <Button
            key="custom-action"
            variant="contained"
            color="primary"
            size="small"
            style={{ marginRight: 8 }}>
            Custom Action
          </Button>,
          ...existingAddons, // Important: preserves default session/locale addons
        ];
      }}
    />
  );
}
```

In this example, a custom button is prepended to the existing addons. By including `...existingAddons`, you ensure that the default session and locale controls remain visible.

## Summary

You have successfully installed the `@blocklet/ui-react` library, rendered default `Header` and `Footer` components, and learned how to provide custom configurations and addons.

With these fundamentals in place, you are now prepared to explore the full range of components available in the library. For detailed documentation on layout, user management, and utility components, please proceed to the [Components](/en/docs/blocklet-ui-react/components-9e3990/) section.

---

## Hooks API

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/hooks-api-9e3990/

This section provides a detailed reference for the custom React Hooks available within the library. These hooks are designed to encapsulate and reuse stateful logic, simplifying common tasks and interactions within a Blocklet environment.

## useComponentInstalled

This hook checks whether one or more specified optional components (identified by their DIDs) are installed. It is essential for implementing features that rely on other Blocklets as dependencies. The hook provides the installation status and necessary URLs to prompt the user for installation if required.

### Parameters

The hook accepts a single object with the following properties:

- **did** `string | string[]` *(required)* — The Decentralized Identifier (DID) or an array of DIDs for the component(s) to check. A single string can contain multiple DIDs separated by ;;.
- **onInstalled** `function` — An optional callback function that is triggered when all specified components are already installed.
- **onError** `function` — An optional callback function that is triggered when one or more specified components are not installed.

### Returns

It returns an object containing the installation state and related data:

- **optComponents** `array` — An array of component objects that are not installed. Each object includes metadata such as meta.did, storeUrl, and installUrl.
- **installed** `boolean` — A boolean value that is true if all specified components are installed and defined in the blocklet.yml, and false otherwise.
- **installStatus** `object` — An object where keys are component DIDs and values are their current installation status (e.g., 'waiting', 'installing'). This state is updated via window.postMessage events.
- **setInstallStatus** `function` — The state setter function to manually update the installStatus object.
- **definedInBlockletYML** `boolean` — A boolean indicating whether the component is defined in the blocklet's configuration (blocklet.yml).

### Example Usage

The following example demonstrates how to use `useComponentInstalled` to conditionally render a feature or a `ComponentInstaller` component if a dependency is missing.

**"ComponentFeature.js"**

```javascript
import React from 'react';
import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';

const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // Example DID

function ComponentFeature() {
  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });

  if (!installed) {
    // Render the installer UI if the component is not present
    return <ComponentInstaller components={optComponents} />;
  }

  // Render the feature that depends on the installed component
  return (
    <div>
      <h2>My Feature</h2>
      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
      {/* ... feature implementation ... */}
    </div>
  );
}

export default ComponentFeature;
```

## useFollow

This hook manages the following relationship between the currently authenticated user and another user specified by their DID. It handles the API calls for following and unfollowing, and provides the current follow status.

### Parameters

- **userDid** `string` *(required)* — The DID of the user profile to check the follow status against.
- **t** `function` *(required)* — A translation function used for displaying success or error messages (e.g., from react-i18next).
- **isMySelf** `boolean` *(required)* — A boolean that should be set to true if the userDid belongs to the currently logged-in user.

### Returns

Returns an object with the following properties:

- **followed** `boolean` — Indicates if the current user is following the user specified by userDid. true if following, false otherwise.
- **followUser** `function` — A stable function to call to follow the user. It handles the API request and updates the followed state on success.
- **unfollowUser** `function` — A stable function to call to unfollow the user. It handles the API request and updates the followed state on success.

### Example Usage

This example shows how to create a `FollowButton` component that displays a "Follow" or "Unfollow" action based on the relationship status.

**"FollowButton.js"**

```javascript
import React from 'react';
import Button from '@mui/material/Button';
import { useTranslation } from 'react-i18next';
import { useFollow } from '@blocklet/ui-react/hooks';
import { useSession } from '@blocklet/did-connect-react';

function FollowButton({ profileDid }) {
  const { session } = useSession();
  const { t } = useTranslation();
  const isMySelf = session?.user?.did === profileDid;

  const { followed, followUser, unfollowUser } = useFollow({
    userDid: profileDid,
    t,
    isMySelf,
  });

  if (isMySelf) {
    return null; // Do not show button on your own profile
  }

  const handleClick = () => {
    if (followed) {
      unfollowUser();
    } else {
      followUser();
    }
  };

  return (
    <Button variant="contained" onClick={handleClick}>
      {followed ? t('profile.unfollow') : t('profile.follow')}
    </Button>
  );
}

export default FollowButton;
```

## useMobile

A simple utility hook for creating responsive components. It leverages Material-UI's `useMediaQuery` to determine if the current viewport width is below a specified breakpoint.

### Parameters

- **key** `number | Breakpoint` (default: `'sm'`) — The Material-UI breakpoint key (e.g., 'xs', 'sm', 'md') or a pixel value to check against. The hook returns true if the screen width is smaller than this value.

### Returns

Returns a `boolean` value: `true` if the viewport is smaller than the specified breakpoint, `false` otherwise.

### Example Usage

This hook must be used within a component tree that is wrapped by a Material-UI `ThemeProvider`.

**"ResponsiveComponent.js"**

```javascript
import React from 'react';
import Typography from '@mui/material/Typography';
import { ThemeProvider, createTheme } from '@mui/material/styles';
import { useMobile } from '@blocklet/ui-react/hooks';

// A component that uses the hook
function ResponsiveComponent() {
  const isMobile = useMobile({ key: 'md' }); // Check against the 'md' breakpoint

  return (
    <div>
      {isMobile ? (
        <Typography variant="h6">Mobile View</Typography>
      ) : (
        <Typography variant="h4">Desktop View</Typography>
      )}
      <p>Resize your browser window to see the content change.</p>
    </div>
  );
}

// The component must be wrapped in a ThemeProvider
const theme = createTheme();

function App() {
  return (
    <ThemeProvider theme={theme}>
      <ResponsiveComponent />
    </ThemeProvider>
  );
}

export default App;
```

By using these hooks, you can efficiently implement complex features with minimal boilerplate code. For more information on the components that might use these hooks, please see the [Components](/en/docs/blocklet-ui-react/components-9e3990/) documentation.

---

## How-to Guides

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/how-to-guides-9e3990/

This section provides practical, step-by-step guides for completing common tasks and implementing specific workflows using the library's components. Each guide is designed to be a self-contained set of instructions to help you achieve a specific outcome efficiently.

::::card-group
::link-card{title="Add Custom Elements to the Header" description="Learn how to use the `addons` render prop to extend the `Header` component with custom buttons, navigation, or other interactive elements." icon="layout" href="#how-to-add-custom-elements-to-the-header"}
::link-card{title="Handle Optional Component Dependencies" description="Implement a workflow that prompts administrators to install required components on-demand, ensuring your blocklet's features run smoothly." icon="box" href="#how-to-handle-optional-component-dependencies"}
::link-card{title="Implement Real-time User Notifications" description="Set up a real-time notification system using WebSockets to keep users informed of important events within your application." icon="bell" href="#how-to-implement-real-time-user-notifications"}
::link-card{title="Publish Resources with BlockletStudio" description="Integrate the `BlockletStudio` component to provide a user interface for publishing and managing resources and dependent components." icon="rocket" href="#how-to-publish-resources-with-blockletstudio"}
::::

## How to Add Custom Elements to the Header

The `Header` component is designed to be extensible. You can add custom buttons, search bars, or other React components directly into the header by leveraging the `addons` prop.

### Goal

To add a custom "Chat" button, a search input, and additional action icons to the main application header.

### Prerequisites

- A functional React application with the `@arcblock/ux` library installed.
- An existing `<Header>` component instance. For more information, see the [Header component documentation](/en/docs/blocklet-ui-react/components-layout-header-9e3990/).

### Steps

The `addons` prop accepts a render function. This function receives the default addons (like the session manager) as its first argument, allowing you to decide where to place your custom elements relative to the defaults.

1. <strong>Define the</strong> <strong>`addons`</strong> <strong>Render Prop</strong> In your `Header` component, pass a function to the `addons` prop. This function should return the JSX you want to render. ```jsx <Header   meta={meta}   addons={(defaultAddons, { navigation }) => {     // Your custom components will go here     return (       <>         {/* Render your custom components */}         {defaultAddons}       </>     );   }} /> ```
2. <strong>Add Custom Components</strong> Inside the render function, you can add any components you need. In this example, we'll add a standard Material-UI `Button`, a few `AddonButton` components for icons, and a `Divider`.
3. <strong>Combine with Default Addons</strong> It is standard practice to render the `defaultAddons` that are passed into the function. This ensures that essential elements like the locale switcher and session manager are still displayed. You can place your custom components before or after the `defaultAddons`.

### Complete Example

Here is a complete example demonstrating how to add several custom elements to the header. This includes navigation, buttons, and icons, rendered alongside the default session manager.

**How to Add Custom Elements to the Header**

```javascript
import { Box, Divider, Button } from '@mui/material';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import { AddonButton } from '@arcblock/ux/lib/Header/addon-button';
import NavMenu from '@arcblock/ux/lib/NavMenu';
import SessionManager from '@arcblock/ux/lib/SessionManager';
import Header from '@arcblock/ux/lib/Header';
import { Icon } from '@iconify/react';

// Mock data for demonstration purposes
const mockBlockletMeta = {
  title: 'My App',
  description: 'A great application',
  logoUrl: 'https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg'
};

const mockSessionContextValue = {
  session: {
    user: {
      fullName: 'Demo User',
      did: 'z1ex...',
      role: 'admin',
    },
    // ... other session properties
  },
};

export default function CustomHeaderGuide() {
  const meta = {
    ...mockBlockletMeta,
    enableConnect: true,
    enableLocale: true,
  };

  return (
    <SessionContext.Provider value={mockSessionContextValue}>
      <Header
        meta={meta}
        homeLink="https://www.arcblock.io"
        addons={(defaultAddons, { navigation }) => (
          <>
            {/* 1. Add custom navigation */}
            {navigation.navItems?.length > 0 && (
              <NavMenu
                activeId={navigation.activeId}
                items={navigation.navItems}
                className="header-nav"
              />
            )}
            {/* 2. Add a custom button */}
            <Button variant="contained" color="primary" size="small">
              Button
            </Button>
            {/* 3. Add custom icon buttons */}
            <AddonButton icon={<Icon icon="tabler:message-circle" />}>Chat</AddonButton>
            <AddonButton icon={<Icon icon="tabler:bell" />} />
            <Divider orientation="vertical" flexItem sx={{ height: 12, alignSelf: 'center' }} />
            {/* 4. Render the default addons (includes session manager) */}
            {defaultAddons}
          </>
        )}
      />
    </SessionContext.Provider>
  );
}
```

## How to Handle Optional Component Dependencies

Many blocklets rely on other components to provide specific features. The `ComponentInstaller` allows you to build features that depend on optional components, and if they are not installed, it provides a user-friendly way for an administrator to install them.

### Goal

To protect a feature that requires another blocklet component to be installed. If the component is missing, an administrator will be shown an interface to install it, while other users will see nothing.

### Prerequisites

- A feature in your application that depends on another component (e.g., a "Media Manager" that requires the "Media Kit" blocklet).
- The DID of the component dependency.
- Familiarity with user roles (`owner`, `admin`).

### Steps

1. <strong>Import</strong> <strong>`ComponentInstaller`</strong> First, import the component from the library. ```javascript import ComponentInstaller from '@arcblock/ux/lib/ComponentInstaller'; ```
2. <strong>Wrap Your Feature</strong> Wrap the component or feature that has the dependency with the `ComponentInstaller`.
3. <strong>Provide the Component DID</strong> Pass the DID of the required component to the `did` prop. This can be a single string or an array of strings if there are multiple dependencies.
4. <strong>Configure Behavior for Non-Admins</strong> Use the `noPermissionMute` prop. When set to `true`, users who do not have permission to install components (i.e., non-admins) will not see the installation prompt. You can provide a `fallback` component to show them instead.

### Complete Example

In this scenario, we have a `MyFeatureButton` that should only be rendered if the component with DID `z8ia...` is installed.

**How to Handle Optional Component Dependencies**

```javascript
import ComponentInstaller from '@arcblock/ux/lib/ComponentInstaller';
import { Button } from '@mui/material';

const REQUIRED_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9'; // Example DID

// This is the component that requires the dependency
function MyFeatureButton() {
  return <Button variant="contained">Use Awesome Feature</Button>;
}

export default function OptionalComponentGuide() {
  return (
    <ComponentInstaller
      // The DID of the component to check for
      did={REQUIRED_COMPONENT_DID}
      // A list of roles that are allowed to see the installer UI
      roles={['owner', 'admin']}
      // If true, non-admins will not see the installer UI
      noPermissionMute
      // Optional: What to show non-admins if the component is not installed
      fallback={<div>This feature is not available.</div>}
      // A callback that fires after a successful installation
      onInstalled={() => console.log('Component was installed successfully!')}
    >
      {/* This child will only be rendered if the component is already installed */}
      <MyFeatureButton />
    </ComponentInstaller>
  );
}
```

When an admin visits this page and the component is not installed, they will see a pop-up allowing them to install it. A regular user will see the fallback message. Once installed, all users will see the `MyFeatureButton`.

## How to Implement Real-time User Notifications

You can provide users with real-time feedback and notifications by listening to WebSocket events from the Blocklet Server. The `NotificationAddon` component is a ready-to-use solution for displaying an unread notification count in the header.

### Goal

To add a notification bell icon to the application header that displays a badge with the count of unread notifications and updates in real-time.

### Prerequisites

- Your blocklet must be running on a Blocklet Server version that supports the notification service (`1.16.42` or higher).
- A `<Header>` component where the notification icon will be placed.
- A session context providing user information.

### Key Concepts

- <strong>WebSocket Events</strong>: The Blocklet Server broadcasts events when notifications are created or read.
- <strong>`useListenWsClient`</strong>: A hook to get a WebSocket client instance for a specific channel (e.g., 'user').
- <strong>Event Naming</strong>: Events are scoped to the user and blocklet. The format for new notifications is `${blocklet.did}/${user.did}/notification:blocklet:create`.

### Steps

The `NotificationAddon` component encapsulates all the required logic for listening to WebSocket events and displaying the unread count.

1. <strong>Import</strong> <strong>`NotificationAddon`</strong> ```javascript import NotificationAddon from '@arcblock/ux/lib/common/notification-addon'; ```
2. <strong>Add to Header</strong> <strong>`addons`</strong> The simplest way to use this is to add it inside the `Header`'s `addons` render prop.
3. <strong>Pass the Session Object</strong> The `NotificationAddon` component requires the `session` object to identify the current user and manage the unread count state.

### Complete Example

This example shows how to integrate the `NotificationAddon` into the `Header`. It will automatically connect to the WebSocket, listen for events, and update the badge count.

**How to Implement Real-time User Notifications**

```javascript
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import Header from '@arcblock/ux/lib/Header';
import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';

// Mock data for demonstration purposes
const mockBlockletMeta = {
  title: 'My App',
  description: 'A great application',
  logoUrl: 'https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg'
};

const mockSessionContextValue = {
  session: {
    user: {
      fullName: 'Demo User',
      did: 'z1ex...',
      role: 'admin',
    },
    unReadCount: 3, // Initial unread count
    setUnReadCount: () => {}, // State setter function
    // ... other session properties
  },
};

export default function NotificationGuide() {
  const meta = { ...mockBlockletMeta, enableConnect: true };

  return (
    <SessionContext.Provider value={mockSessionContextValue}>
      <Header
        meta={meta}
        addons={(defaultAddons) => (
          <>
            {/* The NotificationAddon will handle real-time updates */}
            <NotificationAddon session={mockSessionContextValue.session} />
            {defaultAddons}
          </>
        )}
      />
    </SessionContext.Provider>
  );
}
```

When a new notification for the logged-in user is created, the badge count on the bell icon will automatically increment. Clicking the icon will navigate the user to their notifications page.

## How to Publish Resources with BlockletStudio

The `BlockletStudio` component provides a complete, embeddable UI for publishing resources and components. It handles user connection, resource selection, and the release process, simplifying a complex workflow into a single component.

### Goal

To add a button that opens a dialog, allowing users to select and publish files and dependent components from the blocklet.

### Prerequisites

- An API endpoint in your blocklet that returns a list of available resources.
- The DID of the component that provides the publishing UI (the "studio" component).

### Steps

1. <strong>Import</strong> <strong>`BlockletStudio`</strong> <strong>and Manage State</strong> You'll need to manage the visibility of the studio dialog using component state. ```javascript import { useState } from 'react'; import { BlockletStudio } from '@arcblock/ux/lib/BlockletStudio'; import { Button, CircularProgress } from '@mui/material'; ```
2. <strong>Render the Component</strong> Place the `<BlockletStudio />` component in your app and control its visibility with the `open` and `setOpen` props.
3. <strong>Configure Essential Props</strong>
4.
  - `componentDid`: The DID of the studio blocklet that provides the publishing service.
  - `title`, `description`: Metadata for the item being published.
  - `resourcesParams`: An object passed as query parameters to your resource-fetching API.
  - `components`: An array of components to be pre-selected or required.
  - `resources`: An object specifying which resources to pre-select.
5. <strong>Handle Lifecycle Events</strong> Use the `onOpened`, `onUploaded`, and `onReleased` callbacks to respond to events in the publishing lifecycle, such as hiding a loading spinner or showing a success message.

### Complete Example

This example shows a button that, when clicked, opens the `BlockletStudio` dialog. It also demonstrates managing a loading state for a better user experience.

**How to Publish Resources with BlockletStudio**

```javascript
import { useState } from 'react';
import { Button, CircularProgress } from '@mui/material';
import { BlockletStudio } from '@arcblock/ux/lib/BlockletStudio';

// The DID of the blocklet that provides the studio/publishing UI
const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9'; // Example DID

export default function PublisherGuide() {
  const [isStudioOpen, setStudioOpen] = useState(false);
  const [isOpening, setOpening] = useState(false);

  const handleShowDialog = () => {
    setOpening(true);
    setStudioOpen(true);
  };

  return (
    <>
      <Button
        variant="contained"
        onClick={handleShowDialog}
        disabled={isOpening}
        startIcon={isOpening ? <CircularProgress size={16} /> : null}>
        Publish to Studio
      </Button>

      <BlockletStudio
        // Controls the dialog's visibility
        open={isStudioOpen}
        setOpen={setStudioOpen}
        // Basic information for the published item
        title="My Demo Project"
        description="This is a project published from my blocklet."
        // The DID of the studio service component
        componentDid={AI_STUDIO_COMPONENT_DID}
        // Parameters sent to your blocklet's resource API
        resourcesParams={{ projectId: 'test-project-123' }}
        // Pre-selected components
        components={[
          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
        ]}
        // Pre-selected resources
        resources={{
          // The key is the DID of the resource provider blocklet
          z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB: [
            'template-448698592710885376',
            'example-448698592710885376',
          ],
        }}
        // Event handlers
        onOpened={() => setOpening(false)}
        onUploaded={() => alert('Upload complete!')}
        onReleased={() => {
          alert('Successfully released!');
          setStudioOpen(false);
        }}
      />
    </>
  );
}
```

---

## Overview

URL: https://www.arcblock.io/en/docs/blocklet-ui-react/overview-9e3990/

The `@blocklet/ui-react` library provides a collection of essential React components designed to accelerate the development of applications, known as Blocklets. It streamlines the creation of common user interface elements by intelligently using the blocklet's metadata, enabling developers to build consistent and feature-rich UIs with minimal effort.

This library is built upon `@arcblock/ux`, which is a themed extension of Material-UI. This foundation ensures that all components are robust, accessible, and easily customizable to fit your application's branding.

## The Problem It Solves

Modern web applications often require a standard set of UI components for layout, user management, and notifications. Implementing these from scratch for every project is time-consuming and can lead to inconsistencies. The Blocklet UI React library addresses this by providing pre-built components that automatically configure themselves based on your blocklet's metadata (`blocklet.yml`).

This metadata-driven approach means that elements like your application's name, logo, navigation links, and theme colors are automatically applied across components, drastically reducing boilerplate code and ensuring brand consistency.

## Core Architecture

The library's architecture is designed for simplicity and automation. When a component like `Header` or `Footer` is rendered, it reads configuration data from the `window.blocklet` object, which is populated by the Blocklet Server from your `blocklet.yml` file. This allows you to define your UI's structure and branding in a central configuration file, and the components adapt accordingly.

![Overview](https://media.arcblock.io/lib/1c/1c5479ddfde9dec6.w1600.webp)

## Key Features

- <strong>Metadata-Driven:</strong> Automatically configures components like `Header` and `Footer` using your blocklet's name, logo, and navigation structure defined in `blocklet.yml`.
- <strong>Integrated Session Management:</strong> Components seamlessly integrate with DID Connect sessions, automatically displaying user profile information, session controls, and role-based access to navigation links.
- <strong>Responsive Layouts:</strong> Includes powerful layout components like `Dashboard` that provide a responsive structure for administrative interfaces out of the box.
- <strong>Component Management:</strong> Offers tools like `ComponentInstaller` and `BlockletStudio` to help manage dependencies and resources within the Blocklet ecosystem.

## Core Components

The library is organized into several key modules, each addressing a specific area of application UI.

::::card-group
::link-card{title="Layout" description="Primary components like Header, Footer, and Dashboard that form the main structure of a blocklet application." icon="layout" href="/en/docs/blocklet-ui-react/components-layout-9e3990/"}
::link-card{title="User Management" description="A suite of components for handling user profiles, session management, and organization switching." icon="users" href="/en/docs/blocklet-ui-react/components-user-management-9e3990/"}
::link-card{title="Component Management" description="Tools for dynamically installing, publishing, and managing blocklet components within an application." icon="box" href="/en/docs/blocklet-ui-react/components-component-management-9e3990/"}
::link-card{title="Utilities" description="A collection of helper components and utilities, such as a versatile Icon component and theme providers." icon="wrench" href="/en/docs/blocklet-ui-react/components-utilities-9e3990/"}
::::

## Summary

By leveraging the `@blocklet/ui-react` library, you can significantly reduce development time and focus on your application's unique features. The metadata-driven approach ensures consistency and simplifies the management of common UI elements.

To start building your application, proceed to the [Getting Started](/en/docs/blocklet-ui-react/getting-started-9e3990/) guide for a step-by-step tutorial on installing the library and rendering your first components.

---

## Blocklets

URL: https://www.arcblock.io/en/docs/blocklets/

Developer documentation for ARC **Blocklets** — the package-and-instance unit for applications and services.

Start at [Overview](./overview/).

---

## Read the agent-run dashboard

URL: https://www.arcblock.io/en/docs/blocklets/agent-observability-dashboard/

`/dashboard` is the landing section of the **Agent Observability** blocklet (`blocklets/observability-explorer` in the ARC monorepo). It answers one question: *what have my agents been doing, and which runs deserve a look?*

Verified against the live deployment at `https://observability-explorer.afsd.dev`, build `35de3a0b`, signed in as a registered test user on **2026-08-20**. Your rows will differ; the shapes and the caveats are the reusable part.

> Re-walked on the current build. The first walk (build `400ce96`, 2026-08-15) ran while an
> authorization bug was live: owning *one* app granted deployment-wide trace visibility. That
> was fixed on 2026-08-18, so the earlier walk's rows were partly a symptom. See
> [What you can see](#what-you-can-see) for the rule that holds now.

This is one of three sections. The other two are [Traces](../agent-observability-traces/) — what happened inside one run — and [AI usage](../agent-observability-usage/) — how much AI capacity was consumed. **Dashboard and usage count different populations and are not meant to reconcile**: the dashboard rolls up agent *runs* visible to you, the usage face rolls up *AI calls* attributed to you, and a run can burn tokens without appearing in the other's ledger.

Signed out, nothing renders — the section states `Sign in to view this content.` rather than drawing an empty chart.

## What the page shows

![The dashboard: headline metrics, three highlight cards, three tables of outlier runs, and the runs-per-day and tokens-per-day charts](media/01-dashboard-signal.png)

Top to bottom:

| Block | What it answers |
| --- | --- |
| **Headline** | `40 runs · 494.8K tokens · 90.0% ok · avg 37.4s` — volume, spend, success rate, mean duration |
| **Three cards** | The single worst / most expensive / longest-looping run, each naming the task text and the app |
| **Three tables** | The same three dimensions as lists: failed runs (latest), most expensive runs, most rounds |
| **Two charts** | Runs per day, and tokens per day split into `Tokens In` / `Tokens Out` |
| **Roll-ups** | Top models, top hubs, and a per-app table |

![The lower half: runs-per-day and tokens-per-day charts, top models, top hubs, and the per-app roll-up with runs, tokens, average duration, success rate and last-run time](media/02-dashboard-rollups.png)

The per-app table is the most useful block for a deployment owner: it is the only place that puts **runs, tokens, average duration, success rate and recency on one row per app**. In the walk above it read:

| App | Runs | In | Out | Avg dur | Success | Last run |
| --- | --: | --: | --: | --: | --: | --- |
| todo | 22 | 243K | 2.4K | 38.7s | 100% | 2 days ago |
| observability-explorer | 5 | 36.5K | 1.9K | 29.8s | 100% | 4 days ago |
| arch-qa | 4 | 91.1K | 1.5K | 54.1s | 100% | 8 days ago |
| aistro | 4 | 0 | 0 | 0ms | 0% | 6 days ago |
| aside | 4 | 107.3K | 1.8K | 22.6s | 100% | 5 days ago |
| chain-explorer | 1 | 9.3K | 179 | 38.3s | 100% | 14 days ago |

An app with runs but **zero tokens, zero duration and 0% success** — `aistro` above — is the shape of a run that never reached the model. Those are the same four runs the "needs attention" card is counting.

## Reading it correctly

**"today's signal" is not today.** The headline is labelled *Agent runs · today's signal*, but the charts under it span thirteen days (2026-08-04 → 08-16) and the per-app table's "last run" column reaches back two weeks. Read the headline as *the current state of everything visible to you*, not as a 24-hour window.

**"Failed" in the card, `interrupted` in the table.** The attention card says `4 run(s) failed`; every one of those rows carries the status `interrupted`. They are the same four runs under two names. Do not go looking for a separate `failed` status — there isn't one on this deployment.

**The charts arrive late.** Both charts render `Loading data...` for several seconds after the tables are already populated (over six seconds in the walk). A blank chart area on first paint is loading, not zero.

**The three outlier tables clip on the right.** At a 1440px viewport the `APP` column of the failed / expensive / rounds tables is cut off mid-word. The information is there — the table just has more columns than the card width affords. Widen the window or read the app name from the card above it.

## What you can see

Both this section and [Traces](../agent-observability-traces/) read the same run index through
the same gate, and the gate has **two axes**:

- **Your own runs are always yours.** That row is a fragment of your own DID Space; the isolation is physical, not a filter.
- **A whole app's runs require membership on that app** — same-instance `admin`/`owner`, probed per app.

Nothing else is admitted. An `owner` role on app A grants nothing on app B.

**This rule is younger than the page.** Until 2026-08-18, `authorizedView` mapped an
`owner`/`admin` string on any app to a deployment-wide privilege flag with no app dimension,
so one app's owner enumerated every blocklet's runs — task text included — while the usage
admin face refused the same caller for the same app. Fixed in ARC
[#4170](https://github.com/ArcBlock/arc/issues/4170) /
[PR #4269](https://github.com/ArcBlock/arc/pull/4269).

You can see both axes at work without a second account — compare the apps appearing in
`/traces` against the portfolio on `/usage/admin`. On this walk each list had six apps and
they overlapped on only three:

| Appears in | Apps | What that means |
| --- | --- | --- |
| Both | `todo` `aside` `observability-explorer` | Own runs *and* membership |
| Traces only | `arch-qa` `aistro` `chain-explorer` | My own runs in apps I do not administer — the USER axis |
| Usage admin only | `discuss-kit` `did-space` `showcase` | Apps I administer with no runs in the index — `discuss-kit` has 56 AI calls and zero traces, which is ARC [#3207](https://github.com/ArcBlock/arc/issues/3207), still open: the index read path only sees this instance's runs |

**Invisible and non-existent look identical.** Listing the traces of an app you may not see
returns an empty list, not an error: `/dev/observability/traces/places-notebook` answered `[]`
on the same session where `/dev/observability/traces/todo` answered 22 runs.

## What it cannot tell you

- **Why** a run failed. The dashboard names the run; the reason lives in [the trace](../agent-observability-traces/).
- Anything about runs outside the two axes above — they contribute nothing to these totals, and the page cannot tell you they exist.
- Cost in money. Every number here is a token count or a duration; no page in this blocklet converts tokens to currency.

## Failures to expect

| Symptom | What it actually is |
| --- | --- |
| `Sign in to view this content.` | Not an error — the dashboard has no anonymous projection |
| Charts stuck on `Loading data...` | Normal for the first few seconds; the tables fill in first |
| An app with runs but 0 tokens / 0ms / 0% | Runs that never reached the model — the `interrupted` set |
| Headline says "today", chart shows two weeks | Known label mismatch; the data is the whole visible window |
| Right-hand column of an outlier table cut off | Table wider than the card at this viewport |

---

## Read one agent run in Traces

URL: https://www.arcblock.io/en/docs/blocklets/agent-observability-traces/

`/traces` is where the **Agent Observability** blocklet (`blocklets/observability-explorer` in the ARC monorepo) answers the question the dashboard cannot: *what actually happened inside this run?*

Verified against the live deployment at `https://observability-explorer.afsd.dev`, build `35de3a0b`, signed in as a registered test user on **2026-08-20**. Every screenshot below is that session.

The sibling sections are [the dashboard](../agent-observability-dashboard/) — what ran lately — and [AI usage](../agent-observability-usage/) — how much capacity was consumed. Traces and usage are written by different paths and do not reconcile with each other.

## Which runs you can see

A trace carries the task text, the system prompt and every tool result, so read the gate before
reading the list. Two axes admit a run, and nothing else does:

- **Your own runs, always** — that data is a fragment of your own DID Space.
- **Every run of an app you administer** — same-instance `admin`/`owner`, probed per app.

Being `owner` of one app grants nothing on another. That has only been true since
**2026-08-18**: before ARC [#4170](https://github.com/ArcBlock/arc/issues/4170) /
[PR #4269](https://github.com/ArcBlock/arc/pull/4269), any `owner`/`admin` role was read as
deployment-wide privilege here, and one app's owner could enumerate every app's runs — while
the usage admin face refused the same caller for the same app. If you are on an older build,
this section is not the boundary you actually have.

An app you may not see is indistinguishable from one that does not exist: the listing is empty,
not an error. The [dashboard page](../agent-observability-dashboard/#what-you-can-see) carries
the worked comparison that shows both axes from a single account.

## The list

![The traces list: search box, blocklet filter, time filter, and one row per run with user input, blocklet, status, model, in/out/cache tokens, duration and start time](media/01-traces-list.png)

Newest first, one row per agent run, with three ways to narrow it:

| Control | Effect |
| --- | --- |
| **Search** | Free text over task and status |
| **BLOCKLET** | `All blocklets`, or one app |
| **TIME** | `All` · `Today` · `7d` · `30d` |

The columns are `USER INPUT · BLOCKLET · STATUS · MODEL · IN · OUT · CACHE · TIME · STARTED`. Two things about them are worth knowing before you scan the list:

- **`USER INPUT` is the raw prompt, conversation history included.** Rows from a chat surface start with `<conversation_history> …`, so the first line of the cell is often the *previous* exchange rather than the request that started this run. The full text is in the trace.
- **`STATUS` is `ok` or `interrupted`.** A run that never reached the model shows `interrupted` with `0` in / `0` out and an empty duration — the same runs the dashboard counts as "failed".

## One run

Clicking a row opens the run at its own addressable URL:

```text
/traces/<blocklet>/<date>/<runId>
   e.g. /traces/todo/2026-08-16/195318-dd5abfb7
```

![A run detail: header metrics, the timeline with INPUT, USER, ROUND 1, ROUND 2 and FINAL OUTPUT, the trace assistant below it, and the inspector showing the run's system prompt](media/02-run-timeline.png)

**Header.** `3 rounds · 3 tool calls · 16851→164 tokens · 8153 cached · 50.8s · gemini-2-5-pro`, plus **Copy link** — the run URL is shareable and hard-loadable.

**Timeline** (left). One row per step, with per-row `IN / OUT / CACHE / TIME`:

| Row | What it is |
| --- | --- |
| `⚙️ INPUT` | The call that started the run: action path, tool count, whether a system prompt was attached |
| `👤 USER` | The prompt text |
| `🔄 ROUND n` | One model round, labelled with the tool calls it made |
| `🤖 FINAL OUTPUT` | The answer, with the tokens that produced it |

Note the arithmetic: a run reported as `3 rounds` shows `ROUND 1`, `ROUND 2` and then `FINAL OUTPUT` — the final answer is the third round, not a fourth step.

**Inspector** (right). Whatever row is selected, in full: `type`, `time`, and for the opening event the complete `SYSTEM PROMPT`, `TOOLS` grant and `INPUT PARAMETERS` (including the run budget — `max_rounds`, `actions_per_round`, `total_tokens`).

### Expanding a round

A round with a chevron expands into the steps inside it:

![ROUND 2 expanded to show TOOL USE and the two TOOL RESULT rows beneath it](media/03-round-expanded.png)

`🛠 TOOL USE` is what the model asked for; each `🔧 TOOL RESULT` is one call's outcome and its duration — `afs_write … · ok` in the screenshot. This is the level at which "the agent did the wrong thing" becomes visible.

### A run that never started

![An interrupted run: 0 rounds, 0 tool calls, 0→0 tokens, and a timeline with only INPUT and USER](media/05-run-interrupted.png)

An `interrupted` run keeps its INPUT and USER rows and has nothing after them. The inspector still shows the tools it was granted and the parameters it was given, which is usually enough to tell whether the run was mis-configured or the model was never reached.

## The trace assistant

Below the timeline, an assistant is loaded **with this trace as context**. It is present only inside a run — the list, the dashboard and the usage pages do not show it.

![The trace assistant answering "where do the tokens go?" for the open run, with a token footer under the answer](media/04-trace-assistant.png)

Four canned questions cover the common cases (`这条 run 哪里有问题？` · `token 大头在哪？为什么？` · `哪几轮可以省？` · `总体分析一下`), and the box below takes anything else. Its answer carries its own cost footer — `7877 tokens | 7393 in | 484 out | gemini-2-5-pro` in the screenshot.

**Asking the assistant is itself an AI call**, billed to you and visible afterwards in [the usage face](../agent-observability-usage/) under the `observability-explorer` app. Measured on this walk: two questions moved that app's row from 5 calls to 8.

## Failures to expect

| Symptom | What it actually is |
| --- | --- |
| `Sign in to view this content.` | Not an error — traces have no anonymous projection |
| Inspector reads `Select a row to inspect` | Click any timeline row and it fills — see the note below |
| A row's first line is someone else's question | `USER INPUT` includes conversation history; open the run for the real prompt |
| `interrupted` with 0 tokens | The run never reached the model |
| Round count is one higher than the `ROUND n` rows | The final output is the last round |

### The empty inspector: no longer reproducible

On build `400ce96` the inspector came up empty after a multi-hop path — drill into a run, leave
for `/dashboard` and `/usage`, come back to `/traces` and drill again — and stayed on
`Select a row to inspect` indefinitely (3/3 at the time). **On build `35de3a0b` it does not
reproduce**: the same hop sequence, including the intermediate back-navigation, was driven three
times and the inspector filled with the run's opening event every time.

The blocklet's own man page still records this as an open bug, and cites an issue number that
belongs to a closed QA report — filed back to ARC so the note stops outliving the defect. If you
do land on an empty inspector, clicking any timeline row fills it; the run itself is never the
thing that broke.

---

## Read your AI usage in Agent Observability

URL: https://www.arcblock.io/en/docs/blocklets/agent-observability-usage/

Use this page to read the **AI usage** face of the **Agent Observability** blocklet (`blocklets/observability-explorer` in the ARC monorepo): how many AI calls were made, by which model, from which app, and — if you administer apps — by which user.

Everything below was verified against the live deployment at `https://observability-explorer.afsd.dev`, build `35de3a0b`, signed in as a registered test user on **2026-08-20**. Your numbers, apps, and models will differ; the shapes, paths, and limits are the part to reuse.

> This is the second walk. The first ran on build `400ce96` (2026-08-15); in the five days since, three changes landed that alter how this face reads — breakdown tables and their `合计` footer switched to order-of-magnitude figures, the query action now rejects a misspelled top-level argument, and the admin portfolio picked up DID-Space-published blocklets. Every screenshot and number below was re-shot and rewritten against the new build rather than patched.

## Two different things share the name "observability"

The blocklet has three sidebar sections, and they answer different questions from different data:

| Section | Route | Answers | Data |
| --- | --- | --- | --- |
| **dashboard** | `/dashboard` | What agent runs happened | Trace records |
| **traces** | `/traces` | What happened *inside* one agent run | Trace records |
| **usage** | `/usage` | What AI capacity was consumed | Audit ledger (`/dev/ai/usage`) |

**This page documents `usage` only.** Traces and usage never reconcile with each other and are not derived from one another — a run can consume tokens without producing a trace record and the reverse. If you are looking for "why did this agent do that", you want traces, not this page.

## Open it

The usage face is two routes, one per population:

```text
https://<your-observability-host>/usage          ← your own calls, across every app
https://<your-observability-host>/usage/admin    ← every user's calls, in apps you administer
```

Signed out, the app renders neither. It states the reason rather than an empty chart:

![Agent Observability signed out: sidebar collapsed, primary pane reads "Sign in to view this content."](media/06-signed-out.png)

Sign in, and `/usage` is scoped to you by identity, not by a filter you have to set. The records live in your own DID Space; the page rolls up only calls attributed to you.

## The personal face: `/usage`

![The /usage page: headline totals, cache definition callout, and the daily trend chart with one line per model](media/01-usage-user.png)

Read it top to bottom — each block qualifies the one above it. Every block is bound to a path under `/dev/ai/usage/`:

| Block | What it states | Bound to |
| --- | --- | --- |
| **Headline** | Calls · total tokens (input + output) · cache hit rate with its denominator · time range | `summary` |
| **Cache callout** | That cached tokens are **not** an addend of the total, and that `—` means "not reported", not "zero" | same |
| **消耗趋势 (trend)** | Daily tokens, **one line per model** | `daily` |
| **按模型 (by model)** | Calls / input / output / total / cached / hit-rate per model | `table-by-model` |
| **按应用 (by app)** | The same columns per calling app, plus a **模型构成** (model mix) column | `table-by-caller` |

Three properties of this page are deliberate and worth knowing before you read numbers off it.

**No chart ever sums tokens across models.** A million Haiku tokens and a million Opus tokens differ by more than an order of magnitude in cost, so a bar or line that merges them is a confidently wrong ranking. Whenever the label axis is not the model, the chart splits into one series per model instead. The tables *do* state a cross-model total, because the number is what you came for — and they neutralise the hazard in place by putting the model mix on every row.

**Token counts in the tables are order-of-magnitude; full precision lives in the headline.** Body cells and the `合计` footer print as `462.5K` / `473.6K` (ARC [#3948](https://github.com/ArcBlock/arc/issues/3948), with the footer following when [#4164](https://github.com/ArcBlock/arc/issues/4164) closed), while **head counts** — calls, active users — stay exact everywhere: compacting a head count (5,000 vs 5,400 calls) saves three characters and drops information the reader needs. For exact token totals, read the headline; it prints the same numbers through the same formatter and still says `473,639`.

**The two tables foot to the same grand total, and to the headline.** That is the page's self-check: if `按模型` and `按应用` disagree, they are reading different data. Compaction does not break the invariant — it keeps it as an exact equality: `footer === compact(the total the headline prints)`.

![The two breakdown tables stacked, each ending in a 合计 row equal to the headline totals](media/02-usage-tables.png)

**Days with no calls are omitted, not zero-filled.** The trend axis in the screenshot jumps 08-06 → 08-08; there was no call on 08-07. Read gaps as absence, not as zero.

### One app, on its own page

Every app name in `按应用` is a link to a shareable page for that app alone:

```text
/usage/app/<caller>          e.g. /usage/app/todo
```

![The /usage/app/todo page: "AI 消耗 · 我在这个应用里" with its own headline, trend, by-model bar chart, and table](media/03-usage-one-app.png)

This is **your** consumption inside that app — not the app's total. Its headline reconciles exactly with that app's row on `/usage`: in the walk above, `todo` showed 53 calls / 246,409 tokens in both places. The page carries `← 我的消费` back to the full roll-up.

Its panels are `daily`, `by-model` and `table-by-model` only. `by-caller` and `by-instance` are deliberately absent: a population already narrowed to one app draws a single bar on either.

![Lower half of /usage/app/todo: the by-model bar chart with input, output and cached series, above the by-model table](media/07-usage-one-app-charts.png)

> One rendering caveat, visible above: when input and output differ by two orders of magnitude — 243,000 against 3,409 here — the output bar is a hairline against an axis scaled to the input. The number in the table is the reliable read.

## The admin face: `/usage/admin`

Visible to admin/owner callers only. Where `/usage` reads *your* ledger across all apps, this reads *one app's* ledger across all users — a different population, which is why the two are separate pages rather than tabs, and why their totals are not meant to be compared.

![The /usage/admin portfolio: a table of apps with calls, active users, tokens and last-call time, above the default app's detail](media/04-usage-admin-portfolio.png)

| Block | What it states | Bound to (under `/dev/ai/usage/admin/`) |
| --- | --- | --- |
| **应用一览 (portfolio)** | One row per app you may inspect: calls, active users, tokens, last call | `apps` |
| **Detail below it** | The full breakdown for **one** app — headline, trend, by-user table, by-model table | `<projection>` |

**The app shown in the detail block moves.** It is "the authorized app with the newest activity" — marked with ★ in the portfolio — so a link to `/usage/admin` shows whoever was busiest most recently. To address one app stably, use its own route.

**Rows with zero calls belong there.** The portfolio lists *apps you may inspect*, not *apps with usage*: `did-space` and `showcase` are all zeros above. In the other direction, blocklets published through DID Space were missing from this table entirely until ARC [#3950](https://github.com/ArcBlock/arc/issues/3950) — the enumerator walked only the static registry leg — so on a build older than 2026-08-16 this table is short.

Scroll past the portfolio and the detail block reads like the personal face, with `按用户` where the personal face had `按应用`:

![The detail block under the portfolio: everyone's trend for one app, then the by-user table and the by-model table, both footing to the same 合计](media/08-usage-admin-detail.png)

The `(unknown)` row above is 56 calls that carry no user id — the same records that make the portfolio say "0 active users" for `discuss-kit`.

### One app, and one user in it

```text
/usage/admin/<instanceDid>                 e.g. /usage/admin/discuss-kit
/usage/admin/<instanceDid>/u/<userDid>     one user's consumption inside that app
```

![The /usage/admin/discuss-kit page: trend chart, by-model table, and a by-user table whose only row is (unknown)](media/05-usage-admin-one-app.png)

![The /usage/admin/todo/u/<did> page for one test-fixture user: its own headline, trend and by-model table, with a 「← 这个应用」 button back](media/09-usage-admin-one-user.png)

Both are hard-loadable and shareable; the portfolio table's app ids and the by-user table's DIDs are the links that reach them. A row attributed to `(unknown)` is **not** a link — see below for what that row means. (The DID in the screenshot belongs to a registered test-fixture account on the test deployment.)

An app id that does not exist — or that you may not view — reaches the same page shape with an honest empty state rather than an error or a zero row:

![/usage/admin/__bogus__ rendering "暂无可显示的用量" with the trend and table regions stating they have nothing to attribute](media/10-usage-admin-empty.png)

## Integrate against the same data

Every panel above is bound to a **readable AFS path**. Nothing on the page holds a private copy of the roll-up, so anything the page can show, your own surface can read.

### Readable projections

```text
read /dev/ai/usage/<projection>
```

| Projection | Type | Content |
| --- | --- | --- |
| `summary` | markdown | Headline sentence + cache definition + completeness warnings |
| `table-by-model` `table-by-caller` `table-by-instance` | markdown | Breakdown tables (same columns on every dimension) |
| `daily` `by-model` `by-caller` `by-instance` | JSON | `{labels, datasets}` — Chart.js-shaped, bindable as-is |

Per-app: `/dev/ai/usage/app/<caller>/{table-by-model,daily,by-model}`.
Admin: `/dev/ai/usage/admin/{summary,apps,table-by-model,table-by-user,daily,by-model,by-user}`, plus `/admin/<instanceDid>/<projection>` and `/admin/<instanceDid>/u/<userDid>/<projection>`.

An unknown projection name is an error, not an empty result:

```text
read /dev/ai/usage/table-by-user
→ unknown usage projection "table-by-user" — expected one of
  summary | table-by-model | table-by-caller | table-by-instance |
  daily | by-model | by-caller | by-instance
```

**The `admin/` segment does not behave that way.** `/dev/ai/usage/admin/<x>` treats an unrecognised `<x>` as an app id, so a mistyped projection under `admin/` returns the "no usage to show" empty state instead of the error above. Under `admin/`, check your spelling yourself.

### Why projections exist at all

An AUP `chart` node binds live data through `node.src`, and `node.src` must be a **readable AFS path** — an exec action cannot be bound (`providers/runtime/ui/src/aup-registry.ts`). Without a readable projection, a page would have to call `window.afs.exec()` itself and inject the result, which is the renderer-purity violation ARC forbids. That is the whole reason each drill level ships another set of readable routes rather than one clever query.

Practical consequence when you build on this: **plan a readable path for every panel you want to bind.** If your data only exists behind an action, the chart cannot see it.

### The query action

For anything the fixed projections do not answer:

```text
exec /dev/ai/usage/.actions/query { groupBy, where, from, to, limit, includeCost }
exec /dev/ai/usage/admin/.actions/query { instanceDid, ...same }
```

| Argument | Accepts |
| --- | --- |
| `groupBy` | `type` `model` `hub` `caller` `instanceDid` `userDid` `day` — string or array, de-duplicated |
| `where` | Same keys (except `day`), each a string or string array |
| `from` / `to` | ISO dates; inclusive lower, exclusive upper |
| `limit` | Positive number (default 100) |
| `includeCost` | `true` to attach cost estimates where hub pricing exists |

A real call and its real answer, from the browser console of the running app:

```js
await window.afs.exec('/dev/ai/usage/.actions/query',
                      { groupBy: ['day'], where: { caller: ['todo'] } })
// → { groups: [...], totals: { calls: 53, totalTokens: 246409, ... },
//     groupCount: 10, scanned: 53, skipped: 0, groupBy: ['day'], range: {} }
```

The query is strict by design: an unknown dimension, an unknown `where` key, an unparseable date, or an inverted range each throw rather than degrade. **A misspelled top-level argument throws as well**, and the error names the legal set:

```js
await window.afs.exec('/dev/ai/usage/.actions/query',
                      { groupBy: ['day'], filter: { caller: 'todo' } })
// → AFS_VALIDATION_ERROR: unknown argument "filter" —
//    expected one of from | to | groupBy | where | limit | includeCost
```

That check arrived in ARC PR [#4081](https://github.com/ArcBlock/arc/pull/4081). Before it, `{filter: {...}}` was **silently ignored** and the query answered with the entire unfiltered ledger — and a filter that silently does nothing returns a plausible number. Integrating against a build older than 2026-08-15 means spelling `where` correctly yourself.

One exemption to know about: `_scope_afs` is the object capability the runtime stamps onto args before dispatch (WS seam, AUP auto-dispatch, chat, scheduler all do it). It is exempt by **exact name**, not by a `_` prefix rule, so it is not an unknown argument (ARC [#4169](https://github.com/ArcBlock/arc/pull/4169)) while a mistyped `_scope_af` still errors. Pass it through untouched when you dispatch server-side.

Two ceilings to design around: one query reads at most **5,000** audit records (beyond that the result carries `truncated: true` and a warning — never a quietly short answer), a chart carries at most **8** series (overflow is dropped and named in `warnings`, never merged into an "other" bucket) and **60** label points.

## Known gaps (verified, not inferred)

These are current behaviours of the build named at the top, confirmed by walking it — not speculation.

**The two faces can disagree about the same person in the same app.** They read two different ledgers: `/usage` reads your DID Space records, `/usage/admin` reads the app instance's own ledger. On this walk (08-20) `todo` reported 53 calls / 246,409 tokens on the personal face and 46 calls / 215,415 tokens for the same single user on the admin face; `observability-explorer` went the other way (5 personal, 6 admin). Five days earlier the same pairs were 48 / 41 and 4 / 5 — **the gap grows with new traffic; it is not a one-off historical residue**. The gap is not a rounding artefact — the missing records cluster on the earliest days, and records written without a `userDid` never enter the per-user view at all. Treat each face as authoritative for its own question and do not subtract one from the other. Tracked in ARC [#4082](https://github.com/ArcBlock/arc/issues/4082).

**`(unknown)` is a real bucket, not a user.** A call whose record carries no `userDid` is counted in the totals and lands in an `(unknown)` row. An app can therefore show 40 calls and **0 active users** at the same time — that is what `discuss-kit` shows in the screenshot above. It means "nobody was attributable", not "nobody called".

**`table-by-instance` duplicates `table-by-caller` on most deployments.** `instanceDid` only diverges from `caller` where the host supplies a distinct instance identity; on `afsd.dev` today both are the blocklet id, so the two tables are identical. The page binds only one of them on purpose.

**No money, anywhere.** Every face counts tokens. Cost estimates exist only behind `exec … {includeCost: true}` and only where a hub publishes list pricing; no page converts tokens to a currency, and none of them is a bill.

**Being signed in is not the same as being an admin.** The `我管的应用 →` button and the whole `/usage/admin` face are gated per app, by same-instance admin/owner or membership. If you can sign in but see no admin face, you administer no app on that deployment — the page cannot tell you *who* does.

**The trace face only came under the same rule on 2026-08-18.** Before that, `authorizedView` mapped an `owner`/`admin` role on *any* app to deployment-wide privilege, so one app's owner could read every app's agent runs (task text included) while the same caller was refused per instance by this usage admin face — two faces, two answers about one person. Fixed in ARC [#4170](https://github.com/ArcBlock/arc/issues/4170) / [PR #4269](https://github.com/ArcBlock/arc/pull/4269), which moves the predicate into `@aigne/afs` so it exists once. For what the trace face shows today, see [the dashboard page](../agent-observability-dashboard/).

## Failures to expect

| Symptom | What it actually is |
| --- | --- |
| "Sign in to view this content." | Not an error — the usage face has no anonymous projection |
| A gap in the trend axis | No calls that day; days without records are omitted, not zeroed |
| `—` in a cache column | That source reported no cache data. **Not** a 0% hit rate |
| Admin detail block shows a different app than last time | It follows "most recent activity"; use `/usage/admin/<instanceDid>` for a stable link |
| A shared `/usage/admin/<app>` link shows "暂无可显示的用量" | The app does not exist, is retired, or you may not view it — the empty state does not distinguish them |
| A query answers `unknown argument "…"` | A top-level argument name is misspelled (`filter`, `wehre`…); the error lists the legal set |
| A filtered query returns suspiciously round totals | You are on a build before ARC #4081, which ignored a misspelled top-level argument; compare `scanned` against `totals.calls` |

## See also

- [Search and query](../../afs/search-and-query/) — how `list`, `query` and `search` differ across AFS
- [Reference applications](../reference-applications/) — the other bounded examples under `blocklets/`

---

## Author a Blocklet

URL: https://www.arcblock.io/en/docs/blocklets/author/

Authoring a Blocklet joins several contracts. Keep them separate so changes stay reviewable.

## Three authoring faces

| Face | Question | Page |
| --- | --- | --- |
| **Manifest and capabilities** | What does the package declare? | [Manifest and capabilities](../manifest-and-capabilities/) |
| **Data and AFS** | How does the package use paths, mounts, seed, and collections? | [Data and AFS](../data-and-afs/) |
| **Web surfaces** | Is this AUP UI, Web Device site content, or both? | [Web surfaces](../web-surfaces/) |

## Recommended order

1. Start from a recipe that matches the surface you need (`basic` for empty package, `minimal-app` for web+AUP+agent, or hand-authored Web Device files as in [Build a first site](/en/docs/web-device/first-site/)).
2. Fill identity metadata (`name`, `description`, `logo`, …) before treating the package as shareable.
3. Add only the AFS mounts, sites/bindings, or replicated collections the app actually uses.
4. Re-run `arc dsl validate`, `arc blocklet check`, and a local run after each meaningful change.

## What not to mix

| Do not | Do instead |
| --- | --- |
| Treat AUP page trees as "the Blocklet" | Blocklet = package boundary; AUP is one possible surface |
| Bind product language to a specific database | Use AFS paths and capabilities; see [AFS](/en/docs/afs/) |
| Copy entire CLI man pages into the app | Link [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/) for flags |
| Invent manifest fields from wishlists | Only document fields the parser/checker accept today |

## Entry points in a package directory

| Path / file | Role |
| --- | --- |
| `blocklet.yaml` | Package manifest (required for most workflows) |
| `.aup/` | AUP app and pages |
| `pages/` + `.web/` | Web Device layouts, site components, SEO atoms |
| `.route/` | Route declarations (web vs app handlers) |
| `agents/` | Agent definitions |
| `seed/` | First-run seed material for instance data |
| `skills/` | Packaged skills (when used) |
| `dist/` | Build output only |

Convention-only packages without `blocklet.yaml` still exist as teaching samples (`hello-html`, `hello-declarative`). Prefer an explicit `blocklet.yaml` for new third-party work — `create` always writes one.

---

## Check, build, and inspect

URL: https://www.arcblock.io/en/docs/blocklets/check-build-inspect/

A green build alone does not prove the application surface. Use a short chain and record what each step actually proves.

## Acceptance chain

| Step | Command | Proves | Does not prove |
| --- | --- | --- | --- |
| DSL | `arc dsl validate <dir>` | Declared AUP/DSL sources parse | Runtime behavior or HTTP 200 |
| Package contract | `arc blocklet check [dir] --profile <p>` | Recipe/profile requirements met | Browser layout |
| Convention scan | `arc blocklet dev [dir]` | Detected content type / mounts / index hints | Serving |
| Build | `arc blocklet build [dir]` | `dist/` + AFS/flat manifests written | Readers saw the page |
| Inspect | `arc blocklet inspect <dir>` | Package identity + file list (+ publish status) | Correct UX |
| Local run | `arc blocklet run` / `service start --blocklet` | Observable local surface | Remote deploy health |

## `arc blocklet check`

```bash
arc blocklet check ./demo-basic
arc blocklet check ./demo-min --profile minimal-app
```

Profiles accepted by the CLI: `basic` (default), `minimal-app`, `agent-workspace`, `support-community`.

Verified outputs:

```text
Passed blocklet check (basic)
  dir: /…/demo-basic
  AUP pages: (none)
  web sections: 0
  agents: 0
  settings files: 0

Passed blocklet check (minimal-app)
  dir: /…/demo-min
  AUP pages: agent, home, settings
  web sections: 1
  agents: 1
  settings files: 5
```

`arc blocklet validate` is an alias for `check` with validation-focused wording.

Use JSON when scripting:

```bash
arc blocklet check ./demo-min --profile minimal-app --json
```

## `arc dsl validate` (and lint)

```bash
arc dsl validate ./demo-min
# Passed DSL validation
#   path: /…/demo-min
#   files: 16
```

`arc dsl lint` can report format drift on scaffold output:

```text
Failed DSL lint (3 changed)
  ERROR format_changed .aup/app.aup: File is not formatted. Run arc dsl format --write.
```

Fix with `arc dsl format --write <dir>` when your gate requires a clean lint. Package `check` can still pass while lint reports format_changed — they answer different questions.

## `arc blocklet build`

```bash
arc blocklet build ./demo-basic
arc blocklet build ./demo-min
```

Verified:

```text
Published 1 file(s) → /…/demo-basic/dist
  .afs/manifest.json  (http-mount protocol)
  blocklet.dist.json  (flat manifest)
  instance: stateless

Published 20 file(s) → /…/demo-min/dist
  .afs/manifest.json  (http-mount protocol)
  blocklet.dist.json  (flat manifest)
  instance: requires /instance DID Space
```

Options:

| Flag | Default | Meaning |
| --- | --- | --- |
| `--output <dir>` | `<dir>/dist` | Output directory |
| `--dry-run` | false | Compute manifest without writing |
| `--clean` | true | Clean output before write |

Do not hand-edit `dist/`. Do not commit it unless your release process explicitly requires the generated artifact (this site blocklet gitignores `dist/` and `.web-cache/`).

Example `.afs/manifest.json` fragment after building `demo-basic`:

```json
{
  "afs": "1.0",
  "type": "readonly-tree",
  "files": [
    {
      "path": "blocklet.yaml",
      "size": 107,
      "contentType": "text/yaml",
      "sha256": "aeb371c705d2…"
    }
  ]
}
```

## `arc blocklet inspect`

```bash
arc blocklet inspect ./demo-basic
arc blocklet inspect ./demo-min
```

Verified shapes:

```text
Blocklet: demo-basic (demo-basic)
  path:    /…/demo-basic
  version: 0.1.0
  did:     did:blocklet:demo-basic
  status:  published
  files:   1  (107 bytes)
    blocklet.yaml  (…)

Blocklet: demo-min (demo-min)
  path:    /…/demo-min
  version: 0.1.0
  did:     did:blocklet:demo-min
  status:  published
  files:   20  (4468 bytes)
    .afs/preflight.json
    .aup/app.aup
    …
```

`status: published` here means a local `dist/` package artifact exists for inspect/list purposes — **not** that a remote DID Space or Cloudflare deployment succeeded.

## `arc blocklet dev`

```bash
arc blocklet dev ./demo-basic
# Blocklet: /…/demo-basic

arc blocklet dev ./demo-min
# Blocklet: /…/demo-min
# Content type: aup
# Index: pages → /
# Mount: agents/app-agent → /agents/app-agent
# Mount: pages → /pages
```

Treat `dev` as a **directory convention report**, not a server.

## `arc blocklet list`

```bash
arc blocklet list .
```

Verified:

```text
Blocklets under /…:
  demo-basic v0.1.0  [published]
    path: demo-basic
  demo-min v0.1.0  [unpublished]
    path: demo-min
```

Status flips after a successful `build` for that package.

## Record one acceptance note

For a change that matters, keep a short record:

1. `arc --version`
2. Exact `check` profile and result
3. `build` file count + `instance:` line
4. Local URL and HTTP/browser result
5. Explicit statement that remote publish was **not** part of the test (or was, with target)

CLI man page: [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/). Diagnostics patterns: [Test and diagnose](../test-diagnose/).

---

## Create and run locally

URL: https://www.arcblock.io/en/docs/blocklets/create-run-locally/

Local direct run is the normal starting point. Use it to prove selected source and the observable surface before any formal publish path.

## Local development loop

| Step | Command | Proves |
| --- | --- | --- |
| 1. Create | `arc blocklet create` / `init` | Package scaffold exists |
| 2. Validate | `arc dsl validate` + `arc blocklet check` | DSL and profile contract |
| 3. Run | `arc blocklet run` or `arc service start --blocklet` | Local HTTP surface |
| 4. Accept | Browser on printed URL | Visible result |
| 5. (Later) Build / publish | `arc blocklet build`, then a **separate** publish path | Artifact / release — not step 1 |

![Local loop from create through validate, run, browser acceptance, then optional build and publish](https://raw.githubusercontent.com/ArcBlock/loop-agent-assets/main/arcblock-site/docs-blocklets-20260810/local-dev-loop.svg)

*Validate and run locally first. Publish and remote deploy are a separate path after acceptance.*

## 1. Create a package

```bash
# Manifest only
arc blocklet create ./demo-basic --recipe basic --name demo-basic

# Tiny complete app (web + AUP + agent + settings)
arc blocklet create ./demo-min --recipe minimal-app --name demo-min
```

`arc blocklet init` is an alias for `create` (same flags).

Verified outputs (`2.0.0-beta.28`):

```text
Created blocklet.yaml with did: "did:blocklet:demo-basic"

Created minimal app blocklet "demo-min" with 18 file(s).
Next: arc dsl validate /…/demo-min
```

`basic` tree:

```text
demo-basic/blocklet.yaml
```

`minimal-app` includes (among others) `blocklet.yaml`, `pages/index/…`, `.web/components/…`, `.aup/app.aup`, `agents/app-agent/…`, and `seed/settings/…`.

Options:

| Flag | Meaning |
| --- | --- |
| `[dir]` | Target directory (default: cwd) |
| `--name <name>` | Blocklet name / id basis (default: directory name) |
| `--recipe` / `--template` | `basic`, `blank`, `blog`, `agent`, `minimal-app`, `agent-workspace`, `support-community` |

Discover recipes:

```bash
arc blocklet recipe list
arc blocklet recipe explain basic
```

## 2. Validate before serving

```bash
arc dsl validate ./demo-min
arc blocklet check ./demo-min --profile minimal-app
```

Verified:

```text
Passed DSL validation
  path: /…/demo-min
  files: 16

Passed blocklet check (minimal-app)
  dir: /…/demo-min
  AUP pages: agent, home, settings
  web sections: 1
  agents: 1
  settings files: 5
```

For a `basic` package:

```bash
arc blocklet check ./demo-basic
# Passed blocklet check (basic) — AUP pages (none), web 0, agents 0, settings 0
```

Match `--profile` to the recipe you used for complete-app recipes. Default profile is `basic`.

Optional format gate (may fail on freshly scaffolded DSL until formatted):

```bash
arc dsl lint ./demo-min
# If format_changed: arc dsl format --write ./demo-min
```

## 3. Run locally (preferred paths)

### A. Single Blocklet: `arc blocklet run`

```bash
arc blocklet run ./demo-min
```

Verified:

```text
Serving blocklet "demo-min" on port 4941
  http://demo-min.localhost:4941/
  http://localhost:4941/?blocklet=demo-min  (Safari / universal)
```

`arc blocklet run` reuses or starts the seed instance (`default`, port `4900`). If that port is already taken by something you do not own, start a named instance instead (port auto-assigns). `ARC_SERVICE_PORT` still exists but only affects the seed instance. Do not `stop` a daemon you did not start.

To keep the source on the instance across restarts, use `arc service start --instance <name> --blocklet ./demo-min`.

### B. Cold start with explicit path: `arc service start --blocklet`

```bash
arc service start --instance demo --blocklet ./demo-min --port 4939
```

Omit `--port` on a named instance to let the kernel assign one. Pinning `4939` matches the captured dump below.

Verified:

```text
Starting AFS service...
  Extra blocklet dirs: /…/parent
AFS Service started
  PID:  …
  Port: 4939
  Blocklet: demo-min
    http://demo-min.localhost:4939/
    http://localhost:4939/?blocklet=demo-min (Safari / universal)
```

Both forms print a **subdomain URL** and a **query URL** (`?blocklet=`). Prefer the subdomain host when your browser resolves `*.localhost`. Use the query form when it does not (some Safari setups).

### C. What to open

```bash
curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "Host: demo-min.localhost:4939" \
  http://127.0.0.1:4939/
# 200
```

Open the printed URL in a real browser. Check layout at a wide and a narrow viewport when the surface matters.

## Isolation for throwaway tests

`ARC_HOME` is retired. Use a named instance and `--home`:

```bash
export ARC_INSTANCES_DIR=/tmp/arc-instances-demo
arc service start --instance demo --home /tmp/arc-home-demo --blocklet ./demo-min
# … accept …
arc service stop --instance demo
arc service rm --instance demo
```

Stop only the temporary named instance you started. Do not stop the seed daemon on `:4900` unless you started it.

## Commands that are *not* a local app run

| Command | What it actually does |
| --- | --- |
| `arc blocklet dev [dir]` | Scans directory conventions; prints mounts/content type. **No HTTP server.** |
| `arc blocklet build [dir]` | Writes `dist/`. Does not open a browser surface. |
| `arc deploy <path> --server …` | Remote DID Space publish path — **not** local acceptance |
| `arc deploy <path> --publish` | Local developer DID Space publish — separate from direct run; may require snapshot secrets |

## Prefer these local paths

| Goal | Prefer | Avoid as first step |
| --- | --- | --- |
| Day-to-day acceptance | `arc blocklet run` or `arc service start --blocklet` | DID Space deploy |
| CI / isolated check | `check` + `build` + optional headless HTTP probe | Shared production daemon |
| Multi-blocklet monorepo parent | `arc service start --instance <name> --blocklet <parent>` | Registering into an unknown shared daemon without isolation |

Continue to [Check, build, and inspect](../check-build-inspect/) for the artifact chain, or [Author](../author/) to change package contents.

---

## Data and AFS

URL: https://www.arcblock.io/en/docs/blocklets/data-and-afs/

For a Blocklet, **AFS is the public data boundary**: paths, operations, and declared capabilities. A provider may use files, SQLite, object storage, or a remote service internally. That choice is not the application contract.

This page covers **Blocklet-side integration**. Core AFS operations and provider authoring live on the [AFS board](/en/docs/afs/).

## How a Blocklet meets AFS

| Mechanism | Where declared | Role |
| --- | --- | --- |
| Package files as readonly tree | Built into `dist/.afs/manifest.json` | Static package assets addressable as a tree |
| `mounts` | `blocklet.yaml` | Attach providers at absolute targets (`/ash`, custom modules, …) |
| `seed/` | Package directory + optional `instance.seed` | First-run material for instance data |
| `replicated` | `blocklet.yaml` | Collection ownership/copy contracts |
| `sites.bindings` | `blocklet.yaml` | Map HTTP paths to AFS paths + AUP pages |
| `networkRead` | `blocklet.yaml` | Allow network-origin reads of selected `/instance/**` |
| `index` | `blocklet.yaml` | Index domains for search over declared paths |

## Package tree vs `/instance`

| Path family | Meaning |
| --- | --- |
| Package root / `/packages` projection | Immutable (for a version) application assets |
| `/instance` | Instance-scoped data space when the package needs one |
| `/user` / caller overlays | User-scoped data when `scope` and session model require them |

`arc blocklet build` reports the instance posture:

```text
# basic recipe
instance: stateless

# minimal-app recipe
instance: requires /instance DID Space
```

Rules:

1. If the package needs `/instance` and no real DID Space is bound, **stateful** features must fail closed — do not pretend seed files are a live instance space.
2. `seed/` is initialization input, not a substitute for a bound instance DID Space after first run.
3. Local HTTP 200 on a static or shell page does **not** prove `/instance` writes succeeded.

## Mounts

Declare only providers the package uses:

```yaml
mounts:
  - uri: "ash://"
    target: /ash
    required: true
```

Or a local module:

```yaml
mounts:
  - module: "./providers/my-provider"
    target: /my
    required: true
```

Optional fields include `ops` (whitelist), `aup` (recipe scan path anchored at `$PROGRAM_DIR` or `$DATA_DIR`), `seed` (copy package files into a cold mount), and `shared`.

Inspect what the convention scanner sees:

```bash
arc blocklet dev ./demo-min
# Mount: agents/app-agent → /agents/app-agent
# Mount: pages → /pages
```

## Seed and settings

Complete-app recipes generate `seed/settings/…` JSON and AUP shells. Treat them as **package defaults** for instance initialization. Changing seed changes the package; changing live instance settings changes instance data.

## Replicated collections (reference pattern)

Discuss Kit declares collections under `replicated:` (posts, comments, anon) with `canonical`, `copy`, `minRole`, `readRole`, and delete rules. That pattern is a **reference implementation** of replicated discussion data — not a claim that every historical product surface is platformized.

Read [Discuss Kit lineage](../discuss-kit-lineage/) for scope and limits. Study the live manifest in the ARC tree at `blocklets/discuss-kit/blocklet.yaml` (read-only reference).

## Bindings: URL → AFS → page

Example shape (Discuss Kit):

```yaml
sites:
  - name: discuss-kit
    domains:
      - discuss-kit.localhost
    bindings:
      - id: posts-list
        path: "/posts"
        afs: "/instance/app/content/posts"
        page: index
      - id: post-detail
        path: "/posts/{slug}"
        afs: "/instance/app/content/posts/{slug}"
        page: detail
```

Use bindings when the product URL is a first-class map onto instance content. For pure Web Device static sites, prefer `.route/web` + `pages/` as in [Build a first site](/en/docs/web-device/first-site/).

## What to read next on the AFS board

| Need | AFS page |
| --- | --- |
| Operations and capability boundary | [Core contract](/en/docs/afs/core-contract/) |
| List vs query vs search | [Search and query](/en/docs/afs/search-and-query/) |
| Provider authoring | [Author a provider](/en/docs/afs/author-a-provider/) / [Providers](/en/docs/afs/providers/) |
| Local inspection commands | [Local inspection](/en/docs/afs/local-inspection/) |

## Hard boundaries

| Do | Do not |
| --- | --- |
| Address data via AFS paths | Promise a specific SQL schema as the public API |
| Declare mounts the package needs | Mount host-global paths without understanding scope |
| Mark `/instance`-dependent features clearly | Claim seed files alone prove multi-user instance data |
| Link AFS board for op catalogs | Duplicate the full AFS op reference here |

---

## Discuss Kit lineage

URL: https://www.arcblock.io/en/docs/blocklets/discuss-kit-lineage/

**Discuss Kit** appears as a predecessor product name and as a **current ARC reference package** at `blocklets/discuss-kit` in the ARC monorepo. Use it to study a specific data and surface pattern. Do **not** use the name as proof that every historical Discuss Kit, forum, blog, wiki, bookmark, or messaging feature is available as a platform product today.

## Continuity statement

| Claim | Status |
| --- | --- |
| There is a current ARC package named `discuss-kit` | Yes — `blocklets/discuss-kit` |
| It demonstrates replicated posts/comments (and an anon collection) | Yes — `replicated` in `blocklet.yaml` |
| It demonstrates pretty URL bindings onto `/instance/app/content/posts` | Yes — `sites.bindings` |
| It is used as a multi-layer test anchor for replication / board read / comments | Yes — package README lists runtime tests |
| Every legacy Discuss Kit product surface is platformized unchanged | **No** — not claimed |
| Media Kit, DID Connect UI, or other historical apps are implied by this package | **No** |

## What the current package is for

From its own README and manifest (ARC tree, read-only reference):

- **Role:** Discussion board **reference app** (`scope: app`)
- **Data:** `replicated` collections for posts, comments, and anonymous items with explicit roles and copy modes
- **Surfaces:** AUP pages for list (`index`) and detail (`detail`) with man pilots
- **Bindings:** `/posts` → list AFS path; `/posts/{slug}` → detail
- **Extras:** declarative `cron` for scheduled post generation; `index` domain for instance-axis search; `networkRead` for guest-readable content paths

Study the live files:

- `blocklets/discuss-kit/blocklet.yaml`
- `blocklets/discuss-kit/README.md`
- `.aup/` pages and `seed/` content in the same package

## What it is not

| Not this | Why it matters |
| --- | --- |
| A drop-in replacement guarantee for every old Discuss Kit deployment | Different runtime, data model, and product cut |
| Proof that "comments everywhere" is a global platform service | Collections are **declared per package** |
| A starter recipe equivalent to `arc blocklet create --recipe …` | It is a full reference app with platform-test coupling |
| Permission to describe Media Kit or other kits as fully migrated | Separate evidence required per product |

## How to learn from it without over-claiming

1. Read `replicated` and `sites.bindings` as a **worked example** of collection + URL design.
2. When building your own app, declare **your** collections and bindings — do not assume discuss-kit's paths.
3. For third-party onboarding, prefer `minimal-app` or Web Device first-site for the first green path; graduate to replication only when you need it.
4. Keep public docs language at "reference implementation of replicated discussion data / surfaces," not "the platform forum product."

## Related reading

- [Reference applications](../reference-applications/)
- [Data and AFS](../data-and-afs/)
- [Package and instance](../package-and-instance/)
- Architecture lineage (when published on the architecture board) for name-mapping tables across historical products

---

## Get started

URL: https://www.arcblock.io/en/docs/blocklets/getting-started/

This section is the local-first path from a new directory to a checked, running Blocklet. Remote publish and DID Space deploy are **not** prerequisites.

## Prerequisites

1. Install the public CLI:

```bash
curl -fsSL https://arc.afsd.io/install.sh | bash
arc --version
```

Verified baseline for this board: `2.0.0-beta.28`.

2. Work in a **temporary or project directory outside the ARC monorepo**. You do not need to clone `ArcBlock/arc` to author a third-party Blocklet.

3. Prefer a named instance when experimenting so a test cannot alter the seed daemon on `:4900`. `ARC_HOME` is retired (the CLI warns and ignores it). Isolation is the instance name plus `--home`:

```bash
export ARC_INSTANCES_DIR=/tmp/arc-instances-demo
arc service start --instance demo --home /tmp/arc-home-demo
arc service url --instance demo --print url
# when finished:
arc service stop --instance demo
arc service rm --instance demo
```

## Three pages, one path

| Step | Page | What you prove |
| --- | --- | --- |
| 1 | [Package and instance](../package-and-instance/) | Package (artifact) vs instance (run/deployment) vocabulary |
| 2 | [Create and run locally](../create-run-locally/) | Scaffold + local serve + browser URL |
| 3 | [Check, build, and inspect](../check-build-inspect/) | `check` / `build` / `inspect` / `dev` evidence chain |

## Minimal command sequence

```bash
# 1. Scaffold a complete tiny app (web + AUP + agent + settings)
arc blocklet create ./demo-min --recipe minimal-app --name demo-min

# 2. Validate declared DSL and package profile
arc dsl validate ./demo-min
arc blocklet check ./demo-min --profile minimal-app

# 3. Serve only this Blocklet on a named instance (no DID Space)
arc service start --instance demo --blocklet ./demo-min --port 4939
```

Verified output shape (`arc` `2.0.0-beta.28`):

```text
Created minimal app blocklet "demo-min" with 18 file(s).
Next: arc dsl validate /…/demo-min

Passed DSL validation
  path: /…/demo-min
  files: 16

Passed blocklet check (minimal-app)
  dir: /…/demo-min
  AUP pages: agent, home, settings
  web sections: 1
  agents: 1
  settings files: 5

AFS Service started
  Port: 4939
  Blocklet: demo-min
    http://demo-min.localhost:4939/
    http://localhost:4939/?blocklet=demo-min (Safari / universal)
```

Open the printed subdomain URL. For local acceptance, stop the temporary named instance when finished (`arc service stop --instance demo`). Do not `stop` the seed daemon on `:4900` unless you started it.

## Recipes you can scaffold today

```bash
arc blocklet recipe list
```

| Recipe | Capabilities (as reported by CLI) | Generated files (approx.) |
| --- | --- | --- |
| `basic` / `blank` | manifest only | 1 (`blocklet.yaml`) |
| `blog` | aup | small AUP set |
| `agent` | aup, agent | chat + one agent |
| `minimal-app` | web, aup, agent, settings | ~18 files |
| `agent-workspace` | web, aup, agent, settings | ~19 files |
| `support-community` | web, aup, agent, settings | ~20 files |

Explain one recipe before you scaffold:

```bash
arc blocklet recipe explain minimal-app
```

## What not to do first

| Avoid | Why |
| --- | --- |
| `arc deploy … --server …` as step 1 | Requires auth and a remote DID Space; not local acceptance |
| Treating `arc blocklet dev` as a server | It only **scans conventions**; it does not serve HTTP |
| Assuming `dist/` is hand-edited source | `arc blocklet build` owns `dist/`; do not commit it unless your release process requires the artifact |
| Collapsing package and instance language | Makes data ownership, config, and release discussion ambiguous — see [Package and instance](../package-and-instance/) |

When the local page looks right, continue to authoring ([Author](../author/)) or the release boundary ([Publish and deploy](../publish-deploy/)).

---

## Lifecycle

URL: https://www.arcblock.io/en/docs/blocklets/lifecycle/

Lifecycle documentation is useful only when **state boundaries** stay visible. Collapsing "it builds" into "it is deployed" is a common failure mode.

## Stages

| Stage | What changes | Typical commands | Evidence |
| --- | --- | --- | --- |
| **Author** | Package source | editor, `create` | Diff in VCS |
| **Validate** | Nothing durable | `dsl validate`, `blocklet check`, `dsl lint` | Pass/fail + issue list |
| **Local instance** | Daemon registration / serve | `blocklet run`, `service start --blocklet` | Printed URLs + browser |
| **Build** | `dist/` artifact | `blocklet build` | File count, manifests, `instance:` line |
| **Local daemon register** | Extra blocklet dirs on a running daemon | `deploy <path>` (no flags), `service start --blocklet` | `deploy list` |
| **Local DID Space publish** | Developer space tree under `/blocklets/<id>/` | `deploy <path> --publish` | `deploy show` / `list --published` |
| **Remote DID Space publish** | Remote server write | `deploy <path> --server <url>` | Auth + remote inspection — **often unverified here** |
| **Pages / fleet deploy** | CDN/Pages project | `blocklet deploy`, `blocklet fleet`, `blocklet instance` | Platform-specific verify |

## Default path for developers

```text
create → validate → local run → browser accept
                 ↘ build (when you need an artifact)
```

Only after local acceptance, choose a publish path that matches the release goal. Details and honesty markers: [Publish and deploy](../publish-deploy/).

## Child pages

| Page | Focus |
| --- | --- |
| [Test and diagnose](../test-diagnose/) | Failure modes, what each check means |
| [Publish and deploy](../publish-deploy/) | Local publish vs remote; experimental labels |

## Stateful features

If `arc blocklet build` reports `instance: requires /instance DID Space`, the package has instance-axis dependencies. Lifecycle for those features includes:

1. Package validation (always)
2. Local shell/page serve (may succeed without full instance data)
3. Bound instance DID Space for real writes (separate proof)

Do not mark stage 3 complete because stage 2 returned HTTP 200.

## Stop cleanly

For temporary acceptance:

```bash
arc service stop
```

Only stop the isolated service you started. Persistent developer daemons are an environment choice, not a documentation requirement.

---

## Manifest and capabilities

URL: https://www.arcblock.io/en/docs/blocklets/manifest-and-capabilities/

`blocklet.yaml` is the declared boundary of a Blocklet package. Authority for field acceptance is the current parser (`packages/core/src/blocklet/parse-manifest.ts` / `BlockletManifest` in `types.ts`) and the CLI checker — not historical product docs.

Verified baseline: `arc` `2.0.0-beta.28`.

## Minimum package (scaffold)

`arc blocklet create ./demo-basic --recipe basic --name demo-basic` writes:

```yaml
specVersion: 2
id: demo-basic
name: demo-basic
did: did:blocklet:demo-basic
version: 0.1.0
description: ""
```

That is enough for `arc blocklet check` (profile `basic`) and `arc blocklet build`.

## Identity fields

| Field | Type | Notes |
| --- | --- | --- |
| `specVersion` | number | `2` for packaging-oriented manifests |
| `id` | string | Stable package id (scaffold uses kebab name) |
| `name` | string | Human-readable display name (not forced to kebab) |
| `did` | string | `did:blocklet:<id>` from scaffold |
| `version` | string | SemVer string, e.g. `0.1.0` |
| `description` | string | One-line purpose |

## Publishable metadata (optional but recommended)

| Field | Type | Notes |
| --- | --- | --- |
| `logo` | string | Relative path or URL (SVG preferred) |
| `keywords` | string[] | Discovery |
| `tags` | string[] | UI categories |
| `author` | `{ name, email?, url? }` | Primary author |
| `contributors` / `maintainers` | author[] | Optional |
| `copyright` | `{ owner?, year? }` | Optional |
| `license` | string | SPDX / `UNLICENSED` / etc. |
| `homepage`, `documentation`, `community`, `support` | string | URLs or support contact |
| `repository` | string or `{ type, url, directory? }` | Source pointer |
| `screenshots` | string[] | Paths or URLs |
| `hidden` | boolean | `true` hides from catalogue UIs; still activatable via `?blocklet=` |

## Runtime declaration fields

These are **not** cosmetic metadata. Only use what the package needs.

| Field | Meaning |
| --- | --- |
| `scope` | `app` (default), `user`, `root`, or `agent` — AFS namespace visibility |
| `mounts` | Provider mount declarations (`uri` or `module` + `target` + `required`, optional `ops`, `aup`, `seed`, …) |
| `system` | System service dependencies (e.g. `users`) |
| `sites` | Named sites: `name`, `domains`, optional `port`, `bindings` |
| `surfaces` | Externally accessible paths |
| `instance` | `{ required?, mount?, seed? }` — whether a real `/instance` DID Space is required |
| `cron` | Declarative scheduled tasks registered on activation |
| `replicated` | Replicated collection contracts (incompatible with `scope: root`) |
| `networkRead` | Allow network-origin reads of selected `/instance/**` base paths |
| `redistributable` | Redistribution terms for selected `/instance/**` subtrees |
| `index` | Index domain declarations for search |
| `blocklets` | Sub-blocklet composition list |
| `io` | IO surface / binding declarations |
| `arc` / `engines` | Compatibility ranges |
| `entrypoint` | Script path (specVersion 1 style; optional in v2) |
| `save` | Bookmark + selection-note capability. Omit = on, floating chrome. `false` / `{ enabled: false }` opts out. `chrome: buttons` binds `[data-arc-save]`. Hidden until login. See [Bookmark and note](/en/docs/web-device/save-capability/). |

### Mount entry shape (code-backed)

```yaml
mounts:
  - uri: "ash://"          # or module: "./providers/…"
    target: /ash           # absolute AFS path
    required: true
    ops: [list, read]      # optional whitelist
```

`uri` and `module` are mutually exclusive. See `MountDeclaration` in core types for `aup`, `seed`, `shared`, `options`.

### Sites and bindings (example pattern)

Production packages such as Discuss Kit declare domains and URL→AFS→page bindings under `sites`. Use bindings when pretty URLs map onto instance content. Route files under `.route/` remain the handler-level declaration for web vs app entry.

### Scope reminder

| Scope | Typical use |
| --- | --- |
| `app` | Default application package; supports replicated collections |
| `user` | Caller-scoped overlays (e.g. personal storage UIs) |
| `root` | Full host AFS visibility — **not** combined with `replicated` |
| `agent` | Agent-oriented packaging |

## Capabilities implied by recipes

Recipes report capabilities when listed:

```bash
arc blocklet recipe explain minimal-app
```

| Recipe capability label | Typical files |
| --- | --- |
| `manifest` | `blocklet.yaml` only |
| `web` | `pages/`, `.web/` |
| `aup` | `.aup/` |
| `agent` | `agents/` |
| `settings` | `seed/settings/…` |

Profile checks for complete apps (`minimal-app`, `agent-workspace`, `support-community`) enforce the recipe contract, not only the presence of `blocklet.yaml`.

## Checker profiles

```bash
arc blocklet check . --profile basic
arc blocklet check . --profile minimal-app
```

| Profile | Expectation (summary) |
| --- | --- |
| `basic` | Valid package directory / minimal contract |
| `minimal-app` | AUP pages, web section, agent, settings counts per recipe |
| `agent-workspace` | Workspace-oriented complete app contract |
| `support-community` | Support-community complete app contract |

## What not to invent

- Do not document fields that exist only in planning docs or unmerged designs.
- Do not claim store marketplace publication from metadata alone.
- Do not treat `hidden: true` as a security boundary — it only affects catalogue visibility.

Full CLI surface: [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/). Data path details: [Data and AFS](../data-and-afs/).

---

## Blocklets

URL: https://www.arcblock.io/en/docs/blocklets/overview/

A **Blocklet** is ARC's unit for packaging and running an application or service. One directory holds the package (`blocklet.yaml` plus assets). A local or remote **instance** is a particular running realization of that package.

A Blocklet is **not** another name for AUP, Web Device, or an AFS provider:

| Layer | What it is | Board |
| --- | --- | --- |
| **Blocklet** | Package + instance unit for an application or service | This board |
| **AUP** | Semantic interface contract (pages, events, primitives) | [AUP](/en/docs/aup/) |
| **Web Device** | Web content, site components, themes, routing | [Web Device](/en/docs/web-device/) |
| **AFS** | Path-addressable data and provider operations | [AFS](/en/docs/afs/) |

A Blocklet may include AUP pages, Web Device routes, agents, settings, and AFS mounts. Those are **surfaces and capabilities inside the package**, not synonyms for the package itself.

## Read this board by task

| If you need to | Start here |
| --- | --- |
| Distinguish package from instance | [Package and instance](../package-and-instance/) |
| Scaffold and accept without remote deploy | [Create and run locally](../create-run-locally/) |
| Validate, build, and inspect artifacts | [Check, build, and inspect](../check-build-inspect/) |
| Declare manifest fields and capabilities | [Manifest and capabilities](../manifest-and-capabilities/) |
| Use AFS paths from a Blocklet | [Data and AFS](../data-and-afs/) |
| Choose AUP vs Web Device surfaces | [Web surfaces](../web-surfaces/) |
| Separate local acceptance from release | [Lifecycle](../lifecycle/) · [Publish and deploy](../publish-deploy/) |
| Study real packages in the ARC tree | [Reference applications](../reference-applications/) |

## Local first

Ordinary development and acceptance start with a **directly selected local directory** in an isolated ARC environment:

```bash
arc blocklet create ./my-app --recipe minimal-app --name my-app
arc dsl validate ./my-app
arc blocklet check ./my-app --profile minimal-app
arc service start --blocklet ./my-app --port 4939
# open http://my-app.localhost:4939/
```

That chain proves the source, the declared contract, and the observable surface the local runtime accepts. It does **not** require a DID Space, a remote server, Cloudflare Pages, or `arc deploy --server`.

Verified with `arc` `2.0.0-beta.28` in an isolated temp directory: `minimal-app` scaffold, DSL validation, profile check, and `arc service start --blocklet` all returned success; `GET /` with `Host: demo-min.localhost` returned HTTP 200.

## What this board does not promise

- Feature parity with every historical ArcBlock product named "Blocklet Server", "Media Kit", or similar
- That remote DID Space publish (`--server`) or stateful `/instance` workflows are fully E2E-proven on every machine
- That a green build replaces browser acceptance of the rendered surface

Where a path is incomplete or environment-dependent, the page marks it **experimental** or **unverified** and points at the local path that *is* proven.

## Command map (quick)

| Goal | Command |
| --- | --- |
| Scaffold | `arc blocklet create [dir] --recipe <name> --name <id>` (`init` is an alias) |
| List recipes | `arc blocklet recipe list` / `explain <name>` |
| Validate DSL | `arc dsl validate <dir>` |
| Check package contract | `arc blocklet check [dir] --profile <profile>` |
| Convention scan | `arc blocklet dev [dir]` |
| Build `dist/` | `arc blocklet build [dir]` |
| Inspect package | `arc blocklet inspect <dir>` |
| Local serve (preferred) | `arc blocklet run <dir>` or `arc service start --blocklet <dir>` |
| CLI man page | [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/) |

---

## Package and instance

URL: https://www.arcblock.io/en/docs/blocklets/package-and-instance/

ARC treats a **package** and an **instance** as different objects. Confusing them blurs source ownership, configuration, data, and release.

## Package versus instance

| | **Package** | **Instance** |
| --- | --- | --- |
| What it is | Versioned, reusable application artifact | One configured run or deployment of a package |
| Typical identity | `id` / `did` / `version` in `blocklet.yaml` | Runtime binding: port, host, owner, data mounts |
| Mutability | Source + published tree at a version | Config and data can change while the package version stays fixed |
| Local evidence | Directory with `blocklet.yaml` (or convention entry), `arc blocklet inspect` | `arc blocklet run` / `arc service start --blocklet` serving URLs |
| Build product | `dist/` + `.afs/manifest.json` + `blocklet.dist.json` | Not produced by `build` alone — requires a serve or deploy step |
| Analogy | npm package / container image | Running container / deployed service |

Code-backed anchors (`ArcBlock/arc`, package types and CLI):

- Package shape: `blocklet.yaml` parsed as `BlockletManifest` (`packages/core/src/blocklet/types.ts`)
- Scaffold writes package identity (`specVersion`, `id`, `name`, `did`, `version`) via `arc blocklet create`
- Local instance serve: `arc blocklet run <path>` registers the parent directory with the daemon and prints access URLs
- Build stamps instance **requirements** into the flat manifest (e.g. `instance.required: false` for a `basic` package; `minimal-app` build reports `instance: requires /instance DID Space`)

## Diagram

| Stage | Object | Typical command |
| --- | --- | --- |
| Author source | Package source tree | editor + `create` |
| Validate / package | Package contract + `dist/` | `check`, `build`, `inspect` |
| Local run | Local instance | `blocklet run` / `service start --blocklet` |
| Remote path | Remote instance | `deploy --server` / Pages — **separate, often experimental** |

![Flow from source through package check and build to a local or remote instance](https://raw.githubusercontent.com/ArcBlock/loop-agent-assets/main/arcblock-site/docs-blocklets-20260810/package-instance.svg)

*A package is the versioned application unit. An instance is a particular run or deployment of that package.*

## What belongs where

| Concern | Lives on the package | Lives on the instance |
| --- | --- | --- |
| `blocklet.yaml` identity, `scope`, mounts, sites, replicated declarations | Yes | No (read as declared by the package) |
| Built file tree under `dist/` | Yes (artifact) | Consumed when deployed |
| Daemon port, extra blocklet dirs | No | Yes |
| `/instance` DID Space data (when required) | Seed only (`seed/`) | Runtime data ownership |
| Domain binding for a public deployment | Declared candidates (`sites.domains`) | Actual binding for this deployment |

## Manifest fields that name the split

From the current parser (`BlockletManifest`):

| Field | Package meaning | Instance implication |
| --- | --- | --- |
| `id`, `did`, `version`, `specVersion` | Package identity | Stable package coordinates for a run |
| `scope` | Namespace visibility model (`app` default, also `user` / `root` / `agent`) | Session AFS shape for the run |
| `instance.required` / `instance.mount` / `instance.seed` | Declares whether a real `/instance` DID Space is required | Runtime must fail closed if required and missing |
| `mounts` | Provider dependencies declared by the package | Mounted into the running AFS |
| `sites` / `surfaces` | Declared routing and exposure | Resolved by the host that serves the instance |
| `replicated` | Collection contracts in the package | Writes and copies at instance/user spaces |

Minimal package written by `arc blocklet create --recipe basic` (verified):

```yaml
specVersion: 2
id: demo-basic
name: demo-basic
did: did:blocklet:demo-basic
version: 0.1.0
description: ""
```

After `arc blocklet build`, the flat manifest for that package included:

```json
{
  "specVersion": 2,
  "id": "demo-basic",
  "instance": { "required": false, "mount": "/instance" },
  "scope": "app",
  "mounts": []
}
```

## Local instance without remote deploy

A local instance is enough for acceptance:

```bash
arc blocklet run ./demo-min
# or
arc service start --blocklet ./demo-min --port 4939
```

Verified (`2.0.0-beta.28`; seed-instance port override, today prefer a named instance):

```text
Serving blocklet "demo-min" on port 4941
  http://demo-min.localhost:4941/
  http://localhost:4941/?blocklet=demo-min  (Safari / universal)
```

`GET` with `Host: demo-min.localhost:4941` returned HTTP 200. No DID Space publish was required.

## Rules of reading

1. **Source edits change the package.** Rebuild and re-check when you change declared files.
2. **Runtime state belongs to the instance environment** (daemon config, ports, DID Space data). Do not treat a successful local serve as proof that a remote instance is healthy.
3. **`instance: requires /instance DID Space` on a build** means stateful features of that package need a real instance space. Local HTTP 200 on a shell page does not prove those writes work — see [Publish and deploy](../publish-deploy/) and [Data and AFS](../data-and-afs/).

Next: [Create and run locally](../create-run-locally/).

---

## Publish and deploy

URL: https://www.arcblock.io/en/docs/blocklets/publish-deploy/

Publication and deployment are **not** substitutes for a local direct run. Use local run for ordinary acceptance. Enter a publish path only when the task is release, distribution, or remote hosting.

## Path matrix (strict)

| Path | Command | Target | Auth / secrets | Status on this board |
| --- | --- | --- | --- | --- |
| **Local serve** | `arc blocklet run <dir>` · `arc service start --blocklet <dir>` | Local daemon | None beyond local process | **Verified** (`2.0.0-beta.28`) |
| **Local daemon registration** | `arc deploy <path>` (no publish flags) | Running local daemon extra dirs | Local | Prefer serve commands; registration can be environment-sensitive |
| **Local DID Space publish** | `arc deploy <path> --publish` | Developer local DID Space `/blocklets/<id>/` | Local snapshot secret (see below) | **Partial** — command surface real; secret required in isolated home |
| **Remote DID Space publish** | `arc deploy <path> --server <url> [--token]` | Remote DID Space via RPC | Browser/passkey, vault, or `--token` **always** | **Experimental / unverified** on this board (not E2E'd here) |
| **Pages one-shot** | `arc blocklet deploy [dir]` | Local stage + Cloudflare Pages option | CF credentials when `--cloud=cf` | Platform path — verify in your environment |
| **Instance subcommands** | `arc blocklet instance …` | Deployed Pages instances | Platform | Treat as **advanced**; confirm against live CLI help |
| **Fleet** | `arc blocklet fleet …` | Multi-blocklet aggregate | Platform | Advanced / monorepo ops |

## Prefer local acceptance first

```bash
arc dsl validate ./my-app
arc blocklet check ./my-app --profile <profile>
arc blocklet run ./my-app
# browser accept
```

Only then choose a publish path.

## Local DID Space publish (`--publish`)

Intended semantics (from CLI help and ARC deploy module):

- Writes to the **local** developer DID Space (no network, no browser auth).
- `arc deploy show` / `arc deploy list --published` read that **local** registry path.
- Remote `--server` publishes **do not** populate the local show/list registry.

Example shape (from ARC's third-party workflow guide; re-verify on your machine):

```bash
arc deploy ./my-app --publish
arc deploy list --published
arc deploy show did:blocklet:my-app
```

### Secret prerequisite (verified failure)

On `2.0.0-beta.28` with a clean isolated instance home (`ARC_HOME` is retired; isolate with a named instance and `--home`), publish failed without a snapshot secret:

```text
Error: Local publish failed: Snapshot V2 requires a snapshot token secret:
set AFS_DID_SPACE_SNAPSHOT_SECRET (32-byte hex).
AFS_DID_SPACE_SCOPE_SECRET also satisfies it, but that variable additionally
derives the storage directory name for each DID …
Prefer the dedicated variable.
```

Document this as an **environment requirement** for local publish, not as "publish is unimplemented". Configure secrets only in environments you control; do not commit them.

## Remote DID Space publish (`--server`)

```bash
arc deploy ./my-app --server https://example-did-space.example
# always requires auth: browser flow, cached credential, or --token
# --no-browser requires --token
```

**This board does not claim E2E success** for remote publish. Mark any remote workflow **experimental/unverified** until your team records a successful run against a non-shared target (auth, upload, and independent serve from the remote copy).

Even loopback URLs still require a real credential — not an auth bypass.

## Cloudflare / Pages-oriented commands

```bash
arc blocklet build ./my-app
arc blocklet deploy ./my-app --project <project-name>
# options include --cloud cf|none, --domain, --verify, …
```

`build` prints a deploy hint after packaging. Pages deploy is a **different product surface** from DID Space publish. Verify credentials, project naming, and live routes in your own environment before treating it as a documented default for third-party authors.

## Instance and fleet (advanced)

```bash
arc blocklet instance --help
arc blocklet fleet --help
```

Use these when you already understand package vs instance and have a platform target. Do not require them for "I scaffolded a Blocklet on my laptop."

Stateful `/instance` interactions (settings writes, replicated posts, agent tools that mutate instance trees) need a **real instance DID Space**. Local shell HTTP 200 without that binding does not prove those paths. Treat deep `/instance` E2E as **unverified** unless you have run it.

## Honesty checklist before you write "deployed"

- [ ] Local `check` + browser accept recorded?
- [ ] Which publish target (local space / remote server / Pages)?
- [ ] Auth and secrets path named without embedding secrets?
- [ ] Remote or `/instance` claims labeled if not E2E-proven?
- [ ] Reader still has a local-only path that does not require deploy?

## Related

- [Create and run locally](../create-run-locally/)
- [Test and diagnose](../test-diagnose/)
- [arc deploy CLI](/en/docs/arc-cli/command-reference-deploy/) (if present on the arc-cli board)
- [arc blocklet CLI](/en/docs/arc-cli/command-reference-blocklet/)

---

## Reference

URL: https://www.arcblock.io/en/docs/blocklets/reference/

Stable index for the Blocklets board. Detail pages own the prose; this page is the lookup table.

## Commands

| Command | Purpose | Detail page |
| --- | --- | --- |
| `arc blocklet create [dir]` | Scaffold package (`init` alias) | [Create and run locally](../create-run-locally/) |
| `arc blocklet recipe list` / `explain` | Discover scaffolds | [Get started](../getting-started/) |
| `arc blocklet check [dir]` | Profile contract (`validate` alias) | [Check, build, and inspect](../check-build-inspect/) |
| `arc blocklet build [dir]` | Write `dist/` + manifests | [Check, build, and inspect](../check-build-inspect/) |
| `arc blocklet inspect <dir>` | Manifest + file list | [Check, build, and inspect](../check-build-inspect/) |
| `arc blocklet list [dir]` | Discover packages under a tree | [Check, build, and inspect](../check-build-inspect/) |
| `arc blocklet dev [dir]` | Convention scan (not a server) | [Check, build, and inspect](../check-build-inspect/) |
| `arc blocklet run <path>` | Serve one package on the daemon | [Create and run locally](../create-run-locally/) |
| `arc service start --blocklet <path>` | Cold-start daemon with one package | [Create and run locally](../create-run-locally/) |
| `arc dsl validate` / `lint` / `format` | DSL gates | [Check, build, and inspect](../check-build-inspect/) |
| `arc deploy …` | Register / publish paths | [Publish and deploy](../publish-deploy/) |
| `arc blocklet deploy` / `instance` / `fleet` | Pages-oriented advanced paths | [Publish and deploy](../publish-deploy/) |

Full flag lists: [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/).

## Recipes and check profiles

| Recipe | Check profile (when applicable) |
| --- | --- |
| `basic`, `blank` | `basic` |
| `minimal-app` | `minimal-app` |
| `agent-workspace` | `agent-workspace` |
| `support-community` | `support-community` |
| `blog`, `agent` | start from recipe explain + `basic` / manual validation |

## Manifest field groups

| Group | Fields (summary) | Page |
| --- | --- | --- |
| Identity | `specVersion`, `id`, `name`, `did`, `version`, `description` | [Manifest](../manifest-and-capabilities/) |
| Metadata | `logo`, `keywords`, `tags`, `author`, `license`, links, `hidden` | [Manifest](../manifest-and-capabilities/) |
| Runtime | `scope`, `mounts`, `system`, `sites`, `surfaces`, `instance`, `cron`, `io` | [Manifest](../manifest-and-capabilities/) |
| Data contracts | `replicated`, `networkRead`, `redistributable`, `index` | [Data and AFS](../data-and-afs/) |

## Package vs instance

| Object | One-line | Page |
| --- | --- | --- |
| Package | Versioned application artifact (`blocklet.yaml` + assets / `dist/`) | [Package and instance](../package-and-instance/) |
| Instance | Particular run or deployment with config and data binding | [Package and instance](../package-and-instance/) |

## Lifecycle honesty labels

| Label | Meaning on this board |
| --- | --- |
| **Verified** | Exercised with `arc` `2.0.0-beta.28` in an isolated local environment for the stated command |
| **Partial** | Command exists; environment prerequisites or incomplete success recorded |
| **Experimental / unverified** | Not E2E-proven here — do not document as default developer path |

## Adjacent boards

| Board | Use for |
| --- | --- |
| [AFS](/en/docs/afs/) | Paths, ops, providers |
| [AUP](/en/docs/aup/) | Interface semantics, primitives |
| [Web Device](/en/docs/web-device/) | Sites, components, themes |
| [arc-cli](/en/docs/arc-cli/) | Full CLI man pages |
| Architecture (when present) | System map and product lineage tables |

## Evidence baseline

- CLI: `arc` `2.0.0-beta.28` (`0ec1be4`, 2026-08-07 build stamp on service banner)
- Isolated temp exercises: `basic` + `minimal-app` create/check/build/inspect/run/service start
- Parser/types: `BlockletManifest` in ARC `packages/core/src/blocklet/types.ts`
- Workflow archaeology cross-check: ARC `docs/guides/third-party-blocklet-workflow.md` (history → verified against current CLI where noted)

---

## Reference applications

URL: https://www.arcblock.io/en/docs/blocklets/reference-applications/

Reference applications connect a package, data layer, and surface in one real tree. They are **bounded examples**. Copy structure when it matches your need; do not copy product history or every dependency.

Location (read-only ARC monorepo): `blocklets/<name>/` under `ArcBlock/arc`.

## Quick map

| Package | Demonstrates | Not a proof of |
| --- | --- | --- |
| **hello-html** | Pattern S static web: `index.html` (+ logo) can be served as a convention blocklet **without** `blocklet.yaml` | Production packaging norms for third parties |
| **hello-declarative** | Minimal declarative AUP: `.aup/` pages/tests/man, no hand-written `blocklet.yaml` in source (build may synthesize dist metadata) | Full app product surface |
| **hello-terminal** | Terminal/text convention entry (companion to hello-html) | GUI completeness |
| **minimal-app** (via `arc blocklet create --recipe`) | Scaffolded web + AUP + agent + settings | That every app needs an agent |
| **discuss-kit** | Replicated posts/comments collections, URL bindings, cron, instance index | Full legacy Discuss Kit / forum / wiki / messaging product |
| **did-space** | `scope: user`, dual web+AUP routes, explorer path bindings | That all storage UIs use this shape |
| **arcblock** (this site) | Large content + Web Device site as a Blocklet | A starter template for small apps |

## How to use an example

1. Read its `README.md` and `blocklet.yaml` (when present).
2. Note `scope`, `sites`, `replicated`, and route files.
3. Run **only** if you have a local ARC checkout and understand side effects — prefer scaffolding your own package with `arc blocklet create` for day-to-day learning.
4. Extract **one** concern (bindings, seed, components) rather than forking the whole tree.

## hello-html

- **What:** Static `index.html` as a complete Pattern S sample.
- **Entry:** `/`
- **Teaching point:** Convention-based discovery without a manifest file.
- **For new third-party work:** Still prefer `arc blocklet create` so identity and tooling stay uniform.

## hello-declarative

- **What:** Pure `.aup/` data (pages, man, structure/flow tests).
- **Teaching point:** Declarative AUP without custom JS.
- **Tests:** Structure and navigation fixtures under `.aup/tests/`.

## discuss-kit

See [Discuss Kit lineage](../discuss-kit-lineage/) for the continuity statement and hard limits.

Demonstrates today (from its manifest and README):

- `scope: app` with `replicated` posts/comments/anon
- `sites.bindings` for `/posts` and `/posts/{slug}`
- Declarative `cron` posting into the same content tree
- `networkRead` and `index` domains for guest-readable content and search

## did-space

- **What:** Personal storage-oriented package (`scope: user`).
- **Surfaces:** Marketing web route at `/` and explorer AUP under `/explorer/{tail*}` mapped onto AFS paths.
- **Teaching point:** Coexistence of Web Device and AUP routes in one package without forcing one model on every URL.

## Scaffold recipes vs monorepo samples

| Need | Prefer |
| --- | --- |
| Greenfield third-party package | `arc blocklet create --recipe …` |
| Study edge cases / platform features | Read monorepo `blocklets/*` (no edit required) |
| Site/content product | Web Device board + this site's package layout |

## Continuity note

A historical product name on a directory is **lineage**, not a warranty. When in doubt, read the current manifest and tests, not marketing memory.

---

## Test and diagnose

URL: https://www.arcblock.io/en/docs/blocklets/test-diagnose/

When something fails, establish **four independent facts**: selected source, declared contract, local runtime, and visible/callable surface. One green step never implies the others.

## Quick triage

| Symptom | First commands | Likely layer |
| --- | --- | --- |
| Scaffold missing files | Re-run `create`; `find` tree | Package source |
| "Failed DSL validation" | `arc dsl validate <dir>` | AUP/DSL sources |
| `format_changed` on lint | `arc dsl format --write <dir>` | Formatting only |
| Profile check fails | `arc blocklet check --profile <recipe>` | Missing recipe assets |
| Port already in use | Named instance (auto port) or `--port`. Do not `stop` a seed daemon you did not start | Local daemon |
| No blocklet found at path | Ensure `blocklet.yaml`, `.aup/`, or convention entry | Discovery |
| HTTP not 200 / blank host | Use printed `Host` / `?blocklet=` URL | Routing |
| Build ok, page wrong | Browser accept + source path check | Surface, not package zip |
| Stateful write fails | Confirm `/instance` binding; not seed-only | Instance data |
| Remote publish fails | Auth, secrets, network — see publish page | Release path |

## Diagnostic recipes

### 1. Package identity

```bash
arc blocklet inspect ./my-app
arc blocklet list .
cat ./my-app/blocklet.yaml
```

Confirm `id`, `did`, `version`, and that you are looking at the directory you think you are.

### 2. Contract

```bash
arc dsl validate ./my-app
arc blocklet check ./my-app --profile minimal-app   # or basic
arc blocklet dev ./my-app
```

`dev` reports detected content type and convention mounts. It does not serve traffic.

### 3. Artifact

```bash
arc blocklet build ./my-app
# read the "instance:" line and file count
ls ./my-app/dist/.afs/manifest.json ./my-app/dist/blocklet.dist.json
```

### 4. Local surface

```bash
export ARC_INSTANCES_DIR=/tmp/arc-instances-demo
arc service start --instance demo --home /tmp/arc-home-demo --blocklet ./my-app
arc service url --instance demo --print url
# probe the printed host/port; do not assume 4900
```

Then open the same URL in a real browser. Check console errors if the shell loads but content does not.

### 5. Service status

```bash
arc service status --instance demo
arc service stop --instance demo    # only if this is your temporary named instance
```

## Failure modes seen on `2.0.0-beta.28`

| Observation | Evidence | Documentation stance |
| --- | --- | --- |
| `arc blocklet run` errors with port in use | Seed port 4900 occupied | Named instance (auto port) or explicit `--port`. `ARC_SERVICE_PORT` only affects the seed instance |
| `arc dsl lint` fails on fresh `minimal-app` with `format_changed` | Scaffold emits unformatted DSL | Document `dsl format --write`; do not treat as broken recipe alone |
| `arc deploy <path> --publish` without snapshot secret | Error: Snapshot V2 requires `AFS_DID_SPACE_SNAPSHOT_SECRET` (or scope secret) | Document as local-publish prerequisite — not a Blocklet source bug |
| `arc deploy <path>` daemon register returned `missing 'dir'` in one isolated trial | CLI posts parent dir to `/api/blocklets/dirs/add` | Prefer `blocklet run` / `service start --blocklet` for local accept; treat bare `deploy` register as environment-sensitive |

## What not to conclude

| Evidence | Invalid conclusion |
| --- | --- |
| `check` passed | Users saw the correct page |
| `build` passed | Remote deploy works |
| Local HTTP 200 | `/instance` writes and auth flows work |
| Historical product name in a path | Feature parity with that product |

## Related boards

- CLI man page: [arc blocklet](/en/docs/arc-cli/command-reference-blocklet/)
- AFS inspection: [Local inspection](/en/docs/afs/local-inspection/)
- Web Device diagnose patterns: Web Device board publish/diagnose pages

---

## blocklets/visuals

URL: https://www.arcblock.io/en/docs/blocklets/visuals/

---

## Web surfaces

URL: https://www.arcblock.io/en/docs/blocklets/web-surfaces/

A Blocklet can expose a Web-facing surface. The surface still has its own contract. Choose the layer that matches the work, then compose it inside the package.

## AUP vs Web Device

| | **AUP** | **Web Device** |
| --- | --- | --- |
| Question it answers | What is the semantic UI (pages, events, primitives)? | How is a Web site/content tree rendered? |
| Typical package paths | `.aup/app.aup`, `.aup/pages/`, `.aup/man/` | `pages/**/layout.aup`, `.web/`, SEO atoms, `.route/web` |
| Authoring board | [AUP](/en/docs/aup/) | [Web Device](/en/docs/web-device/) |
| First exercise | [First AUP app](/en/docs/aup/first-app/) | [Build a first site](/en/docs/web-device/first-site/) |
| Checker focus | AUP pages / structure | Site lint, components, content space |

They can coexist in one package (e.g. `minimal-app` recipe: public web page + AUP app + agent). Coexistence does **not** make the two boards the same documentation.

## How the Blocklet owns the surface

| Package concern | Example |
| --- | --- |
| Identity / DID | `blocklet.yaml` |
| Which handler serves `/` | `.route/web` vs `.route/app` vs AUP default |
| Domains and pretty URL bindings | `sites` in `blocklet.yaml` |
| Instance data behind a page | AFS paths + bindings (see [Data and AFS](../data-and-afs/)) |

Without a Web route declaration, a direct Blocklet URL may look for AUP entry (`.aup/app.aup` / `app.json`) rather than a static Web Device entry. The Web Device first-site guide spells out the minimal `.route/web` + `.web/site.yaml` + `pages/index/layout.aup` set.

## Recipe and reference patterns

| Starting point | Surface emphasis |
| --- | --- |
| `arc blocklet create --recipe basic` | Manifest only — add surfaces yourself |
| `--recipe minimal-app` | One web page, AUP app, agent, settings |
| `--recipe blog` / `agent` | AUP-oriented scaffolds |
| Web Device first-site guide | Hand-built minimal static site in a `basic` package |
| `hello-html` (ARC tree) | Convention static HTML without `blocklet.yaml` (teaching sample) |
| `hello-declarative` (ARC tree) | Minimal `.aup/` JSON pages (teaching sample) |
| `did-space` (ARC tree) | Dual surface: marketing `.route/web` + explorer AUP under `/explorer` |

## Do not copy primitive catalogs here

| Need | Go to |
| --- | --- |
| AUP primitives / events / DSL | [AUP board](/en/docs/aup/) |
| Web components, themes, markdown embeds | [Web Device board](/en/docs/web-device/) |
| Capability matrix for AUP/Web Device | AUP/Web Device maintenance matrices (not this board) |

This page only records **composition points**: routes, recipes, and package layout. When a primitive, component, or directive changes, update the owning board — not a fork of the catalog under Blocklets.

## Local acceptance for surfaces

```bash
arc dsl validate .
arc blocklet check . --profile <matching-profile>
arc blocklet run .
# open printed URL — wide + narrow viewport
```

A successful package build is not a substitute for opening the rendered page. See [Check, build, and inspect](../check-build-inspect/) and [Test and diagnose](../test-diagnose/).

---

## Create Blocklet

URL: https://www.arcblock.io/en/docs/createblocklet/

---

## Add new template

URL: https://www.arcblock.io/en/docs/createblocklet/add-new-template/

> [!NOTE]
> this page is a draft and need to be updated

- naming convention
- template attributes
- display on template gallery

---

## Available Scripts

URL: https://www.arcblock.io/en/docs/createblocklet/available-npm-scripts/

The project created by the `create-blocklet` tool will have the corresponding `npm script` configured in `package.json` for developers to use.

The `npm script` can theoretically be executed using the `npm`, `yarn`, and `pnpm` commands.

## yarn dev

Run the blocklet project in development mode (this command requires the @blocklet/ cli tool installed in the development environment). After running the command, wait for a moment, the terminal will print a URL. You can view the current project through this URL.

## yarn bundle

Package the project into an application package that can be deployed to Blocklet Server. The packaged product is compressed and the file name contains the hash value. At this point, your Blocklet project is ready to deploy to Blocklet Server.

## yarn deploy

This command allows you to easily deploy your packaged Blocklet application to your local Blocklet Server (make sure your Blocklet Server is currently running).

## yarn upload

Upload a project to the Blocklet Store. As long as you are a Blocklet Store developer user, you can use this command to upload your project to the Blocklet Store to which you have access.

## yarn lint

Use Eslint to check your code.

## yarn lint:fix

Use Eslint to quickly fix your code.

---

## Folder Structure

URL: https://www.arcblock.io/en/docs/createblocklet/blocklet-folder-structure/

After creation, your project should look like this:

```javascript
my-blocklet/
  README.md
  blocklet.yml
  blocklet.md
  logo.png
  package.json

  .blocklet
  .eslintrc.js
  .prettierrc
  .npmrc
  .editorconfig
  .gitignore
  .env
  .github
  .husky
  .vscode

  src/
  dist/
  screenshots/
```

### README.md

A description document of the project, briefly introducing some basic information about the project.

### blocklet.yml

The configuration file for the Blocklet application, including the project name, version, author, description of the project, etc. It also contains configuration such as Auth Service and children components.

### blocklet.md

A file dedicated to describing the Blocklet application that will be used as the description file for the Blocklet application after uploading the Blocklet to the Blocklet Store.

If this file does not exist, it will be downgraded to use the README.md file as the description file for the Blocklet application.

### logo.png

The Blocklet icon file that will appear in the DID Wallet when the Blocklet application interacts with the DID Wallet.

### package.json

Contains information such as the Blocklet application's dependencies.

### .blocklet

The product folder of a packaged Blocklet application contains code packages that can be run directly in Blocklet Server.

This folder is automatically generated after the `yarn bundle` command is executed.

### .eslintrc.js

A file for configuring ESLint rules.

Different templates come with different rules.

### .prettierrc

The file used to configure Prettier rules.

### .npmrc

The file used to configure npm.

### .editorconfig

The file used to configure EditorConfig rules.

### .gitignore

Used to configure the files that git ignores.

### .env

The file containing the environment variables.

### .github

The file used to configure GitHub.

### .husky

The file used to configure Husky.

### .vscode

The file used to configure the VSCode.

### src/

The source file directory of the project, the structure in src is different in different templates, please refer to the `README.md` file in the production template for details

### screenshots/

The image folder of the Blocklet application is used to display in the Blocklet Store details page after uploading to the Blocklet Store.

You also need to configure the screenshots field in blocklet.yml to specify the path to the blocklet application's image folder.

---

## Composition folder structure

URL: https://www.arcblock.io/en/docs/createblocklet/composition-folder-structure/

After creation, your project should look like this:

```
composition-blocklet
    README.md
    package.json
    eslintrc.js
    .prettierrc
    .gitignore
    .npmrc
    .editorconfig
    .github
    .husky
    LICENSE
    Makefile
    lerna.json
    version
    blocklets/
    scripts/
        batch-modify-deps-version.mjs
        bump-version.mjs
```

### README.md

The project's description document, briefly introducing some basic information of the project.

### package.json

Contains information such as the Blocklet application's dependencies.

### .eslintrc.js

The file used to configure the `ESLint` rules.

### .prettierrc

The file used to configure the `Prettier` rules.

### .npmrc

The file used to configure `npm`.

### .editorconfig

The file used to configure the EditorConfig rules.

### .gitignore

Used to configure files that are ignored by `git`.

### .github

The file used to configure `GitHub`.

### .husky

The file used to configure `Husky`.

### blocklets

The `Blocklet` application folder, containing the `Blocklet` selected in the `create-blocklet` phase

### scripts

Scripts directory, application versioning and such scripts.

For more information about `combination applications`, please refer to [here](https://github.com/blocklet/create-blocklet/tree/main/packages/create-app/templates/monorepo)

---

## Create blocklet composition

URL: https://www.arcblock.io/en/docs/createblocklet/create-composition-blocklet/

## What is a Combined Application

Thanks to the capabilities provided by the [Blocklet Development Platform](https://arcblock.io/docs/blocklet-developer), we can combine multiple `Blocklets` together, each `Blocklet` being both an application and a component. Each `Blocklet` can be combined by other `Blocklets`, and can also combine other `Blocklets`.

In a combined `Blocklet`, each component is a separate service, and they make you feel like you are using a complete application through a unified configuration and UI.

Our `create-blocklet` also provides the ability to quickly create combinatorial `Blocklet` seed projects.

## Creating Monorepo

`create-blocklet` enables the ability to develop combinatorial `Blocklets` by putting multiple `Blocklet` projects together for management by means of [monorepo](https://en.wikipedia.org/wiki/Monorepo).

After executing the `create-blocklet` command in the terminal and entering the project name to enter the template selection phase, we choose multiple templates, here we choose `react-dapp` `vue-static` `express` (with the ability of the `blocklet` platform, we can combine different front-end frameworks together).
![create](https://media.arcblock.io/docs/create-composition-blocklet/image/create.w1600.webp)

Select a project as the main application, here we choose `react` as the main application
![select](https://media.arcblock.io/docs/create-composition-blocklet/image/select.w1600.webp)

Enter the email, author, and other information and press enter to confirm. After waiting for the file to be created, we get a `Monorepo` type project directory containing the three `Blocklets` I chose in the previous step.
![init](https://media.arcblock.io/docs/create-composition-blocklet/image/init.w1600.webp)
![catalogue](https://media.arcblock.io/docs/create-composition-blocklet/image/catalogue.w1600.webp)

## Start the main application

Following the prompts in the terminal, we go to the root of the project and execute `make init` to install the dependencies needed for the project.
![make-init](https://media.arcblock.io/docs/create-composition-blocklet/image/make-init.w1600.webp)

Go to the main application directory in `blocklets` and execute the `npm run dev` command to start the main application in development mode

![start-main](https://media.arcblock.io/docs/create-composition-blocklet/image/start-main.w1600.webp)

## Start the child application

When the main application is successfully launched, execute the `npm run dev:child` command in the other blocklets directory in turn to mount the other blocklets to the main application.

In the administration page of your local blocklet-server instance, we can visualize the mounting relationship between blocklets: react-static as the main app, vue-static, express-api as children mounted on the main app
![view-component](https://media.arcblock.io/docs/create-composition-blocklet/image/view-component.w1600.webp)

## Update the navigation of the portfolio application

> The application's navigation will be displayed in the page

Configure `navigation` in the application's `blocklet.yml`

```javascript
navigation:
  - title:
      en: Vue page
      zh: Vue 页面
    link: /compostive-demo-vue-static
```

Remember the [unified configuration and UI] we mentioned at the beginning of the article (what is a combined app)? We do this by using a unified UI component in each application's page for the configuration in `navigation`, which we show in a `react` type application using `@blocklet/ui-react`.

First install `@blocklet/ui-react` in the main application, and use `@blocklet/ui-react/lib/Header`, `@blocklet/ui-react/lib/Foote`r to transform the home page

```javascript
// compostive-demo/blocklets/react-static/src/components/layout.jsx
import PropTypes from 'prop-types';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

function Layout({ children }) {
  return (
    <div>
      <Header />
      {children}
      <Footer />
    </div>
  );
}
Layout.propTypes = {
  children: PropTypes.any.isRequired,
};

export default Layout;
```

```javascript
// compostive-demo/blocklets/react-static/src/pages/home.jsx
import { Link } from 'react-router-dom';
import Layout from '../components/layout';

import logo from '../logo.svg';

function Home() {
  return (
    <Layout>
      <img src={logo} className="app-logo" alt="logo" />
      <pre style={{ textAlign: 'left' }}>
        <code>window.blocklet = {JSON.stringify(window.blocklet, null, 2)}</code>
      </pre>
      <Link className="app-link" to="/about">
        About
      </Link>
      <a className="app-link" href="https://arcblock.io/docs/blocklet-developer/" target="_blank" rel="noopener noreferrer">
        Learn Blocklet
      </a>
    </Layout>
  );
}

export default Home;
```

After the modification, you will see the following page on the home page: the `navigation` we just configured is displayed in the navigation bar of the coming page
![navigation](https://media.arcblock.io/docs/create-composition-blocklet/image/navigation.w1600.webp)
At this point, you can access our `dev` `vue` sub-application by clicking `vue page`
![vue-child](https://media.arcblock.io/docs/create-composition-blocklet/image/vue-child.w1600.webp)

## Deploying a blocklet application

When development is complete, you can deploy the application to the `blocklet server` using the `blocklet deploy` command;

The `monorepo` project created with the `create-blocklet` tool has `npm script` automatically configured for each `blocklet`, you just need to run `npm run deploy` to package your blocklet and deploy it to the local running `blocklet- server` instance

First deploy the main application : go to the directory where the main application is located, then run `npm run deploy`

![deploy-main](https://media.arcblock.io/docs/create-composition-blocklet/image/deploy-main.w1600.webp)

Then deploy the children in turn: go to the directory where the other children are, and then run `npm run deploy:child`

![deploy-view](https://media.arcblock.io/docs/create-composition-blocklet/image/deploy-view.w1600.webp)

For more information about the `blocklet deploy` command, please refer to [here](/en/docs/blocklet-developer/deploy-blocklet-directly-to-the-server/)

---

## Create first blocklet

URL: https://www.arcblock.io/en/docs/createblocklet/create-first-blocklet/

Create Blocklet is an officially supported Blocklet creation tool that allows you to quickly create Blocklets and automatically add them to your project.

## Preparation

You must first have [node](https://nodejs.org/en/) and make sure the node version is 16.0 or above. (It is recommended to use [nvm](https://github.com/creationix/nvm) to manage node versions under mac)

## Scaffolding

Creating projects with the official tools

```javascript
yarn create blocklet my-blocklet
# or npm create blocklet my-blocklet
# or pnpm create blocklet my-blocklet
```

Project creation via `@blocklet/cli` tool

```javascript
blocklet create my-blocklet
```

## Installing Dependencies

```javascript
yarn

yarn install v1.22.19
[1/4] 🔍  Resolving packages...
success Already up-to-date.
✨  Done in 0.71s.
```

## Launch Project

```javascript
yarn dev
```

Open the URL output from the console and you will see the currently launched project.

## Deployment Release

### Bundle

```javascript
yarn bundle
```

Build the application as a code package that can be deployed to the Blocklet Server, or as an application package that can be uploaded to the Blocklet Store. The build product is generated by default to `.blocklet`

### Deploy

The current deployment supports two forms:

1. directly through the deploy command
2. Deploy by uploading to the Blocklet Store

Before publishing to the Blocklet Store, local validation can be done by deploying to a local Blocklet Server

```javascript
yarn deploy
```

After running, you will see the application you just deployed in the list of cornerstone applications in your local Blocklet Server

### Upload

```javascript
yarn upload
```

You can use this command to upload this to Blocklet Store, check documentation at [here](/en/docs/blocklet-developer/blocklet-cli/)

### What's next

- [Publish to Blocklet Store](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/)
- [Create blocklet composition](/en/docs/createblocklet/create-composition-blocklet/)

---

## How to create a single blocklet?

URL: https://www.arcblock.io/en/docs/createblocklet/create-single-blocklet/

`create-blocklet` supports two creation modes, `create single application` and `combined application` of type `monorepo

## Creating a single application

The `create-blocklet` command allows you to enter the project name and enter the template selection stage, where you can enter keywords to search.

For more information about `blocklet` templates, please refer to [blocklet types](/en/docs/blocklet-developer/create-blocklet/)
![create-blocklet](https://media.arcblock.io/docs/create-single-blocklet/image/single-blocklet.w1600.webp)

Next we choose `[static] react` as an example
![select-blocklet](https://media.arcblock.io/docs/create-single-blocklet/image/select-blocklet.w1600.webp)
The program will automatically create the directory structure of the corresponding template and install the dependencies according to its prompts to enter the development mode of the project (provided that the [blocklet-server](/en/docs/blocklet-developer/install-blocklet-cli/) environment is installed locally). -server) environment).

```javascript
cd my-single-blocklet
npm install
blocklet dev
```

## Start the application

If your `blocklet dev` executes successfully, the terminal will output a `blocklet` application launch address, and you can see the currently launched `blocklet` by clicking on it and visiting it in your browser.

![start-blocklet](https://media.arcblock.io/docs/create-single-blocklet/image/start-blocklet.w1600.webp)

![browser](https://media.arcblock.io/docs/create-single-blocklet/image/browser.w1600.webp)

## Update and preview the application

At this point your `blocklet` is in development run mode, so you can debug the application in the browser while you develop. Next we modify the code in the project by adding the h2 title `Home Page` to `home.jsx`, which will automatically change the content on the page after saving

![preview](https://media.arcblock.io/docs/create-single-blocklet/image/preview.w1600.webp)

## Package and publish the application

When development is complete, your `blocklet` can be packaged using the `blocklet bundle` command provided in `@blocklet/cli`.

```javascript
  "scripts": {
    "dev": "blocklet dev",
    "eject": "vite eject",
    "serve": "vite preview",
    "lint": "eslint src --ext .mjs,.js,.jsx,.ts,.tsx",
    "lint:fix": "npm run lint -- --fix",
    "start": "vite --host",
    "clean": "rm -rf .blocklet",
    "bundle": "npm run clean && vite build && blocklet bundle --zip --create-release",
    "deploy": "npm run bundle && blocklet deploy .blocklet/bundle",
    "upload": "npm run bundle && blocklet upload .blocklet/release/blocklet.json",
    "prepare": "husky install"
  },
```

The project created with the `create-blocklet` tool is automatically configured with the `npm script`, you just need to run `npm run bundle` to package your `blocklet`

![preview](https://media.arcblock.io/docs/create-single-blocklet/image/bundle.w1600.webp)

Next you can upload your `Blocklet` to the `blocklet-store` with the `blocklet upload` command , [detailed documentation here](/en/docs/blocklet-developer/publish-your-blocklet-to-the-world/)

Click on the following links for more information about `@blocklet/cli` and `blocklet-store`

- [blocklet-store](https://store.blocklet.dev/pages/zh/)
- [@blocklet/cli](/en/docs/blocklet-developer/blocklet-cli/)

---

## Customize your blocklet

URL: https://www.arcblock.io/en/docs/createblocklet/customize-your-blocklet/

In the root directory of every `Blocklet` application there exists a `blocklet.yml` file, which is the configuration file for the `Blocklet` application, including the project name, version, author, description of the project and other configuration information.

Here's how to define your application by modifying `blocklet.yml`

## Configure the name  and description of the blocklet

```javascript
title: Example APP
description: Demo blocklet that shows how to configure Blocklet Meta
```

The `Blocklet` name and description are represented by `title` and `description`.

The `title` and `description` will be presented in the page and will be visible to the user.

## Configure the blocklet's logo

> [!WARNING]
> The logo must have the same aspect ratio and be no smaller than 256px * 256px

```javascript
logo: logo.png
```

## Configure blocklet.md file

`blocklet.md` is a file dedicated to describe the `Blocklet` application and will be used as the `Blocklet` application description file after uploading the `Blocklet` to the `blocklet-store`.

## Configure screenshots

`screenshots` is the image folder of the `Blocklet` application, which is used to display in the details page of the `blocklet-store` after uploading to the `blocklet-store`.

We need to configure the `screenshots` field in `blocklet.yml`, specifying the path to the `Blocklet` application's image folder.

```javascript
screenshots:
  - 0.png
  - 1.png
  - 2.png
```

A configured `Blocklet` displayed in the `blocklet-store` looks like

![example](https://media.arcblock.io/docs/customize-your-blocklet/image/example.w1600.webp)

For more configuration see [Blocklet Meta: Infomation](/en/docs/blocklet-developer/blockletyml/#infomation)

---

## FAQs

URL: https://www.arcblock.io/en/docs/createblocklet/frequently-asked-questions2/

## How the documentation is organized?

A high-level overview of how this documentation is organized will help you know where to look for certain things:

- [Quick Start](/en/docs/createblocklet/quick-start/) take you by the hand through a series of steps to create a website. Start here if you’re new to Blocklet.
- [Reference guides](/en/docs/createblocklet/blocklet-folder-structure/) contain technical reference for various aspects of Create Blocklet machinery. They describe how it works and how to use it but assume that you have a basic understanding of key concepts.
- [How-to guides](/en/docs/createblocklet/create-single-blocklet/) are recipes. They guide you through the steps involved in addressing key problems and use-cases.

## Error "not found global / buffer / process"

A solution is provided in vite-plugin-blocklet to solve the problem by passing the parameter `disableNodePolyfills: false`.

Full example:

```javascript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { createBlockletPlugin } from 'vite-plugin-blocklet';
import svgr from 'vite-plugin-svgr';

export default defineConfig(() => {

return {

plugins: [react(), createBlockletPlugin({ disableNodePolyfills: false }), svgr()],

};

}
);
```

## Why isn't GitHub Actions triggering?

If you are using GitHub Actions to implement Blocklet bundle and release workflow, make sure the branch in `.github/workflows/main.yml` matches the default branch of your repository, otherwise GitHub Actions may not be triggered.

---

## vite-plugin-wss-hmr

URL: https://www.arcblock.io/en/docs/createblocklet/funb1aIedrMLVd8q2u3HhuDM/

> [!NOTE]
> This page need to be updated

---

## How To Guides

URL: https://www.arcblock.io/en/docs/createblocklet/how-to-guides2/

- [How to create a single blocklet?](/en/docs/createblocklet/create-single-blocklet/)

- [Create blocklet composition](/en/docs/createblocklet/create-composition-blocklet/)

- [Customize your blocklet](/en/docs/createblocklet/customize-your-blocklet/)

- [Manage blocklet release](/en/docs/createblocklet/manage-blocklet-release/)

- [Add new template](/en/docs/createblocklet/add-new-template/)

- [Where to go from here?](/en/docs/createblocklet/where-to-go-from-here/)

---

## Install Blocklet CLI

URL: https://www.arcblock.io/en/docs/createblocklet/instal-blocklet-cli/

About why Blocklet Server is required and how to install and setup Blocklet Server please refer to [Blocklet Developer Guide](/en/docs/blocklet-developer/install-blocklet-cli/).

---

## Manage blocklet release

URL: https://www.arcblock.io/en/docs/createblocklet/manage-blocklet-release/

The project created by the `create-blocklet` tool is automatically configured with the corresponding versioning script

## Versioning in a single application project

Execute `make bump-version` in the root directory, the script will automatically calculate the next version number, or you can choose to enter the specified version number by typing enter.

![single](https://media.arcblock.io/docs/manage-blocklet-release/image/single-input.w1600.webp)

Follow the prompts in the terminal to adjust the CHANGELOG.md file, continue typing enter and end.

![single](https://media.arcblock.io/docs/manage-blocklet-release/image/single.w1600.webp)

This completes the update of the single application project version

## Versioning in a combined application project

Run `npm run bump-version` in the root directory, select a version update method, and type enter.
![single](https://media.arcblock.io/docs/manage-blocklet-release/image/composition-select.w1600.webp)

Follow the prompts in the terminal to adjust the CHANGELOG.md file, continue typing enter, and finish.

![single](https://media.arcblock.io/docs/manage-blocklet-release/image/composition.w1600.webp)

This completes the update of the composition application version

---

## Getting Started

URL: https://www.arcblock.io/en/docs/createblocklet/quick-start/

If you are an intermediate or advanced developer, and you already have a basic understanding of how blocklet works, you can start from [Create first blocklet](/en/docs/createblocklet/create-first-blocklet/).

If you are new to the [blocklet platform](https://developer.blocklet.io), you should following steps to get started:

- [Setup Node.js](/en/docs/createblocklet/setup-nodejs2/)

- [Setup DID Wallet](/en/docs/createblocklet/setup-did-wallet2/)

- [Install Blocklet CLI](/en/docs/createblocklet/instal-blocklet-cli/)

- [Create first blocklet](/en/docs/createblocklet/create-first-blocklet/)

---

## Reference Guides

URL: https://www.arcblock.io/en/docs/createblocklet/reference-guides2/

- [Folder Structure](/en/docs/createblocklet/blocklet-folder-structure/)

- [Composition folder structure](/en/docs/createblocklet/composition-folder-structure/)

- [Available Scripts](/en/docs/createblocklet/available-npm-scripts/)

- [Available Libraries](/en/docs/createblocklet/0KyjgZbfoJei6IL5v-4SeNW2/)

---

## Setup DID Wallet

URL: https://www.arcblock.io/en/docs/createblocklet/setup-did-wallet2/

About why DID Wallet is required and how to install and setup DID Wallet please refer to [Blocklet Developer Guide](/en/docs/blocklet-developer/setup-did-wallet/).

---

## Setup Node.js

URL: https://www.arcblock.io/en/docs/createblocklet/setup-nodejs2/

About why Node.js is required and how to install Node.js please refer to [Blocklet Developer Guide](/en/docs/blocklet-developer/setup-nodejs/)

---

## Welcome

URL: https://www.arcblock.io/en/docs/createblocklet/welcome2/

## Welcome to Create Blocklet, your Blocklet Project Assistant

Create Blocklet is a command line tool that makes it smooth for developers to start their blocklet projects. With Create Blocklet you can bootstrap a blocklet project that contains best practices from ArcBlock team within minutes. Start your blocklet today, for fun and profit!

<strong>Quick Start</strong>

Get your first blocklet pages project up and running within minutes

- [Setup Develop Environment](/en/docs/createblocklet/instal-blocklet-cli/)
- [Create your first blocklet](/en/docs/createblocklet/create-first-blocklet/)

<strong>How To Guides</strong>

Learn how to use Create Blocklet to bootstrap various kinds of blocklets.

- [Create single blocklet](/en/docs/createblocklet/create-single-blocklet/)
- [Create blocklet composition](/en/docs/createblocklet/create-composition-blocklet/)
- [Customize your blocklet](/en/docs/createblocklet/customize-your-blocklet/)
- [Manage blocklet release](/en/docs/createblocklet/manage-blocklet-release/)
- [Add new template](/en/docs/createblocklet/add-new-template/)

<strong>Reference Guides</strong>

Get detailed guide for building blocklets bootstrapped with Create Blocklet

- [Blocklet folder structure](/en/docs/createblocklet/blocklet-folder-structure/)
- [Composition folder structure](/en/docs/createblocklet/composition-folder-structure/)
- [Available scripts](/en/docs/createblocklet/available-npm-scripts/)

<strong>Other Resources</strong>

Other useful resources for blocklet developers

- [Blocklet Pages](https://pages.blocklet.io/)
- [Blocklet CLI](https://developer.blocklet.io/)
- [Blocklet SDK](https://developer.blocklet.io/)
- [Blocklet UI](https://developer.blocklet.io/)

## How to get help?

Having trouble? We’d like to help!

- Try the [FAQ](/en/docs/blocklet-developer/frequently-asked-questions/) – it’s got answers to many common questions.
- Looking for specific information? Try the search box with your keywords.
- Found something missing? or found a typo? Click "Submit Feedback" on each page footer to create issues on GitHub.

---

## Where to go from here?

URL: https://www.arcblock.io/en/docs/createblocklet/where-to-go-from-here/

- [Blocklet Server](/en/docs/blocklet-developer/install-blocklet-cli/)
- [Blocklet CLI](/en/docs/blocklet-developer/blocklet-cli/)
- [Blocklet Pages](https://pages.blocklet.io/)
- [Blocklet Actions](/en/docs/blocklet-developer/blocklet-actions/)
- [Blocklet SDK](/en/docs/blocklet-developer/blocklet-sdk/)
- [Blocklet UI](/en/docs/blocklet-developer/blocklet-ui/)

---

## vite-plugin-blocklet

URL: https://www.arcblock.io/en/docs/createblocklet/y-HvCOYzIgvJUfUOa_Pp1j7K/

[vite-plugin-blocklet](https://www.npmjs.com/package/vite-plugin-blocklet)

---

## Creator Studio

URL: https://www.arcblock.io/en/docs/creator-studio/

---

## Forum

URL: https://www.arcblock.io/en/docs/creator-studio/CGQylEQoPr58cRUzYWU3k1uu/

Forum Blocklet is a customized application package of Discuss Kit, designed specifically for users and teams who wish to set up a forum.

It is built on the decentralized application architecture of the ArcBlock platform and provides an interactive platform for users to discuss and communicate on specific topics.

Forum Blocklet by default disables the blog, documentation, bookmark, and other modules of Discuss Kit, and comes with preset optimal configurations, saving users setup time. Moreover, Forum Blocklet includes a getting started post to help users get up to speed quickly.

### Main Features

- Discussion Module Provides an open interactive platform where users can start new discussion topics and reply to existing ones. Suitable for scenarios requiring team collaboration, community interaction, and collective decision-making.
- Label Supports adding labels to discussion topics for easy categorization and retrieval.
- Board Allows the creation of different discussion boards to organize and manage discussions of various categories. Boards can also be linked with passports to control access permissions to the content.
- Task Assignment Enables administrators or users to assign discussion topics to specific team members to facilitate task management and follow-up.
- Action Log Provides comprehensive activity log functionality, recording updates to discussion posts, label changes, and board modifications.
- Robust Editing Experience
-
  - Markdown Support: Comprehensive support for Markdown syntax, allowing users to format text flexibly.
  - Image Editing: Built-in image editing tools, enabling users to edit images directly within posts.
  - AI-Assisted Writing Tools: Offers AI-assisted writing tools to help users create content more efficiently.
- Instant Notifications Includes instant messaging and notification systems, allowing you to receive notifications when someone comments on or replies to your post, ensuring real-time interaction.
- Support for Post Rewards (requires Payment Kit installation) Users can reward helpful posts, fostering positive community interaction.

---

## FAQs

URL: https://www.arcblock.io/en/docs/creator-studio/creator-studio-faqs/

## Overview

Here's a quick Q&A of Creator Studio's frequently asked questions.

## Q&A

### What is Blocklet Launcher?

Blocklet Launcher is a fully decentralized app launcher! With just a few clicks, you can quickly install decentralized applications in your digital world and immediately enable and run the applications smoothly.

### Why we need to have this Creator Studio?

We've noticed that content creators often spend a lot of time configuring their authoring tools rather than focusing on content creation itself

So we released a series of apps in the hope that creators can use them out-of-the-box, instead of doing all this tedious configuration and getting out of the way of content creation.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/creator-studio/creator-studio-getting-started/

## Overview

Using Blocklets in <strong>Creator Studio</strong> is very easy, you just need to go to our [Blocklet Store](https://store.blocklet.dev) and make a Launcher!

Quickly build your own content creation apps with no complex configurations!

- [Personal Website (Beta)](/en/docs/creator-studio/personal-website-beta/)

- [Knowledge Planet (Beta)](/en/docs/creator-studio/knowledge-planet-beta/)

- [Forum](/en/docs/creator-studio/CGQylEQoPr58cRUzYWU3k1uu/)

- [Blog](/en/docs/creator-studio/ifPwA_t6HTIhrnZ50VjTu0EL/)

- [Doc](/en/docs/creator-studio/SG1ao-y7jLqIXy4UBR8QwB2x/)

- [Bookmarklet](/en/docs/creator-studio/Q6MgunPR1oUKkiHbAlepZ89y/)

---

## How To Guides

URL: https://www.arcblock.io/en/docs/creator-studio/creator-studio-how-to-guides/

## Overview

- [How to use the "Knowledge Planet" Blocklet](/en/docs/creator-studio/how-to-use-the-knowledge-planet-blocklet/)

---

## How to use the "Knowledge Planet" Blocklet

URL: https://www.arcblock.io/en/docs/creator-studio/how-to-use-the-knowledge-planet-blocklet/

## Introducing

`Knowledge Planet` is a crucial component within Creator Studio, designed to facilitate the rapid creation of personalized knowledge-based payment systems by creators.

This official Blocklet belonging to the ArcBlock Team offers a multitude of features and configurations tailored for creators looking to monetize their valuable content.

## Default Configuration Overview

### 1. Discussion Board Modules

The board is divided into three distinctive modules:

- <strong>General:</strong> Accessible to all users.
- <strong>Subscription Board:</strong> Provides partial public access, with full visibility available to `Discussion Subscribers` Passport.
- <strong>Admin Board:</strong> Restricted to `Owner` or `Admin` Passport holders only.

Each module contains an inherent post which can be readily altered or removed as per individual requirements. For those seeking default configuration modifications, the necessary steps are readily accessible for reference.

![image.png](/e0127782a4734f418395d17865f6f2cc.png)![](https://bbqarpft2b66s4usqfmfb5bsw6sfclz2mjzsdolz4vy.did.abtnet.io/content/uploads/e0127782a4734f418395d17865f6f2cc.png)

#### 2. User Post Creation Permissions

By default, regular users are not permitted to create new posts across different formats such as Discussion, Blog, Doc, or Bookmark.

However, this restriction can be modified through <strong>Dashboard</strong> -> <strong>Settings</strong> -> <strong>Discuss Kit</strong> -> <strong>Preferences</strong>.

![](https://bbqarpft2b66s4usqfmfb5bsw6sfclz2mjzsdolz4vy.did.abtnet.io/content/uploads/33eac7f387379e5775c3e36105170b5d.png)

#### 3. Subscription-Based Access

The subscription functionality within the Subscription Board operates through `Payment Kit` and `Subscription Paywall`, with the default price list is as follows.

- <strong>Monthly:</strong> 10 ABT
- <strong>Yearly:</strong> 100 ABT

Administrators have the flexibility to adjust these defaults based on their specific needs.

![image.png](/73a68b803856086a017a6bf63a426de6.png)![](https://bbqarpft2b66s4usqfmfb5bsw6sfclz2mjzsdolz4vy.did.abtnet.io/content/uploads/73a68b803856086a017a6bf63a426de6.png)

* After the configuration is complete, the `Payment Kit` should be restarted to take effect.

### Conclusion

We extend our sincere thanks to all our users for choosing `Knowledge Planet`. For any queries or concerns, please feel free to reach out to the ArcBlock Team. We're here to support you every step of the way.

[ArcBlock Community](https://community.arcblock.io/)

---

## Blog

URL: https://www.arcblock.io/en/docs/creator-studio/ifPwA_t6HTIhrnZ50VjTu0EL/

The Blog Blocklet is a customized application package of Discuss Kit, specifically designed for users who wish to set up personal or corporate blogs.

The Blog Blocklet disables the discussion, documentation, and bookmark modules of Discuss Kit by default, focusing on providing core functionalities related to blogging.

It is built on the ArcBlock platform and features a decentralized architecture, ensuring the security and high autonomy of content. The Blog Blocklet allows users to publish articles, share knowledge, and offers powerful multilingual support and an enriched editing experience, helping users focus on content creation while easily creating and managing high-quality blog content.

### Key Features

- Article Publishing Allows users to write, edit, and publish blog posts, supports draft saving for later perfection
- Powerful Multilingual Support The blog module has built-in powerful multilingual and translation support. Users can create content in their native language and easily translate it into other languages with one click. It preserves the original format of the translated content, minimizing the need for manual adjustments
- Robust Editing Experience
-
  - Markdown Support: Comprehensive support for Markdown syntax, allowing users to format text flexibly.
  - Image Editing: Built-in image editing tools, enabling users to edit images directly within posts.
  - AI-Assisted Writing Tools: Offers AI-assisted writing tools to help users create content more efficiently.
- Instant Messaging and Notification System
-
  - Integrated with the chat module, allowing private or group communication between users
  - Built-in notification system to promptly remind users when someone comments on an article or replies to a comment
- SEO Support Built-in search engine optimization (SEO) features to significantly improve blog rankings and visibility in search results

---

## Knowledge Planet (Beta)

URL: https://www.arcblock.io/en/docs/creator-studio/knowledge-planet-beta/

> * This blocklet is in beta and is not recommended for production use

## Overview

<strong>Knowledge Planet</strong> is a crucial component within Creator Studio, designed to facilitate the rapid creation of personalized knowledge-based payment systems by creators.

[Knowledge Planet](https://test.store.blocklet.dev/blocklets/z2qaEX61vfHKtcLM5MYH84T2P59L7o2AAcRdF)

---

## Personal Website (Beta)

URL: https://www.arcblock.io/en/docs/creator-studio/personal-website-beta/

> * This blocklet is in beta and is not recommended for production use

## Overview

<strong>Personal Website</strong> is a digital space where an individual showcases their professional skills, personal achievements, and unique personality to the world.

[Personal Website](https://test.store.blocklet.dev/blocklets/z2qa3RrasLbgbrHDWi86qHBXRjGTh99VUVRBP)

---

## Bookmarklet

URL: https://www.arcblock.io/en/docs/creator-studio/Q6MgunPR1oUKkiHbAlepZ89y/

The Bookmarklet Blocklet is a customized application pack of Discuss Kit, aimed at providing a simple and efficient solution for saving and managing web pages for various users.

The Bookmarklet Blocklet disables the discussion, blog, documentation, and other modules of Discuss Kit by default, focusing on providing core functionalities related to bookmarking.

Whether you are a professional, student, or daily browser, the Bookmarklet Blocklet can help you easily organize and tag important content from the web. With this tool, you can build a personalized bookmark library, making information retrieval and content reference more efficient and convenient.

### Main Features

- Web Page Saving Users can easily save any webpage as a bookmark for easy access at any time.
- Classification and Tagging Provides powerful classification and tagging features, allowing users to categorize and tag bookmarks according to their needs, improving the efficiency and flexibility of resource management.
- Quick Search Built-in quick search functionality allows users to quickly find saved web pages or resources through keywords.
- Operation Log Provides a detailed operation log function that records the saving, modification, and deletion history of each bookmark, making it easy for users to track and manage changes.
- Powerful Editing Experience Users can add detailed descriptions and notes when saving bookmarks, and support Markdown format editing, offering a flexible bookmark editing experience.

---

## Doc

URL: https://www.arcblock.io/en/docs/creator-studio/SG1ao-y7jLqIXy4UBR8QwB2x/

The Doc Blocklet is a customized application pack for Discuss Kit, specifically designed for users and teams who need to build and maintain a knowledge base system.

Whether you need to manage technical documents for your team, create a systematic knowledge base, or use it as a personal note-taking tool, the Doc Blocklet can perfectly suit your needs.

To help users get started more quickly, the Doc Blocklet comes with the discussion, blog, and bookmark features of Discuss Kit disabled by default and provides a comprehensive beginner's guide.

### Key Features

- Document Management Users can easily create, edit, and manage various types of documents, including technical documents, project documents, and team handbooks. With an effective categorization and tagging system, users can quickly find the information they need.

- Powerful Multilingual Support The blog module has built-in powerful multilingual and translation support. Users can create content in their native language and easily translate it into other languages with one click. It preserves the original format of the translated content, minimizing the need for manual adjustments
- Robust Editing Experience
-
  - Markdown Support: Comprehensive support for Markdown syntax, allowing users to format text flexibly.
  - Image Editing: Built-in image editing tools, enabling users to edit images directly within posts.
  - AI-Assisted Writing Tools: Offers AI-assisted writing tools to help users create content more efficiently.

- Instant Messaging and Notification System
-
  - Integrated with the chat module, allowing private or group communication between users
  - Built-in notification system to promptly remind users when someone comments on an article or replies to a comment
- Task Assignment The Doc Blocklet allows users to assign documents to team members as tasks, facilitating more efficient team collaboration through this method.
- Operational Logs Provides a detailed and comprehensive operational log feature, recording document updates, label changes, etc., enabling team members to track the modification history of documents.

---

## Welcome

URL: https://www.arcblock.io/en/docs/creator-studio/welcome-fX9dw/

## Overview

<strong>Creator Studio</strong> is a great tool for content creators. Whether you are ready to start your own Blog, News letter, eBook, course, or offer offline services. Which currently consists of the following Blocklets

- <strong>Personal Website</strong> for a digital space where an individual showcases their professional skills, personal achievements, and unique personality to the world.
- <strong>Knowledge Planet</strong> for quickly build your knowledge planet

---

## DID Connect Guide

URL: https://www.arcblock.io/en/docs/did-connect/

---

## DID Connect UI (React)

URL: https://www.arcblock.io/en/docs/did-connect-react/

---

## Advanced Topics

URL: https://www.arcblock.io/en/docs/did-connect-react/advanced-557476/

Once you are comfortable with the core components like `SessionProvider` and `DidConnect`, you're ready to explore the more powerful and flexible features of the `@arcblock/did-connect-react` library. This section covers advanced subjects that allow you to build more sophisticated, robust, and user-friendly decentralized identity applications.

We will explore three main areas:

::::steps
:::step{title="Alternative Authentication Methods"}
Go beyond the default QR code scan and integrate popular login methods like OAuth (social login), Passkeys (passwordless), and Federated Login.
:::

:::step{title="Utility Functions"}
Leverage a suite of helper functions to handle common tasks such as URL encoding, creating API clients, and managing popups.
:::

:::step{title="Error Handling"}
Learn how to gracefully handle common errors, from blocked popups to WebAuthn API failures, ensuring a smooth user experience.
:::
::::

## Authentication Methods

While DID Connect is the primary authentication method, the library provides seamless integration with other popular login flows. This allows you to offer users multiple ways to sign in, catering to different preferences and security levels.

:::action-card{title="Explore Authentication Methods" description="Dive into detailed guides for implementing OAuth (social login), Passkeys (passwordless), and Federated Login within your application." icon="key"}
::action{label="Learn More" href="/en/docs/did-connect-react/advanced-authentication-methods-557476/" variant="primary"}
:::

## Utilities

The library exports a collection of utility functions designed to simplify common tasks and reduce boilerplate code in your application. These helpers cover everything from data encoding and cryptographic operations to managing browser popups for authentication flows.

:::action-card{title="Browse Utility Functions" description="Discover a comprehensive reference for all helper functions, including examples for URL manipulation, API client creation, data encryption, and more." icon="wrench"}
::action{label="View Reference" href="/en/docs/did-connect-react/advanced-utilities-557476/" variant="primary"}
:::

## Error Handling

Building a robust application requires graceful error handling. The `@arcblock/did-connect-react` library provides specific error types and helper functions to make this process easier.

### Popup Errors

When using authentication methods that require a popup window (like OAuth), the browser's popup blocker might interfere. The `openPopup` function will throw a `NotOpenError` if it fails to open the window. You should catch this error and provide appropriate feedback to the user.

**Handling Popup Errors**

```javascript
import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
import { NotOpenError } from '@arcblock/did-connect-react/lib/error';

async function startOAuthFlow(url) {
  try {
    const popup = openPopup(url);
    const result = await runPopup({ popup });
    console.log('OAuth successful:', result);
  } catch (err) {
    if (err instanceof NotOpenError) {
      alert('Popup was blocked. Please allow popups for this site and try again.');
    } else {
      alert(`An error occurred: ${err.message}`);
    }
  }
}
```

### API and WebAuthn Errors

For interactions with backend services or WebAuthn APIs (used by Passkeys), the library provides helper functions to parse complex error objects into user-friendly messages.

- `getApiErrorMessage(err, defaultMessage)`: Extracts an error message from an Axios error response.
- `getWebAuthnErrorMessage(err, defaultMessage, t)`: Handles WebAuthn-specific errors (e.g., user cancellation, unsupported browser) and provides translatable, user-friendly messages.

**Handling WebAuthn Errors**

```javascript
import { usePasskey } from '@arcblock/did-connect-react';
import { getWebAuthnErrorMessage } from '@arcblock/did-connect-react/lib/utils';

function PasskeyLoginButton() {
  const { loginWithPasskey } = usePasskey();

  const handleLogin = async () => {
    try {
      await loginWithPasskey();
      // Handle successful login
    } catch (err) {
      // Use the utility to get a user-friendly message
      const friendlyMessage = getWebAuthnErrorMessage(err, 'An unknown error occurred.');
      alert(friendlyMessage);
    }
  };

  return <button onClick={handleLogin}>Login with Passkey</button>;
}
```

By implementing proper error handling, you can significantly improve the user experience when things don't go as planned.

## Next Steps

Now that you have an overview of the advanced capabilities, you can dive deeper into the topics that are most relevant to your project.

- [<strong>Authentication Methods</strong>](/en/docs/did-connect-react/advanced-authentication-methods-557476/): Implement new ways for your users to log in.
- [<strong>Utilities</strong>](/en/docs/did-connect-react/advanced-utilities-557476/): Streamline your code with our helper functions.
- [<strong>API Reference</strong>](/en/docs/did-connect-react/api-reference-557476/): Get a complete, detailed look at all components, hooks, and functions.

---

## Authentication Methods

URL: https://www.arcblock.io/en/docs/did-connect-react/advanced-authentication-methods-557476/

While DID Wallet is the primary and most secure method for authentication, `@arcblock/did-connect-react` provides robust support for several alternative login methods to offer flexibility and cater to diverse user preferences. This section details how to integrate OAuth (social logins), Passkeys (passwordless authentication), and Federated Login into your application.

These methods are enabled through specific React Context Providers and accessed via corresponding hooks, which should be nested within the main `SessionProvider`.

## OAuth (Social Login)

Integrate popular social login providers like Google, GitHub, or Apple to allow users to sign in with their existing accounts. This functionality is managed by `OAuthProvider` and the `useOAuth` hook.

### 1. Setup with OAuthProvider

To enable OAuth functionalities, wrap your component tree with `OAuthProvider`. It's common to place it inside the `SessionProvider`.

**OAuthProvider Setup**

```jsx
import { SessionProvider } from '@arcblock/did-connect-react';
import { OAuthProvider } from '@arcblock/did-connect-react/lib/OAuth';

function App() {
  return (
    <SessionProvider>
      <OAuthProvider
        onBindOAuth={(provider) => console.log(`${provider.provider} bound!`)}
        onUnbindOAuth={(account) => console.log(`${account.provider} unbound!`)}>
        {/* Your application components */}
      </OAuthProvider>
    </SessionProvider>
  );
}
```

<strong>Props for</strong> <strong>`OAuthProvider`</strong>

- **children** `ReactNode` *(required)* — The child components that will have access to the OAuth context.
- **locale** `string` (default: `en`) — The language for UI messages and toasts.
- **onBindOAuth** `function` — Callback function triggered after a user successfully binds an OAuth account.
- **onUnbindOAuth** `function` — Callback function triggered after a user successfully unbinds an OAuth account.
- **onSwitchPassport** `function` — Callback function triggered after a user switches passports.
- **session** `object` — The current user session object, required for passport switching UI.

### 2. Usage with useOAuth Hook

The `useOAuth` hook provides functions to interact with the OAuth authentication flows.

**useOAuth Hook**

```jsx
import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';

function SocialLoginButtons() {
  const { loginOAuth, getOAuthConfigList, bindAuthLoading } = useOAuth();
  const [providers, setProviders] = React.useState([]);

  React.useEffect(() => {
    getOAuthConfigList().then(setProviders);
  }, [getOAuthConfigList]);

  const handleLogin = async (provider) => {
    try {
      const result = await loginOAuth({ provider: provider.provider });
      console.log('Login successful:', result);
      // Handle login result, e.g., update session
    } catch (error) {
      console.error('Login failed:', error.message);
    }
  };

  if (providers.length === 0) {
    return <p>No third-party login methods configured.</p>;
  }

  return (
    <div>
      {providers.map((p) => (
        <button key={p.provider} onClick={() => handleLogin(p)} disabled={bindAuthLoading}>
          Login with {p.provider}
        </button>
      ))}
    </div>
  );
}
```

### Core Functions

- <strong>`loginOAuth({ provider }, { action, ... })`</strong>: Initiates the login flow for a specific provider. A popup window will open for user authentication.
- <strong>`bindOAuth({ session, oauthItem })`</strong>: Binds a new social account to the currently logged-in user.
- <strong>`unbindOAuth({ session, connectedAccount })`</strong>: Unbinds a social account from the current user.
- <strong>`getOAuthConfigList()`</strong>: Asynchronously fetches the list of enabled OAuth providers configured in the Blocklet settings.
- <strong>`switchOAuthPassport(user)`</strong>: Opens a dialog to switch between different user accounts (passports) associated with the same OAuth identity.

## Passkeys (Passwordless)

Enable modern, secure, and passwordless authentication using Passkeys, which are based on the WebAuthn standard. This allows users to sign in with biometrics (fingerprint, face ID), a device PIN, or a security key.

### 1. Setup with PasskeyProvider

Wrap your application with `PasskeyProvider` to enable Passkey functionality.

**PasskeyProvider Setup**

```jsx
import { SessionProvider } from '@arcblock/did-connect-react';
import { PasskeyProvider } from '@arcblock/did-connect-react/lib/Passkey';

function App() {
  return (
    <SessionProvider>
      <PasskeyProvider
        onAddPasskey={(result) => console.log('Passkey added!', result)}
        onRemovePasskey={(result) => console.log('Passkey removed!', result)}>
        {/* Your application components */}
      </PasskeyProvider>
    </SessionProvider>
  );
}
```

<strong>Props for</strong> <strong>`PasskeyProvider`</strong>

- **children** `ReactNode` *(required)* — The child components that will have access to the Passkey context.
- **locale** `string` (default: `en`) — The language for UI messages and toasts.
- **onAddPasskey** `function` — Callback function triggered after a user successfully adds a Passkey.
- **onRemovePasskey** `function` — Callback function triggered after a user successfully removes a Passkey.
- **onSwitchPassport** `function` — Callback function triggered after a user switches passports.
- **session** `object` — The current user session object, required for passport switching UI.

### 2. Usage with usePasskey Hook

The `usePasskey` hook provides all the necessary functions for Passkey registration and authentication.

**usePasskey Hook**

```jsx
import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';
import { useSession } from '@arcblock/did-connect-react';

function PasskeyAuth() {
  const { loginPasskey, connectPasskey, connecting } = usePasskey();
  const { session } = useSession();

  const handleLogin = async () => {
    try {
      const result = await loginPasskey();
      console.log('Passkey login successful:', result);
      // Handle login result
    } catch (error) {
      console.error('Passkey login failed:', error.message);
    }
  };

  const handleConnect = async () => {
    // This should be called when a user is already logged in
    // and wants to add a passkey in their profile settings.
    if (!session.user) {
      alert('You must be logged in to add a passkey.');
      return;
    }
    try {
      await connectPasskey();
    } catch (error) {
      console.error('Failed to connect passkey:', error.message);
    }
  };

  return (
    <div>
      <button onClick={handleLogin}>Login with Passkey</button>
      {session.user && (
        <button onClick={handleConnect} disabled={connecting}>
          {connecting ? 'Connecting...' : 'Add a Passkey'}
        </button>
      )}
    </div>
  );
}
```

### Core Functions

- <strong>`loginPasskey({ action, ... })`</strong>: Initiates the Passkey authentication flow (also known as assertion). This is used for logging in existing users.
- <strong>`connectPasskey(extraParams)`</strong>: A high-level function to create and bind a new Passkey to the current user's account. It handles the full registration ceremony.
- <strong>`disconnectPasskey({ session, connectedAccount })`</strong>: Removes a Passkey from the current user's account after successful verification.
- <strong>`createPasskey(params)`</strong>: The lower-level function that starts the WebAuthn registration process. `connectPasskey` uses this internally.
- <strong>`verifyPasskey(params)`</strong>: The lower-level function that starts the WebAuthn authentication process. `loginPasskey` and `disconnectPasskey` use this internally.
- <strong>`switchPassport(user)`</strong>: Opens a dialog to switch between different user accounts (passports) that might share Passkeys.

## Federated Login

Federated Login allows a group of associated Blocklet applications (a "Federated Login Group") to share a single login session. When a user logs into the designated "master" site, they can be automatically authenticated on any "member" sites without needing to log in again.

### 1. Concept and Setup

This feature relies on a master-member site configuration within your Blocklet's settings. The `FederatedProvider` component is required to handle the cross-domain communication needed for this to work in modern browsers, particularly for managing third-party cookie access.

Like other providers, `FederatedProvider` should be included in your component tree, typically within `SessionProvider`.

**FederatedProvider Setup**

```jsx
import { SessionProvider } from '@arcblock/did-connect-react';
import { FederatedProvider } from '@arcblock/did-connect-react/lib/Federated';

function App() {
  return (
    <SessionProvider>
      <FederatedProvider>
        {/* Your application components */}
      </FederatedProvider>
    </SessionProvider>
  );
}
```

### 2. Usage

Federated login logic is integrated directly into the session management. You can trigger it using the `loginFederated` function available on the `session` object returned by `useSession`.

`loginFederated` supports two modes:

- <strong>`auto`</strong>: Attempts to silently log the user in if they have an active session on the master site. This is ideal for checking on page load.
- <strong>`manual`</strong>: Initiates a standard DID Connect login flow. Upon successful login, it also establishes the federated session with the master site.

**Federated Login Example**

```jsx
import { useSession } from '@arcblock/did-connect-react';
import React from 'react';

function FederatedLogin() {
  const { session } = useSession();
  const { federatedEnabled, loginFederated } = session;

  // Attempt auto-login on component mount
  React.useEffect(() => {
    if (federatedEnabled) {
      loginFederated((err) => {
        if (err) {
          console.warn('Auto federated login failed:', err);
        } else {
          console.log('Auto federated login successful!');
        }
      }, { mode: 'auto' });
    }
  }, [federatedEnabled, loginFederated]);

  const handleManualLogin = () => {
    loginFederated((err) => {
      if (err) console.error('Manual federated login failed:', err);
    }, { mode: 'manual' });
  };

  if (!federatedEnabled) {
    return <p>Federated login is not enabled.</p>;
  }

  return (
    <button onClick={handleManualLogin}>
      Login with Master Site Account
    </button>
  );
}
```

---

## Utilities

URL: https://www.arcblock.io/en/docs/did-connect-react/advanced-utilities-557476/

The `@arcblock/did-connect-react` library exports a collection of utility functions designed to simplify common tasks related to authentication flows, data handling, and API communication. While the core components and hooks handle most use cases, these utilities offer granular control for advanced integrations or custom implementations.

## API Client

### createAxios

This function is a factory for creating a pre-configured `axios` instance. It automatically includes essential headers like `x-did-connect-version` and `x-blocklet-visitor-id`, ensuring proper communication with Blocklet-based services. It's the recommended way to create API clients in your application.

<strong>Parameters</strong>

- **options** `object` — Standard Axios configuration object.
- **lazyOptions** `object` — Configuration for lazy sending.
  - **lazy** `boolean` (default: `false`) — Whether to enable lazy sending.
  - **lazyTime** `number` (default: `300`) — The debounce time in milliseconds for lazy sending.

<strong>Returns</strong>

- **axiosInstance** `AxiosInstance` — A configured instance of Axios.

<strong>Example</strong>

**apiClient.js**

```javascript
import { createAxios } from '@arcblock/did-connect-react/lib/utils';

const apiClient = createAxios({
  baseURL: '/api',
});

export default apiClient;
```

## URL and Popup Handling

These functions help manage the URLs and popup windows used during the DID Connect authentication process.

| Function  | Description  |
|---|---|
| `encodeConnectUrl(url)`  | Encodes a URL to be safely passed as a `__connect_url__` query parameter.  |
| `decodeConnectUrl(encoded)`  | Decodes a URL that was encoded with `encodeConnectUrl`.  |
| `parseTokenFromConnectUrl(connectUrl)`  | Extracts the session token (`_t_`) from a DID Connect URL.  |
| `openPopup(url, options)`  | Opens a new, centered popup window. It's used internally by the `DidConnect` component to display the wallet connection interface. Throws a `NotOpenError` if the popup is blocked.  |
| `runPopup(config)`  | A promise-based wrapper that manages the lifecycle of a popup created with `openPopup`. It listens for `message` events from the popup, handles timeouts, and resolves when the authentication flow is complete.  |
| `decodeUrlParams()`  | Parses custom `__did-connect__` parameters from the current window's URL.  |

<strong>Example: Custom Popup Flow</strong>

**customAuthButton.js**

```javascript
import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';

const handleCustomLogin = async () => {
  const authUrl = 'https://your-auth-service.com/connect';
  try {
    const popup = openPopup(authUrl);
    const result = await runPopup({ popup, timeoutInSeconds: 600 });
    console.log('Authentication successful:', result);
    // Handle successful login
  } catch (error) {
    console.error('Authentication failed:', error.message);
    // Handle popup closed or timeout
  }
};
```

## Session and Cookie Management

These helpers are used to read and write user connection information to cookies, enabling session persistence across page loads.

| Function  | Description  |
|---|---|
| `getConnectedInfo(data)`  | Formats the raw response data from a connection request into a standardized object suitable for cookie storage.  |
| `updateConnectedInfo(info, parsed)`  | Sets the necessary cookies (`connected_did`, `connected_pk`, `connected_app`) after a successful connection. This allows the library to optimize subsequent authentication checks.  |
| `getVisitorId()`  | Retrieves the unique visitor ID from cookies.  |
| `setVisitorId(id)`  | Sets the unique visitor ID in cookies.  |

<strong>Example</strong>

**sessionManager.js**

```javascript
import { getConnectedInfo, updateConnectedInfo } from '@arcblock/did-connect-react/lib/utils';

// Assuming 'authResponse' is the object returned from your login API
function persistSession(authResponse) {
  const connectedInfo = getConnectedInfo(authResponse);
  updateConnectedInfo(connectedInfo, true);
  console.log('Session info saved to cookies.');
}
```

## Encryption Utilities

For advanced scenarios requiring client-side encryption or decryption, the library exposes helpers that wrap the `tweetnacl-sealedbox-js` library.

| Function  | Description  |
|---|---|
| `encodeKey(key)`  | Base64URL encodes a key for transmission.  |
| `decodeKey(str)`  | Decodes a Base64URL string into a `Uint8Array` key.  |
| `encrypt(value, encryptKey)`  | Encrypts a string value using a public key.  |
| `decrypt(value, encryptKey, decryptKey)`  | Decrypts a base64 string using the corresponding public and private keys.  |

## Error Handling

To provide better feedback to users, you can use these functions to parse technical error objects into human-readable messages.

| Function  | Description  |
|---|---|
| `getApiErrorMessage(err, defaultMessage)`  | Extracts a user-friendly error message from an `axios` error object.  |
| `getWebAuthnErrorMessage(err, defaultMessage, t)`  | Handles WebAuthn/Passkey specific errors (e.g., user cancellation, browser not supported) and returns localized, user-friendly messages.  |

<strong>Example</strong>

**errorHandling.js**

```javascript
import { getApiErrorMessage } from '@arcblock/did-connect-react/lib/utils';
import apiClient from './apiClient';

async function fetchData() {
  try {
    const response = await apiClient.get('/data');
    return response.data;
  } catch (error) {
    const message = getApiErrorMessage(error, 'Failed to fetch data.');
    alert(message);
  }
}
```

By leveraging these utilities, you can build more complex and customized authentication experiences. For a complete list of all exported members and their types, please refer to the [API Reference](/en/docs/did-connect-react/api-reference-557476/).

---

## API Reference

URL: https://www.arcblock.io/en/docs/did-connect-react/api-reference-557476/

This section provides a comprehensive reference for all the major TypeScript types used throughout the `@arcblock/did-connect-react` library. Understanding these data structures is crucial for effectively using components like `SessionProvider` and hooks like `useConnect`.

## Connection Types

These types are primarily used when configuring and interacting with the DID Connect modal.

### ConnectProps

This is the main configuration object passed to the `open` function from the `useConnect` hook or the `openDidConnect` function from the session context. It allows for extensive customization of the connection flow's behavior and appearance.

- **action** `string` *(required)* — The primary action for the connection, e.g., 'login'.
- **containerEl** `Element` — The DOM element to which the connection modal should be appended.
- **prefix** `string` (default: `/api/did`) — The API endpoint prefix for DID Connect services.
- **locale** `'en' | 'zh'` (default: `en`) — The language to be used for the UI.
- **popup** `boolean` (default: `false`) — If true, the connection UI will be displayed in a popup window instead of a modal.
- **checkInterval** `number` (default: `2000`) — The interval in milliseconds to check the session status.
- **checkTimeout** `number` (default: `300000`) — The timeout in milliseconds for the entire session check process (5 minutes).
- **closeTimeout** `number` (default: `2000`) — The delay in milliseconds before closing the modal after a successful connection.
- **extraParams** `object` (default: `{}`) — Any extra parameters to be sent with the connection request.
- **tokenKey** `string` (default: `_t_`) — The key used to store the session token.
- **encKey** `string` (default: `_ek_`) — The key used for encryption.
- **baseUrl** `string` (default: `''`) — The base URL for API requests.
- **messages** `ConnectMessages` — An object to customize the text displayed in the connection UI.
- **autoConnect** `boolean` (default: `true`) — If true, automatically attempts to connect using a saved session.
- **forceConnected** `boolean | string` (default: `true`) — Forces the connection to be treated as established.
- **saveConnect** `boolean` (default: `true`) — If true, the successful connection session will be saved for autoConnect.
- **useSocket** `boolean` (default: `true`) — If true, uses WebSockets for real-time status updates.
- **allowWallet** `boolean` (default: `true`) — If true, allows connection via DID Wallet.
- **passkeyBehavior** `'none' | 'both' | 'only-existing' | 'only-new'` (default: `true`) — Defines how Passkeys are handled during the authentication process.
- **provider** `'wallet' | 'auth0' | ''` (default: `wallet`) — Specifies the authentication provider.
- **qrcodeSize** `number` (default: `160`) — The size of the QR code in pixels.
- **showDownload** `boolean` (default: `true`) — If true, shows download links for the DID Wallet.
- **webWalletUrl** `string` (default: `https://web.abtwallet.io`) — The URL for the web-based DID Wallet.
- **enabledConnectTypes** `Array<'web' | 'mobile' | 'auth0' | 'github' | 'apple' | 'google' | 'passkey'>` (default: `["web", "mobile", "github", "apple", "google", "auth0", "passkey"]`) — An array of connection methods to enable in the UI.
- **extraContent** `any` — Custom content to be rendered within the connection modal.
- **loadingEle** `any` — A custom loading element to display.
- **disableSwitchApp** `boolean` (default: `false`) — If true, disables the automatic app switching on mobile devices.
- **hideCloseButton** `boolean` (default: `false`) — If true, hides the close button in the modal.
- **options** `object` (default: `{}`) — Additional configuration options.
  - **showQuickConnect** `boolean` (default: `true`) — If true, shows the quick connect option for saved sessions.
- **onRecreateSession** `Function` — Callback function executed when a session is recreated.
- **checkFn** `() => boolean` — A custom function to check the connection status.
- **onSuccess** `(result: object) => void` — Callback function executed upon a successful connection.
- **onError** `(error: any) => void` — Callback function executed when an error occurs.
- **onClose** `Function` — Callback function executed when the connection modal is closed.

### ConnectMessages

Object to customize the text displayed within the DID Connect UI.

- **title** `string` *(required)* — The main title of the connect modal.
- **scan** `string` *(required)* — The instruction text for scanning the QR code.
- **success** `ReactNode` *(required)* — The message or component displayed upon successful connection.
- **confirm** `string` — The text prompting the user to confirm the action in their wallet.
- **error** `string` — A custom error message to display.

### OpenDidConnect

This function type defines the signature for opening the DID Connect flow with advanced requirements, often used for progressive authorization.

- **params** `ConnectProps` *(required)* — The standard connection properties.
- **options** `object` — Additional options to control the connection mode and specify requirements.
  - **openMode** `'redirect' | 'window' | 'popup'` (default: `popup`) — Determines how the DID Connect window is opened.
  - **requirements** `object` — Specifies the requirements for the session.
    - **login** `boolean` (default: `true`) — If true, requires the user to be logged in.
    - **bindWallet** `boolean` (default: `true`) — If true, requires the user to have a DID Wallet account bound.
    - **bindDidSpaces** `false | 'read' | 'full'` (default: `false`) — Specifies if DID Spaces binding is required, and what level of access is needed.
  - **baseUrl** `string` — The base URL for API requests.
  - **locale** `BaseLocale` — The language for the UI ('en' or 'zh').

## Session and User Types

These types define the structure of the user and session data managed by `SessionProvider`.

### SessionProps

The main session object, accessible via the `useSession` hook. It contains the user's state, session information, and methods to manage the session.

- **action** `string` — The current action being performed (e.g., 'login').
- **error** `string` — Any error message that occurred during the session management.
- **initialized** `boolean` — True if the session has been initialized.
- **loading** `boolean` — True if the session is currently in a loading state.
- **open** `boolean` — True if the DID Connect modal is currently open.
- **walletOS** `WalletOS` — The operating system of the connected wallet ('web', 'android', 'ios').
- **user** `User` — The authenticated user object. Undefined if no user is logged in.
- **locale** `UserLocale` — The current locale for the user.
- **provider** `WalletProvider` — The provider used for the current session.
- **baseUrl** `string` — The base URL used for API calls.
- **federatedMaster** `object` — Information about the master site in a Federated Login group.
- **login** `LoginSessionFn` — Function to initiate the login process.
- **logout** `LogoutSessionFn` — Function to log the user out.
- **switch** `Function` — Function to switch between different user accounts.
- **switchDid** `CommonSessionFn` — Function to switch the user's active DID.
- **autoSwitchDid** `Function` — Function to automatically switch DIDs.
- **switchProfile** `CommonSessionFn` — Function to switch user profiles.
- **switchPassport** `CommonSessionFn` — Function to switch between different passports.
- **bindWallet** `CommonSessionFn` — Function to initiate the wallet binding process.
- **refresh** `Function` — Function to manually refresh the session data.
- **updateConnectedInfo** `(data: object) => void` — Function to update connection information.
- **openDidConnect** `OpenDidConnect` — Function to open the DID Connect modal with advanced requirements.
- **useOAuth** `Function` — Hook for OAuth integration.
- **OAuthProvider** `Function` — Provider component for OAuth context.
- **OAuthConsumer** `Function` — Consumer component for OAuth context.
- **OAuthContext** `object` — The React context object for OAuth.
- **usePasskey** `Function` — Hook for Passkey integration.
- **PasskeyProvider** `Function` — Provider component for Passkey context.
- **PasskeyConsumer** `Function` — Consumer component for Passkey context.
- **PasskeyContext** `object` — The React context object for Passkey.
- **useDid** `(options: { session: Session }) => void` — A utility hook to work with DID information.
- **WrapDid** `Function` — A wrapper component related to DID functionality.
- **getUserSessions** `() => Promise<UserSession[]>` — Function to fetch all active sessions for the current user.

### User

Represents the detailed profile of an authenticated user.

- **did** `string` *(required)* — The user's Decentralized Identifier (DID).
- **pk** `string` *(required)* — The user's public key.
- **avatar** `string` *(required)* — URL of the user's avatar.
- **fullName** `string` *(required)* — The user's full name.
- **email** `string` *(required)* — The user's email address.
- **role** `UserRole` *(required)* — The role of the user within the application (e.g., 'guest', 'member', 'admin').
- **locale** `UserLocale` *(required)* — The user's preferred language.
- **connectedAccounts** `ConnectAccount[]` *(required)* — A list of accounts connected to the user's DID.
- **passports** `Passport[]` *(required)* — A list of passports associated with the user.
- **permissions** `any[]` *(required)* — A list of permissions granted to the user.
- **didSpace** `object` — Information about the user's DID Space.
- **approved** `boolean` *(required)* — Indicates if the user has been approved.
- **remark** `string` — An optional remark or note about the user.
- **createdAt** `string` *(required)* — Timestamp of when the user account was created.
- **updatedAt** `string` *(required)* — Timestamp of the last update to the user account.
- **firstLoginAt** `string` — Timestamp of the user's first login.
- **lastLoginAt** `string` — Timestamp of the user's last login.
- **lastLoginIp** `string` — IP address from the user's last login.

### UserSession

Represents a single active session for a user, typically retrieved from `getUserSessions`.

- **id** `string` *(required)* — The unique identifier for the session.
- **appName** `string` *(required)* — The name of the application for this session.
- **appPid** `string` *(required)* — The application's Passport ID.
- **updatedAt** `string` *(required)* — Timestamp of the last session update.
- **userDid** `string` *(required)* — The DID of the user for this session.
- **visitorId** `string` *(required)* — The visitor ID associated with the session.
- **extra** `object` *(required)* — Any extra data associated with the session.
- **user** `SessionUser` *(required)* — A simplified user object for the session.
- **passportId** `string` — The ID of the passport used for this session.

### Core Data Types

These are fundamental string union types used across various other interfaces.

| Type  | Description  | Possible Values  |
|---|---|---|
| `WalletProvider`  | Identifies the authentication method or provider.  | `wallet`, `auth0`, `apple`, `github`, `google`, `passkey`  |
| `WalletOS`  | Represents the operating system of the DID Wallet.  | `web`, `android`, `ios`, `''` (empty string)  |
| `UserRole`  | Defines the role of a user within the application.  | `guest`, `member`, `admin`, `owner`, or any `string`  |
| `BaseLocale`  | The base set of supported languages.  | `en`, `zh`  |
| `UserLocale`  | The user's locale, can be a base locale or a more specific one.  | `en`, `zh`, or any `string` (e.g., 'en-US')  |

---

## Core Components

URL: https://www.arcblock.io/en/docs/did-connect-react/core-components-557476/

The `@arcblock/did-connect-react` library is built around a few essential components that provide the foundation for integrating decentralized identity into your application. These components handle session management and the user-facing connection interface.

Understanding these two core components is the first step to mastering the library. They work together to provide a seamless and secure authentication experience.

::::card-group
::link-card{title="SessionProvider" description="The heart of the library. This provider wraps your application to manage user session state, handle authentication logic, and expose session data and control functions to all nested components." icon="key" href="/en/docs/did-connect-react/core-components-session-provider-557476/"}
::link-card{title="DidConnect" description="The pre-built UI for user interaction. It displays the QR code, login options (like Passkeys and OAuth), and handles the entire connection flow. You typically won't render it directly but control it programmatically." icon="qr-code" href="/en/docs/did-connect-react/core-components-did-connect-557476/"}
::::

Start by learning how to set up the `SessionProvider` to manage application-wide state, then explore how the `DidConnect` component facilitates the user authentication journey.

---

## Connection UI (DidConnect)

URL: https://www.arcblock.io/en/docs/did-connect-react/core-components-did-connect-557476/

The `DidConnect` component is a pre-built, comprehensive UI solution for handling various decentralized identity (DID) connection flows. It provides a user-friendly interface for actions like login, authentication, and profile requests, supporting multiple connection methods out-of-the-box.

It serves as the visual centerpiece of the `@arcblock/did-connect-react` library, abstracting away the complexity of session management and real-time status updates. The component displays a QR code for DID Wallet users and offers alternative login options such as social logins (OAuth) and passwordless authentication (Passkeys).

Before using `DidConnect`, ensure you have wrapped your application with the [`SessionProvider`](/en/docs/did-connect-react/core-components-session-provider-557476/) to manage the overall session state.

## Basic Usage

To use `DidConnect`, you need to import it and provide a few essential props. The component is typically controlled by a state variable that determines its visibility.

**DID Connect Example**

```jsx
import React, { useState } from 'react';
import axios from 'axios';
import DidConnect from '@arcblock/did-connect-react/lib/Connect';

function App() {
  const [isConnectOpen, setConnectOpen] = useState(false);

  const handleClose = () => setConnectOpen(false);
  const handleSuccess = () => {
    // Handle successful login, e.g., redirect the user
    window.location.href = '/profile';
  };

  return (
    <div>
      <button onClick={() => setConnectOpen(true)}>Login with DID</button>
      {isConnectOpen && (
        <DidConnect
          action="login"
          checkFn={axios.get}
          onClose={handleClose}
          onSuccess={handleSuccess}
          messages={{
            title: 'Scan to Sign In',
            scan: 'Scan QR code with your DID Wallet',
            confirm: 'Confirm login on your DID Wallet',
            success: 'You have successfully signed in!',
          }}
        />
      )}
    </div>
  );
}

export default App;
```

In this example, clicking the "Login with DID" button sets the `isConnectOpen` state to `true`, which renders the `DidConnect` component as a modal dialog. The `checkFn` prop is crucial, as it's the function the component uses to poll for the session status from your backend.

## How It Works

The `DidConnect` component orchestrates the entire user authentication flow, from displaying connection options to handling the final success or error state. The following diagram illustrates this flow:

![Connection UI (DidConnect)](https://media.arcblock.io/lib/d4/d4d69cd28f31d5fe.w1600.webp)

## Component Props

The `DidConnect` component is highly configurable through its props. Below is a detailed list of the available options.

### Core Configuration

These props are essential for setting up the component's basic functionality.

- **action** `string` *(required)* — Defines the purpose of the connection, such as login, claim, sign, etc. This string is passed to your backend to determine the required actions.
- **checkFn** `function` *(required)* — The function used to poll the backend for session status updates. It should be a function that makes an API request, like axios.get.
- **baseUrl** `string` (default: `''`) — The base URL for the API endpoints. If your API is on a different domain, specify it here.
- **prefix** `string` (default: `/api/did`) — The URL prefix for the DID Connect API endpoints on your backend.

### Behavior Control

These props control how the connection process behaves.

- **enabledConnectTypes** `string[]` (default: `["web", "mobile", ...]`) — An array of strings specifying which connection methods to display. Possible values include web, mobile, github, google, apple, passkey, etc.
- **passkeyBehavior** `'none' | 'both' | 'only-existing' | 'only-new'` (default: `'none'`) — Controls the behavior of Passkey authentication. none disables it, both allows creating new passkeys and using existing ones, only-existing restricts to existing passkeys, and only-new forces new passkey creation.
- **allowWallet** `boolean` (default: `true`) — If false, the QR code and mobile wallet connection options will be hidden.
- **autoConnect** `boolean` (default: `true`) — If true, the component will automatically try to use a previously established connection from the same device.
- **forceConnected** `boolean | string` (default: `true`) — If true, a user must connect with the same DID they are already logged in with. If a DID string is provided, the user must connect with that specific DID.
- **saveConnect** `boolean` (default: `true`) — If true, the successful connection information is saved locally for future autoConnect attempts.
- **useSocket** `boolean` (default: `true`) — If true, attempts to use a WebSocket for real-time status updates, falling back to polling if a connection cannot be established.

### UI Customization

Customize the appearance and text of the `DidConnect` component.

- **mode** `'dialog' | 'drawer' | 'page'` (default: `'dialog'`) — Determines how the component is displayed. dialog shows it as a centered modal, drawer as a bottom sheet (on mobile), and page embeds it directly into the document flow.
- **messages** `object` — An object to customize the text displayed in the UI.
  - **title** `string` — The main title at the top.
  - **scan** `string` — The instructional text below the title.
  - **confirm** `string` — Text shown after the QR code is scanned.
  - **success** `string | ReactNode` — Message displayed upon successful connection.
  - **error** `string` — Message displayed on error.
- **hideCloseButton** `boolean` (default: `false`) — If true, the close button (X) in the top-right corner is hidden.
- **extraContent** `ReactNode` (default: `null`) — Allows you to inject a custom React component or element into the UI, typically appearing below the main title/description.
- **customItems** `ReactNode[]` (default: `[]`) — An array of custom React nodes to be added to the list of connection methods.
- **disableSwitchApp** `boolean` (default: `false`) — If you are using Federated Login, this prop prevents users from switching between different applications in the group during the login process.
- **webWalletUrl** `string` — The URL of the web-based DID Wallet to be used for the "Connect with Web Wallet" option. Defaults to the official ArcBlock web wallet.

### Callbacks

Functions that are called at different stages of the connection lifecycle.

- **onClose** `function` *(required)* — Callback function that is executed when the user closes the DidConnect dialog (e.g., by clicking the close button or outside the modal).
- **onSuccess** `function` *(required)* — Callback function that is executed upon a successful connection. The session data is passed as an argument.
- **onError** `function` — Callback function that is executed when an error occurs during the process. The error object or message is passed as an argument.
- **onRecreateSession** `function` — A callback function that is invoked when the session needs to be reset, for example, after a timeout or when the user manually cancels and retries.

## Next Steps

With a solid understanding of the `DidConnect` component, you can now build robust authentication experiences. For more programmatic control over the connection UI, explore the [`useConnect` hook](/en/docs/did-connect-react/hooks-use-connect-557476/), which allows you to open and close the `DidConnect` modal from anywhere in your application.

---

## Session Management (SessionProvider)

URL: https://www.arcblock.io/en/docs/did-connect-react/core-components-session-provider-557476/

The `SessionProvider` is the cornerstone of the `@arcblock/did-connect-react` library. It's a React Context Provider that encapsulates all session-related logic, state, and actions. By wrapping your application with `SessionProvider`, you make the user's session information and authentication methods available to any component in your application tree, without having to pass props down manually.

This component handles everything from storing session tokens and managing user data to orchestrating login/logout flows and refreshing sessions automatically.

## How It Works

`SessionProvider` creates a session context that holds the current user's state (`user` object, `loading` status, etc.) and provides functions to modify that state (e.g., `login`, `logout`). Any component nested within `SessionProvider` can subscribe to this context to access this data and trigger authentication actions.

Here is a diagram illustrating the basic architecture:

![Session Management (SessionProvider)](https://media.arcblock.io/lib/7c/7c0fb9de07147b9f.w1600.webp)

## Getting Started

To use the session management features, you first need to import and wrap your application with `SessionProvider`. The library exports factory functions to create a configured provider.

### Basic Setup

The most common way to set up the provider is by using `createAuthServiceSessionContext`, which is pre-configured for applications running within the ArcBlock ecosystem (Blocklets).

**App.js**

```javascript
import React from 'react';
import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
import AuthButton from './AuthButton';

// Create the SessionProvider and a hook to access the context
const { SessionProvider, SessionContext } = createAuthServiceSessionContext();

export const useSession = () => React.useContext(SessionContext);

export default function App() {
  return (
    <SessionProvider>
      <div className="App">
        <h1>Welcome to DID Connect</h1>
        <AuthButton />
      </div>
    </SessionProvider>
  );
}
```

**AuthButton.js**

```javascript
import React from 'react';
import { useSession } from './App';

export default function AuthButton() {
  const { session } = useSession();

  if (session.loading) {
    return <div>Loading...</div>;
  }

  if (session.user) {
    return (
      <div>
        <p>Welcome, {session.user.fullName || session.user.did}</p>
        <button onClick={() => session.logout()}>Logout</button>
      </div>
    );
  }

  return <button onClick={() => session.login()}>Login</button>;
}
```

In this example, `createAuthServiceSessionContext` generates a `SessionProvider`. We wrap our `App` with it, and now any child component, like `AuthButton`, can use the `useSession` hook to access session data and functions.

## SessionProvider Props

You can configure the `SessionProvider`'s behavior by passing it various props.

- **serviceHost** `string` — The base URL for the authentication service backend. Defaults to the current Blocklet's prefix or '/'.
- **autoConnect** `boolean` (default: `false`) — If true, the DID Connect dialog will automatically open if no user session is found on page load.
- **autoDisconnect** `boolean` (default: `true`) — If true, the session will be automatically cleared if the application ID mismatches the one stored in the session cookie.
- **protectedRoutes** `string[]` (default: `["*"]`) — An array of route patterns to protect. If a non-authenticated user tries to access these routes, they will see a loading spinner until the session is resolved. Wildcards (*) are supported.
- **locale** `string` — Sets the display language for the DID Connect UI. Defaults to the browser's language.
- **webWalletUrl** `string` — The URL of the web-based DID Wallet to use for the connection process.
- **timeout** `number` (default: `120000`) — The timeout in milliseconds for waiting for a response from DID Wallet during the connection process.
- **useSocket** `boolean` (default: `true`) — Determines whether to use WebSockets for real-time communication with the wallet, providing a faster user experience.
- **extraParams** `object` — An object of extra parameters to be sent with every authentication request to the backend.

## The Session Context Object

When you consume the `SessionContext`, you get an object containing the session state and API. The primary property is `session`, which holds all the data and methods you'll interact with.

### State Properties

These are read-only properties that describe the current state of the user session.

- **user** `User | null` — The authenticated user object if a session exists, otherwise null. Contains details like DID, name, email, avatar, etc.
- **loading** `boolean` — True when the session is being initialized, refreshed, or during a login/logout process.
- **initialized** `boolean` — True once the initial session check has completed on page load.
- **open** `boolean` — True if the DID Connect dialog is currently open.
- **error** `string` — Contains an error message if the last session operation failed.
- **provider** `string` — The provider used for the last login (e.g., 'wallet', 'github', 'google').
- **walletOS** `string` — The operating system of the connected DID Wallet (e.g., 'ios', 'android', 'web').
- **unReadCount** `number` — The number of unread notifications for the current user.

### Action Methods

These are functions you can call to initiate authentication flows or manage the session.

- **login()** `function` — Initiates the user login process by opening the DID Connect UI. It accepts optional callbacks and parameters.
- **logout()** `function` — Logs the current user out, clearing the session from storage. It accepts an optional callback function to be executed upon completion.
- **switchDid()** `function` — Allows a logged-in user to switch to a different DID account. It re-opens the DID Connect UI with a context for switching accounts.
- **bindWallet()** `function` — For users logged in via social providers (OAuth) or Passkeys, this function initiates a flow to connect a DID Wallet to their existing account.
- **refresh()** `function` — Manually triggers a refresh of the user's session data from the server. Useful for fetching updated profile information or permissions.
- **switchProfile()** `function` — Opens the DID Connect UI to allow the user to switch between different profiles within the same DID account (e.g., personal, work).
- **switchPassport()** `function` — Opens the DID Connect UI to allow the user to switch between different passports, which may represent different sets of credentials or roles.
- **connectToDidSpaceForFullAccess()** `function` — Initiates a connection to the user's DID Space, requesting full access permissions. This is often required for applications that need to read and write data to the user's personal data store.
- **withSecondaryAuth()** `function` — A higher-order function that wraps another function, requiring the user to complete a secondary authentication step (e.g., re-enter password, use passkey) before the wrapped function is executed. This is ideal for protecting sensitive actions.

### Event Subscription

The context also provides an `events` object, which is an instance of `EventEmitter3`. You can use it to subscribe to various lifecycle events of the session.

**EventListener.js**

```javascript
import React, { useEffect } from 'react';
import { useSession } from './App';

function EventListener() {
  const { events } = useSession();

  useEffect(() => {
    const handleLogin = (result) => {
      console.log('User logged in:', result.user.did);
    };

    const handleLogout = () => {
      console.log('User logged out');
    };

    events.on('login', handleLogin);
    events.on('logout', handleLogout);

    // Cleanup listeners on component unmount
    return () => {
      events.off('login', handleLogin);
      events.off('logout', handleLogout);
    };
  }, [events]);

  return null; // This component doesn't render anything
}
```

Available events include `login`, `login-failed`, `logout`, `change`, `bind-wallet`, `switch-passport`, and more.

## Advanced Customization

For scenarios that require different storage mechanisms or more granular control, you can use the generic `createSessionContext` factory.

**customSession.js**

```javascript
import { createSessionContext } from '@arcblock/did-connect-react/lib/Session';

const { SessionProvider, SessionContext } = createSessionContext(
  'my_app_session_token', // Custom storage key
  'ls',                   // Use localStorage instead of cookies
  {},
  {
    rolling: false,         // Disable automatic token refresh
  }
);

// ... export and use as needed
```

This allows you to fine-tune session behavior, such as changing the storage engine to `localStorage` ('ls') or `cookie`, or adjusting token refresh policies.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/did-connect-react/getting-started-557476/

This guide will walk you through the essential steps to integrate decentralized identity (DID) authentication into your React application using `@arcblock/did-connect-react`. In just a few minutes, you'll have a fully functional login and logout flow.

### Prerequisites

Before you begin, ensure your development environment meets the following criteria:

- You have a React project set up.
- You have a running Blocklet Server instance that will handle the authentication requests. The library is designed to work seamlessly with a backend powered by Blocklet Server.

## Step 1: Install the Library

First, add the `@arcblock/did-connect-react` package to your project. You can use either npm or yarn.

**Install with npm**

```bash
npm install @arcblock/did-connect-react
```

**Install with yarn**

```bash
yarn add @arcblock/did-connect-react
```

## Step 2: Set Up the SessionProvider

The `SessionProvider` is the heart of the library. It's a context provider that manages the user's session state (like login status and user information) and makes it available to all components wrapped within it. You should place it at the root of your application, for instance, in your `App.js` file.

For applications built on Blocklet, the recommended way to initialize the provider is by using the `createAuthServiceSessionContext` factory function.

**App.js**

```javascript
import React from 'react';
import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
import Home from './Home'; // We will create this component in the next step

// createAuthServiceSessionContext is optimized for Blocklet environments
const { SessionProvider } = createAuthServiceSessionContext();

function App() {
  return (
    // The serviceHost prop points to the base path of your backend authentication service.
    // For a standard Blocklet, this is usually the blocklet's prefix or '/'.
    <SessionProvider serviceHost="/">
      <Home />
    </SessionProvider>
  );
}

export default App;
```

## Step 3: Implement Login and Logout

Now, let's create a component that allows users to log in and log out. We can access the session data and functions using React's `useContext` hook with the `SessionContext`.

The `session` object gives you everything you need: the current `user`, the `loading` state, and functions like `login()` and `logout()`.

**Home.js**

```javascript
import React, { useContext } from 'react';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
import Button from '@arcblock/ux/lib/Button'; // A general-purpose button
import CircularProgress from '@mui/material/CircularProgress';

function Home() {
  // Access the session context
  const { session } = useContext(SessionContext);

  // Destructure for easier access
  const { user, loading, login, logout } = session;

  // Display a loading indicator while the session is being initialized
  if (loading) {
    return <CircularProgress />;
  }

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      {user ? (
        // If the user is logged in, show their DID and a logout button
        <div>
          <h1>Welcome!</h1>
          <p>Your DID: {user.did}</p>
          <Button variant="contained" color="secondary" onClick={logout}>
            Logout
          </Button>
        </div>
      ) : (
        // If not logged in, show the login button
        <div>
          <h1>Please Sign In</h1>
          <ConnectButton onClick={() => login()}>
            Connect Wallet
          </ConnectButton>
        </div>
      )}
    </div>
  );
}

export default Home;
```

When the user clicks the `ConnectButton`, the `login()` function is called. This function handles opening the DID Connect modal, which displays a QR code for the user to scan with their DID Wallet, and manages the entire authentication process.

## Step 4: Access User Data

Once a user has successfully logged in, the `session.user` object will be populated. This object contains the user's profile information retrieved from their DID Wallet.

The `session` object provided by the context is your main interface to the user's authentication state. Here are its key properties:

- **user** `object | null` — The authenticated user object. It's `null` if no user is logged in.
  - **did** `string` — The user's Decentralized Identifier (DID).
  - **fullName** `string` — The user's full name from their wallet profile.
  - **email** `string` — The user's email from their wallet profile.
- **loading** `boolean` — `true` while the session is being initialized or refreshed, `false` otherwise.
- **login** `function` — A function to initiate the login process, which opens the DID Connect UI.
- **logout** `function` — A function to log the user out and clear the session.
- **initialized** `boolean` — `true` once the initial session check is complete.

## You're All Set!

Congratulations! You have successfully implemented a complete DID-based authentication flow in your React application. Users can now sign in using their DID Wallet, and your application can securely access their session information.

### Next Steps

To dive deeper and explore more advanced features, check out the following sections:

::::card-group
::link-card{title="Session Management (SessionProvider)" description="Learn about all the configuration options for `SessionProvider` to customize session behavior, timeouts, and more." icon="key" href="/en/docs/did-connect-react/core-components-session-provider-557476/"}
::link-card{title="Connection UI (DidConnect)" description="Explore the `DidConnect` component for a declarative way to embed the connection UI directly into your pages." icon="qr-code" href="/en/docs/did-connect-react/core-components-did-connect-557476/"}
::::

---

## Hooks

URL: https://www.arcblock.io/en/docs/did-connect-react/hooks-557476/

The `@arcblock/did-connect-react` library offers a powerful set of React hooks that provide programmatic control and flexible data access. While the [SessionProvider](/en/docs/did-connect-react/core-components-session-provider-557476/) offers a convenient context-based approach, hooks give you the fine-grained control needed for complex UIs and advanced use cases.

These hooks allow you to manage the connection flow, access user data, and integrate various authentication methods from any component within the `SessionProvider`'s scope.

::::card-group
::link-card{title="useConnect" description="Programmatically open, close, and manage the DID Connect UI modal. This is the core hook for controlling the connection flow." icon="zap" href="/en/docs/did-connect-react/hooks-use-connect-557476/"}
::link-card{title="useDid" description="A convenient utility hook to easily access and work with the authenticated user's DID, profile, and wallet information from the session." icon="user-check" href="/en/docs/did-connect-react/hooks-use-did-557476/"}
::link-card{title="useOAuth & usePasskey" description="Integrate modern, alternative authentication methods. `useOAuth` handles social logins, while `usePasskey` enables secure, passwordless authentication." icon="key" href="/en/docs/did-connect-react/hooks-use-oauth-passkey-557476/"}
::::

## Summary

By leveraging these hooks, you can build highly customized and seamless user experiences. Start by exploring `useConnect` to understand how to trigger the login flow, then see how `useDid` can help you display user information.

Ready to dive deeper? Choose a hook from above to learn more, or proceed to the [UI Components](/en/docs/did-connect-react/ui-components-557476/) section to see how you can display user data.

---

## useConnect

URL: https://www.arcblock.io/en/docs/did-connect-react/hooks-use-connect-557476/

The `useConnect` hook provides a powerful, programmatic way to open, close, and manage the `DidConnect` UI modal. It's the ideal solution when you need more control over the connection flow than the declarative `Button` component offers, such as triggering the modal from a custom UI element, a menu item, or in response to an application event.

This hook is the engine behind the `Button` component and gives you direct access to the same core functionalities.

## How It Works

The `useConnect` hook returns two main elements:

::::steps
:::step{title="`connectHolder`"}
A React element that must be rendered in your component tree. This element is responsible for rendering the `DidConnect` modal when it's activated. It remains invisible until the `open` function is called.
:::

:::step{title="`connectApi`"}
An object containing the functions (`open`, `close`, `openPopup`, `loginOAuth`) you'll use to control the modal's lifecycle.
:::
::::

![useConnect](https://media.arcblock.io/lib/9e/9ee8686ea5cf1854.w1600.webp)

## Setup

To use the hook, import it and call it within your component. Then, ensure you render the `connectHolder` somewhere in your application, preferably at a top-level component to ensure the modal can overlay all other content.

**Basic Setup**

```javascript
import React from 'react';
import { useConnect } from '@arcblock/did-connect-react';

function MyComponent() {
  // 1. Initialize the hook
  const { connectHolder, connectApi } = useConnect();

  const handleLogin = () => {
    // 2. Use the API to open the modal
    connectApi.open({
      action: 'login',
      onSuccess: (result) => {
        console.log('Login successful!', result);
      },
      onClose: () => {
        console.log('Modal closed by user.');
      }
    });
  };

  return (
    <div>
      <button type="button" onClick={handleLogin}>
        Login with DID
      </button>

      {/* 3. Render the holder component */}
      {connectHolder}
    </div>
  );
}

export default MyComponent;
```

## API Reference

The `connectApi` object provides the following methods to control the connection process.

### connectApi.open(options)

This is the primary function to trigger and display the `DidConnect` modal. It accepts a single `options` object to configure the behavior, appearance, and callbacks for the connection session.

<strong>Parameters (</strong><strong>`options`</strong><strong>)</strong>

- **action** `string` *(required)* — The purpose of the connection request, e.g., login, claim, sign, etc. This determines the workflow within the wallet.
- **onSuccess** `(result: object) => void` — Callback function executed when the user successfully completes the action in their wallet. The result object contains the response from the wallet.
- **onClose** `() => void` — Callback function executed when the user manually closes the modal without completing the action.
- **onError** `(error: any) => void` — Callback function executed if an error occurs during the process, such as a timeout or a network issue.
- **messages** `ConnectMessages` — An object to customize the text displayed in the modal. See ConnectMessages type for details.
  - **title** `string` — Modal title.
  - **scan** `string` — Text accompanying the QR code.
  - **confirm** `string` — Text for the confirmation step.
  - **success** `ReactNode` — Content for the success screen.
- **popup** `boolean` (default: `true`) — If true, the UI is displayed as a modal dialog. If false, it renders inline, requiring containerEl to be set.
- **containerEl** `Element` — A DOM element where the DidConnect component will be rendered if popup is set to false.
- **closeTimeout** `number` (default: `2000`) — The delay in milliseconds before the modal automatically closes after a successful connection.
- **checkInterval** `number` (default: `2000`) — The interval in milliseconds for polling the server to check the session status.
- **checkTimeout** `number` (default: `300000`) — The total time in milliseconds before the connection attempt times out.
- **extraParams** `object` (default: `{}`) — Any extra parameters to be included in the session creation request, which can be retrieved on the server-side.

### connectApi.close()

Manually closes the `DidConnect` modal. The modal closes automatically on success or user cancellation, but you can call this function if you need to close it programmatically for other reasons.

```javascript
// Example: Close the modal after a short delay in the success callback
connectApi.open({
  action: 'login',
  onSuccess: () => {
    showTemporarySuccessMessage();
    setTimeout(() => {
      connectApi.close();
    }, 1500);
  },
  closeTimeout: 999999 // Prevent auto-close
});
```

### connectApi.openPopup(params, options)

This function provides an alternative connection method that opens the DID Connect flow in a new browser popup window instead of a modal within the current page. This is useful for certain OAuth-like flows or when integrating with sites where you cannot inject a modal.

<strong>Parameters</strong>

- **params** `ConnectProps` *(required)* — Similar to the open method's options. A key difference is that params.extraParams.provider is required to identify the authentication method (e.g., 'github', 'google').
- **options** `object` — Configuration for the popup window itself.
  - **baseUrl** `string` — The base URL for constructing the popup URL.
  - **locale** `string` (default: `en`) — The locale for the popup content.
  - **popupOptions** `object` — Options passed directly to `window.open()` for customizing the popup's size and features.

<strong>Usage</strong>

The `openPopup` function returns a `Promise` that resolves with the authentication data on success or rejects on failure or cancellation.

```javascript
const handleGithubLogin = async () => {
  try {
    const result = await connectApi.openPopup({
      action: 'login',
      onSuccess: () => console.log('This callback is also triggered'),
      extraParams: { provider: 'github' } // This is required
    });
    console.log('Login successful via popup:', result);
  } catch (err) {
    if (err.message === 'Popup closed') {
      console.log('User closed the popup window.');
    } else {
      console.error('An error occurred:', err);
    }
  }
};
```

### connectApi.loginOAuth(options)

This is a helper function to directly initiate an OAuth login flow. It's a lower-level utility that is internally used by other parts of the library.

<strong>Parameters (</strong><strong>`options`</strong><strong>)</strong>

- **provider** `string` *(required)* — The OAuth provider to use, e.g., 'github', 'google'.
- **action** `string` *(required)* — The action, typically 'login'.
- **extraParams** `object` — Additional parameters for the OAuth flow.
- **onLogin** `function` *(required)* — Callback function executed upon successful login.

---

## useDid

URL: https://www.arcblock.io/en/docs/did-connect-react/hooks-use-did-557476/

The `useDid` hook is a convenient utility for easily extracting and working with specific DID-related information from the `session.user` object. It simplifies parsing the user object to get commonly needed data like the permanent DID, wallet information, and connected accounts without manual processing.

This hook should be used within a component that is a child of the `SessionProvider` to ensure it has access to the session context.

## How to Use

To use the hook, import it along with `useSession`. Call `useSession` to get the current session state, and then pass the `session` object to `useDid`.

**Basic Usage**

```javascript
import { useSession } from '@arcblock/did-connect-react';
import { useDid } from '@arcblock/did-connect-react/lib/User';

function UserProfile() {
  const { session } = useSession();
  const {
    did,
    walletDid,
    connectedDids,
    sourceProvider,
    connectedAccounts,
  } = useDid({ session });

  if (!session.user) {
    return <p>Please log in to view your DID information.</p>;
  }

  return (
    <div>
      <h2>User DID Information</h2>
      <p><strong>Permanent DID:</strong> {did}</p>
      <p><strong>Wallet DID:</strong> {walletDid || 'N/A'}</p>
      <p><strong>Login Method:</strong> {sourceProvider}</p>
      <h3>Connected Accounts ({connectedAccounts.length})</h3>
      <ul>
        {connectedAccounts.map((account) => (
          <li key={account.did}>
            {account.provider}: {account.did}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

## Parameters

The `useDid` hook accepts a single object as its parameter.

- **options** `object` *(required)*
  - **session** `object` *(required)* — The session object obtained from the `useSession` hook. The hook will only compute data when `session.user` is present.
    - **user** `object` — The user object provided by the session context after a successful login.

## Return Value

The hook returns a state object containing various pieces of derived DID information. This object will be updated whenever the `session.user` object changes.

- **did** `string` — The user's permanent DID. This is an alias for `permanentDid`.
- **wallet** `object` — The connected account object where the provider is 'wallet'. Returns `undefined` if no wallet is connected.
  - **did** `string` — The DID of the wallet account.
  - **provider** `string` — The provider name, which will be 'wallet'.
- **walletDid** `string` — The DID of the user's connected wallet. Returns `undefined` if no wallet is connected.
- **permanentDid** `string` — The user's permanent DID, which is the primary identifier from `user.did`.
- **connectedDids** `string[]` — An array of all DIDs from the user's connected accounts.
- **connectedAccounts** `object[]` — The full array of connected account objects.
  - **did** `string` — The DID of the connected account.
  - **provider** `string` — The provider of the account (e.g., 'wallet', 'github').
- **sourceProvider** `string` — The provider the user originally used to log in (e.g., 'wallet', 'github'). Defaults to 'wallet'.
- **sourceProviders** `string[]` — An array of all provider names from the user's connected accounts.

## Standalone Helper Functions

The `useDid` hook is built on a set of exported helper functions. If you don't need the reactive state management of a hook and just want to extract a specific piece of information from a user object, you can import and use these functions directly.

| Function  | Description  |
|---|---|
| `getPermanentDid(user)`  | Extracts the permanent DID from the user object.  |
| `getWalletDid(user)`  | Extracts the DID of the connected wallet.  |
| `getConnectedAccounts(user)`  | Retrieves the array of connected accounts.  |
| `getConnectedDids(user)`  | Retrieves an array of DIDs from all connected accounts.  |
| `getSourceProvider(user)`  | Gets the provider used for the initial login.  |
| `getSourceProviders(user)`  | Gets an array of all connected provider names.  |
| `getWallet(user)`  | Finds and returns the complete wallet account object.  |

### Example: Using a Helper Function

**Direct Function Usage**

```javascript
import { getWalletDid } from '@arcblock/did-connect-react/lib/User/use-did';
import { useSession } from '@arcblock/did-connect-react';

// This approach can be useful inside event handlers or other non-React functions
function handleUserAction() {
  const { session } = useSession();
  if (session.user) {
    const walletDid = getWalletDid(session.user);
    console.log('User Wallet DID:', walletDid);
  }
}
```

---

## useOAuth & usePasskey

URL: https://www.arcblock.io/en/docs/did-connect-react/hooks-use-oauth-passkey-557476/

While the `DidConnect` component and `useConnect` hook provide a comprehensive, pre-built UI for all authentication methods, you may need to build a custom authentication flow. The `useOAuth` and `usePasskey` hooks offer direct access to the underlying logic for social logins (OAuth) and passwordless authentication (Passkey).

These hooks are powerful tools for creating bespoke user experiences. They depend on their respective context providers, `OAuthProvider` and `PasskeyProvider`, which are typically included within the main `SessionProvider`. For more information on session management, see the [SessionProvider documentation](/en/docs/did-connect-react/core-components-session-provider-557476/).

## useOAuth

The `useOAuth` hook provides functions and state for handling third-party social login flows.

### Import

```javascript
import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
```

### Return Value

The hook returns an object containing the following properties and methods:

- **loginOAuth** `function` *(required)* — Initiates a login flow with a specified OAuth provider. It opens a popup for user authorization and returns a promise that resolves with the login result.
- **bindOAuth** `function` *(required)* — Binds a new OAuth account to the currently logged-in user's session.
- **unbindOAuth** `function` *(required)* — Unbinds an OAuth account from the current user's session.
- **getOAuthConfigList** `function` *(required)* — Fetches the list of enabled and configured OAuth providers from the blocklet settings. Returns a promise that resolves to an array of provider configuration objects.
- **switchOAuthPassport** `function` *(required)* — Initiates a flow to switch between different connected accounts (passports) of the same identity.
- **bindAuthLoading** `boolean` *(required)* — A boolean flag that is true while the bindOAuth operation is in progress.
- **unbindAuthLoading** `boolean` *(required)* — A boolean flag that is true while the unbindOAuth operation is in progress.
- **oauthState** `object` *(required)* — An object containing the real-time status of the authentication process.
  - **loading** `boolean` — True if an OAuth operation is in progress.
  - **error** `string` — Contains an error message if the operation failed.
  - **status** `string` — The current status of the flow (e.g., 'scanned', 'succeed', 'error').

### Usage Example

Here's an example of how to build a custom social login component.

**CustomSocialLogin.jsx**

```jsx
import React, { useEffect, useState } from 'react';
import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
import { useSession } from '@arcblock/did-connect-react/lib/Session';

export default function CustomSocialLogin() {
  const { loginOAuth, getOAuthConfigList } = useOAuth();
  const { session } = useSession();
  const [providers, setProviders] = useState([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  useEffect(() => {
    // Fetch the list of available OAuth providers when the component mounts
    getOAuthConfigList().then(setProviders).catch(console.error);
  }, [getOAuthConfigList]);

  const handleLogin = async (provider) => {
    setLoading(true);
    setError('');
    try {
      const result = await loginOAuth({ provider: provider.provider });
      // After successful login, the session will be updated automatically by the SessionProvider.
      console.log('Login successful:', result);
      // You might want to refresh the session or redirect the user here.
    } catch (err) {
      setError(err.message);
      console.error('Login failed:', err);
    } finally {
      setLoading(false);
    }
  };

  if (session.user) {
    return <div>You are already logged in as {session.user.name}.</div>;
  }

  if (providers.length === 0) {
    return <div>No social login methods configured.</div>;
  }

  return (
    <div>
      <h3>Login with Social Media</h3>
      {providers.map((p) => (
        <button key={p.provider} onClick={() => handleLogin(p)} disabled={loading}>
          {loading ? 'Logging in...' : `Login with ${p.provider}`}
        </button>
      ))}
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}
```

## usePasskey

The `usePasskey` hook provides functions and state for handling passwordless authentication using WebAuthn (Passkeys).

### Import

```javascript
import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';
```

### Return Value

The hook returns an object containing the following properties and methods:

- **loginPasskey** `function` *(required)* — Initiates a login flow using an existing Passkey. It triggers the browser's native WebAuthn authentication prompt.
- **connectPasskey** `function` *(required)* — Initiates a flow to create and bind a new Passkey to the current user's session.
- **disconnectPasskey** `function` *(required)* — Unbinds a Passkey from the current user's session after successful verification.
- **switchPassport** `function` *(required)* — Initiates a flow to switch between different connected accounts (passports).
- **connecting** `boolean` *(required)* — A boolean flag that is true while the connectPasskey operation is in progress.
- **disconnecting** `boolean` *(required)* — A boolean flag that is true while the disconnectPasskey operation is in progress.
- **passkeyState** `object` *(required)* — An object containing the real-time status of the Passkey operation.
  - **loading** `boolean` — True if a Passkey operation is in progress.
  - **creating** `boolean` — True during the Passkey creation phase.
  - **verifying** `boolean` — True during the Passkey verification phase.
  - **error** `string` — Contains an error message if the operation failed.
  - **status** `string` — The current status of the flow (e.g., 'scanned', 'succeed', 'error').

### Usage Example

Here's an example of how to create a "Login with Passkey" button.

**PasskeyLoginButton.jsx**

```jsx
import React, { useState } from 'react';
import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';

export default function PasskeyLoginButton() {
  const { loginPasskey, passkeyState } = usePasskey();
  const [error, setError] = useState('');

  const handleLogin = async () => {
    setError('');
    try {
      const result = await loginPasskey();
      console.log('Passkey login successful:', result);
      // The session will be updated automatically by the SessionProvider.
    } catch (err) {
      setError(err.message);
      console.error('Passkey login failed:', err);
    }
  };

  return (
    <div>
      <button onClick={handleLogin} disabled={passkeyState.loading}>
        {passkeyState.loading ? 'Verifying...' : 'Login with Passkey'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}
```

These hooks provide the flexibility to integrate DID Connect's powerful authentication features into any part of your application with a completely custom UI. To learn about programmatically controlling the pre-built `DidConnect` modal, proceed to the [useConnect hook documentation](/en/docs/did-connect-react/hooks-use-connect-557476/).

---

## Overview

URL: https://www.arcblock.io/en/docs/did-connect-react/overview-557476/

The `@arcblock/did-connect-react` library provides a comprehensive set of React components and hooks designed to seamlessly integrate decentralized identity (DID) capabilities into your web applications. It simplifies the process of user authentication and session management using ArcBlock's DID Wallet, offering a secure and user-friendly alternative to traditional login systems.

This library is built to be flexible and easy to use, whether you need a complete out-of-the-box solution or granular control over the authentication flow.

### Key Features

::::card-group
::link-card{title="Complete Connection UI" description="Includes the `DidConnect` component, a pre-built, customizable modal for handling the entire QR code scanning and connection process." icon="qr-code"}
::link-card{title="Seamless Session Management" description="Leverage the `SessionProvider` and `useSession` hook to effortlessly manage user login states, sessions, and profile data throughout your application." icon="key"}
::link-card{title="Flexible Programmatic Control" description="Use hooks like `useConnect` to programmatically open, close, and manage the connection modal, giving you full control over the user experience." icon="link"}
::link-card{title="Rich UI Toolkit" description="A collection of supplementary UI components like `Avatar`, `Address`, and `Button` to display user identity information consistently." icon="star"}
::::

### Core Architecture

The library revolves around a central `SessionProvider` that manages the user's session state. UI components like `Button` can trigger the `DidConnect` modal, which handles the secure, QR-code-based interaction with the user's DID Wallet. Once the connection is complete, the session is updated, and your application's UI reacts accordingly.

It's important to note that `@arcblock/did-connect-react` is a client-side library and requires a corresponding backend service to handle the authentication logic. This service should be built using the [`@arcblock/did-connect-js`](https://www.arcblock.io/docs/did-connect-sdk) library for Node.js.

![Overview](https://media.arcblock.io/lib/f6/f6212a14a8104c75.w1600.webp)

### Installation

To get started, add the library to your project using `yarn` or `npm`.

**Installation**

```shell
# With yarn
yarn add @arcblock/did-connect-react

# With npm
npm install @arcblock/did-connect-react
```

### How It Works: A Quick Look

Here is a minimal example of how to set up a login flow. The application is wrapped in a `SessionProvider`, and a `Button` is used to toggle the `DidConnect` modal.

**App.js**

```jsx
import React from 'react';
import axios from 'axios';
import { SessionProvider, SessionConsumer } from '@arcblock/did-connect-react/lib/Session';
import DidConnect from '@arcblock/did-connect-react/lib/Connect';
import Button from '@arcblock/did-connect-react/lib/Button';

const webWalletUrl = 'https://web.abtwallet.io/';

function App() {
  const [isConnectOpen, setConnectOpen] = React.useState(false);

  const handleClose = () => setConnectOpen(false);
  const handleSuccess = () => {
    // Redirect or update UI after successful login
    window.location.reload();
  };

  return (
    <SessionProvider serviceHost="/">
      <div className="main-content">
        <SessionConsumer>
          {({ session }) => {
            if (session.loading) {
              return <div>Loading session...</div>;
            }

            return session.user ? (
              <div>
                <h2>Welcome, {session.user.did}!</h2>
                <button onClick={() => session.logout()}>Logout</button>
              </div>
            ) : (
              <Button onClick={() => setConnectOpen(true)}>Connect Wallet</Button>
            );
          }}
        </SessionConsumer>
      </div>

      <DidConnect
        popup
        open={isConnectOpen}
        action="login"
        checkFn={axios.get}
        onClose={handleClose}
        onSuccess={handleSuccess}
        messages={{
          title: 'Login to My App',
          scan: 'Scan QR code with your DID Wallet',
          confirm: 'Confirm login on your wallet',
          success: 'You have successfully signed in!',
        }}
        webWalletUrl={webWalletUrl}
      />
    </SessionProvider>
  );
}

export default App;
```

This example demonstrates how to manage user sessions and trigger the login process with just a few components.

### Next Steps

Now that you have a basic understanding of the library, you're ready to dive deeper.

:::action-card{title="Getting Started" description="Follow our step-by-step guide to integrate DID Connect into your own application from scratch." icon="rocket"}
::action{label="Start Building" href="/en/docs/did-connect-react/getting-started-557476/" variant="primary"}
:::

---

## UI Components

URL: https://www.arcblock.io/en/docs/did-connect-react/ui-components-557476/

The `@arcblock/did-connect-react` library includes a set of pre-styled, supplementary UI components designed to help you display DID-related information consistently and beautifully. These components work seamlessly with the core connection flow and are built upon the robust `@arcblock/ux` and `@mui/material` libraries, ensuring a cohesive look and feel in your application.

This section provides an overview of these components. Click on any card to view detailed documentation, including properties and usage examples.

::::card-group
::link-card{title="Avatar" description="A component designed to display a user's avatar, which is automatically derived from their DID." icon="user" href="/en/docs/did-connect-react/ui-components-avatar-557476/"}
::link-card{title="Address" description="Used for displaying a user's DID address in a formatted and optionally shortened manner for better readability." icon="key" href="/en/docs/did-connect-react/ui-components-address-557476/"}
::link-card{title="Button" description="A pre-styled button, specifically the `ConnectButton`, for initiating the DID Connect flow with a consistent design." icon="navigation" href="/en/docs/did-connect-react/ui-components-button-557476/"}
::link-card{title="Logo" description="A simple component to display the official DID Connect logo, useful for branding and UI consistency." icon="box" href="/en/docs/did-connect-react/ui-components-logo-557476/"}
::::

## Combined Usage Example

These components are designed to be composed together to build user interfaces. Here is an example of how you might use `Avatar`, `Address`, and `ConnectButton` to create a simple user profile display.

**Combined UI Example**

```javascript
import Avatar from '@arcblock/did-connect-react/lib/Avatar';
import Address from '@arcblock/did-connect-react/lib/Address';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
import { Box, Typography, Paper } from '@mui/material';

function UserDisplay({ userDid, userName }) {
  if (!userDid) {
    return <ConnectButton />;
  }

  return (
    <Paper elevation={2} sx={{ padding: '16px', display: 'flex', alignItems: 'center', gap: '16px' }}>
      <Avatar size={60} did={userDid} />
      <Box>
        <Typography variant="h6" component="div">{userName || 'Anonymous'}</Typography>
        <Address variant="body2" color="text.secondary">{userDid}</Address>
      </Box>
    </Paper>
  );
}

// Example usage:
// <UserDisplay userDid="z123..." userName="Alice" />
// <UserDisplay userDid={null} />
```

This example demonstrates how easily you can construct a common UI pattern for logged-in and logged-out states using the provided components.

### Next Steps

After familiarizing yourself with the UI components, you may want to explore the library's [Hooks](/en/docs/did-connect-react/hooks-557476/) for more programmatic control over the authentication flow and session data.

---

## Address

URL: https://www.arcblock.io/en/docs/did-connect-react/ui-components-address-557476/

The `Address` component is a specialized UI element designed to display Decentralized Identifier (DID) addresses in a clean, readable, and user-friendly format. It intelligently handles the long strings typical of DIDs by providing options for shortening and easy copying, enhancing the overall user experience.

This component is a simple re-export from `@arcblock/ux/lib/Address`, providing a consistent way to display addresses within the DID Connect ecosystem.

## How to Import

To use the `Address` component, import it from its specific module path within the library.

**Import**

```javascript
import Address from '@arcblock/did-connect-react/lib/Address';
```

## Basic Usage

Simply pass the DID string as a child to the component to render the full address.

**Basic Address Display**

```jsx
import React from 'react';
import Address from '@arcblock/did-connect-react/lib/Address';

function UserProfile() {
  const userDid = 'z1Zg2a5Vw2fA2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t';

  return (
    <div>
      <h4>User DID:</h4>
      <Address>{userDid}</Address>
    </div>
  );
}
```

## Features

The `Address` component includes several helpful features to improve usability.

### Shortening

Long DIDs can clutter the UI. Use the `shorten` prop to display a truncated version of the address, showing only the beginning and end characters. This is essential for lists or compact profile views.

### Copy to Clipboard

By adding the `copyable` prop, the component will render a copy icon next to the address. Clicking this icon copies the full DID to the user's clipboard, providing a convenient one-click action.

## Props

The `Address` component accepts the following props:

- **children** `string` *(required)* — The DID address string that you want to display.
- **shorten** `boolean` (default: `false`) — If true, the address will be shortened to a more compact format (e.g., z1Zg2a...s0t).
- **copyable** `boolean` (default: `false`) — If true, a copy icon is displayed, allowing users to copy the full address to their clipboard with a single click.
- **responsive** `boolean` (default: `true`) — When true, the component will automatically shorten the address based on the available width, ensuring it fits within its container without breaking the layout.

## Examples

Here are some common use cases for the `Address` component.

### Shortened and Copyable Address

This is the most common configuration, providing a compact and functional display suitable for most UIs.

**Shortened and Copyable**

```jsx
import React from 'react';
import Address from '@arcblock/did-connect-react/lib/Address';

function UserCard({ did }) {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <span>DID:</span>
      <Address shorten copyable>
        {did}
      </Address>
    </div>
  );
}
```

### Usage with Avatar

The `Address` component works great alongside the `Avatar` component to build user profile elements.

**Profile Header**

```jsx
import React from 'react';
import Address from '@arcblock/did-connect-react/lib/Address';
import Avatar from '@arcblock/did-connect-react/lib/Avatar';
import { useSession } from '@arcblock/did-connect-react';

function ProfileHeader() {
  const { session } = useSession();

  if (!session.user) {
    return <p>Please log in.</p>;
  }

  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
      <Avatar did={session.user.did} />
      <div>
        <strong>{session.user.name}</strong>
        <Address shorten copyable>
          {session.user.did}
        </Address>
      </div>
    </div>
  );
}
```

Now that you know how to display user addresses, you might want to learn how to display their profile pictures. Check out the [Avatar](/en/docs/did-connect-react/ui-components-avatar-557476/) component documentation for more details.

---

## Avatar

URL: https://www.arcblock.io/en/docs/did-connect-react/ui-components-avatar-557476/

The `Avatar` component is a simple and convenient way to display a user's profile picture. It can automatically generate a unique avatar based on the user's Decentralized Identifier (DID) or display an image from a specified URL.

This component is a direct re-export from the `@arcblock/ux` library, ensuring a consistent look and feel across ArcBlock's ecosystem.

## Import

You can import the `Avatar` component from the library as follows:

```javascript
import Avatar from '@arcblock/did-connect-react/lib/Avatar';
```

## Usage

The most common use case is to display the avatar of the currently logged-in user. You can get the user's information from the `useSession` hook and pass their DID to the `Avatar` component.

**User Profile Example**

```jsx
import React from 'react';
import Avatar from '@arcblock/did-connect-react/lib/Avatar';
import { useSession } from '@arcblock/did-connect-react';

export default function UserProfile() {
  const { session } = useSession();

  if (!session.user) {
    return <div>Loading user...</div>;
  }

  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>
      <Avatar size={64} did={session.user.did} />
      <h3>{session.user.fullName || 'Anonymous User'}</h3>
    </div>
  );
}
```

## Props

The `Avatar` component forwards all its props to the underlying component from `@arcblock/ux`. Below are some of the most commonly used props:

- **did** `string` — The user's DID. If provided, a unique, block-based avatar will be generated. This is the preferred method for displaying avatars for DID users.
- **src** `string` — The URL of a specific image to display. If both src and did are provided, src will take precedence.
- **size** `number` (default: `40`) — The size (width and height) of the avatar in pixels.
- **shape** `'circle' | 'square'` (default: `'circle'`) — Defines the shape of the avatar. Can be either circle or square.
- **variant** `string` (default: `'beam'`) — The algorithm used to generate the avatar from the DID. Common values include beam, pixel, ring, etc.
- **...rest** `any` — Any other standard HTML attributes like className or style can be passed to the root div element of the component.

After displaying the user's avatar, you might also want to show their DID address. Proceed to the next section to learn about the [Address](/en/docs/did-connect-react/ui-components-address-557476/) component.

---

## Button

URL: https://www.arcblock.io/en/docs/did-connect-react/ui-components-button-557476/

The `ConnectButton` component offers a pre-styled and recognizable button for initiating the DID Connect authentication process. It simplifies creating a consistent user experience for your application's login flow. The button is styled with the official DID Connect branding, including the logo and color scheme, providing a clear call-to-action for users.

## Import

To use the button, import it from the library's `Button` module.

```javascript
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
```

## Basic Usage

The most common use case is to pair the `ConnectButton` with the `useConnect` hook. The `onClick` prop of the button can be directly mapped to the `open` function returned by the hook to trigger the connection modal.

**Basic Usage**

```javascript
import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';

export default function MyLoginComponent() {
  const { open } = useConnect();

  return (
    <ConnectButton onClick={open} />
  );
}
```

By default, the button renders with the text "Continue With" followed by the DID Connect logo.

## Customization

You can easily customize the button's appearance and behavior.

### Custom Text

To change the default text, simply pass your desired content as children to the component.

**Customizing Button Text**

```javascript
import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';

export default function CustomLoginComponent() {
  const { open } = useConnect();

  return (
    <ConnectButton onClick={open}>
      Login with DID Wallet
    </ConnectButton>
  );
}
```

### Additional Props

The `ConnectButton` is a wrapper around the `@arcblock/ux/lib/Button` component (which is based on Material-UI's Button) and accepts all of its standard props. This allows for extensive customization, such as disabling the button, making it full-width, or applying custom styles with the `sx` prop.

**Passing Additional Props**

```javascript
import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';

export default function DisabledButtonComponent() {
  const { open } = useConnect();

  // Example: disable the button while a process is running
  const isLoading = true;

  return (
    <ConnectButton
      onClick={open}
      disabled={isLoading}
      fullWidth
      sx={{ mt: 2, mb: 2 }}
    >
      {isLoading ? 'Connecting...' : 'Login with DID Wallet'}
    </ConnectButton>
  );
}
```

## Props

- **children** `React.ReactNode` — The content to display inside the button. If not provided, it defaults to "Continue With".
- **...rest** `ButtonProps` — The ConnectButton accepts any other props that are valid for the underlying Material-UI Button component. This includes common props like onClick, disabled, variant, color, fullWidth, and sx.

## Next Steps

Now that you know how to add a `ConnectButton`, the next logical step is to understand the hook that powers its functionality.

::link-card{title="useConnect Hook" description="Learn how to programmatically open, close, and manage the DidConnect UI modal using the useConnect hook." icon="link" href="/en/docs/did-connect-react/hooks-use-connect-557476/"}

---

## Logo

URL: https://www.arcblock.io/en/docs/did-connect-react/ui-components-logo-557476/

The `Logo` component provides a simple and consistent way to display the official DID Connect logo within your application. It's a straightforward visual component designed for brand representation, ensuring your users recognize the familiar decentralized identity connection method.

## Usage

To use the component, simply import it and include it in your JSX. You can control its size using the `size` prop.

**MyHeader.js**

```jsx
import React from 'react';
import Logo from '@arcblock/did-connect-react/lib/Logo';

export default function AppHeader() {
  return (
    <header style={{ display: 'flex', alignItems: 'center', padding: '16px', borderBottom: '1px solid #eee' }}>
      <Logo size={40} />
      <h1 style={{ marginLeft: '12px', fontSize: '24px' }}>My Application</h1>
    </header>
  );
}
```

## Props

The `Logo` component is a wrapper around an SVG element and accepts the following props:

- **size** `number` (default: `24`) — Sets both the width and height of the logo in pixels.
- **...rest** `any` — Any other props are passed directly to the underlying SVG element, allowing for customization with attributes like `className` or `style`.

## When to Use

- In the header or footer of your application to show that it's powered by DID Connect.
- On login or connection screens, often placed near the `Button` or within the `DidConnect` modal for brand consistency.
- On informational or "About" pages that describe the authentication methods available.

## Next Steps

After adding the `Logo`, explore other UI components to complete your user interface:

::::card-group
::link-card{title="Button" description="Use the pre-styled Button component to trigger the DID Connect flow." icon="navigation" href="/en/docs/did-connect-react/ui-components-button-557476/"}
::link-card{title="Avatar" description="Display a user's profile picture after they have successfully logged in." icon="user" href="/en/docs/did-connect-react/ui-components-avatar-557476/"}
::link-card{title="Address" description="Show the user's decentralized identifier (DID) in a formatted and readable way." icon="fingerprint" href="/en/docs/did-connect-react/ui-components-address-557476/"}
::::

---

## DID Connect SDK (Node.js)

URL: https://www.arcblock.io/en/docs/did-connect-sdk/

---

## API Reference

URL: https://www.arcblock.io/en/docs/did-connect-sdk/api-reference-b5860f/

This section provides detailed documentation of the core classes, constructors, methods, and options available in the DID Connect SDK. Understanding these components is key to building robust and secure authentication flows for your application.

The SDK is primarily composed of two main classes that work together to handle the entire DID Connect workflow:

- <strong>WalletAuthenticator</strong>: The low-level engine that handles the creation, signing, and verification of cryptographic messages exchanged between your application and the user's DID Wallet.
- <strong>WalletHandlers</strong>: A high-level utility for Express.js servers that sets up the necessary API endpoints and manages the session state, simplifying the integration process.

Explore the detailed documentation for each class to understand their full capabilities.

::::card-group
::link-card{title="WalletAuthenticator" description="The core class for creating and verifying authentication requests and responses. It manages cryptographic operations, claim generation, and communication with the DID Wallet." icon="key" href="/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/"}
::link-card{title="WalletHandlers" description="A convenience class for integrating DID Connect into an Express.js or similar web server framework. It automates the setup of required API endpoints and manages the session lifecycle." icon="routes" href="/en/docs/did-connect-sdk/api-reference-wallet-handlers-b5860f/"}
::::

We recommend starting with the [WalletAuthenticator](/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/) documentation to grasp the fundamental concepts of the protocol before moving on to the `WalletHandlers` for web integration.

---

## WalletAuthenticator

URL: https://www.arcblock.io/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/

The `WalletAuthenticator` is the core class for server-side logic in a DID Connect session. It is responsible for creating authentication requests, signing responses, and verifying the data returned from the user's wallet. It operates independently of any specific web framework, handling all the cryptographic operations and JWT management.

For integrating DID Connect into an Express.js application, see the [WalletHandlers](/en/docs/did-connect-sdk/api-reference-wallet-handlers-b5860f/) class, which builds upon `WalletAuthenticator`.

## Constructor

### new WalletAuthenticator(config)

Creates a new instance of the `WalletAuthenticator`. This is the entry point for setting up your application's identity and configuration for DID Connect.

**Authenticator Setup**

```javascript
const { WalletAuthenticator } = require('@arcblock/did-connect');
const { fromRandom } = require('@ocap/wallet');

// The application's wallet
const appWallet = fromRandom().toJSON();
const chainHost = 'https://beta.abtnetwork.io/api';
const chainId = 'beta';

const auth = new WalletAuthenticator({
  wallet: appWallet,
  baseUrl: 'https://example.com',
  appInfo: {
    name: 'DID Connect Demo',
    description: 'A demo application for DID Connect',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
    link: 'https://example.com'
  },
  chainInfo: {
    host: chainHost,
    id: chainId,
  },
});
```

<strong>Parameters</strong>

- **wallet** `WalletObject | Function` *(required)* — The application's wallet instance or a function that returns one. This wallet is used to sign all communications with the user's wallet.
- **appInfo** `ApplicationInfo | Function` *(required)* — An object or function that returns the application's basic information (name, description, icon, etc.) to be displayed in the user's wallet.
- **chainInfo** `ChainInfo | Function` — Information about the blockchain the application is connected to. Can be an object or a function that returns one. Defaults to a 'none' chain.
- **delegator** `WalletObject | Function` — The wallet that authorizes `config.wallet` to act on its behalf. Used for delegated authentication flows.
- **delegation** `string | Function` — The JWT token that proves the delegation relationship between `delegator` and `wallet`.
- **baseUrl** `string` — The base URL for constructing callback URLs. Can often be inferred from the request object in a web server context.
- **timeout** `number` (default: `8000`) — Timeout in milliseconds for generating claims.
- **tokenKey** `string` (default: `_t_`) — The query parameter key used for the session token.

## Methods

### uri()

Generates a deep link URL that can be rendered as a QR code for the DID Wallet to scan and initiate a session.

**Generating a Connect URL**

```javascript
const connectUrl = auth.uri({
  baseUrl: 'https://example.com',
  pathname: '/api/connect/relay/auth',
  token: 'some_session_token',
  query: { userAction: 'login' },
});

// connectUrl will be similar to:
// https://abtwallet.io/i/?action=requestAuth&url=https%3A%2F%2Fexample.com%2Fapi%2Fconnect%2Frelay%2Fauth%3FuserAction%3Dlogin%26_t_%3Dsome_session_token
```

<strong>Parameters</strong>

- **params** `object` — An object containing the parameters for the URI.
  - **baseUrl** `string` — The base URL from which the callback URL will be constructed.
  - **pathname** `string` — The path for the wallet callback endpoint.
  - **token** `string` — The unique session token for this authentication action.
  - **query** `object` (default: `{}`) — An object of additional query parameters to persist in the callback URL.

<strong>Returns</strong>

- **** `string` — A deep link URL for DID Wallet.

### sign()

Signs an authentication request to be sent to the wallet. This JWT-formatted response contains the application's info, chain info, and the specific claims being requested from the user.

**Signing an Auth Request**

```javascript
const authResponse = await auth.sign({
  claims: { profile: { items: ['fullName', 'email'] } }, // Requesting user's name and email
  pathname: '/api/connect/relay/auth',
  baseUrl: 'https://example.com',
  challenge: 'random_challenge_string',
  context: { token: 'some_session_token' },
});

// authResponse contains { appPk, authInfo, ... }
```

<strong>Parameters</strong>

- **params** `object` *(required)* — Parameters for signing the authentication request.
  - **claims** `object` *(required)* — An object defining the information required from the user's wallet. See Claims Reference for details.
  - **pathname** `string` — The pathname to assemble the callback URL.
  - **baseUrl** `string` — The base URL for the callback.
  - **challenge** `string` — A random challenge string to prevent replay attacks.
  - **context** `object` *(required)* — An object containing session context.
    - **token** `string` *(required)* — The session token.
    - **userDid** `string` — The user's DID.
    - **userPk** `string` — The user's public key.
    - **sharedKey** `string` — Shared key between app and wallet for sensitive claims.
    - **encryptionKey** `string` — Encryption key from the wallet.
  - **request** `object` — The original request object from the web server, if available.

<strong>Returns</strong>

- **** `Promise<object>` — A promise that resolves to an object containing the signed `authInfo` (JWT), the application's public key `appPk`, and other relevant keys like `agentPk` or `sharedKey`.

### signResponse()

Signs a simple, final response to the wallet, typically used after a successful operation or to report an error. This response can optionally redirect the user's wallet to a new URL.

**Signing a Success Response**

```javascript
const successResponse = await auth.signResponse({
  successMessage: 'Login successful!',
  nextUrl: 'https://example.com/dashboard',
}, 'https://example.com', requestContext);

// This response can be sent back to the wallet.
```

<strong>Parameters</strong>

- **params** `object` *(required)* — Parameters for the response.
  - **successMessage** `string` — A message to display in the wallet on success.
  - **errorMessage** `string` — A message to display in the wallet on error.
  - **nextUrl** `string` — A URL to open in the wallet's webview after the message is displayed.
  - **nextWorkflow** `string` — A URL to another DID Connect workflow to chain multiple requests together.
  - **response** `object` — Any additional JSON data to be included in the response.
  - **cookies** `object` — Key-value pairs to be set as cookies before opening `nextUrl`.
  - **storages** `object` — Key-value pairs to be set as localStorage before opening `nextUrl`.

<strong>Returns</strong>

- **** `Promise<object>` — A promise that resolves to an object containing the signed `authInfo` and `appPk`.

### verify()

Verifies a response sent from the DID Wallet. It checks the signature using the user's public key and decodes the JWT to extract the claims and other session information.

**Verifying a Wallet Response**

```javascript
try {
  const walletResponse = {
    userPk: 'user_public_key_from_wallet',
    userInfo: 'jwt_token_from_wallet',
    token: 'the_original_session_token'
  };

  const verificationResult = await auth.verify(walletResponse);

  console.log('Verification successful!');
  console.log('User DID:', verificationResult.userDid);
  console.log('Requested Claims:', verificationResult.claims);
} catch (error) {
  console.error('Verification failed:', error.message);
}
```

<strong>Parameters</strong>

- **data** `object` *(required)* — An object containing the `userPk` and `userInfo` (the JWT) from the wallet's response.
- **locale** `string` (default: `en`) — The locale for error messages.
- **enforceTimestamp** `boolean` (default: `true`) — Whether to enforce the JWT's timestamp validity. Set to `false` to debug time-sync issues.

<strong>Returns</strong>

- **** `Promise<object>` — A promise that resolves to a decoded object.
  - **token** `string` — The original session token.
  - **userDid** `string` — The DID of the authenticated user.
  - **userPk** `string` — The public key of the authenticated user.
  - **claims** `array` — An array of claims fulfilled by the user.
  - **challenge** `string` — The original challenge string.
  - **timestamp** `number` — The issuance timestamp of the JWT.

## Type Definitions

### ApplicationInfo

This object defines the information about your application that is displayed to the user in their DID Wallet during a connect session.

- **name** `string` *(required)* — The name of your application.
- **description** `string` *(required)* — A brief description of your application.
- **icon** `string` *(required)* — A URL to your application's logo.
- **link** `string` — A link to your application's home page, allowing the user to return from their wallet.
- **publisher** `string` — The DID of the application publisher. Automatically set to the application wallet's DID if not provided.
- **path** `string` (default: `https://abtwallet.io/i/`) — The deep link URL prefix for the wallet.

### ChainInfo

This object specifies the blockchain that your application interacts with.

- **id** `string` *(required)* — The ID of the chain (e.g., 'beta', 'main'). For EVM chains, this is the Chain ID number.
- **host** `string` *(required)* — The GraphQL endpoint for ArcBlock chains, or a JSON-RPC endpoint for EVM chains.
- **type** `string` (default: `arcblock`) — The type of blockchain. Can be 'arcblock', 'ethereum', etc.

Now that you understand how to create and manage authentication logic, the next step is to integrate it into a web server. Proceed to the [WalletHandlers API Reference](/en/docs/did-connect-sdk/api-reference-wallet-handlers-b5860f/) to learn how to attach DID Connect endpoints to an Express.js application.

---

## WalletHandlers

URL: https://www.arcblock.io/en/docs/did-connect-sdk/api-reference-wallet-handlers-b5860f/

The `WalletHandlers` class is a high-level utility designed to seamlessly integrate the DID Connect workflow into an Express.js or similar server-side framework. It automates the setup of all required API endpoints for a given action, handling the communication between your application and the user's DID Wallet.

It works in tandem with the [`WalletAuthenticator`](/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/), which manages the cryptographic signing and verification of messages. Since `WalletHandlers` is built on Node.js's `EventEmitter`, you can listen for various lifecycle events as the session state changes in your token storage.

## Constructor

Creates an instance of the DID Connect handlers. This instance orchestrates the handling of HTTP requests for the DID Connect process.

**DID Connect Handler Setup**

```javascript
const { WalletHandlers } = require('@did-connect/handler');
const { WalletAuthenticator } = require('@did-connect/authenticator');
const { FileStorage } = require('@did-connect/storage-file');

// 1. Initialize the authenticator with your app's wallet and info
const authenticator = new WalletAuthenticator({ wallet, appInfo, chainInfo });

// 2. Initialize a storage adapter to manage session state
const tokenStorage = new FileStorage({ dbPath: './sessions.json' });

// 3. Create the handlers instance
const handlers = new WalletHandlers({
  authenticator,
  tokenStorage,
});
```

### Parameters

- **config** `object` *(required)* — Configuration object for the WalletHandlers instance.
  - **authenticator** `WalletAuthenticator` *(required)* — An instance of `WalletAuthenticator` responsible for cryptographic operations.
  - **tokenStorage** `object` *(required)* — A token storage instance that handles session state (e.g., `FileStorage`, `MongoStorage`).
  - **pathTransformer** `function` — An optional function to transform the URL pathname for the wallet callback, useful in proxy or complex routing scenarios.
  - **onConnect** `function` — An optional global callback executed when a wallet scans the QR code, before the auth request is sent. It can be used for global permission checks. Throws an error to halt the process.
  - **options** `object` — An optional object to customize the behavior of the handlers.
    - **prefix** `string` (default: `/api/did`) — The URL prefix for all generated endpoints.
    - **cleanupDelay** `number` (default: `60000`) — The time in milliseconds to wait before cleaning up a completed session from storage.
    - **tokenKey** `string` (default: `_t_`) — The query parameter key for the session token.
    - **encKey** `string` (default: `_ek_`) — The query parameter key for the encryption key.
    - **versionKey** `string` (default: `_v_`) — The query parameter key for the protocol version.

## Methods

### attach(config)

This is the primary method of the `WalletHandlers` class. It attaches the necessary DID Connect routes to your Express app for a specific user action (e.g., 'login', 'payment'). This method creates a full set of endpoints to handle the entire connection lifecycle, from token generation to wallet response handling.

Once attached, the following routes are created for the given `action`:

- `GET {prefix}/{action}/token`: Creates a new session token.
- `POST {prefix}/{action}/token`: Creates a new session token.
- `GET {prefix}/{action}/status`: Checks the status of a session token (e.g., pending, scanned, approved).
- `GET {prefix}/{action}/timeout`: Manually expires a session token.
- `GET {prefix}/{action}/auth`: The endpoint for the wallet to fetch authentication requirements.
- `POST {prefix}/{action}/auth`: The endpoint for the wallet to submit the signed response.

#### Parameters

- **config** `object` *(required)* — Configuration object for attaching the routes.
  - **app** `object` *(required)* — The Express app instance.
  - **action** `string` *(required)* — A unique name for this workflow (e.g., 'login', 'claim-asset'). This becomes part of the URL.
  - **onAuth** `function` *(required)* — The callback executed after the user successfully completes the flow in their wallet. This is where you handle the verified data.
  - **claims** `object[]` — An optional array of claims to request from the user (e.g., profile, signature).
  - **onStart** `function` — An optional callback executed when a new session is started.
  - **onConnect** `function` — An optional callback executed when the wallet scans the code. It overrides the constructor's `onConnect` for this specific action.
  - **onDecline** `function` — An optional callback executed if the user declines the request in their wallet.
  - **onComplete** `function` — An optional callback executed after the entire workflow is finished and the session token is destroyed.
  - **onExpire** `function` — An optional callback for when the session token expires.
  - **onError** `function` (default: `console.error`) — An optional callback for handling any errors during the process.
  - **authPrincipal** `boolean | string` (default: `true`) — Whether to request an `authPrincipal` claim first to establish the user's DID.
  - **persistentDynamicClaims** `boolean` (default: `false`) — Whether to persist dynamically generated claims in the session storage.

#### Example

**Attach Login Handler**

```javascript
const express = require('express');
// ... setup for authenticator and tokenStorage from the constructor example

const app = express();
const handlers = new WalletHandlers({ authenticator, tokenStorage });

handlers.attach({
  app,
  action: 'login',
  claims: [{ type: 'profile' }], // Request user's profile
  onAuth: async ({ userDid, claims }) => {
    // Core logic after a successful login.
    // Find or create a user in your database with userDid.
    const profile = claims.find(x => x.type === 'profile');
    console.log(`User ${userDid} logged in with name: ${profile.fullName}.`);
    // You can now set a cookie or JWT for the user's web session.
  },
  onComplete: ({ token }) => {
    console.log(`Session ${token} completed and cleaned up.`);
  },
  onError: ({ error }) => {
    console.error('An error occurred in the login flow:', error);
  }
});

app.listen(3000, () => {
  console.log('DID Connect server is running on port 3000');
});
```

## Events

Since `WalletHandlers` extends `EventEmitter` and listens to the `tokenStorage` instance, you can subscribe to events to monitor the session lifecycle. This is particularly useful for providing real-time feedback to the user, for example, by using WebSockets to update the UI when a QR code is scanned.

| Event  | Payload  | Description  |
|---|---|---|
| `created`  | `object`  | Emitted when a new session token is created. The payload contains the token and initial session data.  |
| `updated`  | `object`  | Emitted when a session is updated. The payload includes the updated session data. A common use is to check for `status: 'scanned'`.  |
| `deleted`  | `object`  | Emitted when a session token is destroyed, either upon completion, expiration, or manual timeout. The payload contains the token that was removed.  |

### Example

**Listening to Session Events**

```javascript
// Assuming 'io' is a Socket.IO server instance attached to your Express app
handlers.on('updated', (payload) => {
  // Notify the specific web client that the QR code has been scanned
  if (payload.status === 'scanned') {
    console.log(`Wallet scanned token: ${payload.token}`);
    // The 'sid' (socket ID) should be stored in the session when it's created
    if (payload.sid) {
      io.to(payload.sid).emit('wallet_scanned');
    }
  }
});

handlers.on('deleted', ({ token }) => {
  console.log(`Token ${token} was deleted from storage.`);
});
```

::::card-group
::link-card{title="Next Step: WalletAuthenticator" description="Dive into the WalletAuthenticator to see how requests and responses are cryptographically managed." icon="key" href="/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/"}
::link-card{title="View Example: Simple Login" description="See a complete, end-to-end implementation of a user login flow." icon="arrow-right" href="/en/docs/did-connect-sdk/examples-simple-login-b5860f/"}
::::

---

## Agreement Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-agreement-b5860f/

The Agreement Claim is a powerful tool for obtaining explicit user consent for documents like Terms of Service, Privacy Policies, or any other formal agreement. Instead of a simple checkbox, this claim requires the user to cryptographically sign a hash (digest) of the document, creating a verifiable and non-repudiable record of their consent.

This process ensures that the user agrees to the <em>exact</em> version of the document you presented, as the DID Wallet independently verifies the document's integrity before requesting the user's signature.

## How It Works

The workflow for an Agreement Claim is designed for security and transparency:

::::steps
:::step{title="Application Side"}
Your application provides the wallet with a URL (`uri`) where the document is hosted and a pre-calculated cryptographic hash (`digest`) of that document's content.
:::

:::step{title="Wallet Side"}
The user's DID Wallet receives the request.
:::

:::step{title="Verification"}
The wallet fetches the document from the provided `uri`, calculates its hash using the same `method` (e.g., SHA256), and compares it to the `digest` sent by your application.
:::

:::step{title="User Consent"}
If the hashes match, the wallet displays the document and a confirmation prompt to the user. If they don't match, the wallet warns the user of a potential discrepancy, protecting them from bait-and-switch attacks.
:::

:::step{title="Signature"}
Upon user approval, the wallet signs the verified digest with the user's private key.
:::

:::step{title="Response"}
The resulting signature is sent back to your application as proof of agreement.
:::
::::

![Agreement Claim](https://media.arcblock.io/lib/45/4593da9653fc7572.w1600.webp)

## Parameters

The `agreement` claim object accepts the following parameters:

| Parameter  | Type  | Description  |
|---|---|---|
| `uri`  | string  | <strong>Required</strong>. The URL of the document (e.g., Terms of Service) that the user needs to review and agree to. Must be an `http` or `https` URL.  |
| `digest`  | string  | <strong>Required</strong>. The cryptographic hash (digest) of the document's content. The wallet will verify this digest against the document at the `uri` before asking for a signature.  |
| `method`  | string  | <em>Optional</em>. The hashing algorithm used to create the digest. Defaults to `sha2`. Supported methods include `sha2`, `sha3`, and `keccak`.  |
| `description`  | string  | <em>Optional</em>. A custom message displayed to the user in the wallet, explaining what they are agreeing to. Defaults to "Confirm your agreement to continue.".  |

## Example: Requesting Agreement to Terms of Service

Here's how you can configure `WalletHandlers` to request a user's agreement to a Terms of Service document. You would first need to generate a SHA256 hash of your `terms.txt` file.

**Requesting User Agreement**

```javascript
const { WalletHandlers } = require('@arcblock/did-connect');

// You can generate this digest using a command like:
// shasum -a 256 path/to/your/terms.txt
const termsDigest = 'f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2';

const handlers = new WalletHandlers({
  chainInfo: { host: 'https://beta.abtnetwork.io/api' },
  appInfo: {
    name: 'My App',
    description: 'My App Description',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
    link: 'https://my-app.com',
  },
  claims: {
    agreement: {
      description: 'Please read and agree to our new Terms of Service to proceed.',
      uri: 'https://my-app.com/terms.txt',
      method: 'sha2',
      digest: termsDigest,
    },
  },
  onAuth: async ({ claims, userDid }) => {
    // The claims array will contain the agreement claim response
    const agreementClaim = claims.find(c => c.type === 'agreement');
    console.log(`${userDid} agreed and signed with digest:`, agreementClaim.sig);

    // You can now verify the signature against the user's DID and the original digest
  },
});
```

In the `onAuth` callback, you receive the `sig` field, which is the user's signature over the document digest. You can store this signature along with the user's DID as a durable, verifiable record of their consent.

## Next Steps

After securing user agreement, you might need to verify specific attributes or qualifications they possess. Learn how to do this by requesting a Verifiable Credential.

:::action-card{title="Verifiable Credential Claim" description="Request the user to present a Verifiable Credential (VC) to prove an attribute or qualification." icon="file"}
::action{label="Read More" href="/en/docs/did-connect-sdk/claims-verifiable-credential-b5860f/" variant="primary"}
:::

---

## Asset Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-asset-b5860f/

The Asset Claim is used to request that a user present proof of ownership for a specific on-chain digital asset, such as a Non-Fungible Token (NFT). This is particularly useful for scenarios like NFT-gated access, where entry to a service or content is restricted to owners of a particular asset.

This claim allows your application to verify asset ownership by specifying various criteria, including the asset's address, its issuer, or its parent collection.

For more general requests that can accept either an asset or a Verifiable Credential, see the [Asset or VC Claim](/en/docs/did-connect-sdk/claims-asset-or-vc-b5860f/).

## How It Works

When you request an Asset Claim, DID Connect prompts the user to select a qualifying asset from their wallet. The wallet filters the user's assets based on the criteria you define in the claim request. Once the user selects and presents a valid asset, your application receives its details for verification.

## Parameters

The `asset` claim is configured using an object with the following properties. The core of the request is the `filters` array, which allows you to define one or more sets of criteria.

| Parameter  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | <strong>Required.</strong> A message displayed to the user explaining why they need to present the asset.  |
| `optional`  | `boolean`  | If `true`, the user can skip this claim. Defaults to `false`.  |
| `filters`  | `Array<Object>`  | An array of filter objects. The wallet will find assets that match <strong>any</strong> of the filters (OR logic).  |
| `acquireUrl`  | `string`  | An optional URL where the user can go to obtain the required asset if they don't already own one.  |

### Filter Object Properties

Each object within the `filters` array can contain the following properties. All properties within a single filter are combined with AND logic.

| Property  | Type  | Description  |
|---|---|---|
| `address`  | `string`  | The specific DID address of the asset.  |
| `trustedIssuers`  | `Array<string \| Object>`  | A list of DIDs of trusted asset issuers. An issuer can be a simple DID string or an object `{ did: string, endpoint: string }`.  |
| `trustedParents`  | `Array<string>`  | A list of DIDs of trusted parent assets. This is commonly used to verify if an NFT belongs to a specific collection.  |
| `tag`  | `string`  | A specific tag that must be associated with the asset.  |
| `ownerDid`  | `Array<string>`  | An array of DIDs. The asset's owner must be one of the DIDs in this list.  |
| `consumed`  | `boolean`  | Specifies whether the asset must be in a consumed (`true`) or unconsumed (`false`) state.  |

## Requesting an Asset

Here are some examples of how to structure an `asset` claim request within the `claims` object passed to the authenticator.

### Example 1: Gating Access with an NFT Collection

This example requests any asset whose parent is a specific NFT collection DID. This is a common way to grant access to holders of a particular NFT project.

**Requesting an NFT from a specific collection**

```javascript
const claims = {
  asset: {
    description: 'Please present your Membership NFT to access the private community.',
    filters: [
      {
        // The parent DID of the NFT collection
        trustedParents: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
    ],
    acquireUrl: 'https://example.com/mint-nft',
  },
};

// In your route handler
const { authInfo } = await authenticator.sign({ context, claims });
```

### Example 2: Requesting a Specific Asset by Address

If you need the user to present a very specific asset, you can filter by its unique address.

**Requesting a specific asset by its address**

```javascript
const claims = {
  asset: {
    description: 'Please present your Golden Ticket NFT to proceed.',
    filters: [
      {
        // The unique DID address of the Golden Ticket NFT
        address: 'zjddPDAK5rm1E4syjTkgoiskGBAfve5YYN2s',
      },
    ],
  },
};
```

### Example 3: Using Multiple Filters

You can provide multiple filter objects to give the user more options. In this example, the user can present either an asset from a trusted issuer OR an asset from a trusted collection.

**Using multiple filters for more flexibility**

```javascript
const claims = {
  asset: {
    description: 'Present an asset from our official issuer or a partner collection.',
    optional: true, // Making this optional
    filters: [
      {
        // Option 1: Asset from a trusted issuer
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
        tag: 'official-badge',
      },
      {
        // Option 2: Asset from a partner NFT collection
        trustedParents: ['z9f9aE3E6d4c4b2A1c8f8b6e2d0F0g2H2i4j6k8m'],
      },
    ],
  },
};
```

## Wallet Response

If the user successfully presents a valid asset, the `onAuth` or `onConnect` callback in your handler will receive the asset details. The presented asset will be included in the `claims` array of the session context.

You can access it like this:

**Handling the wallet response**

```javascript
const handlers = new WalletHandlers({
  authenticator,
  // ...other handlers
  onAuth: async (req, res) => {
    const { userDid, claims } = req.context.did_connect;

    // Find the presented asset claim in the response
    const presentedAsset = claims.find(x => x.type === 'asset');

    if (presentedAsset) {
      console.log(`User ${userDid} presented asset:`, presentedAsset.asset);
      // The `presentedAsset.asset` will contain the full details of the presented NFT
      // e.g., its address, issuer, owner, etc.
    } else {
      console.log('User did not present the required asset.');
    }

    res.redirect('/profile');
  },
});
```

Next, explore how to request a Verifiable Credential, another powerful way to verify user attributes.

:::action-card{title="Verifiable Credential Claim" description="Requesting the user to present a Verifiable Credential (VC) to prove an attribute or qualification." icon="file"}
::action{label="Read More" href="/en/docs/did-connect-sdk/claims-verifiable-credential-b5860f/" variant="primary"}
:::

---

## Asset or VC Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-asset-or-vc-b5860f/

The `assetOrVC` claim provides a flexible way to request that a user present proof of ownership of either an on-chain asset (like an NFT) or a Verifiable Credential (VC) that meets a specified set of criteria. This is particularly useful for scenarios requiring flexible access control, where multiple forms of qualification are acceptable.

For more specific requests, you can refer to the [Asset Claim](/en/docs/did-connect-sdk/claims-asset-b5860f/) or [Verifiable Credential Claim](/en/docs/did-connect-sdk/claims-verifiable-credential-b5860f/) documentation.

## How It Works

The core of the `assetOrVC` claim is the `filters` array. This array allows you to define one or more sets of conditions. The logic for evaluating these filters is as follows:

- <strong>OR Logic between Filters</strong>: The wallet evaluates each filter object in the `filters` array independently. The user only needs to present an asset or VC that satisfies the conditions of <strong>at least one</strong> of these filter objects.
- <strong>AND Logic within a Filter</strong>: Within a single filter object, all specified properties (e.g., `trustedIssuers`, `tag`) must be met by the presented asset or VC.
- <strong>OR Logic for Array Values</strong>: For properties that accept an array of values (like `type` or `trustedIssuers`), the presented item only needs to match one of the values in the array.

## Parameters

The `assetOrVC` claim object is configured with the following parameters:

| Parameter  | Type  | Description  | Default  |
|---|---|---|---|
| `type`  | `string`  | The type of the claim. Must be `assetOrVC`.  | `'assetOrVC'`  |
| `description`  | `string`  | A message displayed to the user in their wallet, explaining what is being requested.  | `'Please present NFT to continue.'`  |
| `optional`  | `boolean`  | If `true`, the user can choose to skip this claim request without terminating the session.  | `false`  |
| `filters`  | `object[]`  | <strong>Required.</strong> An array of filter objects defining the acceptable criteria for the asset or VC.  | `[]`  |

### Filter Object Parameters

Each object within the `filters` array can contain the following properties to specify the required criteria:

| Parameter  | Type  | Description  |
|---|---|---|
| `type`  | `string[]`  | <strong>VC Only.</strong> An array of acceptable VC type names (e.g., `['ProofOfCommunity']`).  |
| `address`  | `string`  | The DID address of a specific asset or VC.  |
| `trustedIssuers`  | `string[]`  | A list of trusted issuer DIDs for the asset or VC.  |
| `trustedParents`  | `string[]`  | <strong>Asset Only.</strong> A list of trusted parent DIDs (e.g., an NFT collection address).  |
| `tag`  | `string`  | A specific tag that must be present on the asset or VC.  |
| `ownerDid`  | `string[]`  | An array of DIDs. The wallet must prove it controls one of these DIDs and owns the asset/VC. Defaults to the connected user's DID.  |
| `consumed`  | `boolean`  | <strong>Asset Only.</strong> Specifies whether the asset must be in a `consumed` or `unconsumed` state.  |
| `claimUrl`  | `string`  | <strong>VC Only.</strong> A URL where the wallet can find more information about the required credential.  |
| `acquireUrl`  | `string`  | <strong>Asset Only.</strong> A URL where the user can go to acquire the asset if they don't already have it.  |

## Example

Imagine you want to grant access to a premium event. Access is granted to users who either hold a "VIP Ticket" NFT or a "VerifiedMember" credential. You can construct an `assetOrVC` claim like this:

**DID Connect Claim Request**

```javascript
const claims = {
  assetOrVC: {
    description: 'Please present your VIP Ticket or Membership Credential to enter.',
    filters: [
      // Condition 1: User has a VIP Ticket NFT from our official collection
      {
        trustedParents: ['zNKoA8Y4m1a3b5C7E9F1G3H5J7K9L1M3N5'], // The DID of the NFT collection
        tag: 'VIP_TICKET_2024',
        acquireUrl: 'https://example.com/buy-ticket'
      },
      // Condition 2: User has a VerifiedMember credential from a trusted partner
      {
        type: ['VerifiedMember'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'] // The DID of the trusted partner
      }
    ]
  }
};
```

In this example:

- The user's wallet will first look for an asset that belongs to the `trustedParents` collection AND has the tag `VIP_TICKET_2024`.
- If no such asset is found, it will then look for a Verifiable Credential of type `VerifiedMember` issued by the specified `trustedIssuers`.
- If the user has an item that matches either condition, they can present it to satisfy the claim. If they have neither, the wallet might show them the `acquireUrl` to get a ticket.

This flexible claim is a powerful tool for building sophisticated access control systems. To see it in a practical application, check out the [NFT Gated Access](/en/docs/did-connect-sdk/examples-nft-gate-b5860f/) example.

---

## Auth Principal Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-auth-principal-b5860f/

The `authPrincipal` claim is the cornerstone of any DID Connect session. It is the most fundamental and commonly used claim, designed to ask the user to connect their wallet and select a Decentralized Identifier (DID) to interact with your application. This initial step establishes a secure session and provides the application with the user's primary DID, upon which all subsequent interactions are built.

Think of it as the "Log in with Wallet" button. It doesn't ask for specific personal data, but simply for the user to identify themselves by choosing an account.

## When to Use

You should use the `authPrincipal` claim as the first step in almost any workflow that requires user interaction, including:

- <strong>User Login:</strong> The most basic use case, allowing users to sign in to your application.
- <strong>Session Initiation:</strong> Starting a multi-step process where you'll later request more specific information or actions (e.g., signing a transaction or presenting a credential).
- <strong>Establishing Context:</strong> When you need to know the user's DID to personalize the user experience or check for existing data associated with that DID.

## Parameters

The `authPrincipal` claim can be configured with the following parameters to tailor the request to your needs.

| Parameter  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | <strong>Required.</strong> A message displayed to the user in their wallet, explaining why they are being asked to connect. Defaults to: `"Please continue with your account"`.  |
| `target`  | `string`  | Optional. A specific DID you suggest the wallet should use. The wallet may ignore this suggestion if the user does not own the DID or chooses another.  |
| `supervised`  | `boolean`  | Optional. If set to `true`, it indicates a delegated connection scenario where the wallet might be acting on behalf of another DID. Defaults to `false`.  |
| `targetType`  | `object`  | Optional. An object specifying the desired properties of the DID to be selected. This is useful for requesting a DID with specific cryptographic characteristics.  |

### Target Type Fields

The `targetType` object can contain the following fields to filter the DIDs presented to the user:

| Field  | Type  | Description  |
|---|---|---|
| `key`  | `string`  | The desired key type. Valid values: `"ed25519"`, `"secp256k1"`, `"ethereum"`. Defaults to `"ed25519"`.  |
| `hash`  | `string`  | The desired hash function. Valid values: `"sha3"`, `"keccak"`, `"sha2"`. Defaults to `"sha3"`.  |
| `role`  | `string`  | The desired role type of the wallet account. Valid values include `"account"`, `"node"`, `"application"`, `"smart_contract"`, etc. Defaults to `"account"`.  |
| `encoding`  | `string`  | The desired encoding format. Valid values: `"base58"`, `"base16"`. Defaults to `"base58"`.  |

## Example Usage

Here's how you would request a user to connect with a standard account. This is typically done within the `claims` array of your DID Connect configuration.

**Requesting a Basic Connection**

```javascript
const claims = {
  authPrincipal: {
    description: 'Sign in to our awesome app',
  },
};

// This claims object would be used by your WalletAuthenticator instance
// when generating the QR code for the user to scan.
```

### Example: Requesting a Specific Type of DID

If your application needs to interact with a specific blockchain or requires a certain key type, you can use `targetType`.

**Requesting an Ethereum-compatible DID**

```javascript
const claims = {
  authPrincipal: {
    description: 'Connect your Ethereum-compatible account',
    targetType: {
      key: 'ethereum',
      role: 'account',
    },
  },
};
```

## Wallet Response

After the user scans the QR code and approves the request in their wallet, your application's `onConnect` and `onAuth` handlers will be triggered. The `onAuth` callback will receive a session object containing the user's selected DID and public key.

**Example onAuth Callback**

```javascript
const handlers = new WalletHandlers({
  // ...other handlers
  onAuth: async (session) => {
    console.log('User connected!', session);
    // The session object contains:
    // session.userDid - e.g., 'z1...' (the user's address)
    // session.userPk - The user's public key in base58

    // You can now create a user session in your database
    // or proceed to the next step in your workflow.
  },
});
```

## Next Steps

Once a session is established with the `authPrincipal` claim, you can proceed to request more detailed information or actions from the user. Common next steps include:

::::card-group
::link-card{title="Profile Claim" description="Request basic user information like their name, email, or avatar to create a user profile." icon="user" href="/en/docs/did-connect-sdk/claims-profile-b5860f/"}
::link-card{title="Signature Claim" description="Ask the user to sign a message or transaction to prove ownership or authorize an action." icon="edit" href="/en/docs/did-connect-sdk/claims-signature-b5860f/"}
::::

---

## Claims Reference

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-b5860f/

DID Connect enables applications to request specific information or actions from a user's digital wallet. These requests are called "claims." Each claim type is designed for a distinct purpose, ranging from simple identity verification to complex, multi-step workflows like transaction signing or presenting digital credentials.

Understanding the different types of claims is crucial for building robust and user-friendly decentralized applications. This section serves as a comprehensive reference for all available claims in the DID Connect SDK. Each entry provides a detailed explanation, use cases, and code examples to help you implement them effectively.

Explore the different claims below to find the ones that best fit your application's needs.

::::card-group
::link-card{title="Auth Principal Claim" description="Request the user to connect their wallet and select a DID to establish a session." icon="user-check" href="/en/docs/did-connect-sdk/claims-auth-principal-b5860f/"}
::link-card{title="Profile Claim" description="Request personal information from the user, such as name, email, and avatar." icon="user" href="/en/docs/did-connect-sdk/claims-profile-b5860f/"}
::link-card{title="Signature Claim" description="Request the user to sign a message, transaction, or other data to prove control of their DID." icon="edit" href="/en/docs/did-connect-sdk/claims-signature-b5860f/"}
::link-card{title="Prepare Transaction Claim" description="Request the wallet to complete and sign a partially constructed transaction, common in payment scenarios." icon="edit" href="/en/docs/did-connect-sdk/claims-prepare-tx-b5860f/"}
::link-card{title="Agreement Claim" description="Request the user to confirm their agreement to a document or terms of service by signing its digest." icon="file" href="/en/docs/did-connect-sdk/claims-agreement-b5860f/"}
::link-card{title="Verifiable Credential Claim" description="Request the user to present a Verifiable Credential (VC) to prove an attribute or qualification." icon="check-circle" href="/en/docs/did-connect-sdk/claims-verifiable-credential-b5860f/"}
::link-card{title="Asset Claim" description="Request the user to present ownership of a specific on-chain asset, such as an NFT." icon="star" href="/en/docs/did-connect-sdk/claims-asset-b5860f/"}
::link-card{title="Asset or VC Claim" description="Request the user to present either a Verifiable Credential or an on-chain asset that matches certain criteria." icon="layers" href="/en/docs/did-connect-sdk/claims-asset-or-vc-b5860f/"}
::link-card{title="Key Pair Claim" description="Request the wallet to generate a new key pair for a specific purpose, such as a new application account." icon="key" href="/en/docs/did-connect-sdk/claims-key-pair-b5860f/"}
::link-card{title="Encryption Key Claim" description="Request the wallet to derive a secret encryption key from its master key using a provided salt." icon="lock" href="/en/docs/did-connect-sdk/claims-encryption-key-b5860f/"}
::::

Choosing the appropriate claim is key to creating a seamless and secure user experience. Click on any of the cards above to dive into the specific details, parameters, and implementation examples for each claim type.

---

## Encryption Key Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-encryption-key-b5860f/

The `encryptionKey` claim is a powerful feature that allows your application to request a secret encryption key from the user's wallet. This key is deterministically derived from the wallet's master secret and a `salt` you provide. It enables applications to encrypt user-specific data without ever handling the user's primary private key, enhancing security and privacy.

## How It Works

The process is straightforward and secure:

::::steps
:::step{title="Application Initiates:"}
Your application requests an `encryptionKey` claim, providing a unique `salt` string.
:::

:::step{title="Wallet Derives Key:"}
The user's wallet receives the request. It uses a secure key derivation function (specifically `SHA3(Buffer.concat(keyPair.sk, salt), 3)`) to combine its master secret with the provided `salt`.
:::

:::step{title="User Approval:"}
The wallet prompts the user to approve the request, explaining that the application wants to generate an encryption key.
:::

:::step{title="Key Returned:"}
Upon user approval, the derived key is sent back to your application as part of the DID Connect response.
:::
::::

This method ensures that even if two different applications request a key with the same `salt`, the derived keys will be different because they are tied to each user's unique master secret.

## Parameters

The `encryptionKey` claim object accepts the following parameters:

| Parameter  | Type  | Required  | Description  |
|---|---|---|---|
| `type`  | String  | Yes  | Must be set to `'encryptionKey'`.  |
| `description`  | String  | No  | A message displayed to the user in the wallet to explain the purpose of the key. Defaults to 'Please provide encryptionKey to continue.'.  |
| `salt`  | String  | Yes  | A unique string provided by your application. This is a critical component in the key derivation process. Using a different salt will result in a different key.  |
| `delegation`  | String  | No  | An optional JWT token proving a delegation relationship, allowing an agent to request the key on behalf of another DID.  |
| `meta`  | Any  | No  | An object to hold any custom metadata you want to associate with the claim. Defaults to `{}`.  |

## Requesting an Encryption Key

Here is an example of how to request an `encryptionKey` claim within your application. You would typically define this within the claims object when initiating a DID Connect session.

**DID Connect Claims**

```javascript
const claims = {
  encryptionKey: {
    description: 'Generate a key to encrypt your application settings',
    salt: 'a-unique-and-persistent-salt-for-this-user-and-context',
  },
};

// This claims object would be passed to your WalletAuthenticator instance
const { authInfo } = await authenticator.sign({
  claims,
  // ... other context parameters
});
```

In the example above, the application requests a key, providing a descriptive message for the user and a unique `salt`.

## Wallet Response

After the user approves the request, your application's callback endpoint will receive the wallet's response. Once verified, the `claims` array in the response payload will contain the derived encryption key.

**Wallet Response Payload**

```json
{
  "userDid": "z1...",
  "userPk": "...",
  "claims": [
    {
      "type": "encryptionKey",
      "salt": "a-unique-and-persistent-salt-for-this-user-and-context",
      "delegation": "",
      "key": "...derived_encryption_key..."
    }
  ],
  "challenge": "...",
  "timestamp": 1678886400
}
```

Your application can then extract the `key` from the response and use it for encryption and decryption tasks.

## Use Cases

This claim is ideal for scenarios where you need to protect user data stored by your application:

- <strong>Encrypting User Preferences:</strong> Securely store user settings or profile information in your database.
- <strong>Securing Application Data:</strong> Encrypt data specific to a user's session or activity within your application.
- <strong>End-to-End Encryption:</strong> Establish a shared secret for creating an encrypted communication channel.

By leveraging the `encryptionKey` claim, you can build more secure and privacy-preserving applications. To dive deeper into how claims are handled, proceed to the [API Reference for WalletAuthenticator](/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/).

---

## Key Pair Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-key-pair-b5860f/

The Key Pair Claim is a powerful feature that allows your application to request the user's wallet to generate a new cryptographic key pair. This is particularly useful for creating new, application-specific accounts or identities that are securely managed by the user's wallet but dedicated to interacting with your service.

Instead of managing user credentials on your server, you can offload this responsibility to the user's DID Wallet, enhancing both security and user control.

## Use Cases

- <strong>Application-Specific Accounts:</strong> When a user signs up, you can request a new key pair to create a dedicated account for them within your application. This new account's DID is distinct from the user's primary DID.
- <strong>Session or Device Keys:</strong> Generate temporary key pairs for specific sessions or devices, enhancing security by limiting the key's scope and lifetime.
- <strong>Identity Migration:</strong> Facilitate the process of migrating a user from an old account to a new one by specifying the `migrateFrom` property.

## How It Works

When you request a `keyPair` claim, the DID Wallet will prompt the user with the description you provide. If the user approves, the wallet generates a new key pair according to the parameters you've set (`targetType`). By default, the wallet also declares the new DID on the blockchain. The wallet then returns the new key pair (public key, secret key, and address) to your application through the secure DID Connect channel.

## Parameters

The `keyPair` claim accepts the following parameters:

| Name  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | <strong>Required.</strong> A message displayed to the user explaining why a new key pair is needed.  |
| `moniker`  | `string`  | <strong>Required.</strong> A human-readable name for the new account, which will be visible in the user's wallet. Must match the regex `^[a-zA-Z0-9][-a-zA-Z0-9_]{2,128}$`.  |
| `declare`  | `boolean`  | Optional. If `true` (the default), the new DID will be declared on the chain. Set to `false` to generate an off-chain key pair.  |
| `migrateFrom`  | `string`  | Optional. A DID address to migrate from. The wallet can use this to link the new account to an old one.  |
| `targetType`  | `object`  | Optional. An object specifying the cryptographic properties of the key pair to be generated.  |

### The targetType Object

You can customize the type of key pair generated with the `targetType` object:

| Key  | Type  | Default  | Description  |
|---|---|---|---|
| `role`  | `string`  | `account`  | The role of the DID, e.g., `account`, `application`, `blocklet`.  |
| `key`  | `string`  | `ed25519`  | The cryptographic key algorithm, e.g., `ed25519`, `secp256k1`.  |
| `hash`  | `string`  | `sha3`  | The hash algorithm used for generating the address, e.g., `sha3`, `sha2`, `keccak`.  |
| `encoding`  | `string`  | `base58`  | The encoding for the address, e.g., `base58`, `base16`.  |

## Example: Requesting a New Account

Here is an example of how to request a new key pair for a user, which can be used as their account within your application.

**Requesting a new key pair**

```javascript
const claims = {
  keyPair: {
    description: 'Create a new account for our awesome app',
    moniker: 'my-app-account',
    targetType: {
      role: 'account',
    },
  },
};

// In your handler
const { authInfo } = await authenticator.sign({
  claims,
  // ... other context properties
});
```

## Example: Generating a Key Pair for a Blocklet

If you are building a Blocklet, you might need a key pair with a specific role. You can also choose not to declare it on-chain immediately and migrate from an existing DID.

**Requesting a key pair for a blocklet**

```javascript
const claims = {
  keyPair: {
    description: 'Generate a key pair to manage your new Blocklet',
    moniker: 'my-blocklet-key',
    declare: false, // Generate the key pair but don't broadcast a declare tx
    migrateFrom: 'z3CtKiQt2QnLXaZfEfBYvJHTZoPXJggnHEYx4', // The DID to migrate from
    targetType: {
      role: 'blocklet',
      key: 'ed25519',
      hash: 'sha3',
    },
  },
};

// In your handler
const { authInfo } = await authenticator.sign({
  claims,
  // ... other context properties
});
```

## Wallet Response

If the user approves the request, your application's `onAuth` callback will receive the newly generated key pair within the `claims` array. The response for a single `keyPair` claim will look like this:

**Wallet Response Example**

```json
{
  "type": "keyPair",
  "sk": "...", // The secret key of the new key pair
  "pk": "...", // The public key of the new key pair
  "address": "...", // The DID address of the new key pair
  "moniker": "my-app-account",
  "meta": {}
}
```

Your application should securely handle the received secret key (`sk`), as it grants full control over the newly created DID.

Now that you understand how to request a new key pair, you might be interested in deriving keys for other purposes.

:::action-card{title="Next: Encryption Key Claim" description="Learn how to request the wallet to derive a secret encryption key from its master key using a provided salt." icon="key"}
::action{label="Read More" href="/en/docs/did-connect-sdk/claims-encryption-key-b5860f/" variant="primary"}
:::

---

## Prepare Transaction Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-prepare-tx-b5860f/

The `prepareTx` claim is a powerful tool for dApps that need users to complete and sign transactions, especially in payment and asset transfer scenarios. Unlike a standard `signature` claim where the entire transaction is pre-defined, `prepareTx` sends a <em>partially constructed</em> transaction to the wallet. The wallet is then responsible for adding the necessary inputs (like tokens or assets) to meet a specified `requirement`, signing the completed transaction, and returning it to the dApp.

This is particularly useful when the dApp knows <em>what</em> needs to be paid but doesn't know <em>which specific assets</em> the user will pay with. The user can select the required inputs directly from their wallet, providing a flexible and secure user experience.

See the [Signature Claim](/en/docs/did-connect-sdk/claims-signature-b5860f/) for simpler signing requests where the transaction is fully formed by the dApp.

## How It Works

The workflow for a `prepareTx` claim involves the application defining the core logic of a transaction while leaving the funding part to the user's wallet.

![Prepare Transaction Claim](https://media.arcblock.io/lib/5d/5dc18ae5759aca76.w1600.webp)

::::steps
:::step{title="Initiation"}
The user performs an action in the dApp that requires a transaction, like making a purchase.
:::

:::step{title="Claim Generation"}
The dApp constructs a partial transaction (e.g., a transfer to its own address) and a `requirement` object detailing what the user needs to contribute (e.g., 100 native tokens).
:::

:::step{title="Wallet Interaction"}
The wallet receives the claim, presents the transaction details to the user, and provides an interface for them to select the tokens or assets needed to satisfy the `requirement`.
:::

:::step{title="Completion & Signing"}
Once the user approves and selects their assets, the wallet completes the transaction with the chosen inputs and signs it with the user's private key.
:::

:::step{title="Return to dApp"}
The wallet returns the fully signed, ready-to-broadcast transaction to the dApp.
:::

:::step{title="Broadcast"}
The dApp receives the signed transaction and can then submit it to the blockchain for processing.
:::
::::

## Parameters

The `prepareTx` claim object is configured with the following properties:

| Parameter  | Type  | Description  |
|---|---|---|
| `description`  | string  | A user-friendly message explaining the purpose of the transaction. Defaults to 'Prepare and sign this transaction to continue.'.  |
| `partialTx`  | string or object  | <strong>Required.</strong> The partially constructed transaction. This can be a raw transaction object or a pre-encoded, Base58-encoded string.  |
| `requirement`  | object  | <strong>Required.</strong> An object specifying the resources the wallet must add to the transaction.  |
| `display`  | string  | Optional. A JSON string containing `{ type, content }` to provide a richer UI display in the wallet.  |
| `chainInfo`  | object  | The blockchain information where the transaction will be executed. Can be provided here or globally in the `WalletAuthenticator` config.  |
| `meta`  | any  | Optional. Any extra metadata you want to associate with the claim. Defaults to `{}`.  |
| `mfa`  | boolean  | Optional. If set to `true`, the wallet will be prompted to perform multi-factor authentication.  |
| `nonce`  | string  | Optional. A nonce to be included in the transaction if required by the protocol.  |

### Requirement Object

The `requirement` object is crucial for defining what the user needs to contribute.

| Field  | Type  | Description  |
|---|---|---|
| `tokens`  | `Array<object>`  | <strong>Required.</strong> An array of token requirements. Each object must contain `address` (the token's DID) and `value` (the amount required as a string or BN.js instance).  |
| `assets`  | `object`  | Optional. An object specifying NFT requirements. You can filter assets by `address`, `parent`, `issuer`, or specify an `amount` of assets to be included.  |

## Example

Here is an example of how to request a `prepareTx` claim. The dApp wants to receive 100 units of a specific token. It creates a partial transaction and defines the requirement for the wallet.

**DID Connect Handler**

```javascript
const claims = {
  // Using a raw transaction object that the SDK will encode
  prepareTx_raw: [
    'prepareTx',
    ({ userDid, userPk }) => ({
      type: 'TransferV2Tx', // The transaction type for the SDK to encode
      description: 'Complete this payment to purchase the item.',
      display: JSON.stringify({ type: 'text', content: 'Purchase confirmation for Item #123' }),
      partialTx: {
        itx: {
          to: 'z2qa5b3g7492c3697a4e69b9a6b986b59e4d5',
        },
      },
      requirement: {
        tokens: [
          {
            address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt', // Token Address
            value: '100',
          },
        ],
      },
    }),
  ],

  // Using a pre-encoded partial transaction
  prepareTx_encoded: async ({ userDid, userPk }) => {
    // This encoding step would typically happen on your backend
    const client = new Client('https://beta.abtnetwork.io/api');
    const encoded = await client.encodeTransferV2Tx({
      tx: {
        itx: {
          to: 'z2qa5b3g7492c3697a4e69b9a6b986b59e4d5',
        },
      },
      wallet: fromRandom(), // A placeholder wallet for encoding
    });

    return {
      type: 'prepareTx',
      description: 'Complete this payment to purchase the item.',
      partialTx: toBase58(encoded.buffer), // The pre-encoded buffer as a Base58 string
      requirement: {
        tokens: [
          {
            address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt',
            value: '100',
          },
        ],
      },
    };
  },
};
```

In both cases, the wallet will receive the partial transaction and the requirement. It will then prompt the user to select 100 units of the token with address `z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt` from their holdings, add them as inputs to the transaction, sign it, and return the result.

## Next Steps

After mastering the `prepareTx` claim, you might be interested in other related functionalities.

::::card-group
::link-card{title="Signature Claim" description="For scenarios where you need the user to sign a fully-formed transaction or a simple message." icon="edit" href="/en/docs/did-connect-sdk/claims-signature-b5860f/"}
::link-card{title="Transaction Payment Example" description="See a practical, end-to-end example of using `prepareTx` to handle a payment flow." icon="shopping-cart" href="/en/docs/did-connect-sdk/examples-transaction-payment-b5860f/"}
::::

---

## Profile Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-profile-b5860f/

The Profile Claim is used to request personal information from a user's DID Wallet. This is a foundational step for many applications, enabling features like user registration, personalized experiences, and communication by securely obtaining user data with their explicit consent.

## Structure

The `profile` claim object is configured with the following parameters:

| Parameter  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | <strong>Required</strong>. A message displayed to the user in their wallet, explaining why their profile information is being requested. E.g., "Please provide your profile to create an account."  |
| `items`  | `string[]`  | An array specifying the profile fields to request. Defaults to `['fullName']`. See the "Available Profile Fields" table below for all options. The key `fields` can also be used as an alias for `items`.  |
| `meta`  | `any`  | Optional. Any custom metadata you want to associate with the claim. This is not sent to the wallet but can be used in your application's logic.  |

### Available Profile Fields

You can request any combination of the following fields in the `items` array:

| Field  | Description  |
|---|---|
| `did`  | The user's Decentralized Identifier.  |
| `fullName`  | The user's full name.  |
| `email`  | The user's email address.  |
| `phone`  | The user's phone number.  |
| `signature`  | A signature proving ownership of the DID.  |
| `avatar`  | A URL to the user's avatar image.  |
| `birthday`  | The user's date of birth.  |
| `url`  | A URL to the user's personal website or profile.  |

## Example: Requesting User Name and Email

Here's how to configure DID Connect handlers to request the user's full name and email address. This is a common pattern for a simple login or registration flow.

**DID Connect Handler**

```javascript
const { WalletHandlers } = require('@arcblock/did-connect');

const handlers = new WalletHandlers({
  authenticator,
  // ... other configurations
});

app.get('/api/auth/login', handlers.createAuthUrl({
  claims: {
    profile: {
      description: 'Please provide your name and email to sign up.',
      items: ['fullName', 'email'],
    }
  },
  onAuth: async ({ userDid, userPk, claims }) => {
    // The 'claims' array will contain the user's profile data
    const profileData = claims.find(c => c.type === 'profile');
    console.log('User DID:', userDid);
    console.log('Profile Data:', profileData);

    // TODO: Find or create a user in your database with the provided information
  }
}));
```

In this example:

1. We define a `profile` claim within the `claims` object.
2. The `description` provides context to the user in their wallet.
3. The `items` array specifies that we need the `fullName` and `email`.
4. The `onAuth` callback receives the wallet's response, which includes a `claims` array containing the requested profile information.

## Wallet Response

After the user approves the request in their DID Wallet, your `onAuth` callback will receive a payload containing the requested data. The `claims` array will hold an object of type `profile` with the user's information.

**Wallet Response Example**

```json
{
  "userDid": "z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ",
  "userPk": "...",
  "claims": [
    {
      "type": "profile",
      "fullName": "Alice",
      "email": "alice@example.com",
      "meta": {}
    }
  ],
  "challenge": "...",
  "status": "ok"
}
```

Your application can then use this data to provision an account, personalize the user experience, or perform other actions as needed.

### Next Steps

After identifying the user with a profile claim, you might need to verify their control over the DID for security-sensitive operations. The [Signature Claim](/en/docs/did-connect-sdk/claims-signature-b5860f/) is the perfect tool for this purpose.

---

## Signature Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-signature-b5860f/

The Signature Claim is a versatile tool used to request a user to sign arbitrary data using the private key associated with their DID. This cryptographic signature serves as undeniable proof that the user has seen and approved the data, effectively demonstrating control over their digital identity. Common use cases include signing messages, authorizing transactions, or confirming delegations.

For more complex payment scenarios where the wallet needs to contribute inputs to a transaction, consider using the [Prepare Transaction Claim](/en/docs/did-connect-sdk/claims-prepare-tx-b5860f/).

## How It Works

The application constructs a `signature` claim detailing what needs to be signed. This includes the data itself (as a raw string or a pre-computed digest), the type of data (which helps the wallet display it correctly), and a hashing method. DID Wallet receives this request, presents the information to the user for confirmation, and upon approval, signs the data and returns the signature to the application for verification.

## Parameters

The `signature` claim object accepts the following parameters:

| Parameter  | Type  | Description  |
|---|---|---|
| `typeUrl`  | `string`  | <strong>Required.</strong> Specifies the data type. This helps the wallet interpret and display the content correctly. Common values include `mime:text/plain`, `mime:text/html`, `fg:t:transaction` (for a Forge-encoded transaction), or a specific transaction type like `TransferV2Tx`.  |
| `origin`  | `string`  | The raw data to be signed, encoded as a Base58 string. This is used when you want the wallet to see and hash the full data. You should provide either `origin` or `digest`.  |
| `digest`  | `string`  | A pre-computed hash of the data. Use this when the original data is too large to send or when you don't need the wallet to see the raw content.  |
| `method`  | `string`  | The hashing algorithm the wallet should apply to the `origin` data before signing. Defaults to `sha3`. If set to `'none'`, the wallet will sign the `origin` data directly without hashing it first.  |
| `display`  | `string`  | A JSON string for providing a rich display in the wallet, such as showing a formatted message or a link. Example: `JSON.stringify({ type: 'url', content: 'https://www.arcblock.io' })`.  |
| `description`  | `string`  | A user-friendly message explaining what the user is being asked to sign. Defaults to 'Sign this transaction or message to continue.'.  |
| `requirement`  | `object`  | An optional object specifying token or asset requirements that the user must meet to be able to provide the signature.  |
| `nonce`  | `string`  | An optional random string used to prevent replay attacks.  |

## Usage Examples

Here are a few examples of how to request different types of signatures.

### 1. Signing a Plain Text Message

This is the simplest use case, where you ask the user to sign a simple string of text.

**Requesting a Text Signature**

```javascript
const claims = {
  signature: {
    typeUrl: 'mime:text/plain',
    description: 'Please sign this message to verify your identity.',
    data: 'I agree to the terms and conditions.',
  },
};

// In your handler
const { authInfo } = await authenticator.sign({
  claims,
  // ... other params
});
```

In this example, the `data` string will be converted to a Buffer, encoded in Base58, and sent to the wallet as the `origin` field.

### 2. Signing a Transaction (from Raw Data)

For on-chain operations, you can ask the user to sign a transaction. You can provide the raw transaction object, and DID Connect will handle the encoding for you. This requires configuring `chainInfo` in your `WalletAuthenticator` instance.

**Requesting a Transaction Signature**

```javascript
const claims = {
  signature: {
    // This is a specific transaction type known by @ocap/client
    type: 'TransferV2Tx',
    description: 'Please sign to confirm the transfer of 100 TBA.',
    display: JSON.stringify({ type: 'html', content: '<div>Transfer <b>100 TBA</b> to recipient</div>' }),
    // The raw transaction data object
    data: {
      itx: {
        to: 'z123...',
        tokens: [
          {
            address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt',
            value: '100',
          },
        ],
      },
    },
    // Optional: specify token requirements for the wallet
    requirement: {
      tokens: [
        {
          address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt',
          value: '100',
        },
      ],
    },
  },
};
```

Behind the scenes, `WalletAuthenticator` will use `@ocap/client` to encode the `data` object into a transaction buffer. The `typeUrl` sent to the wallet will automatically be set to `fg:t:transaction`, and the `origin` will be the Base58-encoded buffer.

### 3. Signing a Transaction (Pre-Encoded)

If you have already encoded the transaction buffer on your server, you can send it directly. In this case, you must set `typeUrl` to `fg:t:transaction`.

**Signing a Pre-Encoded Transaction**

```javascript
const { Client } = require('@ocap/client');
const { toBase58 } = require('@ocap/util');

// Assume client is an instance of @ocap/client
const { buffer: txBuffer } = await client.encodeTransferV2Tx({
  // ... tx params
});

const claims = {
  signature: {
    typeUrl: 'fg:t:transaction',
    description: 'Please confirm this pre-encoded transaction.',
    // The `data` is the base58-encoded buffer
    data: toBase58(txBuffer),
  },
};
```

This approach gives you more control but requires you to handle the transaction encoding yourself.

By leveraging the Signature Claim, you can build secure and verifiable interactions with your users. The next section covers a specialized type of transaction claim for payment scenarios.

::link-card{title="Next: Prepare Transaction Claim" description="Learn how to request the wallet to complete and sign a partially constructed transaction." icon="arrow-right" href="/en/docs/did-connect-sdk/claims-prepare-tx-b5860f/"}

---

## Verifiable Credential Claim

URL: https://www.arcblock.io/en/docs/did-connect-sdk/claims-verifiable-credential-b5860f/

A Verifiable Credential (VC) is a digital tamper-proof credential that can be used to prove something about the holder. The Verifiable Credential claim allows your application to request that a user present a specific VC from their DID Wallet to prove an attribute, qualification, or entitlement.

This is a powerful way to verify information without needing to contact the original issuer every time. Common use cases include:

- Verifying a user's age without revealing their birthdate.
- Confirming membership in an organization.
- Proving ownership of a ticket or pass.
- Gating access to content based on a specific achievement or certificate.

## How to Request a Verifiable Credential

To request a Verifiable Credential, you include a `verifiableCredential` object in the `claims` array when creating a DID Connect session. You can specify various criteria to filter the exact credential you need from the user's wallet.

**DID Connect Handler**

```javascript
const handlers = new WalletHandlers({
  authenticator,
  // ... other configurations
});

app.get('/api/auth/login', async (req, res) => {
  const claims = {
    verifiableCredential: {
      description: 'Please present your Blocklet Server Passport to continue.',
      filters: [
        {
          type: ['BlockletServerPassport'],
          trustedIssuers: ['zNKjDm4Xsoaffb19UE6Q_YOUR_ISSUER_DID_HERE'], // Example Issuer DID
        },
      ],
    },
  };

  // The wallet will prompt the user to select a matching credential
  return handlers.auth(req, res, claims);
});
```

### Parameters

The `verifiableCredential` claim object accepts the following parameters to define the request:

| Parameter  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | <strong>Required.</strong> A message displayed to the user in their wallet, explaining why the credential is being requested.  |
| `optional`  | `boolean`  | If set to `true`, the user can skip this claim and still proceed. Defaults to `false`.  |
| `filters`  | `array`  | An array of filter objects. The wallet will find credentials that match <strong>any</strong> of the filters (logical OR). Within each filter object, all conditions must be met (logical AND). This is the recommended modern approach.  |
| `claimUrl`  | `string`  | A URL where the user can view more information about the claim being requested.  |
| `acquireUrl`  | `string`  | A URL where the user can go to obtain the required credential if they don't already have it.  |

### Filter Object Parameters

Each object inside the `filters` array can contain the following fields:

| Parameter  | Type  | Description  |
|---|---|---|
| `type`  | `string[]`  | An array of acceptable VC type names. The credential must match one of the types in this list.  |
| `trustedIssuers`  | `string[]`  | An array of DIDs. The credential must have been issued by one of these DIDs.  |
| `target`  | `string`  | The DID of the subject to whom the credential was issued. Usually, this is the user's own DID.  |
| `tag`  | `string`  | A specific tag that must be present on the credential.  |
| `ownerDid`  | `string[]`  | An array of DIDs who are allowed to present the credential.  |

### Legacy Parameters

For backward compatibility, the following parameters can be used at the top level of the claim object. However, using the `filters` array is the recommended approach for new applications.

- `item`: (string[]) Alias for `filters[0].type`.
- `trustedIssuers`: (string[]) Alias for `filters[0].trustedIssuers`.
- `target`: (string) Alias for `filters[0].target`.
- `tag`: (string) Alias for `filters[0].tag`.

## Examples

### Requesting a Credential by Type and Issuer

This is the most common use case. You know what kind of credential you need and who you trust to issue it.

**Request a specific VC**

```javascript
const claims = {
  verifiableCredential: () => ({
    description: 'Please present your Blocklet Server Passport.',
    filters: [
      {
        type: ['BlockletServerPassport'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
    ],
  }),
};
```

### Requesting a Credential with Multiple Criteria

You can provide multiple filters to give the user more options. For example, you might accept a passport from one issuer OR a membership card with a specific tag from another.

**Request VC with multiple filters**

```javascript
const claims = {
  verifiableCredential: () => ({
    description: 'Please present a valid passport or a tagged membership card.',
    optional: true,
    filters: [
      // Option 1: A specific type of passport from a trusted issuer
      {
        type: ['BlockletServerPassport'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
      // Option 2: Any credential from another issuer that has a specific tag
      {
        trustedIssuers: ['zNKoA97a922N4234UE6QxVeevuaTaLCS1abc'],
        tag: 'gold_member_card',
      },
    ],
  }),
};
```

In this example, the user can satisfy the request by presenting either a `BlockletServerPassport` from the first issuer or any credential from the second issuer that is tagged as `gold_member_card`.

After successfully requesting a Verifiable Credential, you might want to request ownership of a different kind of on-chain data. Learn how to do this in the next section.

::link-card{title="Next: Asset Claim" description="Learn how to request the user to present an on-chain asset, such as an NFT, to prove ownership." icon="star" href="/en/docs/did-connect-sdk/claims-asset-b5860f/"}

---

## Examples

URL: https://www.arcblock.io/en/docs/did-connect-sdk/examples-b5860f/

Welcome to the examples section. Here, you'll find a collection of practical, end-to-end examples designed to help you quickly understand and implement various features of DID Connect. Each example provides a real-world scenario with runnable code snippets to guide you through the process.

Whether you're building a simple login system or a complex, multi-chain dApp, these examples serve as a great starting point.

::::card-group
::link-card{title="Simple Login" description="Learn the fundamentals of DID Connect by implementing a basic user login flow that requests a user's profile." icon="arrow-right" href="/en/docs/did-connect-sdk/examples-simple-login-b5860f/"}
::link-card{title="NFT Gated Access" description="Discover how to restrict access to content or features by verifying a user's ownership of a specific NFT asset." icon="star" href="/en/docs/did-connect-sdk/examples-nft-gate-b5860f/"}
::link-card{title="Transaction Payment" description="See how to request a user to sign and submit a token transfer transaction, a core feature for Web3 applications." icon="receipt" href="/en/docs/did-connect-sdk/examples-transaction-payment-b5860f/"}
::link-card{title="Multi-Step Session" description="Explore how to chain multiple DID Connect requests together to create complex, multi-step user workflows." icon="list" href="/en/docs/did-connect-sdk/examples-multi-step-session-b5860f/"}
::link-card{title="Multi-Chain Connect" description="Learn how to configure DID Connect to interact with different blockchains, such as Ethereum and ArcBlock chains." icon="routes" href="/en/docs/did-connect-sdk/examples-multi-chain-connect-b5860f/"}
::::

After exploring these examples, you can dive deeper into the specific configurations and methods in the [API Reference](/en/docs/did-connect-sdk/api-reference-b5860f/).

---

## Multi-Chain Connect

URL: https://www.arcblock.io/en/docs/did-connect-sdk/examples-multi-chain-connect-b5860f/

DID Connect is designed with interoperability in mind, extending its capabilities beyond the ArcBlock ecosystem. You can configure it to seamlessly interact with other major blockchains, such as Ethereum and Solana. This example demonstrates how to set up a DID Connect session to request actions on the Ethereum network.

The key to multi-chain functionality is the `chainInfo` object, which tells the user's wallet which network to connect to for the session.

## The chainInfo Object

To initiate a request on a specific blockchain, you must provide a `chainInfo` object. This object specifies the target network's type, ID, and connection endpoint.

Here are the fields for the `chainInfo` object:

| Field  | Type  | Description  | Required  |
|---|---|---|---|
| `type`  | string  | The type of blockchain. Supported values are `'arcblock'`, `'ethereum'`, and `'solona'`.  | Yes  |
| `id`  | string  | The network's Chain ID. For example, `'1'` for Ethereum Mainnet or `'11155111'` for the Sepolia testnet.  | For `ethereum`, `solona`  |
| `host`  | string  | The RPC endpoint for the network. While optional, it's highly recommended for reliable communication.  | No  |

## Example: Requesting a Signature on Ethereum

Let's walk through an example of how to request a user to sign a message using their Ethereum account on the Sepolia testnet.

First, define the `chainInfo` for the target network. This object will be passed to `WalletHandlers` to configure the DID Connect session.

**Ethereum Chain Configuration**

```javascript
const ethereumChainInfo = {
  type: 'ethereum',
  id: '11155111', // Sepolia Chain ID
  host: 'https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID', // Example RPC endpoint
};
```

Next, use this configuration within the `handlers.attach` method. You can set the `chainInfo` in the `authPrincipal` claim to define the context for the entire session. You can also specify it for individual claims if you need to orchestrate a workflow across multiple chains.

**Attaching Wallet Handlers**

```javascript
const { WalletHandlers } = require('@arcblock/did-connect');

// Assuming 'authenticator' and 'tokenStorage' are already configured
const handlers = new WalletHandlers({ authenticator, tokenStorage });

handlers.attach({
  app: server, // Your Express.js app instance
  action: 'eth-signature',

  // Set the chain context for the entire authentication request
  authPrincipal: {
    chainInfo: ethereumChainInfo,
  },

  // Define the claims to be requested on the specified chain
  claims: {
    signature: () => ({
      typeUrl: 'eth:personal-data', // Request a personal signature
      display: 'Sign a message to verify your Ethereum account',
      origin: 'https://yourapp.com',
      // This is optional if authPrincipal.chainInfo is set
      chainInfo: ethereumChainInfo,
    }),
  },

  // Handle the wallet's response
  onAuth: ({ claims, userDid }) => {
    const signatureClaim = claims.find(c => c.type === 'signature');
    console.log(`User ${userDid} provided a signature: ${signatureClaim.signature}`);
    // You can now verify the signature on the Ethereum network
    return { successMessage: 'Ethereum signature verified!' };
  },
});
```

### How It Works

1. When your application generates the DID Connect QR code, it will be encoded with the Ethereum `chainInfo` you provided.
2. The user scans the QR code with a compatible wallet like ABT Wallet.
3. The wallet recognizes the `type: 'ethereum'` and prompts the user to switch to the Sepolia Ethereum network.
4. The user is then asked to sign the message using their selected Ethereum account.
5. Upon approval, the wallet sends the signature back to your application, which you can then process in the `onAuth` callback.

This same pattern can be applied to other chains like Solana by simply changing the `chainInfo` object accordingly. This powerful feature allows you to build decentralized applications that leverage identities and assets across multiple blockchain ecosystems.

::::card-group
::link-card{title="Signature Claim" description="Learn more about the different types of signatures you can request." icon="edit" href="/en/docs/did-connect-sdk/claims-signature-b5860f/"}
::link-card{title="WalletHandlers API" description="Explore the full API for WalletHandlers to customize your integration." icon="server" href="/en/docs/did-connect-sdk/api-reference-wallet-handlers-b5860f/"}
::::

---

## Multi-Step Session

URL: https://www.arcblock.io/en/docs/did-connect-sdk/examples-multi-step-session-b5860f/

In many real-world applications, a single interaction isn't enough to complete a task. You might need to guide a user through a sequence of steps, such as registering a profile first, then verifying ownership of an asset, and finally signing a user agreement. The DID Connect library facilitates these complex interactions by allowing you to chain multiple sessions together into a single, seamless multi-step workflow.

This example demonstrates how to create a sequential, two-step process where the successful completion of the first step automatically triggers the second.

## The Core Mechanism: nextWorkflow

The key to creating a multi-step session lies in the response from the `onAuth` callback. By returning a `nextWorkflow` object, you instruct the user's wallet to immediately start a new DID Connect session using the provided URL.

Here's how it works:

1. The user completes the first DID Connect session (e.g., provides a profile).
2. Your `onAuth` handler for the first session processes the data and generates a new DID Connect URL for the second session.
3. The `onAuth` handler returns an object containing `nextWorkflow` (the new session URL) and `nextToken` (for your frontend to track the new session).
4. The DID Wallet receives this response and automatically initiates the next workflow, presenting the user with the request for the second step without requiring them to scan a new QR code.

## Example: Profile and Asset Verification

Let's build a two-step workflow: first, we'll ask for the user's profile, and then we'll ask them to present a specific asset.

### Step 1: Requesting the User Profile

First, we set up an endpoint for the initial step. In the `onAuth` callback, after successfully receiving the user's profile, we generate a new session for the second step (`/api/did/multi-step/step2/token`) and return it as the `nextWorkflow`.

We can also pass data from this step to the next using `nextWorkflowData`. In this case, we'll pass the user's full name to be used in the description of the second step.

**Step 1: Request Profile and Chain to Step 2**

```javascript
const { WalletHandlers, WalletAuthenticator } = require('@arcblock/did-connect-js');
const SimpleStorage = require('@arcblock/did-connect-storage-nedb');
const { fromRandom } = require('@ocap/wallet');
const axios = require('axios');

// Assume authenticator and handlers are already initialized
const wallet = fromRandom();
const authenticator = new WalletAuthenticator({ /* ...config... */ });
const handlers = new WalletHandlers({
  authenticator,
  tokenStorage: new SimpleStorage({ dbPath: '/tmp/multi-step.db' }),
});

// Handler for the first step
handlers.attach({
  app: server, // Your express app instance
  action: 'multi-step/step1',
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Step 1: Please provide your profile information.',
    }),
  },
  onAuth: async ({ claims, userDid, req }) => {
    const profile = claims.find((x) => x.type === 'profile');
    console.log(`Step 1 complete for ${userDid}. Profile name: ${profile.fullName}`);

    // Generate the URL for the next step in the workflow
    const baseUrl = `${req.protocol}://${req.get('host')}`;
    const { data } = await axios.get(`${baseUrl}/api/did/multi-step/step2/token`);

    return {
      nextWorkflow: data.url, // URL for the wallet to open next
      nextToken: data.token,    // Token for the frontend to poll
      nextWorkflowData: {      // Data to pass to the next step
        fullName: profile.fullName,
      },
    };
  },
});
```

### Step 2: Requesting an Asset

Next, we define the handler for the second step. This handler will receive the data passed from Step 1 via the `extraParams.previousWorkflowData` object. We can use this data to customize the claim, for example, by personalizing the description.

**Step 2: Receive Data and Request Asset**

```javascript
// Handler for the second step
handlers.attach({
  app: server, // Your express app instance
  action: 'multi-step/step2',
  claims: {
    asset: ({ extraParams }) => {
      // Access data from the previous step
      const { fullName } = extraParams.previousWorkflowData;
      return {
        description: `Hi ${fullName}, please present your NFT to complete the process.`,
        trustedIssuers: ['zNKjDm4Xsoaffb19a41w3g9d3AZp2k1YxV4a'], // Example issuer DID
      };
    },
  },
  onAuth: async ({ claims, userDid }) => {
    const asset = claims.find((x) => x.type === 'asset');
    console.log(`Step 2 complete for ${userDid}. Asset presented: ${asset.asset}`);

    // This is the final step, so we return a success message
    return { successMessage: 'You have successfully completed all steps!' };
  },
});
```

## Visualizing the Multi-Step Flow

The following diagram illustrates the interaction between the user, the application backend, and the DID Wallet during a chained session.

![Multi-Step Session](https://media.arcblock.io/lib/19/19a4735000abcff5.w1600.webp)

With this pattern, you can build sophisticated, user-friendly workflows that break down complex processes into simple, sequential steps, all without friction for the end-user.

## Next Steps

Now that you understand how to chain workflows, explore other advanced features and examples:

::::card-group
::link-card{title="Handling Wallet Responses" description="Dive deeper into the various lifecycle callbacks like onConnect, onDecline, and onError to handle every possible user interaction." icon="refresh" href="/en/docs/did-connect-sdk/guides-handling-responses-b5860f/"}
::link-card{title="Transaction Payment Example" description="See a practical example of how to request a user to sign and submit an on-chain transaction." icon="credit-card" href="/en/docs/did-connect-sdk/examples-transaction-payment-b5860f/"}
::::

---

## NFT Gated Access

URL: https://www.arcblock.io/en/docs/did-connect-sdk/examples-nft-gate-b5860f/

This example demonstrates how to restrict access to specific content or features in your application to users who own a particular Non-Fungible Token (NFT) or on-chain asset. This is a common Web3 pattern used for exclusive memberships, event tickets, or special digital items.

DID Connect simplifies this process by allowing your application to request proof of asset ownership directly from the user's wallet using an `asset` claim. For a detailed reference on this claim type, please see the [Asset Claim documentation](/en/docs/did-connect-sdk/claims-asset-b5860f/).

## How It Works

The flow for NFT-gated access involves the application requesting that the user present a specific asset from their wallet. The application defines the criteria for the required asset, such as its issuer, parent collection, or unique address. If the user's wallet holds a matching asset and they approve the request, the application verifies the response and grants access.

![NFT Gated Access](https://media.arcblock.io/lib/44/4431e183d2eac599.w1600.webp)

## Implementation Steps

Here’s how to implement NFT-gated access using `did-connect` handlers. We will configure a session that requires the user to present an NFT from a trusted issuer.

### 1. Configure the Wallet Handlers

First, set up your `WalletHandlers`. In the `onConnect` callback, we will dynamically add an `asset` claim to the list of requested claims.

This claim will instruct the wallet to find an asset that matches the criteria defined in the `filters` array. In this case, we're asking for any asset created by a specific `trustedIssuers` DID.

**Wallet Handler Setup**

```javascript
const { WalletHandlers } = require('@arcblock/did-connect');

const handlers = new WalletHandlers({
  authenticator: auth, // Your WalletAuthenticator instance
  // ... other configurations

  onConnect: async ({ claims }) => {
    // Add the asset claim to the request
    claims.push({
      type: 'asset',
      description: 'Please present your VIP Membership NFT to access this content.',
      optional: false, // Setting optional to false makes it a requirement
      filters: [
        {
          // Replace with the DID of the authority that issued your NFTs
          trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
        },
      ],
    });
  },

  // ... other handlers like onAuth
});
```

### 2. Verify the Presented Asset

In the `onAuth` callback, which runs after the user has successfully responded to the request, you need to verify that the required asset was presented.

The `claims` array in the `onAuth` payload will contain the data returned from the wallet. We find the `asset` claim result and check if it contains the `asset` address. If it does, the user has proven ownership, and we can grant them access.

**Verifying the Wallet Response**

```javascript
const handlers = new WalletHandlers({
  authenticator: auth,
  // ... other configurations

  onConnect: (req) => { /* ... as above ... */ },

  onAuth: async ({ claims, userDid }) => {
    // Find the result of our asset claim request
    const presentedAssetClaim = claims.find(c => c.type === 'asset');

    // The `asset` property will contain the address of the presented NFT
    if (presentedAssetClaim && presentedAssetClaim.asset) {
      console.log(`Access granted to ${userDid}.`);
      console.log(`Presented Asset Address: ${presentedAssetClaim.asset}`);

      // Here you would typically:
      // 1. Create a session for the user.
      // 2. Redirect them to the protected content.
      return {
        status: 'ok',
        message: 'Access Granted',
      };
    }

    console.log(`Access denied for ${userDid}. Required NFT not presented.`);
    // 1. Throw an error or return a specific status to deny access.
    throw new Error('Required NFT was not presented.');
  },
});
```

### Asset Claim Filtering

The `filters` property is highly flexible. You can require assets based on various criteria:

- `address`: The specific address of the NFT.
- `trustedIssuers`: The DID of the entity that created the NFT.
- `trustedParents`: The address of a parent collection NFT.

By combining these filters, you can create sophisticated access rules for your application, such as requiring a specific ticket NFT from a specific event organizer.

This example provides a solid foundation for building powerful, decentralized access control systems in your applications. To explore another common use case, check out the [Transaction Payment example](/en/docs/did-connect-sdk/examples-transaction-payment-b5860f/).

---

## Simple Login

URL: https://www.arcblock.io/en/docs/did-connect-sdk/examples-simple-login-b5860f/

This example provides a step-by-step guide to implementing a basic user login system using DID Connect. The goal is to authenticate a user with their DID Wallet and retrieve their basic profile information, such as their name and email address. This is one of the most common use cases for the library.

We will use `WalletHandlers` to integrate with an Express.js server and request a `profile` claim from the user.

## How It Works

The login process follows the standard DID Connect workflow:

::::steps
:::step{title="Initialization"}
The backend sets up a `WalletAuthenticator` with the application's identity and a `WalletHandlers` instance to manage sessions.
:::

:::step{title="Handler Attachment"}
A specific handler is attached to an Express route (e.g., `/api/did/login`). This handler defines the information to be requested (claims) and the logic to execute upon successful authentication (`onAuth`).
:::

:::step{title="User Interaction"}
The frontend displays a DID Connect button or QR code, initiating the session with the backend.
:::

:::step{title="Wallet Approval"}
The user scans the QR code with their DID Wallet, reviews the request (to share their profile), and approves it.
:::

:::step{title="Backend Callback"}
The `onAuth` callback on the server is triggered, receiving the user's DID (`userDid`) and their profile data.
:::

:::step{title="Session Creation"}
The application can now use this information to create a user session, issue a token, or save the user's profile to a database.
:::
::::

## Implementation

Here’s how to build a simple login endpoint.

### Step 1: Initialize Authenticator and Handlers

First, you need to configure the `WalletAuthenticator` with your application's details and the `WalletHandlers` to manage the session state.

**Simple Login Setup**

```javascript
const express = require('express');
const { fromRandom } = require('@ocap/wallet');
const { WalletAuthenticator, WalletHandlers } = require('@arcblock/did-connect-js');
const SimpleStorage = require('@arcblock/did-connect-storage-nedb');

// 1. Create a wallet for the application
const wallet = fromRandom();

// 2. Configure the authenticator with app and chain info
const authenticator = new WalletAuthenticator({
  wallet,
  baseUrl: 'http://localhost:3000', // Your application's base URL
  appInfo: {
    name: 'Simple Login Example',
    description: 'A simple example to demonstrate DID Connect login',
    icon: '/images/logo.png', // A URL to your app's icon
  },
  chainInfo: {
    host: 'https://beta.abtnetwork.io/api',
    id: 'beta',
  },
});

// 3. Initialize handlers with the authenticator and a storage adapter
const handlers = new WalletHandlers({
  authenticator,
  tokenStorage: new SimpleStorage({ dbPath: '/tmp/did_connect_login_example.db' }),
});

// 4. Create an Express app
const app = express();

// This is required for dynamic baseUrl inference if your app is behind a proxy
app.set('trust proxy', true);
```

- <strong>`WalletAuthenticator`</strong>: This object holds your application's identity (wallet) and metadata (`appInfo`, `chainInfo`) that will be displayed to the user in their wallet.
- <strong>`WalletHandlers`</strong>: This class orchestrates the DID Connect session. It requires an `authenticator` and a `tokenStorage` adapter to persist session state. `did-connect-storage-nedb` is a simple file-based storage suitable for examples.

### Step 2: Attach the Login Handler

Next, use the `handlers.attach()` method to create the API endpoints and define the logic for your login flow. This method automatically creates routes like `/api/did/login/token` and `/api/did/login/status` for you.

**Attach Login Handler**

```javascript
handlers.attach(app, {
  // The base path for the DID Connect endpoints
  // e.g., /api/did/login, /api/did/profile
  action: 'login',

  // Define the claims to request from the user's wallet
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Please provide your name and email to log in.',
    }),
  },

  // The callback function executed upon successful authentication
  onAuth: async ({ userDid, claims }) => {
    // userDid: The DID of the authenticated user.
    // claims: An array of claims submitted by the user.
    try {
      const profile = claims.find((x) => x.type === 'profile');
      console.log('Login successful!', { userDid, profile });

      // In a real application, you would typically:
      // 1. Find or create a user in your database with the userDid.
      // 2. Store the profile information.
      // 3. Create a session or issue a JWT for the user.

    } catch (err) {
      console.error('Error in onAuth callback', err);
    }
  },
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
  console.log(`DID Connect login endpoint is ready at /api/did/login`);
});
```

- <strong>`action: 'login'`</strong>: This sets the base path for the generated endpoints to `/api/did/login`.
- <strong>`claims.profile`</strong>: This object specifies that we are requesting a `profile` claim. The `fields` array lists the specific pieces of information we need, and the `description` is shown to the user in their wallet to explain why the information is needed.
- <strong>`onAuth`</strong>: This is the most critical part. This function runs only after the user has successfully authenticated and approved the request. It receives the `userDid` and the `claims` data. Here, we simply log the information, but in a real-world application, this is where you would handle user session management.

After running this server, you can integrate the frontend using the [DID Connect UX](https://www.npmjs.com/package/@arcblock/did-connect) library, pointing it to the `/api/did/login` endpoint to initiate the login flow.

## Next Steps

Now that you have a basic login system, you can explore more advanced features:

::::card-group
::link-card{title="Requesting Claims" description="Learn how to request multiple pieces of information or dynamically generate claims based on user context." icon="file" href="/en/docs/did-connect-sdk/guides-requesting-claims-b5860f/"}
::link-card{title="NFT Gated Access" description="See a practical example of how to verify ownership of an NFT to grant access to exclusive content." icon="star" href="/en/docs/did-connect-sdk/examples-nft-gate-b5860f/"}
::::

---

## Transaction Payment

URL: https://www.arcblock.io/en/docs/did-connect-sdk/examples-transaction-payment-b5860f/

This example demonstrates a common and powerful use case for DID Connect: requesting a user to sign and submit an on-chain transaction for payment. This pattern is ideal for e-commerce checkouts, service subscriptions, content purchases, or any scenario that requires a transfer of tokens or assets.

We will use the `signature` claim to ask the user to sign a pre-constructed token transfer transaction.

## How It Works

The process involves the application creating a transaction and then asking the user's wallet to sign it. This ensures that the user maintains full control over their assets, and the application never handles the user's private key.

Here is the typical flow:

::::steps
:::step{title="Transaction Creation"}
The application's backend determines the details of the payment (e.g., amount, token type, recipient address) and uses a library like `@ocap/client` to construct a raw transaction.
:::

:::step{title="Claim Request"}
The application initiates a DID Connect session and requests a `signature` claim from the user. The raw transaction data is embedded within this claim request.
:::

:::step{title="User Approval"}
The user's DID Wallet receives the request, decodes the transaction, and displays a human-readable summary (e.g., "Pay 100 ABC Tokens to 'My App'"). The user can then choose to approve and sign the transaction with their private key.
:::

:::step{title="Response Handling"}
Upon approval, the wallet sends the signed transaction back to the application. The application can then verify the signature and broadcast the transaction to the blockchain to complete the payment.
:::
::::

This entire process is secure and non-custodial, providing a seamless Web3 payment experience.

## Code Example

Let's build an example where our application requests a payment of 100 native tokens from the user.

### 1. Configure WalletAuthenticator

First, set up the `WalletAuthenticator` with your application's details and the chain information.

**Transaction Payment Authenticator Setup**

```javascript
import { WalletAuthenticator } from '@did-connect/lib';
import { fromRandom } from '@ocap/wallet';

// Your application's wallet
const appWallet = fromRandom();

const auth = new WalletAuthenticator({
  wallet: appWallet,
  baseUrl: 'https://yourapp.com',
  appInfo: {
    name: 'My Awesome App',
    description: 'An app that requires payment.',
    icon: 'https://yourapp.com/logo.png',
    link: 'https://yourapp.com',
  },
  chainInfo: {
    host: 'https://beta.abtnetwork.io/api',
    id: 'beta',
  },
});
```

### 2. Define the Signature Claim

Next, define the `claims` to be requested. We'll use a single `signature` claim. Inside the claim function, we'll construct the transaction.

This requires `@ocap/client` to encode the transaction and `@ocap/util` to convert the resulting buffer to a Base58 string, which is the format the wallet expects.

**Create Transaction Signature Claim**

```javascript
import Client from '@ocap/client';
import { fromPublicKey } from '@ocap/wallet';
import { toBase58 } from '@ocap/util';

const client = new Client('https://beta.abtnetwork.io/api');
const NATIVE_TOKEN_ADDRESS = 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt'; // Native token on ArcBlock chains

// Define the claims for an Express.js handler
const claims = {
  signature: async ({ userDid, userPk }) => {
    // 1. Construct the transaction object
    const txPayload = {
      tx: {
        from: userDid,
        pk: userPk,
        itx: {
          to: appWallet.address, // Send payment to the app's address
          tokens: [
            {
              address: NATIVE_TOKEN_ADDRESS,
              value: '100000000000000000000', // 100 tokens (with 18 decimals)
            },
          ],
        },
      },
      wallet: fromPublicKey(userPk),
    };

    // 2. Encode the transaction into a buffer
    const encoded = await client.encodeTransferV2Tx(txPayload);

    // 3. Return the claim object for the wallet
    return {
      type: 'fg:t:transaction', // Specifies a native framework transaction
      data: toBase58(encoded.buffer), // The transaction data must be Base58 encoded
      description: 'Sign this transaction to complete your payment of 100 tokens.',
      // The requirement object is used by the wallet to display a clear summary to the user
      requirement: {
        tokens: [
          {
            address: NATIVE_TOKEN_ADDRESS,
            value: '100000000000000000000',
          },
        ],
      },
    };
  },
};

// In your route handler, you would then generate the request URL
// const signed = await auth.sign({ context: { userDid, userPk }, claims });
```

In this example:

- `userDid` and `userPk` are provided by the DID Connect session context after the user has connected their wallet.
- We use `client.encodeTransferV2Tx` to create a standard token transfer transaction.
- The `to` address is our application's wallet address, where the funds will be sent.
- The `requirement` object is crucial for a good user experience. It allows the wallet to parse the transaction and show the user exactly what they are being asked to pay, preventing them from signing a malicious or incorrect transaction.

### 3. Handling the Wallet's Response

After the user signs the transaction in their wallet, your application's callback endpoint will receive the signed transaction data. You can then use a library like `@ocap/client` again to broadcast it to the blockchain.

For a complete guide on setting up handlers to process wallet responses, see the [Handling Wallet Responses](/en/docs/did-connect-sdk/guides-handling-responses-b5860f/) guide.

This example covers a fundamental Web3 interaction. By leveraging the `signature` claim, you can securely request payments and other on-chain actions without ever taking custody of user keys.

To see another practical application of claims, check out the [NFT Gated Access](/en/docs/did-connect-sdk/examples-nft-gate-b5860f/) example.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/did-connect-sdk/getting-started-b5860f/

This guide provides a minimal, step-by-step example to help you set up a basic DID Connect session in your Node.js application. By the end of this tutorial, you will have a working server that can request a user's profile information via their DID Wallet.

## 1. Installation

First, you need to install the necessary packages. This library is designed to work with web server frameworks like Express.js. You will also need a storage adapter to manage session tokens.

**Install required packages**

```bash
# Using npm
npm install express @arcblock/did-connect-js @arcblock/did-connect-storage-nedb @ocap/wallet

# Using pnpm
pnpm install express @arcblock/did-connect-js @arcblock/did-connect-storage-nedb @ocap/wallet
```

- `express`: The web server framework.
- `@arcblock/did-connect-js`: The main library for handling DID Connect sessions.
- `@arcblock/did-connect-storage-nedb`: A simple file-based storage adapter for session tokens. Other adapters are also available.
- `@ocap/wallet`: A library to create and manage DID wallets, which we'll use to create an identity for our application.

## 2. Initializing the Server

Now, let's set up the core components for DID Connect in an `index.js` file. The two main classes you'll work with are `WalletAuthenticator` and `WalletHandlers`.

- <strong>`WalletAuthenticator`</strong>: Manages your application's identity and is responsible for creating and signing authentication requests.
- <strong>`WalletHandlers`</strong>: Provides a set of Express.js middleware to handle the entire DID Connect session lifecycle.

Here's the initial setup:

**index.js**

```javascript
const express = require('express');
const { fromRandom } = require('@ocap/wallet');
const SimpleStorage = require('@arcblock/did-connect-storage-nedb');
const { WalletAuthenticator, WalletHandlers } = require('@arcblock/did-connect-js');

// 1. Create a wallet for your application
// This wallet represents your application's identity.
// In a real application, you should persist and reuse this wallet.
const wallet = fromRandom();

// 2. Configure the WalletAuthenticator
const authenticator = new WalletAuthenticator({
  wallet, // The application's wallet
  baseUrl: 'http://localhost:3000', // Your application's public URL
  appInfo: {
    name: 'My First DID Connect App',
    description: 'A simple app to demonstrate DID Connect.',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png', // URL to your app's logo
  },
  chainInfo: {
    host: 'https://babel.arcblock.io/api',
    id: 'babel',
  },
});

// 3. Configure the WalletHandlers
const handlers = new WalletHandlers({
  authenticator,
  tokenStorage: new SimpleStorage({ dbPath: './auth.db' }), // Storage for session tokens
});

// 4. Create an Express app
const app = express();

// This is required for dynamic baseUrl inference if not explicitly set
app.set('trust proxy', true);

// ... Attach handlers in the next step

// 5. Start the server
const port = 3000;
app.listen(port, () => {
  console.log(`Server started on http://localhost:${port}`);
  console.log(`Application DID: ${wallet.toAddress()}`);
});
```

## 3. Handling the Connection

With the authenticator and handlers configured, the final step is to attach the DID Connect endpoints to your Express app. This is done using the `handlers.attach()` method, where you define the specific claims to request and the callback to execute upon successful authentication.

Add the following code to your `index.js` file before `app.listen()`:

**index.js**

```javascript
// Attach the DID Connect session handler
handlers.attach(app, {
  // A unique name for this authentication action
  action: 'profileLogin',

  // Define the information you want to request from the user
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Please provide your name and email to sign in.',
    }),
  },

  // This callback is executed after the user approves the request in their wallet
  onAuth: async ({ userDid, claims }) => {
    // `userDid` is the DID of the connected user.
    // `claims` is an array containing the information submitted by the user.
    const profile = claims.find((x) => x.type === 'profile');
    console.log('Login successful!');
    console.log('User DID:', userDid);
    console.log('User Profile:', profile);
  },
});
```

## 4. The Complete Code

Here is the complete, runnable code for your `index.js` file. You can save this and run it directly.

**index.js**

```javascript
const express = require('express');
const { fromRandom } = require('@ocap/wallet');
const SimpleStorage = require('@arcblock/did-connect-storage-nedb');
const { WalletAuthenticator, WalletHandlers } = require('@arcblock/did-connect-js');

// 1. Create a wallet for your application
const wallet = fromRandom();

// 2. Configure the WalletAuthenticator
const authenticator = new WalletAuthenticator({
  wallet,
  baseUrl: 'http://localhost:3000',
  appInfo: {
    name: 'My First DID Connect App',
    description: 'A simple app to demonstrate DID Connect.',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
  },
  chainInfo: {
    host: 'https://babel.arcblock.io/api',
    id: 'babel',
  },
});

// 3. Configure the WalletHandlers
const handlers = new WalletHandlers({
  authenticator,
  tokenStorage: new SimpleStorage({ dbPath: './auth.db' }),
});

// 4. Create an Express app and attach handlers
const app = express();
app.set('trust proxy', true);

handlers.attach(app, {
  action: 'profileLogin',
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Please provide your name and email to sign in.',
    }),
  },
  onAuth: async ({ userDid, claims }) => {
    const profile = claims.find((x) => x.type === 'profile');
    console.log('Login successful!');
    console.log('User DID:', userDid);
    console.log('User Profile:', profile);
  },
});

// 5. Start the server
const port = 3000;
app.listen(port, () => {
  console.log(`Server started on http://localhost:${port}`);
  console.log(`Application DID: ${wallet.toAddress()}`);
});
```

Now, run the application:

```bash
node index.js
```

Your backend is now ready to handle a DID Connect session. To complete the flow, you'll need a frontend to display the QR code. For a quick test, you can use the [DID Connect UX](https://www.npmjs.com/package/@arcblock/did-connect) library or integrate it into your web application.

## Next Steps

Congratulations! You've successfully set up a basic DID Connect server. Now you can explore more advanced features.

::::card-group
::link-card{title="The DID Connect Workflow" description="Understand the end-to-end process of a DID Connect session, from QR code generation to handling the final response." icon="flag" href="/en/docs/did-connect-sdk/guides-workflow-b5860f/"}
::link-card{title="Requesting Claims" description="Learn how to request different types of information from a user's wallet, including assets, credentials, and signatures." icon="file" href="/en/docs/did-connect-sdk/guides-requesting-claims-b5860f/"}
::::

---

## Guides

URL: https://www.arcblock.io/en/docs/did-connect-sdk/guides-b5860f/

Welcome to the DID Connect Guides. This section provides practical, step-by-step instructions for implementing common use cases and leveraging the advanced features of the library. Whether you're setting up your first DID Connect session or building complex, multi-step workflows, these guides are designed to help you succeed.

Browse through the guides below to master different aspects of DID Connect.

::::card-group
::link-card{title="The DID Connect Workflow" description="Understand the complete end-to-end process of a DID Connect session, from generating a QR code to handling the final wallet response." icon="routes" href="/en/docs/did-connect-sdk/guides-workflow-b5860f/"}
::link-card{title="Requesting Claims" description="Learn how to request different types of information from a user's wallet, including single, multiple, or dynamically generated claims." icon="file" href="/en/docs/did-connect-sdk/guides-requesting-claims-b5860f/"}
::link-card{title="Handling Wallet Responses" description="Dive deep into the lifecycle callbacks like onAuth and onConnect to effectively manage user approvals, declines, and submitted data." icon="arrow-left" href="/en/docs/did-connect-sdk/guides-handling-responses-b5860f/"}
::link-card{title="Chaining Workflows" description="Discover how to link multiple DID Connect sessions together to create sophisticated, multi-step user journeys." icon="link" href="/en/docs/did-connect-sdk/guides-chaining-workflows-b5860f/"}
::link-card{title="Delegated Connect" description="Implement delegated sessions where one application or DID can act on behalf of another, enabling powerful new use cases." icon="users" href="/en/docs/did-connect-sdk/guides-delegated-connect-b5860f/"}
::::

After reviewing these guides, you might want to explore the detailed [Claims Reference](/en/docs/did-connect-sdk/claims-b5860f/) for specific data requests or dive into the [API Reference](/en/docs/did-connect-sdk/api-reference-b5860f/) for a comprehensive look at all available classes and methods.

---

## Chaining Workflows

URL: https://www.arcblock.io/en/docs/did-connect-sdk/guides-chaining-workflows-b5860f/

DID Connect allows you to link multiple, distinct authentication sessions together, creating a seamless, multi-step process for the user from a single initial interaction. This is ideal for complex scenarios like user registration followed by KYC, or a login followed by a transaction confirmation.

This guide explains the mechanism behind chaining workflows and how to pass data between them.

## The Core Mechanism

The key to chaining workflows lies in the `onAuth` lifecycle callback. When a step in a DID Connect session is successfully completed, instead of simply concluding the session, the `onAuth` handler can initiate a new session and instruct the user's wallet to proceed to it automatically.

This is accomplished by returning two specific properties from the `onAuth` function:

- `nextWorkflow`: The full deep link URL for the next DID Connect session.
- `nextToken`: The session token for the next workflow.

When the wallet receives a response containing `nextWorkflow`, it immediately opens this URL, starting the next phase of the process without requiring the user to scan a new QR code. The original session remains in a pending state until the entire chain of workflows is completed or declined.

### How Session Completion Works

When you link Session A to Session B:

1. Session A's `onAuth` returns the `nextWorkflow` and `nextToken` for Session B.
2. Session A is not marked as `succeed`. Instead, it records that it has been succeeded by Session B.
3. When Session B (the final session in the chain) completes successfully, it marks itself as `succeed`.
4. It then looks for a `prevToken` (Session A's token) and marks that session as `succeed` as well, ensuring the entire chain is properly closed.

![Chaining Workflows](https://media.arcblock.io/lib/e0/e08b7179a6aca9dc.w1600.webp)

## Passing Data Between Workflows

Often, you'll need to pass context from one step to the next. For example, passing the user's DID from a login step to a subsequent purchase step. This is achieved using `nextWorkflowData` and `previousWorkflowData`.

::::steps
:::step{title="Sending Data"}
In the `onAuth` handler of the first session, return an object called `nextWorkflowData`. This object will be automatically Base64-encoded and appended to the `nextWorkflow` URL as a `previousWorkflowData` query parameter.
:::

:::step{title="Receiving Data"}
The next session will automatically parse this parameter. The decoded data will be available in the `extraParams.previousWorkflowData` object inside all lifecycle hooks (`onStart`, `onConnect`, `onAuth`) for that session.
:::
::::

If you chain more than two workflows (A → B → C), the data is merged. When session B returns its own `nextWorkflowData`, it gets merged with the `previousWorkflowData` it received from A, and the combined object is passed to C.

## Implementation Example

Let's consider a scenario where a user logs in and then is immediately prompted to sign a welcome message.

### Step 1: Define the Login Workflow

In your `onAuth` handler for the login session, you'll generate a new session for signing the message and return it as the `nextWorkflow`.

**login-handler.js**

```javascript
// This is a simplified example. In a real app, you would have a separate endpoint to generate tokens.
const { WalletHandlers, WalletAuthenticator } = require('@arcblock/did-connect');
const get = require('lodash/get');

// Assume authenticator and tokenStorage are initialized
const authenticator = new WalletAuthenticator(/* ... */);
const tokenStorage = new MemoryAuthStorage();

const handlers = new WalletHandlers({ authenticator, tokenStorage });

// Handler for the first step: login
handlers.attach({
  app: server,
  action: 'login',
  claims: { profile: { description: 'Please provide your profile' } },
  onAuth: async ({ userDid, claims }) => {
    const profile = claims.find(x => x.type === 'profile');
    console.log(`${userDid} with name ${profile.fullName} logged in.`);

    // Now, create the next workflow for signing a message
    // In a real app, you'd call your own token generation endpoint
    const { data: nextSession } = await axios.get('https://yourapp.com/api/did/sign/token');

    return {
      // The URL and token for the next session
      nextWorkflow: nextSession.url,
      nextToken: nextSession.token,
      // Pass the user's name to the next step
      nextWorkflowData: {
        fullName: profile.fullName,
      },
    };
  },
});
```

### Step 2: Define the Signature Workflow

This workflow will receive the user's name from the login step and use it to customize the signature request.

**sign-handler.js**

```javascript
// Handler for the second step: sign a message
handlers.attach({
  app: server,
  action: 'sign',
  claims: {
    signature: ({ extraParams }) => {
      // Access data from the previous workflow
      const fullName = get(extraParams, 'previousWorkflowData.fullName', 'user');
      return {
        type: 'mime:text/plain',
        description: `Hi ${fullName}, please sign this welcome message!`,
        data: `Welcome aboard, ${fullName}!`,
      };
    },
  },
  onAuth: async ({ userDid }) => {
    console.log(`${userDid} signed the welcome message.`);
    // This is the last step, so we don't return a nextWorkflow
    return { successMessage: 'Onboarding complete!' };
  },
});
```

With this setup, the user scans a single QR code for login, approves it, and is immediately presented with the personalized signature request in their wallet. After signing, the entire multi-step process is complete.

Chaining workflows is a powerful feature for designing sophisticated and user-friendly interactions. You can create complex onboarding flows, multi-party agreements, or any process that requires sequential, authenticated steps.

Next, learn about another advanced feature for more complex application structures. See the [Delegated Connect](/en/docs/did-connect-sdk/guides-delegated-connect-b5860f/) guide.

---

## Delegated Connect

URL: https://www.arcblock.io/en/docs/did-connect-sdk/guides-delegated-connect-b5860f/

Delegated Connect is an advanced feature that enhances security by allowing an application to perform DID Connect operations using a temporary or lower-privilege "agent" DID, while still presenting its primary, official DID to the end-user. This means the application's main private key is never exposed in the hot wallet that handles day-to-day interactions.

This guide explains the concept of Delegated Connect and shows how to implement it using `WalletAuthenticator`.

## How It Works

Delegated Connect involves three key participants:

- <strong>Delegator</strong>: The primary DID that owns the application's identity. This is the DID that users will see and trust. The delegator's wallet holds the main private key, which should be kept in secure, cold storage.
- <strong>Agent</strong>: A secondary, temporary DID that is authorized to act on behalf of the delegator for specific DID Connect operations. The agent's wallet is used by the application backend to sign authentication requests.
- <strong>Delegation Certificate</strong>: A Verifiable Credential, formatted as a JWT, signed by the <strong>Delegator</strong>. This certificate cryptographically proves that the Agent has permission to act for the Delegator. It typically includes an expiration time and a list of permitted claims.

The process ensures that even if the agent's key is compromised, the damage is limited by the permissions and expiration date defined in the delegation certificate. The delegator's primary key remains secure.

### The Flow

Here is a diagram illustrating the delegated authentication flow:

![Delegated Connect](https://media.arcblock.io/lib/8e/8eeb43a26c3eada0.w1600.webp)

::::steps
:::step{title="Delegation"}
The Delegator signs a JWT that grants the Agent permission to perform DID Connect actions.
:::

:::step{title="Request"}
The application's `WalletAuthenticator` creates an authentication request. It's signed by the <strong>Agent</strong>, but the `iss` (issuer) field is set to the <strong>Delegator's</strong> DID. The request also includes the Delegation Certificate.
:::

:::step{title="Verification"}
The user's wallet receives the request. It first verifies the message signature using the Agent's public key. Then, it verifies the included Delegation Certificate using the Delegator's public key. This two-step process confirms the agent's authority.
:::

:::step{title="Response"}
The user approves the request, which clearly shows the Delegator's identity, and the wallet sends the response back to the application.
:::
::::

## Implementation

To implement Delegated Connect, you need to configure the `WalletAuthenticator` with the delegator, the agent wallet, and the delegation certificate.

### Step 1: Define Delegator and Agent

First, you need two distinct wallets. One will serve as the delegator (the main identity) and the other as the agent (the active signer).

**Wallet Setup**

```javascript
const { fromRandom } = require('@ocap/wallet');

// The primary, trusted identity of your application
const delegator = fromRandom();

// The agent wallet that will handle daily operations
const agent = fromRandom();
```

### Step 2: Create the Delegation Certificate

The certificate is a JWT signed by the `delegator`, granting permissions to the `agent`.

**Create Delegation JWT**

```javascript
const Jwt = require('@arcblock/jwt');
const { toDid } = require('@ocap/util');

const createDelegation = async () => {
  const now = Math.floor(Date.now() / 1000);
  const claims = [
    'authPrincipal',
    'profile',
    'signature',
    'prepareTx',
    'agreement',
    'verifiableCredential',
    'asset',
    'keyPair',
    'encryptionKey',
  ];

  const payload = {
    agentDid: toDid(agent.address),
    permissions: [
      {
        role: 'DIDConnectAgent',
        claims: claims,
      },
    ],
    exp: now + 3600, // Expires in 1 hour
    iat: now,
    nbf: now,
  };

  return Jwt.signV2(delegator.address, delegator.secretKey, payload);
};

const delegationCert = await createDelegation();
```

### Step 3: Configure WalletAuthenticator

Instantiate `WalletAuthenticator` by providing the `delegator`, the `delegation` certificate, and the `wallet` (which is the agent).

**Authenticator Configuration**

```javascript
const { WalletAuthenticator, WalletHandlers } = require('@arcblock/did-connect');
const MemoryAuthStorage = require('@arcblock/did-connect-storage-memory');

const authenticator = new WalletAuthenticator({
  // The 'wallet' property is our AGENT
  wallet: () => agent.toJSON(),

  // The delegator is the main app identity
  delegator: () => delegator.toJSON(),

  // The JWT proving the delegation
  delegation: () => delegationCert,

  appInfo: () => ({
    name: 'Delegated Connect Demo',
    description: 'Demo of delegated authentication',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
  }),
});

const handlers = new WalletHandlers({
  tokenStorage: new MemoryAuthStorage(),
  authenticator,
});

// Attach to your Express app
handlers.attach({
  app: server, // your express app instance
  action: 'delegatedLogin',
  claims: {
    profile: () => ({ fields: ['fullName'], description: 'Login with delegation' }),
  },
  onAuth: (claims) => {
    console.log('User authenticated:', claims);
  },
});
```

When the DID Connect session starts, the `WalletAuthenticator` will automatically handle the delegated flow. The QR code will contain the necessary information for the user's wallet to verify the chain of trust from the delegator to the agent. The user will see a request from your application's main identity (the delegator), providing a seamless and secure experience.

For more details on the constructor options, see the [WalletAuthenticator API Reference](/en/docs/did-connect-sdk/api-reference-wallet-authenticator-b5860f/).

---

## Handling Wallet Responses

URL: https://www.arcblock.io/en/docs/did-connect-sdk/guides-handling-responses-b5860f/

Once you've defined the claims for a DID Connect session as shown in the [Requesting Claims](/en/docs/did-connect-sdk/guides-requesting-claims-b5860f/) guide, the next critical step is to process the user's response from their DID Wallet. The `@arcblock/did-connect-js` library provides a comprehensive set of lifecycle callbacks to manage every possible outcome of a session, whether the user approves, declines, or the session times out.

These callbacks are passed as functions to the `handlers.attach()` method and give you specific hooks into the authentication process to run your business logic.

## The DID Connect Lifecycle

A typical DID Connect session follows a clear sequence of events. The diagram below illustrates this flow and indicates when each major lifecycle callback is triggered.

![Handling Wallet Responses](https://media.arcblock.io/lib/e1/e1ce2f7604c7a6db.w1600.webp)

## Lifecycle Callbacks

Here is a detailed breakdown of the available callbacks you can use to handle the entire DID Connect session lifecycle.

| Callback  | Triggered When...  | Common Use Cases  |
|---|---|---|
| `onStart`  | A new session is initiated and the QR code is ready.  | Logging session initiation, preparing session-specific resources.  |
| `onConnect`  | The user's wallet scans the QR code and establishes a connection, but <em>before</em> claims are approved.  | Permission checks based on `userDid`, generating dynamic claims.  |
| `onDecline`  | The user explicitly rejects the request in their wallet.  | Displaying a cancellation message, logging the rejection.  |
| `onAuth`  | <strong>(Required)</strong> The user approves the request and submits the requested claims.  | <strong>Core business logic:</strong> validating claims, creating a user session, updating a database.  |
| `onComplete`  | The entire DID Connect session has finished, regardless of success or failure.  | Final cleanup tasks, removing temporary session data.  |
| `onExpire`  | The session times out before the user completes the action.  | Notifying the user that the QR code has expired, cleaning up stale sessions.  |
| `onError`  | An unexpected error occurs during the session.  | Error logging and reporting.  |

### onConnect: Pre-Approval Logic & Dynamic Claims

The `onConnect` callback is particularly powerful because it allows you to run logic after you know the user's DID but before they've seen the full list of claims. This is the ideal place to perform permission checks or dynamically generate claims based on the user's identity.

<strong>Parameters:</strong> `{ req, challenge, userDid, userPk, extraParams, updateSession }`

**Example: Generating Dynamic Claims with onConnect**

```javascript
handlers.attach({
  action: 'dynamic-claims',

  // This function can be async
  onConnect: ({ userDid }) => {
    // You can check the user's DID against an allow-list
    if (!isUserAllowed(userDid)) {
      throw new Error('You are not authorized to access this service.');
    }

    // Or return a dynamic set of claims based on user properties
    return {
      profile: () => ({
        fields: ['fullName', 'email'],
        description: 'Please provide your name and email to continue',
      }),
    };
  },

  onAuth: async ({ claims, userDid }) => {
    // `claims` now contains the result for the dynamically generated profile claim
    console.log('Dynamic claim approved by:', userDid, claims);
  },
});
```

### onAuth: Handling Successful Authentication

The `onAuth` callback is the heart of your DID Connect integration. It is the only required callback and is executed when the user successfully approves the request in their wallet. It receives the claims data submitted by the user, which you can then use to complete your application's logic, such as logging the user in or verifying ownership of an asset.

<strong>Parameters:</strong> `{ req, challenge, claims, userDid, userPk, extraParams, updateSession }`

**Example: Processing Submitted Claims in onAuth**

```javascript
handlers.attach({
  action: 'profile-login',
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Please provide your name and email to log in.',
    }),
  },

  onAuth: async ({ userDid, claims }) => {
    try {
      const profileClaim = claims.find((c) => c.type === 'profile');
      if (profileClaim) {
        console.log(`Login success for ${userDid}`);
        console.log('User Profile:', profileClaim.value);
        // Here you would typically create a user session, save to a database, etc.
        const user = await findOrCreateUser(userDid, profileClaim.value);
      }
    } catch (err) {
      console.error('Error during login process:', err);
    }
  },
});
```

### onDecline: Handling User Cancellation

If a user decides to cancel the request in their wallet, the `onDecline` callback is triggered. This allows you to handle the cancellation gracefully, for example, by informing the user on the frontend that the login attempt was canceled.

<strong>Parameters:</strong> `{ req, challenge, userDid, userPk, extraParams, updateSession }`

**Example: Handling a Declined Request**

```javascript
handlers.attach({
  action: 'profile-login',
  claims: { /* ... */ },
  onAuth: async ({ userDid, claims }) => { /* ... */ },

  onDecline: ({ userDid }) => {
    console.log(`User ${userDid} declined the connection request.`);
    // You might update the session to notify the frontend
  },
});
```

## Persisting Data with updateSession

Several callbacks, including `onAuth`, `onConnect`, and `onStart`, receive an `updateSession` function as a parameter. This utility is essential for passing information from your backend logic back to the session state, which can then be polled and retrieved by your frontend application.

For example, after a successful login in `onAuth`, you can generate an application-specific JWT and save it to the session. Your frontend can then retrieve this token to authenticate subsequent API requests.

- <strong>To persist plain, non-sensitive info</strong>: `await updateSession({ key: 'value' });`
- <strong>To persist sensitive info (will be encrypted)</strong>: `await updateSession({ key: 'sensitive-value' }, true);`

**Example: Using updateSession to Pass a Token to the Frontend**

```javascript
handlers.attach({
  action: 'profile-login',
  claims: { /* ... */ },
  onAuth: async ({ userDid, claims, updateSession }) => {
    const user = await findOrCreateUser(userDid, claims);
    const appToken = generateAppToken(user);

    // Persist a non-sensitive session ID
    await updateSession({ sessionId: 'some-session-id' });

    // Persist a sensitive JWT, which will be encrypted in the session store
    await updateSession({ token: appToken }, true);

    console.log(`Session updated for user ${userDid}`);
  },
});
```

By effectively using these lifecycle callbacks, you can build robust and user-friendly authentication flows. Now that you understand how to handle responses for a single session, you are ready to explore more complex user journeys.

Next, learn how to create multi-step interactions by linking multiple DID Connect sessions together in the [Chaining Workflows](/en/docs/did-connect-sdk/guides-chaining-workflows-b5860f/) guide.

---

## Requesting Claims

URL: https://www.arcblock.io/en/docs/did-connect-sdk/guides-requesting-claims-b5860f/

In a DID Connect session, a "claim" is a specific piece of information or action you request from a user's wallet. This could be anything from their name and email to a cryptographic signature proving ownership of an asset. This guide will walk you through the different ways to request claims from a user.

All claim requests are configured within the `claims` property of the `handlers.attach` method. For a full list of available claim types and their parameters, please see the [Claims Reference](/en/docs/did-connect-sdk/claims-b5860f/).

## Requesting a Single Claim

The most straightforward use case is requesting a single piece of information. You define a `claims` object where each key represents a specific claim you want to request. The value is typically a function that returns the claim's definition object.

For example, to request a user's profile containing their full name and email, you would configure it as follows:

**Basic Profile Claim**

```javascript
handlers.attach({
  action: 'profile',
  claims: {
    // The key 'profile' specifies the claim type.
    // The value is a function that returns the claim's parameters.
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Please provide your name and email to continue',
    }),
  },

  onAuth: async ({ userDid, claims }) => {
    // The 'claims' array contains the data submitted by the user.
    try {
      const profile = claims.find((x) => x.type === 'profile');
      console.info('login.success', { userDid, profile });
    } catch (err) {
      console.error('login.error', err);
    }
  },
});
```

In this example, we request a single `profile` claim. The wallet will prompt the user to share their full name and email. Once the user approves, the `onAuth` callback receives the submitted information in the `claims` array.

## Requesting Multiple Claims

DID Connect allows you to request multiple pieces of information in a single session, which is highly efficient. There are two ways to do this, depending on whether the claims are of different types or the same type.

### Multiple Different Claims

To request several different types of claims at once, simply add more key-value pairs to the `claims` object. For instance, you can ask for a user's profile and proof of ownership of a specific asset in the same session.

**Multiple Different Claims**

```javascript
handlers.attach({
  action: 'multiple-claims',
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: 'Please provide your name and email to continue',
    }),
    asset: ({ userDid, extraParams }) => {
      // The asset claim can be a function to dynamically set parameters
      return {
        description: 'Please prove ownership of a valid NFT',
        trustedIssuers: ['z1...', 'z2...'], // Optional: filter by trusted NFT issuers
      };
    },
  },
  onAuth: async ({ claims, userDid }) => {
    // `claims` is an array containing both the profile and the asset claim results.
    const profile = claims.find(c => c.type === 'profile');
    const asset = claims.find(c => c.type === 'asset');
    console.log({ userDid, profile, asset });
  },
});
```

### Multiple Claims of the Same Type

If you need to request multiple claims of the <em>same</em> type (e.g., asking the user to sign two different messages), you need a slightly different syntax. You use a unique key for each request and provide the claim type and its definition as a two-element array.

Here's how to request two different `signature` claims:

**Multiple Same-Type Claims**

```javascript
handlers.attach({
  action: 'multiple-signatures',
  claims: {
    // 'signText' is a unique identifier for this specific request.
    signText: [
      'signature', // The first element is the claim type as a string.
      {          // The second element is the claim definition object.
        type: 'mime:text/plain',
        data: 'I agree to the terms of service.',
        description: 'Please sign the text to continue',
      },
    ],
    // 'signHtml' is another unique identifier.
    signHtml: [
      'signature',
      {
        type: 'mime:text/html',
        data: `<h2>Transaction Summary</h2><p>Amount: 100 ABC</p>`,
        description: 'Please sign to confirm the transaction',
      },
    ],
  },
  onAuth: async ({ claims, userDid }) => {
    // `claims` will contain the results for both signature requests.
    console.log('User signed messages:', claims);
  },
});
```

## Dynamic Claims

In some scenarios, the information you need to request depends on who the user is. For example, you might want to request a KYC (Know Your Customer) credential only if the user hasn't provided one before. This can be achieved using <strong>dynamic claims</strong> with the `onConnect` lifecycle callback.

The `onConnect` callback runs after the user has scanned the QR code and selected a DID in their wallet, but <em>before</em> the claims are sent to them. This gives you access to the user's DID (`userDid`) to perform business logic.

**Dynamic Claims with onConnect**

```javascript
handlers.attach({
  action: 'dynamic-claims',

  // This function runs after the wallet connects but before claims are requested.
  onConnect: async ({ userDid }) => {
    // Example: Check if the user needs to provide a profile.
    const userExists = await checkUserInDatabase(userDid);

    if (!userExists) {
      // Return a claims object to request the needed information.
      return {
        profile: () => ({
          fields: ['fullName', 'email'],
          description: 'Please create your profile to continue',
        }),
      };
    }

    // If no claims are needed, return null or an empty object.
    return {};
  },

  onAuth: async ({ claims, userDid }) => {
    // `claims` will contain the result for the dynamically requested claim, if any.
    if (claims.length > 0) {
      console.log('User submitted dynamic claims:', claims);
    }
  },
});
```

By returning a claims object from `onConnect`, you can tailor the DID Connect session to each user's specific context, creating a more intelligent and streamlined experience.

Now that you know how to request information from the user, the next step is to learn how to process their responses.

:::action-card{title="Next Step: Handling Wallet Responses" description="Discover the various lifecycle callbacks like onAuth, onDecline, and onError to manage the entire session flow." icon="arrow-right"}
::action{label="Read More" href="/en/docs/did-connect-sdk/guides-handling-responses-b5860f/" variant="primary"}
:::

---

## The DID Connect Workflow

URL: https://www.arcblock.io/en/docs/did-connect-sdk/guides-workflow-b5860f/

A DID Connect session is a secure, decentralized authentication process that allows a user to interact with a decentralized application (DApp) using their DID Wallet. This guide breaks down the end-to-end process, from the initial QR code scan to the final handling of the user's response.

The typical workflow involves four main actors:

::::steps
:::step{title="User"}
The individual interacting with the application.
:::

:::step{title="Browser (DApp Frontend)"}
The user interface of your application running in the user's browser.
:::

:::step{title="DApp Backend"}
Your server-side application where the `@arcblock/did-connect-js` library is integrated.
:::

:::step{title="DID Wallet"}
The user's mobile or web-based wallet that manages their decentralized identity (DID) and private keys.
:::
::::

## Visual Overview

The following diagram illustrates the high-level interaction between the DApp and the DID Wallet during a typical authentication session.

![A diagram showing the DID Connect workflow between a DApp and a DID Wallet.](https://media.arcblock.io/lib/13/133ae93d6e75370d.w1600.webp)

## Step-by-Step Breakdown

Let's dive into the technical details of each step in the process. The sequence diagram below shows the complete communication flow.

![The DID Connect Workflow](https://media.arcblock.io/lib/6f/6f7fdd15036ba111.w1600.webp)

### 1. Session Initiation: Generating the QR Code

The process begins when the user wants to log in or perform a protected action.

1. <strong>Frontend Request</strong>: The DApp's frontend makes a request to a dedicated endpoint on its backend (e.g., `GET /api/did/login/token`).
2. <strong>Backend Handler</strong>: The `did-connect-js` handler (`generateSession`) on your backend creates a new, unique session. It generates:
3.
  - A unique `token` to identify the session.
  - A cryptographic `challenge` to prevent replay attacks.
  - A full DID Connect URL (e.g., `https://didconnect.io/i/?url=...`) containing this information.
4. <strong>Frontend Display</strong>: The backend returns the `token` and the `url` to the frontend. The frontend then renders the `url` as a QR code for the user to scan.

### 2. Wallet Interaction: Scanning and Approval

::::steps
:::step{title="Scan"}
The user scans the QR code with their DID Wallet.
:::

:::step{title="Request Claims"}
The wallet makes a `GET` request to the auth URL from the QR code. This hits the `onAuthRequest` handler on your backend.
:::

:::step{title="Backend Response"}
Your backend updates the session status to `scanned` and sends back a signed JSON Web Token (JWT). This JWT contains the information your application is requesting from the user, known as <strong>claims</strong> (e.g., `authPrincipal` to request a connection, or `profile` to request user data).
:::

:::step{title="User Approval"}
The wallet verifies the JWT and presents the request to the user. The user can then choose to approve or decline the request.
:::
::::

### 3. Handling the Response

1. <strong>Wallet Submission</strong>: If the user approves, the wallet creates and signs its own JWT containing the requested information. It then `POST`s this JWT back to the same auth URL.
2. <strong>Backend Verification</strong>: This request is handled by the `onAuthResponse` function in your backend. The library automatically verifies the wallet's signature and the challenge. This is the most critical step for security.
3. <strong>Execute Business Logic</strong>: If the verification is successful, the library triggers your `onAuth` callback. This is where you put your core business logic, such as:
4.
  - Finding or creating a user account based on their `userDid`.
  - Processing the `claims` data (e.g., saving the user's profile).
  - Generating a web session token for the browser.
  - Using `updateSession` to store data that the frontend can later retrieve.
5. <strong>Session Completion</strong>: The backend marks the session status as `succeed`.

### 4. Updating the Frontend

While the user is interacting with their wallet, your DApp's frontend polls a status endpoint (e.g., `GET /api/did/login/status?_t_={token}`). Once it sees the status change to `succeed`, it knows the process is complete. It can then fetch any necessary data (like a login token) from the session and update the UI accordingly, for example, by redirecting the user to their dashboard.

This entire flow provides a secure, passwordless authentication experience that puts the user in control of their data.

For a deeper understanding of how to manage the data received from the wallet, proceed to our guide on [Handling Wallet Responses](/en/docs/did-connect-sdk/guides-handling-responses-b5860f/).

---

## Overview

URL: https://www.arcblock.io/en/docs/did-connect-sdk/overview-b5860f/

Welcome to DID Connect, a protocol designed for seamless and secure authentication using Decentralized Identifiers (DIDs). This library, `@arcblock/did-connect-js`, provides the tools you need to integrate DID Connect into your Node.js applications, enabling users to log in, prove ownership of assets, sign transactions, and more, all from the security of their DID Wallet.

DID Connect empowers users by giving them control over their digital identity, while offering developers a straightforward way to build next-generation applications. For more information on the protocol itself, visit the official website at [https://www.didconnect.io](https://www.didconnect.io).

This library is designed to work in tandem with the [DID Connect UX package](https://www.npmjs.com/package/@arcblock/did-connect), which provides the frontend components necessary for a complete user experience.

## Core Concepts

At the heart of the library are two primary classes that manage the entire DID Connect session:

::::card-group
::link-card{title="WalletAuthenticator" description="This class is responsible for the application's side of the cryptographic exchange. It configures your application's identity (name, description, icon), defines the blockchain it interacts with, and handles the signing and verification of all messages sent to and from the user's wallet." icon="key"}
::link-card{title="WalletHandlers" description="This class acts as a middleware for your web server (e.g., Express.js). It manages the lifecycle of a DID Connect session, from creating the initial QR code to handling the final wallet response. You use it to define what information you need from the user (Claims) and what business logic to execute upon successful authentication." icon="server"}
::::

## The DID Connect Workflow

A typical DID Connect session involves a secure, QR-code-based interaction between your application and the user's DID Wallet. The process ensures that the user is always in control and must explicitly consent to any requested actions or data sharing.

The following diagram illustrates the end-to-end flow:

![Overview](https://media.arcblock.io/lib/04/04adf6d11870000f.w1600.webp)

## Key Concept: Claims

The central concept in a DID Connect session is the <strong>Claim</strong>. A claim is a piece of information that your application requests from the user. This could be anything from basic profile data to a cryptographic signature.

For example, you can request:

- A <strong>Profile Claim</strong> to get the user's name and email address.
- An <strong>Asset Claim</strong> to verify the user owns a specific NFT.
- A <strong>Signature Claim</strong> to have the user sign a message, such as agreeing to terms of service.

The library supports a wide variety of claim types, each designed for a specific use case. You can explore them in detail in the [Claims Reference](/en/docs/did-connect-sdk/claims-b5860f/) section.

## Next Steps

Now that you have an overview of DID Connect, you're ready to dive deeper. Where you go next depends on your goal.

::::card-group
::link-card{title="Getting Started" description="Follow our step-by-step guide to build and run your first DID Connect application from scratch." icon="rocket" href="/en/docs/did-connect-sdk/getting-started-b5860f/"}
::link-card{title="API Reference" description="Explore the detailed documentation for all available classes, methods, and options." icon="book-open" href="/en/docs/did-connect-sdk/api-reference-b5860f/"}
::::

---

## How to add/switch accounts?

URL: https://www.arcblock.io/en/docs/did-connect/add-switch-account/

1. Click on the profile picture in the top right corner of the site to open the personal control panel![image.png](https://media.arcblock.io/lib/ee/ee15c2a68efd993aab836fb4de16ee9c.w1600.webp)

1. Click on the account section below the avatar to see all the currently logged-in accounts and the button to add an account ![image.png](https://media.arcblock.io/lib/89/891a74d0d937142ddc1f8ab08cf0895e.w1600.webp)
2. If you click to switch to another account, it will automatically switch to the other account without the need to log in again.
3. If you click on add another account, the normal DID Connect process will be opened to complete the account login. The successfully logged-in account will also be displayed in this list.

---

## How do I connect my social account to a wallet?

URL: https://www.arcblock.io/en/docs/did-connect/connect-oauth-account-to-wallet/

You can easily connect to some Blocklets using your social accounts, like Google or Apple, without setting up a DID Wallet right away.

## To Connect a Social Account (OAuth)

1. Open the <strong>Profile</strong> page in the connected Blocklet

![image.png](https://media.arcblock.io/lib/2d/2db0305213da45b0dd3d2d4fa9c600ba.w1600.webp)

1. Go to the <strong>Settings</strong> tab and choose a provider (like Google or Apple) to connect

![image.png](https://media.arcblock.io/lib/bf/bf66c488a3adb180b8c90652dfe7f9c1.w1600.webp)

## To Connect a DID Wallet

There are a few ways to link your DID Wallet to your account:

1. From the <strong>Profile</strong> menu, follow the prompt to “Connect Wallet” and complete the steps

![image.png](https://media.arcblock.io/lib/3c/3c839d05f777685691099c3c69e855c3.w1600.webp)

1. Or go to <strong>Profile</strong> → <strong>Settings</strong> → <strong>Connected Accounts</strong>, and connect your DID Wallet there

![image.png](https://media.arcblock.io/lib/c0/c0b7b07748cb6bf9ec08d14eedcc09a5.w1600.webp)

1. Complete Connect（Use Web wallet or DID wallet）

![image.png](https://media.arcblock.io/lib/ed/ed43d3e50c2b588951fd3b0c94087496.w1600.webp)

<strong>If you don’t have a DID Wallet yet? You can:</strong>

1.
  - Install the [Web Wallet browser extension](https://chromewebstore.google.com/detail/did-wallet/ibjflpbmadchofnbpppegdbnifdgincp)
  - Or download the [<strong>DID Wallet</strong>](https://www.didwallet.io/en) mobile app for iOS or Android

After creating your wallet, simply scan the QR code shown in the Connect Modal, or select the “DID Wallet (Extension)” option to finish connecting.
Once linked, your wallet will appear in your <strong>ABT account</strong> as one of the connected apps.

![image.png](https://media.arcblock.io/lib/23/23a4ff24061a667357e3fef6f2160a3e.w1600.webp)

---

## Developer Guide

URL: https://www.arcblock.io/en/docs/did-connect/developer-guides/

## Overview

In this chapter, you will learn to integrate relevant DID Connect ecosystem components into your application.

## Object-Oriented

- Developers experienced in React and Node.js development

## Guide

For DID Connect integration, we offer [DID Connect UI (React)](https://www.arcblock.io/docs/did-connect-react) and [DID Connect SDK (Node.js)](https://www.arcblock.io/docs/did-connect-sdk), two major frameworks.

In addition, we have provided some usage examples below for reference:

- [Quick Start](/en/docs/did-connect/did-connect-getting-started/)

- [Request NFT](/en/docs/did-connect/request-nft/)

- [Request for signature](/en/docs/did-connect/request-text-signature/)

- [Request digest signature](/en/docs/did-connect/request-digest-signature/)

- [Request payment](/en/docs/did-connect/request-payment/)

- [Request multiple claims](/en/docs/did-connect/request-multiple-claims/)

- [Request multiple steps](/en/docs/did-connect/request-multiple-steps/)

- [Subscribe to DID Connect Events](/en/docs/did-connect/subscribe-to-events/)

- [Specify the behavior of DID Connect via URL.](/en/docs/did-connect/did-connect-custom-in-url/)

---

## Specify the behavior of DID Connect via URL.

URL: https://www.arcblock.io/en/docs/did-connect/did-connect-custom-in-url/

In some cases, users need to be able to quickly switch to a specified account in any link. This can be achieved by customizing the behavior of the DID Connect section through URL parameters.

The current features include:

- Ask the user to switch to the specified account

```typescript
type DIDConnectUrlOptions = {
  forceConnected: string;
  // sourceAppPid?: string; // 不再需要该字段，会通过 forceConnected 去查询获得
  // auto 代表引导切换（进行弹窗提示，用户可选择不切换）；
  // disabled 代表不提示（适用于支付页面，允许用户不以当前登录账户来进行支付）；
  // required 代表强制要求切换（进行页面跳转强制切换账号）
  // switchAccount?: boolean || 'auto'; // 默认 'auto'
  switchBehavior?: 'auto'|'disabled'|'required';
  // 是否展示关闭按钮（通常用于 switchBehavior 为 auto 时，但又不想展示关闭按钮的情况使用）
  showClose?: boolean; // 默认：undefined（但实际在 Confirm 组件中，默认为 true）
}
```

The overall parameters are processed by `Buffer.from(JSON.stringify(data), 'utf8').toString('base64')`, carried through the `__did-connect__` parameter.

Reference Example:

```javascript
bbqa2ma5eznki36ug2xtb2u2qy4fnysu5dnehnoft4a.did.abtnet.io/?__did-connect__=eyJzd2l0Y2hCZWhhdmlvciI6ImF1dG8iLCJmb3JjZUNvbm5lY3RlZCI6InoxZlV3VWdLanRQRUpzNkFCTGVQRWR6amRERXZadndXcDRoIiwic291cmNlQXBwUGlkIjoiek5LWWN5QmdOb0hRM0dIalVRSlVrSkg4b3A0Q0xYeVFINGVlIn0%3D
```

The final decoded data is

```javascript
{
    "switchBehavior": "auto",
    "forceConnected": "z1fUwUgKjtPEJs6ABLePEdzjdDEvZvwWp4h",
    "sourceAppPid": "zNKYcyBgNoHQ3GHjUQJUkJH8op4CLXyQH4ee"
}
```

---

## Quick Start

URL: https://www.arcblock.io/en/docs/did-connect/did-connect-getting-started/

Integrating DID Connect is simplest by first creating a Blocklet. If you are unsure how to create a Blocklet, please refer to: [Create Blocklet Document](/en/docs/createblocklet/welcome2/)

## Preconditions

- Already installed and configured [DID Wallet](https://www.didwallet.io/), and the phone and computer are connected to the same local area network.
- The Blocklet using React template has been created, the following document uses `@arcblock/did-connect`, and the Blocklet has been successfully running.

## Install dependencies

```plain
npm install @/arcblock/did-connect
# yanr add @arcblock/did-connect
# pnpm i @arcblock/did-connect
```

## Project Preparation

> The following code is an example of requesting user personal information

In the server-side code of the project, add a  `lib/auth.js`  file:

```javascript
const path = require('path');
const WalletAuthenticator = require('@blocklet/sdk/lib/wallet-authenticator');
const WalletHandler = require('@blocklet/sdk/lib/wallet-handler');

const authenticator = new WalletAuthenticator();
const handlers = new WalletHandler({
  authenticator,
});

module.exports = {
  handlers,
};

```

Then add the corresponding auth-handler file:

```javascript
const omit = require('lodash/omit');

const action = 'request-profile';

module.exports = {
  action,

onConnect() {

return {

    profile: () => ({

      description: 'Please provide your full profile',

      fields: ['fullName', 'email', 'phone', 'signature', 'avatar', 'birthday'],

    }),

  }

},

  onAuth: ({ userDid, userPk, claims, updateSession }) => {
    const claim = claims.find((x) => x.type === 'profile');
    updateSession({
      result: {
        ...omit(claim, ['type', 'signature']),
        did: userDid,
        pk: userPk,
      },
    });
  },
};

```

Then the auth-handler needs to be registered in the entry file of the service-side code:

```javascript
const express = require('express');
const app = express();

const { handlers } = require('./libs/auth');

handlers.attach({ app, ...require('./routes/auth/request-profile') });

const port = parseInt(process.env.BLOCKLET_PORT, 10);
app.listen(port, (err) => {
  if (err) throw err;
  logger.info(`> ${name} v${version} ready on ${port}`);
});

```

At this point, the server has the ability to respond to requests for user personal information in DID Connect. Next, we need to build the front-end part of the DID Connect code.

Add the `ThemeProvider` in the entry file of a React project (usually src/app.js):

```javascript
import { ThemeProvider } from '@did-connect/react';

export default function WrappedApp() {
  return (
    <ThemeProvider>
      <App />
    </ThemeProvider>
  );
}

```

## Connect Wallet

Add the following components to the application, and then mount the components onto a certain page:

```javascript
import { useState } from 'react';
import useConnect from '@arcblock/did-connect/lib/Connect/use-connect';

function RequestProfileConnect() {
  const { connectApi, connectHolder } = useConnect();
  const [connectedUser, setConnectedUser] = useState({});

  const openConnect = () => {
    connectApi.open({
      action: 'request-profile',
      locale: 'en',
      onSuccess({ result }) {

setConnectedUser(result);
      },
      messages: {
        title: 'Request user profile',
        scan: 'Please provide your name and email to continue'
      },
    });
  }

  return (
    <header className="app-header">
      {!connectedUser && (
        <Button type="button" variant="contained" size="large" onClick={openConnect}>
          Continue With
        </Button>
      )}
      {connectedUser && (
        <div style={{ textAlign: 'left' }}>
          Connected: <pre>{JSON.stringify(connectedUser, null, 2)}</pre>
          <button type="button" onClick={​openConnect}>
            Switch User
          </button>
        </div>
      )}
      {connectHolder}
    </header>
  );
}

export default RequestProfileConnect;

```

The role of this component is: After the user connects the wallet, the user information is stored in connectedUser and displayed on the page.

The key part in the code:

```javascript
connectApi.open({

action: 'request-profile',

locale: 'en',

onSuccess({ result }) {

setConnectedUser(result);

},

messages: {

title: 'Request user profile',

scan: 'Please provide your name and email to continue'

},
});

```

- messages: The text that users see during the conversation
- action: The name of the action corresponding to the server-side code
- Locale: The language displayed in the current session
- onSuccess: Callback after the current session is successful.

For complete examples, please refer to:

[did-connect/playground/react at main · ArcBlock/did-connect](https://github.com/ArcBlock/did-connect/tree/main/playground/react)

---

## Introduction

URL: https://www.arcblock.io/en/docs/did-connect/did-connect-introduction/

This is where you will learn everything about [DID Connect](https://www.didconnect.io/).

## What is DID Connect?

DID Connect is an open protocol and development kit for connecting users and decentralized applications designed and implemented based on the W3C DID standard.

- The open protocol defines the problem to be solved, the data format and the basic flow, as detailed [here](/en/docs/did-connect/did-connect-protocol/).
- The development kit provides a set of components to integrate DID Connect into applications to meet different business needs, see [here](/en/docs/did-connect/did-connect-getting-started/).

If you are a developer, please take a moment to understand the [workflow](/en/docs/did-connect/did-connect-workflow/) of DID Connect before integrating it into your application.

## Curious about what DID is?

The ArcBlock DID documentation site is under construction and will include the process of creating a DID and how to encode and decode it.

This site will only cover documentation related to DID Connect.

## Feedback

Feel free to [submit feedback](https://github.com/ArcBlock/did-connect/issues) and we will address it as soon as possible.

---

## DID Connect Protocol

URL: https://www.arcblock.io/en/docs/did-connect/did-connect-protocol/

DID Connect Protocol is an open protocol that provides a secure and decentralized mechanism for connecting users with DApps by using cryptography technology. In this protocol, we define `Connect` as the workflow that the user provides answers of the requested claims to the DApp.

This protocol involves following parties:

- User: The end user, usually involed in the workflow by using a Wallet, [DID Wallet](https://www.didwallet.io/) is a solution provided by DID Labs.
- DApp: The application that provides service to users.
- Relay: Which acts as bridge between the DApp and the User.
- REGISTRY_CHAIN: The decentralized trust authority. ArcBlock provides the ABT chain as the decentralized trust authority.

The entire connect workflow contains three processes:

- Pre-knowledge
- Request DID Connect
- Response DID Connect (could be multiple rounds)

![Image](https://media.arcblock.io/lib/31/31ac1b90c3c1b3129714d4defc5df621.w1600.webp)

### Pre-knowledge

Pre-knowledge refers to the process that user gets the information of a DApp before the real connect starts. DApp can provide the information in a QR code or deep link.

The following is an example of the content of a QR code or deep link.

```javascript
https://didWallet.io/i?action=requestAuth&url=https://example-dapp.io/auth/
```

- `linkPath`: The `linkPath` is located at the beginning of the link and is used to locate the Wallet. In this example, the 'linkPath' is [`https://didWallet.io/i`](https://didWallet.io/i) . This part is configurable, and the SDK allows developers to register their domain for their applications.
-
  - If the QR code is scanned by a third-party camera, e.g. iPhone, Wallet should be open, and the parameters will be passed to Wallet if it is installed. If Wallet is not installed, an installation page should be open. The same behavior applies to the case when the user clicks such a link. The process illustrated above depends on the deep link technology of different platforms such as [iOS](https://developer.apple.com/ios/universal-links/) and [Android](https://developer.android.com/training/app-links/).
  - If the QR code is scanned by Wallet, Wallet should ignore this section and parse the parameters.
- `action`: the action Wallet should perform in the next step. Here the action should be `requestAuth` and the Wallet should use `GET` method to access the `url`
- `url`: a [x-www-form-urlencoded](https://en.wikipedia.org/wiki/Percent-encoding#The_application.2Fx-www-form-urlencoded_type) URL. Wallet uses this url to start the Request DID Connect process latter.

### Request DID Connect

Request DID Connect is the step that the Wallet actually starts the connect process. The Wallet makes a request to the endpoint pointed by the `url` obtained from the previous step. The following is the step-by-step break down of what's going to happen of this process:

1. Wallet makes a request to the endpoint. ```javascript GET https://example-dapp.io/api/connect/relay ```
2. The response returned by the DApp shall contain following fields:

- `appPk`: required, the DApp's public key, encoded by Bitcoin Base58.
- `agentPk`: optional, the public key of the agent that has authorization from an DApp.
- `authInfo`: required, a standard JWT token.
- `appSession`: optional, the encrypted information for the DApp to process this connect session. Wallet must return it to DApp with no change. It is up to the DApp to how to encrypt this field. The following is an example response payload.

```javascript
{
  "appPk": "zBdZEnbDJTijVVCx4Nx68bzDPPMFwVizSRorvzSS3SGG2",
  "agentPk": "zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "authInfo": "eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiSldUIn0.eyJleHAiOjE1NDg4MDM0MjIsImlhdCI6MTU0ODcwMzQyMiwiaXNzIjoiZGlkOmFidDp6Tkt0Q05xWVdMWVdZVzNnV1JBMXZuUnlrZkNCWllIWnZ6S3IiLCJuYmYiOjE1NDg3MDM0MjIsInJlcXVlc3RlZENsYWltcyI6eyJkb2N1bWVudHMiOlt7Imhhc2giOiJUaGUgaGFzaCBvZiB0aGUgZG9jdW1lbnQncyBjb250ZW50IiwidXJpIjoiaHR0cHM6Ly9kb2N1bWVudC0xLmlvIn0seyJoYXNoIjoiVGhlIGhhc2ggb2YgdGhlIGRvY3VtZW50J3MgY29udGVudCIsInVyaSI6ImlwZnM6Ly9kb2N1bWVudC0yIn1dLCJwcm9maWxlIjpbImZ1bGxOYW1lIiwicGhvbmUiLCJzaGlwcGluZ0FkZHJlc3MiXSwicHJvb2ZPZkhvbGRpbmciOlt7InRva2VuIjoidG9rZW4gbmFtZSAxIiwidmFsdWUiOjE4MDAwMDB9LHsidG9rZW4iOiJ0b2tlbiBuYW1lIDIiLCJ2YWx1ZSI6MTAwMDAwMH1dfSwicmVzcG9uc2VBdXRoVXJpIjoiaHR0cHM6Ly9leGFtcGxlLWFwcGxpY2F0aW9uL3Jlc3BvbnNlLWF1dGgifQ.RasZv6ydSxOBj3H726P8THeo4K4IAd7wapqrdE4hrOVRONByAHYK1kr7uAXASc_-Mw9ShD3IcqAuwnLiEkvHCQ",
  "appSession": ""
}
```

The header and body part of `authInfo` displayed above decodes as

```javascript
{
  "alg": "Ed25519",
  "typ": "JWT"
}
```

```javascript
{
  "iss": "did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "agentDid": "did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "iat": 1548703422,
  "nbf": 1548703422,
  "exp": 1548803422,
  "challenge": "F16E730BFB914FA1",
  "version": "1.0",
  "appInfo": {
    "name": "The name of the DApp",
    "description": "The description of the DApp.",
   "url": "https://example-dapp",
    "logo": "https://example-dapp/logo"
  },
  "chainInfo": {
    "host": "https://example-dapp/api"
  },
  "action": "responseAuth",
  "url": "https://example-dapp/api/connect/relay/auth",
  "requestedClaims": [
    {
      "type": "authPrincipal",
      "description": "Please select account to continue."
    }
  ],
  "verifiableClaims:" [
    {
      "type": "certificate",
      "content": "eyJleHAiOjE1NDg4MDM0MjIsImlhdCI6MTU0ODcwMzQyMiwiaXNzIjoiVGhlIGlzc3VlcidzIGRpZCBvZiB0aGUgY2VydGlmaWNhdGUuIiwibmJmIjoxNTQ4NzAzNDIyLCJvcHMiOnsiYWdyZWVtZW50IjpbImRpZ2VzdCBvZiBhZ3JlZW1lbnQgb25lIiwiZGlnZXN0IG9mIGFncmVlbWVudCB0d28iXSwicHJvZmlsZSI6WyJmdWxsTmFtZSIsIm1vYmlsZVBob25lIiwibWFpbGluZ0FkZHJlc3MiXX0sInBrIjoiVGhlIHBrIG9mIHRoZSBpc3N1ZXIiLCJzdWIiOiJUbyB3aG9tIHRoZSBjZXJ0aWZpY2F0ZSBpcyBpc3N1ZWQuIn0",
      "sig": "The signature"
    }
  ]
}
```

- `iss`: The issuer of this JWT payload. In this example, it is the DApp's DID generated from `appPk`.
- `iat`, `nbf` and `exp`: Follows the JWT standard.
- `version`: The version of DID Auth Protocol.
- `agentDid`: If this payload is signed by an agent with the authorization from another DApp, this should be the agent DID.
- `challenge`: A 8 bytes random number in hex format that generated by DApp and must be returned unchanged by Wallet, and included when signing the auth response, the DApp should be able to verify that the both the signature and the challenge are correct.
- `appInfo`: The basic information of this DApp, such as name, description, logo and so on.
- `chainInfo`: The basic information of this chain. The protocol right now only supports `host` in side this field.
- `url`: A must-have field that will be used by the Wallet in Response DID Connect process.
- `action`: Tells what action should the Wallet perform in next step. Here it should be `responseAuth` and the Wallet shall use `POST` method to access the `url`.
- `requestedClaims`: The verifiable claims required by the DApp's. In this example, the type of the requested claim is `authPrincipal` which usually is the first claim required by the DApp in the connect process. This claim means that the DApp is asking the Wallet to set the authentication principal before they can continue to the reset of operations. The authentication principal is the user's DID whose private key shall be used to sign all of the requests sent from the Wallet to the DApp.
- `verifiableClaims`: The verifiable claims provided by the DApp, Wallet should verify those claims before any furthur processing.

1. After gets the response, the Wallet should do following verifications:
2.
  1. Verifies if the `iat` is later than the request is sent.
  2. Verifies if the response has expired by using `exp`.
  3. Verifies if the signature matches the `appPk` and if the `appPk` matches the appDid in the `iss` field.
3. <strong>(TBD)</strong> The Wallet could (may under users' request) ask a registry blockchain for the metadata of the DApp, `trustLevel` for example. ArcBlock provides ABT chain as a registry chain.
4. <strong>(TBD)</strong> The `trustLevel` can be used by the Wallet when displaying requested claims to user. For the DApp whose `appDid` cannot be found on registry blockchain, the Wallet should make the entire page with high risk mark. If an DApp is asking verifiable claims whose required trust_level is higher than the `appDid`s', the Wallet should display those claims with high risk mark.
5. The Wallet needs to determine the DID to use to set as the authentication principal. If the user has accessed the DApp before, then the Wallet should directly use extended DID as the `authPrincipal`. Otherwise, the Wallet shall create an [Extended DID](/en/docs/did-connect/did-connect-protocol/#create-extended-did) before any other operations.

### Response DID Connect

This step can be thought of as that the Wallet is answering the questions asked by the DApp through the `requestedClaims` field and the DApp would possibly return more questions depending on the answers.

After determined the value of the `userDid` to respond to the DApp, the Wallet shall organize the response just in following format:

```javascript
{
  "userPk": "",
  "userInfo": "",
  "userSession": "",
  "appSession": ""
}

```

- `userPk`: The corresponding public key of the `userDid`.
- `userInfo`: The signed authentication object in JWT format.
- `userSession`: The encrypted information for the Wallet to process this connect session. DApp must return this filed back to Wallet with no change. It is up to the Wallet to encrypt this part.
- `appSession`: The encrypted information for the DApp to process this connect session. Wallet must return it to DApp with no change.

Just like the `authInfo`, the `userInfo` is also a standard JWT object which can be decoded as follows in this example:

```javascript
{
  "alg": "Ed25519",
  "typ": "JWT"
}
{
  "iss": "userDid",
  "iat": "1548713422",
  "nbf": "1548713422",
  "exp": "1548813422",
  "challenge": "F16E730BFB914FA1",
}

```

The fields `iss` means the issuer of this JWT payload. It is also the <strong>authentication principal</strong> determined in the previous step.

### More Response DID Authentication

After the Wallet set the authentication principal, the DApp could send more claims back to the Wallet depending on its business logic. It is just like a customer manager in a bank could ask a serious of questions before he or she can process the business service for the customer. So let's see another example response that a DApp could return to the Wallet after the first round authentication.

```javascript
{
  "appPk": "zBdZEnbDJTijVVCx4Nx68bzDPPMFwVizSRorvzSS3SGG2",
  "authInfo": "eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiSldUIn0.eyJleHAiOjE1NDg4MDM0MjIsImlhdCI6MTU0ODcwMzQyMiwiaXNzIjoiZGlkOmFidDp6Tkt0Q05xWVdMWVdZVzNnV1JBMXZuUnlrZkNCWllIWnZ6S3IiLCJuYmYiOjE1NDg3MDM0MjIsInJlcXVlc3RlZENsYWltcyI6eyJkb2N1bWVudHMiOlt7Imhhc2giOiJUaGUgaGFzaCBvZiB0aGUgZG9jdW1lbnQncyBjb250ZW50IiwidXJpIjoiaHR0cHM6Ly9kb2N1bWVudC0xLmlvIn0seyJoYXNoIjoiVGhlIGhhc2ggb2YgdGhlIGRvY3VtZW50J3MgY29udGVudCIsInVyaSI6ImlwZnM6Ly9kb2N1bWVudC0yIn1dLCJwcm9maWxlIjpbImZ1bGxOYW1lIiwicGhvbmUiLCJzaGlwcGluZ0FkZHJlc3MiXSwicHJvb2ZPZkhvbGRpbmciOlt7InRva2VuIjoidG9rZW4gbmFtZSAxIiwidmFsdWUiOjE4MDAwMDB9LHsidG9rZW4iOiJ0b2tlbiBuYW1lIDIiLCJ2YWx1ZSI6MTAwMDAwMH1dfSwicmVzcG9uc2VBdXRoVXJpIjoiaHR0cHM6Ly9leGFtcGxlLWFwcGxpY2F0aW9uL3Jlc3BvbnNlLWF1dGgifQ.RasZv6ydSxOBj3H726P8THeo4K4IAd7wapqrdE4hrOVRONByAHYK1kr7uAXASc_-Mw9ShD3IcqAuwnLiEkvHCQ",
  "appSession": "",
  "userSession": ""
}

```

The header and body part of `authInfo` displayed above decodes as

```javascript
{
  "alg": "Ed25519",
  "typ": "JWT"
}
{
  "iss": "did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "iat": 1548703422,
  "nbf": 1548703422,
  "exp": 1548803422,
  "version": "1.0",
  "challenge": "F16E730BFB914FA1",
  "appInfo": {
    "name": "The name of the application",
    "description": "The description of the application.",
    "logo": "https://example-dapp/logo"
  },
  "action": "responseAuth",
  "url": "https://example-app/auth",
  "requestedClaims": [
    {
      "type": "profile",
      "description": "Please fill in basic information.",
      "items": ["fullName", "mobilePhone", "mailingAddress"]
    },
    {
      "type": "agreement",
      "description": "The user data usage agreement.",
      "meta": {
        "name": "user_agreement",
      },
      "uri": "https://document-1.io",
      "hash": {
        "method": "sha2",
        "digest": "The hash result of the document's content"
      }
    },
    {
      "type": "agreement",
      "description": "The service agreement",
      "meta": {
        "name": "service_agreement"
      },
      "uri": "ipfs://document-2",
      "hash": {
        "method": "sha3",
        "digest": "The hash result of the document's content"
      }
    }
  ]
}

```

- `meta`: An optional field in each requested claim, the Wallet <strong>MUST</strong> return this field to the DApp without any change.
- `description`: The description to display to end user.

So in this example, the DApp is asking the Wallet to provide some basic information of the user. The Wallet shall prompt a user to let him or her to finish this claims and send back to the DApp again. We will talk about how to process each type claim in next section.

### Ends an Authentication Workflow

To end an authentication workflow, you can send the last response like this:

```javascript
{
  "alg": "Ed25519",
  "typ": "JWT"
}
{
  "iss": "did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "iat": 1548703422,
  "nbf": 1548703422,
  "exp": 1548803422,
  "version": "1.0",
  "challenge": "F16E730BFB914FA1",
  "appInfo": {
    "name": "The name of the application",
    "description": "The description of the application.",
    "logo": "https://example-dapp/logo"
  },
  "status": "ok",
  "successMessage": "success message"
  "response": {
    "key": "value"
  }
}

```

Or you can return some error message like:

```javascript
{
  "status": "error",
  "errorMessage": "error message"
}

```

Send some data back to Wallet to persist:

```javascript
{
  "status": "ok",
  "response": {
    "disposition": "attachment",
    "type": "VerifiableCredential",
    "data": "json presentation of the credential"
  }
}

```

### Concatenate multiple Workflow

If you hope the Wallet continue to process another workflow after the current one, you can put the deeplink of the next workflow into the last response. For example:

```javascript
{
  "alg": "Ed25519",
  "typ": "JWT"
}
{
  "iss": "did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "iat": 1548703422,
  "nbf": 1548703422,
  "exp": 1548803422,
  "version": "1.0",
  "challenge": "F16E730BFB914FA1",
  "appInfo": {
    "name": "The name of the application",
    "description": "The description of the application.",
    "logo": "https://example-dapp/logo"
  },
  "nextWorkflow": "https://didWallet.io/i?action=requestAuth&url=https://example-dapp.io/next/workflow/"
}

```

### Decline DID Authentication

In some cases, user may choose to decline the request from the DApp, the Wallet should tell the DApp about user's decline to provide better user experience by setting `action` field to `declineAuth`, with an empty `requestedClaims` field.

```javascript
{
  "iss": "did:abt:zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr",
  "iat": 1548703422,
  "nbf": 1548703422,
  "exp": 1548803422,
  "version": "1.0",
  "action": "declineAuth",
  "challenge": "F16E730BFB914FA1",
  "requestedClaims": []
}

```

### Revoke DID Authentication

<em>TBD</em>

## Verifiable Claims

Verifiable claims is a list of claim item. Different types of claims have some common attributes even though they are designed to server under different scenarios.

- `type`: This is a must-have field for types of claims items.
- `description`: The message to display to end users, a must-have field for all types of claims items. The Wallet could omit this field when returning the claims for the sake of network bandwidth.
- `meta`: An optional field available for all types of claim item. It is up to the DApp to put some information there so that it can easily process the claims sent back from the Wallet. The Wallet <strong>MUST</strong> return this field in each claim item without any changes.

The supported types of claims are described as follows:

### AuthPrincipal

This is the first claim to ask by the DApp, it is used to informing the Wallet to set the authentication principal for the entire authentication process. The authentication principal is the `iss` field of the JWT payload sent from the Wallet.

To ask the Wallet to set up authentication principal, the DApp should respond the Wallet with this claim, usually the authPrincipal claim is silent and completed without user notice, but the DApp can ask Wallet to display a connect screen by setting `supervised` field to `true` in the claim:

```javascript
{
  "requestedClaims": [
    {
      "type": "authPrincipal",
      "description": "Please set the authentication principal.",
      "supervised": true
    }
  ]
}

```

Sometimes a DApp may want the Wallet to prove that it is a specific user. In such cases, the DApp can add the field `target` in the claim item. The Wallet must set the authentication principal to the specific DID.

```javascript
{
  "requestedClaims": [
    {
      "type": "authPrincipal",
      "description": "Please set the authentication principal to start this atomic swap.",
      "target": "did:abt:z1fw9Ycbb7cJnj1NUm6hyuSYHuTHEwph8yH",
      "supervised": false
    }
  ]
}

```

Sometimes a DApp may want the Wallet to generate a DID with customized arguments, the DApp can add the following fields in the claim item:

```javascript
{
  "requestedClaims": [
    {
      "type": "authPrincipal",
      "description": "Please generate an application account with the following settings",
      "declareParams": {
        "moniker": "application_moniker",
        "issuer": "z1fw9Ycbb7cJnj1NUm6hyuSYHuTHEwph8yH"
      },
      "targetType": {
        "role": "application",
        "hash": "sha3",
        "key": "ed25519"
      },
      "supervised": false
    }
  ]
}

```

> By default all DID are encoded into `base58_btc` format.
>

The Wallet shall generate a new DID with `targetType` settings, and make sure the DID is declared with `declareParams" before answering the claim. The Wallet should just generate the key pair of the DID randomly.

### Profile

Profile is the verifiable claim used to gather users' basic information such as name, email, age and so on. The requested information is put in the `items` sub-field. For example, when the DApp requires users to provide their first name, mobile phone number and mailing address, it could respond a claim to the Wallet in following way.

```javascript
{
  "requestedClaims": [
    {
      "type": "profile",
      "description": "Please provide the basic information.",
      "items": ["fullName", "mobilePhone", "mailingAddress"]
    }
  ]
}

```

The Wallet shall answer this claim in such way:

```javascript
{
  "requestedClaims": [
    {
      "type": "profile",
      "fullName": "Alice Bean",
      "mobilePhone": "123456789",
      "mailingAddress": {
        "addressLine1": "456 123th AVE",
        "addressLine2": "Apt 106",
        "city": "Redmond",
        "state": "WA",
        "postalCode": "98052",
        "country": "USA"
      }
    }
  ]
}

```

Please see the [appendix](/en/docs/did-connect/did-connect-protocol/#profile) for the list of all profile items.

### Agreement

Agreement is another commonly used type of claim. It stands for the agreements that a DApp asks the user to sign. An `agreement` claim type contains following fields:

- `uri`: An URI points to the content of the agreement.
- `hash`: An object where `method` sub field specifies the algorithm (sha3, sha2 and so on) used, and `digest` sub field is the hash result.
- `agreed`: A boolean value added by the Wallet to indicate if the user agrees the agreement.
- `sig`: The DSA signature of the `hash`.

When a DApp wants a user to sign agreements, it should add a list of such claim items in the response.

```javascript
{
  "requestedClaims": [
    {
      "type": "agreement",
      "description": "The user data usage agreement.",
      "meta": {
        "name": "user_agreement."
      },
      "uri": "https://document-1.io",
      "method": "sha2",
      "digest": "The hash result of the document's content"
    },
    {
      "type": "agreement",
      "description": "The service agreement",
      "meta": {
        "name": "service_agreement"
      },
      "uri": "ipfs://document-2",
      "method": "sha3",
      "digest": "The hash result of the document's content"
    }
  ]
}
```

When see this response, Wallet should prompt the user to sign the agreements. Later, the Wallet should submit a list of signed claim items back to the DApp. If the user agrees, Wallet shall add the `agreed` and the `sig` field. If the user declines, then the Wallet just need to add the `agreed` field with value `false`. No signature is required in this situation.

```javascript
{
  "requestedClaims": [
    {
      "type": "agreement",
      "uri": "https://document-1.io",
      "method": "sha2",
      "digest": "The hash result of the document's content",
      "meta": {
        "name": "user_agreement."
      },
      "agreed": true,
      "sig": "user's signature against the doc digest plus AGREED."
    },
    {
      "type": "agreement",
      "uri": "ipfs://document-2",
      "method": "sha3",
      "digest": "The hash result of the document's content",
      "meta": {
        "name": "service_agreement"
      },
      "agreed": false
    }
  ]
}
```

### Asset

The Asset claim item is used to let the Wallet to provide a on-chain Asset DID to the DApp. Usually the DApp would need to verify the ownership of the Asset against the signature and on chain Asset State. To ask the Wallet to provide an Asset DID, the DApp shall send the claim in following way:

- `filters`: required field to specify a list of filters for Wallet to select assets, if multiple filters are specified, they should be interpreted as `OR`, multiple fields inside a filter should be interpreted as `AND`, multiple values inside a field should be interpreted as `OR`, each filter can contain any of the following parameters:
-
  - `trustedIssuers`: did list of trusted issuers, default to empty list
  - `trustedParents`: did list of trusted parents, usually this refers to the nft-factory address, default to empty list
  - `tag`: asset tag for filter, default to empty
  - `address`: did of the asset, either on-chain or off-chain, default to empty string
- `optional`: field for user to skip this claim. If `optional` is true, claim response can be empty. The `optional` field is false default.

```javascript
{
  "requestedClaims": [
    {
      "type": "asset",
      "description": "Please provide the coupon you own.",
      "optional": false,
      "filters": [
        {
          "address": "zje1uzZTCZN551EWGLyyCEW9AM2wAdjymfHb"
        },
        {
          "trustedIssuers": ["zje1uzZTCZN551EWGLyyCEW9AM2wAdjymfHb"],
          "tag": "abcd"
        },
        {
          "trustedParents": ["zje1uzZTCZN551EWGLyyCEW9AM2wAdjymfHb"],
          "tag": "abcd"
        },
        {
          "trustedIssuers": ["zje1uzZTCZN551EWGLyyCEW9AM2wAdjymfHb"],
          "trustedParents": ["zje1uzZTCZN551EWGLyyCEW9AM2wAdjymfHb"],
          "tag": "abcd"
        }
      ],
      "meta": {}
    }
  ]
}
```

The Wallet shall return the response in following way:

```javascript
{
  "requestedClaims": [
    {
      "type": "Asset",
      "asset": "did:abt:zje1uzZTCZN551EWGLyyCEW9AM2wAdjymfHb",
      "ownerDid": "NFTOwner.address",
      "ownerPk": "toBase58(NFTOwner.publicKey)",
      "ownerProof": "toBase58(NFTOwner.sign(challenge))",
      "meta": {}
    }
  ]
}
```

- `asset` is the address of the on-chain asset owned by the USER, which can be any valid user within the same Wallet.
- `ownerDid` is the did of the on-chain asset owner, this should always be included because sometimes the owner maybe different from the session userDid
- `ownerPk` is the public key of the on-chain asset owner, this should always be included because sometimes the owner public key can not be found anywhere else.
- `ownerProof` is the signature by the on-chain asset owner against the session challenge.

### Signature

Signature is a commonly used claim between the Wallet and the DApp. When the DApp need to guide the Wallet user through a certain business operation, they will probably end up with signing and broadcasting a transaction to the blockchain. In this situation, the DApp usually assembles a transaction and sends to the user and asks for signature. The DApp is supposed to send the origin full payload and the type URL of the transaction to the Wallet so that the Wallet can validate the hash and display transaction to the user.

Besides the common fields among all types of claim items, the Signature claim item has following extra fields:

- `typeUrl`: The type url of this transaction. This field helps the Wallet to decode and display the raw transaction.
- `origin`: The Base58 encoded payload of the transaction. This payload should be decoded by using the `typeUrl`.
- `method`: The Hash method to use to generate the message digest of the `origin`. This value should be equal to the hash method in user's DID.
- `digest`: The message digest of the `origin`. This is the data that the Wallet signs. Wallet will validate if this digest matches with the origin data.
- `display`: A visual presentation of what user will get when the transaction is executed.
- `sig`: The signature to return.

```javascript
{
  "requestedClaims": [
    {
      "type": "signature",
      "description": "Please sign this exchange transaction.",
      "typeUrl": "fg:t:transaction",
      "origin": "base58 encoded data",
      "method": "sha3",
      "display": "JSON stringified display info",
      "digest": "base58 encoded digest",
      "meta": {
        "id": 12345
      }
    }
  ]
}

```

The Wallet shall return the signature in following format:

```javascript
{
  "requestedClaims": [
    {
      "type": "signature",
      "typeUrl": "fg:t:transaction",
      "origin": "base58 encoded data",
      "method": "sha3",
      "digest": "base58 encoded digest",
      "meta": {
        "id": 12345
      },
      "sig": "the value to return"
    }
  ]
}

```

The list of known `typeUrl`:

- `fg:t:transaction`: need Wallet decode the origin to a transaction and sign it.
- `mime:text/plain`: need Wallet decode the origin to the text and show to user.
- `mime:text/html`: need Wallet decode the origin to the html content and show to user.
- `eth:transaction`: need Wallet decode the origin to a json string, the json format: ```javascript {   "network": 1, // the eth network id   "tx": {     "to": "<eth address>",     "value": "<number string>", // eg: "10000000000000000" => 0.1 ETH     "gasLimit": "<number string>", // eg: 25100, 80000...     "data": "xxxx" // if this is not contract call, just pass empty string   } }  ``` Wallet will use the json data to create and send a ETH Transaction, before send it Wallet need display the tx detail to user, and let user use password double confirm before finally send it.

### prepareTx

prepareTx is a commonly used when the the DApp needs Wallet to pay certain amount of token to complete a business workflow, the DApp knows which kind of transaction to send, but does not know some parameters to assemble the transaction, the DApp first assembles a partial transaction and the payment requirements and sends them to the Wallet. The Wallet then figure out which accounts should be used to pay for the transaction, and then assembles the complete transaction for display and signing. Upon user confirmation, the Wallet shall submit the complete transaction with signatures to DApp for broadcasting.

Besides the common fields among all types of claim items, the `prepareTx` claim item has following extra fields:

- `partialTx`: The Base58 encoded result of the partial transaction. The Wallet shall leave it untouched on submit.
- `requirement`: The payment requirement of the transaction. The Wallet shall leave it untouched on submit.
-
  - `requirement.tokens`: Is a list to specify the required amount of each token address, token address is set to empty for primary token. When set to empty array, means that this transaction does not need any tokens.
  - `requirement.assets`: Is an object for Wallet to select a list of assets, can filter by address or parent address. When set to empty object, means that this transaction does not need any assets
- `finalTx`: The Base58 encoded result of the final signed transaction, which can be broadcasted to blockchain without any further operation. The Wallet can change the following fields to create the final transaction:
-
  - `tx.signatures` and `tx.signature` and `tx.itx.inputs`: if the transaction requires multiple accounts to pay
  - `tx.from` and `tx.delegator`: if the transaction requires delegation to complete
- `display`: A visual presentation of what user will get when the transaction is executed.

```javascript
{
  "requestedClaims": [
    {
      "type": "prepareTx",
      "description": "Please pay 2 ABT to buy VIP",
      "partialTx": "base58 encoded partial tx",
      "display": "JSON stringified display info",
      "requirement": {
        "tokens": [
          {
            "address": "TOKEN_ADDRESS",
            "value": "TOKEN_AMOUNT_AS_BIG_NUMBER_STRING"
          }
        ],
        "assets": {
          "address": ["LIST_OF_SPECIFIC_ASSETS"],
          "parent": ["LIST_OF_ASSET_PARENTS"],
          "amount": 2
        }
      },
      "meta": {
        "orderId": 12345
      }
    }
  ]
}

```

The Wallet shall return the final transaction in following format:

```javascript
{
  "requestedClaims": [
    {
      "type": "prepareTx",
      "partialTx": "base58 encoded partial tx",
      "finalTx": "base58 encoded final tx",
      "requirement": {
        "tokens": [
          {
            "address": "TOKEN_ADDRESS",
            "value": "TOKEN_AMOUNT_AS_BIG_NUMBER_STRING"
          }
        ],
        "assets": {
          "address": ["LIST_OF_SPECIFIC_ASSETS"],
          "parent": ["LIST_OF_ASSET_PARENTS"],
          "amount": 2
        }
      },
      "meta": {
        "orderId": 12345
      }
    }
  ]
}

```

### Certificate

The core of a certificate is a JWT token signed by the issuer.

```javascript
{
  "type": "certificate",
  "content": "eyJhbGciOiJFZDI1NTE5IiwidHlwZSI6IkpXVCJ9.eyJhZ2VudERpZCI6ImRpZDphYnQ6ek5LcnJQSHdCbnlWb01WWjZaRnRwcW5MR3NDUVh3aXNFdTZqIiwiZXhwIjoxNjA1MDg3MjQyLCJpYXQiOjE1NzM1NTEyNDIsImlzcyI6ImRpZDphYnQ6ek5LZzVweGNaUExvZFJBYTVZcGJoQTRtTWZIdzlRRHFyNjVzIiwibmJmIjoxNTczNTUxMjQyLCJvcHMiOnsicHJvZmlsZSI6WyJmdWxsTmFtZSIsIm1vYmlsZVBob25lIiwibWFpbGluZ0FkZHJlc3MiXX0sInZlcnNpb24iOiIxLjAifQ.3O08a7Dgqlebg-2Pu6eZQ2hOsUdjqCu6yE7DsDKUXI18D2bf6hWOpiGvT2wkIAZyvFdiiD0kQm1PgKXcXLTeBw"
}

```

The token payload looks like this:

```javascript
{
  "iss": "The issuer's did of the certificate.",
  "pk": "The pk of the issuer",
  "agentDid": "To whom the certificate is issued.",
  "iat": 1548703422,
  "nbf": 1548703422,
  "exp": 1548803422,
  "ops": {
    "profile": ["fullName", "mobilePhone", "mailingAddress"],
    "agreement": ["digest of agreement one", "digest of agreement two"]
  }
}

```

### Verifiable Credential

This claim is used by DApp to verify that the Wallet holds a valid desired verifiable credential.

- `filters` required field to specify a list of filters for Wallet to select verifiable credential, if multiple filters are specified, they should be interpreted as `OR`, multiple fields inside a filter should be interpreted as `AND`, multiple values inside a field should be interpreted as `OR`, each filter can contain any of the following parameters:
-
  - `trustedIssuers`: did list of trusted issuers, default to empty list
  - `type`: list of valid verifiable credential types, default to empty list
  - `tag`: verifiable credential tags, default to empty
  - `target`: did of the verifiable credential, either on-chain or off-chain, default to empty string
- `optional` field for user to skip this claim. If `optional` is true, claim response can be empty. The `optional` field is false default.

```javascript
{
  "requestedClaims": [
    {
      "type": "verifiableCredential",
      "description": "Please provide the coupon you own.",
      "optional": false,
      "filters": [
        {
          "trustedIssuers": ["did:abt:z1RuF9Xa2AUTJ3VHZKy2xroKzphwWKsLrY6"],
          "type": ["ServerOwnershipNFT"],
          "tag": "extra tag to filter credential"
        },
        {
          "trustedIssuers": ["did:abt:z1RuF9Xa2AUTJ3VHZKy2xroKzphwWKsLrY6"],
          "type": ["BlockletServerPassport"]
        },
        {
          "trustedIssuers": ["did:abt:z1RuF9Xa2AUTJ3VHZKy2xroKzphwWKsLrY6"],
          "type": ["BlockletServerPassport"]
        },
        {
          "target": "did:abt:z1RuF9Xa2AUTJ3VH"
        }
      ],
      "meta": {}
    }
  ]
}
```

return

```javascript
{
  "requestedClaims": [
    {
      "type": "verifiableCredential",
      "presentation": "xxxx",
      "assetDid": [""]
    }
  ]
}
```

What's Presentation

```javascript
{
  "@context": ["https://achema.arcblock.io/v0.1/context.jsonld"],
  "challenge": "F16E730BFB914FA1",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [{}],
  "proof": [{}]
}
```

proof is generated same as Verifiable Credential. One Presentation can contains multiple VCs and it have to provide multiple proofs( if VC comes from different DID). And the challenge come from did-auth JWT.

The proof‘s structure is

```javascript
{
  "type": proofTypes[typeInfo.pk],
  "created": new Date().toISOString(),
  "proofPurpose": "assertionMethod",
  "pk": "vc recipience's PK base58",
  "jws": toBase64(signature)
}
```

signature is signed by VC holder's private key.

### Use Cases

The DID Connect protocol is a generic peer-to-peer protocol that can be used in any case where authentication is required. It can be used in but is not limited to following scenarios:

- User registration.
- User logon.
- Signing documents.
- Requesting/issuing certificate.
- Applying for VISA.
- Peer-to-peer information exchange.

---

## DID Connect Workflow

URL: https://www.arcblock.io/en/docs/did-connect/did-connect-workflow/

### Glossary

We can refer to the complete DID Connect process as a `DID Connect session`, and the parties involved in the session include

- `User(Agent)`: usually refers to a digital wallet that supports the DID Connect protocol and can help manage a user's digital identity and digital assets, such as [DID Wallet](https://didwallet.io/)
- `DApp`: can be any type of decentralized application, applications in a DID Connect session usually require certain information from the user to complete a specific business process, in the ArcBlock ecosystem, applications are usually referred to by [Blocklet](https://blocklet.io/).
- `Relay`: Maintains the state of the session during the DID Connect process, relaying and verifying application requests and user responses, Relay is usually hosted in a Web Server and relies on some underlying storage to hold the session state
- `Requested Claims`: data pieces that the application assembles and sends to the user to describe what it needs the user to do according to the protocol, multiple requests can be sent at once
- `Response Claims`: data pieces assembled and submitted to the application by the wallet after the user has reviewed the application's request and agreed to it

### Flow diagram

The complete `DID Connect session` flow is illustrated in the following diagram.

![Image](https://media.arcblock.io/lib/82/82e56f7deaab3637aa945ef2fca2840c.w1600.webp)

Each step is explained as follows.

1. the user interacts with the application by providing data such as digital identity, data signature, transaction signature, verifiable statement, proof of asset ownership, pass, etc.
2. the application generates a DID Connect session and saves the session in Relay to obtain the deepLink of the session
3. the application presents the deepLink QR code to the user, and the user sweeps the code with his wallet
4. the application saves the information required from the user (Requested Claims) to Relay in a standard format after the wallet sweeps the code
5. the wallet gets the Requested Claims from the application, parses them and presents them to the user
6. The user reviews and agrees with the wallet
7. The wallet submits the response (Response Claims) to Relay, which is verified by Relay and saved in the session
8. the application gets the wallet's response by subscription or polling and continues the business process

Additional notes on the above process.

- Step 4 is merged separately from Step 2 to allow the application to know the identity of the user in some cases before it can determine exactly what information it needs from the user, for example, if it has to provide a pass under an account
- In Step 6, the user can choose to reject in the wallet, and the application will be notified of the rejection and can execute the corresponding callback.
- In step 7, if the current session is divided into multiple steps, it will go back to step 5 until all steps are completed.
- For a good user experience, most of the waits during a DID Connect session are set to timeout

In addition, steps 4 and 8 may not occur in the browser, mainly because some calculations cannot be done in the browser and some calculations are sensitive and not suitable for the browser.

- The application can provide an API at session creation time, which Relay requests to get Requested Claims when the wallet is swept
- The application can provide an API at session creation time, and Relay forwards the request here when the wallet submits Response Claims

In this case, the entire process becomes the following diagram.

![Image](https://media.arcblock.io/lib/89/89cfe5df712d02954a6f0d2172016d56.w1600.webp)

### State machine perspective

> If you are not a developer, you can safely skip this part.
>

Because the entire DID Connect process involves the wallet, the application, the user, and possibly the remote API, the state change flow and branching is complex, and the complete process of a `DID Connect session` is best described by a [<strong>state machine</strong>](https://stately.ai/viz/embed/98beeb99-5b56-4c3f-9743-3250bac3ec50?mode=viz&panel=code&showOriginalLink=1&readOnly=1&pan=0&%20zoom=1&controls=1).

Under normal circumstances, the complete sequence of state changes for a successful `DID Connect session` is

- start: session started
- loading: means the session is being created or loaded
- created: the session has been created successfully and is waiting to be scanned
- walletScanned: the wallet has been scanned
- walletConnected: the wallet has selected the identity to use for the current session
- appConnected: the application has determined the Requested Claims required for the current session
- walletApproved: The wallet has reviewed and submitted Response Claims
- appApproved: The application has consumed the Response Claims and given a response
- completed: The session is complete

In addition to these normal processes, a DID Connect session may have a number of exception states.

- rejected: The user has rejected the current operation in the wallet
- error: An error in any part of the process will cause the session to be terminated
- timeout: Waiting for the wallet or application to complete an action has timed out
- canceled: the user cancelled the operation in the browser

---

## FAQ

URL: https://www.arcblock.io/en/docs/did-connect/faq/

- [How to use DID Connect in other frameworks](/en/docs/did-connect/work-with-other-frameworks/)

---

## User Guides

URL: https://www.arcblock.io/en/docs/did-connect/guides/

- [How do I update profile?](/en/docs/did-connect/switch-profile/)

- [How to change my passport?](/en/docs/did-connect/switch-passport/)

- [How to add/switch accounts?](/en/docs/did-connect/add-switch-account/)

- [How to manage login sessions?](/en/docs/did-connect/user-session-management/)

- [How to manage storage?](/en/docs/did-connect/storage-management/)

- [How do I connect my social account to a wallet? ](/en/docs/did-connect/connect-oauth-account-to-wallet/)

- [Configure OAuth login](/en/docs/did-connect/oauth-config/)

---

## Configure OAuth login

URL: https://www.arcblock.io/en/docs/did-connect/oauth-config/

- [Configure GitHub login](/en/docs/did-connect/oauth-config-github/)

- [Configure Google Login](/en/docs/did-connect/oauth-config-google/)

- [Configure Auth0 Login](/en/docs/did-connect/oauth-config-auth0/)

---

## Configure Auth0 Login

URL: https://www.arcblock.io/en/docs/did-connect/oauth-config-auth0/

Auth0 is a third-party login management platform that allows easy integration of login methods such as Google, Apple, GitHub, etc. Blocklet Server supports configuring and enabling Auth0 login for a Blocklet.

The following will introduce how to configure Auth0 login in Blocklet and use the Auth0 account to complete the login.

1. Sign up for an Auth0 account.
2.
  - Open the website [https://auth0.com/](https://auth0.com/) and create an account.
3. Create a tenant
4.
  - Click on the button in the top left corner, select "Create tenant"
  - ![image.png](https://media.arcblock.io/lib/36/36f75b0f4019d61823fdb0dbb4cd9b33.w1600.webp)
5. Create an application
6.
  1. Click the "Create Application" button.
  2. ![image.png](https://media.arcblock.io/lib/25/25b64b4515a62a83089c409039bdeed7.w1600.webp)
  3. Create "Single Page Web Applications" selected.
  4. ![image.png](https://media.arcblock.io/lib/b1/b11e2e1a78b8299393ccfe1dc9a12f83.w1600.webp)
  5. Save Domain, Client ID, and Client Secret for future use
  6. ![image.png](https://media.arcblock.io/lib/4a/4a9e629a419d2b47eaaa1f0049818adf.w1600.webp)
7. Configure Auth0 information in the Blocklet control panel.
8.
  1. Go to the control panel of Blocklet, click on "Dashboard", "Configuration", "Login" and "Third Party Login" in order.
  2.
    1. ![image.png](https://media.arcblock.io/lib/05/05a31e4b9544c30aebd918592b1528d9.w1600.webp)
  3. Enter the "Domain", "Client ID", and "Client Secret" that were just saved, and save
9. Fill in trusted site information in the Auth0 control panel.
10.
  1. Find the designated application details page of Auth0, open the "Settings" panel, and locate the `Application URIs` on the page.
  2. ![image.png](https://media.arcblock.io/lib/10/106043c0eaf6bcbb3f7427ecd19ae25b.w1600.webp)
  3. According to the above screenshot, fill in the corresponding URL, and replace `demo.blocklet.dev` with the access domain of your current Blocklet.
  4. Save to complete configuration
11. At this time on the Blocklet login page, you can see that you can log in via Auth0
12. ![image.png](https://media.arcblock.io/lib/0d/0dbfc0082997e1c0c28ce38a31dc21de.w1600.webp)

---

## Configure GitHub login

URL: https://www.arcblock.io/en/docs/did-connect/oauth-config-github/

Github provides OAuth login method, users can log in to GitHub OAuth-enabled applications through their GitHub accounts. For users, they no longer need to remember different accounts and passwords; for applications, there is no need to develop their own login and registration system. So, it is a good thing for both users and application developers.

The Blocklet Server supports configuring and enabling GitHub login for a Blocklet. Below is how to configure GitHub login in a Blocklet and use a GitHub account to complete the login.

1. Sign up for a GitHub account
2. Create GitHub OAuth project
3.
  - Open  [https://github.com/settings/developers](https://github.com/settings/developers)
  - Click `New OAuth App`, fill in the corresponding information as prompted on the page. Replace `demo.blocklet.dev` with the domain of the Blocklet for GitHub login configuration as shown in the figure below.
  -
    - Application name: Fill in the application name, support customization.
    - Homepage URL: Fill in the address of the application homepage, such as: [`https://demo.blocklet.dev`](https://demo.blocklet.dev), remember to replace demo.blocklet.dev with the domain of your application.
    - Authorization callback URL: Fill in the callback address of the application, such as: [`https://demo.blocklet.dev/.well-known/service/oauth/callback/github`](https://demo.blocklet.dev/.well-known/service/oauth/callback/github), remember to replace demo.blocklet.dev with the domain of your application.

1.
  -
    - ![image.png](https://media.arcblock.io/lib/f1/f1d3f6f86824ad0805a9852762807ef4.w1600.webp)
  - Click on `Register application`, and you will be taken to the details page of this OAuth project.
  - Click `Generate a new client secret`
  -
    - ![image.png](https://media.arcblock.io/lib/24/24cf4779e6b8e617730a4a95b6e2f47d.w1600.webp)
  - Save `Client ID` and `Client secrets`
2. Configure Blocklet
3.
  - Arrive at the control panel of Blocklet, click "Dashboard", "Configuration", "Login", "Third Party Login" in sequence.
  -
    - ![image.png](https://media.arcblock.io/lib/6a/6aab11976b0561e625fac88a971fa195.w1600.webp)
  - fill in the `Client ID` that was just saved, `Client Secret`, save
4. At this time on the login page of Blocklet, you can now see the option to log in with GitHub.
5.
  - Click on  `GitHub`  to log in.
  -
    - ![image.png](https://media.arcblock.io/lib/d3/d394aff2b0db2211dc8d682feb08eefe.w1600.webp)

---

## Configure Google Login

URL: https://www.arcblock.io/en/docs/did-connect/oauth-config-google/

Google provides the OAuth login method, allowing users to log in to applications that have integrated Google OAuth using their Google accounts. For users, this means they no longer need to remember different accounts and passwords, and for applications, there is no need to develop their own login and registration system. So it's a good thing for both users and application developers.

Blocklet Server supports configuring and enabling Google login for a Blocklet. Below is how to configure Google login in a Blocklet and use Google accounts to log in.

1. Register your Google Account.
2. Create project
3.
  - Open the website: [https://console.cloud.google.com/cloud-resource-manager](https://console.cloud.google.com/cloud-resource-manager)
  - Click `CREATE PROJECT`
  - "Fill in the project name"
  -
    - ![image.png](https://media.arcblock.io/lib/19/1941c893ee39ea609b3746037787ad27.w1600.webp)
  - Go to [https://console.cloud.google.com/apis/dashboard](https://console.cloud.google.com/apis/dashboard)
  - Make sure that the top left corner of the screen displays the project you just created.
  -
    - ![image.png](https://media.arcblock.io/lib/b6/b675086e579d98600de2cfc81f6f085c.w1600.webp)
4. Configure OAuth
5.
  - Click `OAuth consent screen`, select `External`, click `CREATE`
  -
    - ![image.png](https://media.arcblock.io/lib/fc/fc89035d17de943f1b696c3f591d02cb.w1600.webp)
  - Fill in the necessary information according to the instructions on the page
  -
    - ![image.png](https://media.arcblock.io/lib/2f/2fe2f5d0bbffcc453ce173f4a7bbb1ec.w1600.webp)
6. Create credentials
7.
  - Click  `Credentials`  , click  `CREATE CREDENTIALS`  , select  `OAuth client ID`
  -
    - ![image.png](https://media.arcblock.io/lib/ea/ea3a0526a521944c3948df5591885ef4.w1600.webp)
  - Select `Web application`, fill in `Name`, configure the domain name of the Blocklet that needs Google login according to your needs, and replace `demo.blocklet.dev` with the corresponding fields as shown in the figure.
  -
    - ![image.png](https://media.arcblock.io/lib/3a/3a3f07fb3fd66baf1c02d5fa8d6e0d4a.w1600.webp)
  - After clicking on `CREATE`, the page will display a success message.
  -
    - ![image.png](https://media.arcblock.io/lib/1d/1da43b162061da62110288de19aaec09.w1600.webp)
  - Save `Client ID` and `Client secret`
8. Configure Blocklet
9.
  - Arrive at the control panel of Blocklet, click "Dashboard", "Configuration", "Login", "Third Party Login" in order
  -
    - ![image.png](https://media.arcblock.io/lib/0a/0a841852d50d86ca3ac7e093ca29f7c4.w1600.webp)
  - Fill in the just saved `Client ID`, `Client Secret`, save
10. At this time on the Blocklet login page, you can see that you can log in via Google.
11. ![image.png](https://media.arcblock.io/lib/b1/b1ad8dbf2d055c10ab418cc3d8ff2ad8.w1600.webp)
  - Click `Google` to log in.

---

## Reference

URL: https://www.arcblock.io/en/docs/did-connect/references/

- [DID Connect Protocol](/en/docs/did-connect/did-connect-protocol/)

- [DID Connect Workflow](/en/docs/did-connect/did-connect-workflow/)

- [Type cheatsheet](/en/docs/did-connect/type-cheatsheet/)

---

## Request digest signature

URL: https://www.arcblock.io/en/docs/did-connect/request-digest-signature/

> This function is basiclly same as
> [Request for signature](/en/docs/did-connect/fyJuA72xu-IcyCJnjdhQya0u/)
>  , the difference lies in the ability to simplify the data to be signed and protect the original content of the signature, <em>follow this article to learn how to sign a data digest with DID Connect.</em>

The basic process is consistent with the "Quick Start" chapter, change the code in the handler as follows:

```javascript
const { toTypeInfo } = require('@arcblock/did');
const { fromPublicKey } = require('@ocap/wallet');
const { types, getHasher } = require('@ocap/mcrypto');
const { toBase58 } = require('@ocap/util');

const logger = require('../../libs/logger');

const hasher = getHasher(types.HashType.SHA3);
const data = 'abcdefghijklmnopqrstuvwxyz'.repeat(32);

const action = 'request-digest-signature';

module.exports = {
  action,

onConnect() {

  return {

    signature: () => {

      return {

        description: 'Please sign the digest',

        digest: toBase58(hasher(data, 1)),

      };

    },

  };

},

  onAuth: ({ userDid, userPk, claims, updateSession }) => {
    const type = toTypeInfo(userDid);
    const user = fromPublicKey(userPk, type);
    const claim = claims.find((x) => x.type === 'signature');

    logger.info(`${action}.onAuth`, { userPk, userDid, claim });

    if (claim.origin) {
      if (user.verify(claim.origin, claim.sig, claim.method !== 'none') === false) {
        throw new Error('Invalid origin signature');
      }
    }

    // We do not need to hash the data when verifying
    if (claim.digest) {
      if (user.verify(claim.digest, claim.sig, false) === false) {
        throw new Error('Invalid digest signature');
      }
    }
    updateSession({
      result: {
        origin: data,
        digest: claim.digest,
        sig: claim.sig,
      },
    });
  },
};
```

Change the front-end part calling the DID Connect code to the following:

```javascript
connectApi.open({
  locale: 'en',
  action: 'request-digest-signature',
  onSuccess({ result }) {
    // signatue data will be in result
  },
  messages: {
    title: 'Request Digest Signature',
    scan: 'Please sign the digest to continue',
  },
});

```

---

## Request multiple claims

URL: https://www.arcblock.io/en/docs/did-connect/request-multiple-claims/

> In some cases, you may need do multiple signature in single one DID Connect, which can get a smoother experience,  <em>follow this article to learn how to do multiple claims with DID Connect.</em>

The basic process is consistent with the "Quick Start" chapter, change the code in the handler as follows:

```javascript
const { fromBase58, toBase58 } = require('@ocap/util');
const { getHasher, types } = require('@ocap/mcrypto');

const { getRandomMessage } = require('../../libs/utils');
const logger = require('../../libs/logger');

const hasher = getHasher(types.HashType.SHA3);
const data = 'abcdefghijklmnopqrstuvwxyz'.repeat(32);

const action = 'request-multiple-claims';

module.exports = {
  action,

onConnect() {

  return {

    signText: [

      'signature',

      () => {

        return {

          type: 'mime:text/plain',

          data: getRandomMessage(),

          description: 'Please sign the text',

        };

      },

    ],

    signDigest: [

      'signature',

      () => {

        return {

          description: 'Please sign the digest',

          digest: toBase58(hasher(data, 1)),

        };

      },

    ],

  };

},

  onAuth: ({ userDid, userPk, claims, updateSession }) => {
    logger.info(`${action}.onAuth`, { userPk, userDid, claims });
    updateSession({
      result: [
        {
          origin: fromBase58(claims[0].origin).toString(),
          sig: claims[0].sig,
        },
        {
          origin: data,
          digest: claims[1].digest,
          sig: claims[1].sig,
        },
      ],
    });
  },
};
```

Change the front-end part calling the DID Connect code to the following:

```javascript
connectApi.open({
  locale: 'en',
  action: 'request-multiple-claims',
  onSuccess({ result }) {
    // multi claims data will be in result, result would be an array
  },
  messages: {
    title: 'Request Multiple Claims',
    scan: 'In this session, you will do both text signing and summary signing',
  },
});
```

---

## Request multiple steps

URL: https://www.arcblock.io/en/docs/did-connect/request-multiple-steps/

> Similar to
> [Request multiple claims](/en/docs/did-connect/UPgUNaoBNy_PsL5xsxadby5R/)
>  , you can do multiple signature in single one DID Connect, but there are some different features, <em>follow this article to learn how to do multiple steps with DID Connect.</em>

The basic process is consistent with the "Quick Start" chapter, change the code in the handler as follows:

```javascript
const { fromBase58, toBase58 } = require('@ocap/util');
const { getHasher, types } = require('@ocap/mcrypto');

const { getRandomMessage } = require('../../libs/utils');
const logger = require('../../libs/logger');

const hasher = getHasher(types.HashType.SHA3);
const data = 'abcdefghijklmnopqrstuvwxyz'.repeat(32);

const action = 'request-multiple-steps';

module.exports = {
  action,

onConnect() {

  return [

    {

      signature: () => {

        return {

          type: 'mime:text/plain',

          data: getRandomMessage(),

          description: 'Please sign the text',

        };

      },

    },

    {

      signature: () => {

        return {

          description: 'Please sign the digest',

          digest: toBase58(hasher(data, 1)),

        };

      },

    },

  ];

},

  onAuth: ({ userDid, userPk, claims, step, req, updateSession }) => {
    logger.info(`${action}.onAuth`, { step, userPk, userDid, claims });
    const result = req?.context?.store?.result || [];
    const claim = claims.find((x) => x.type === 'signature');
    if (step === 1) {
      result.push({
        step,
        origin: fromBase58(claim.origin).toString(),
        sig: claim.sig,
      });
    } else if (step === 2) {
      result.push({
        step,
        origin: data,
        digest: claim.digest,
        sig: claim.sig,
      });
    }

    updateSession({
      result,
    });
  },
};
```

1. `onConnect` field must return an array
2. Will not see `Prev` button in the DID Connect process, because each claim item is independent
3.
  - ![image.png](https://media.arcblock.io/lib/7a/7abfc6aaa55477d4b0384d8ce420e60f.w1600.webp)
4. `onAuth` callback will be called multiple times, which means you can get results from the previous DID Connect, this is the biggest difference with  [Request multiple claims](/en/docs/did-connect/UPgUNaoBNy_PsL5xsxadby5R/)

Change the front-end part calling the DID Connect code to the following:

```javascript
connectApi.open({
  locale: 'en',
  action: 'request-multiple-steps',
  onSuccess({ result }) {
    // multi claims data will be in result, result would be an array
  },
  messages: {
    title: 'Request Multiple Steps',
    scan: 'In this session, you will do a text signature followed by a summary signature',
  },
});
```

---

## Request NFT

URL: https://www.arcblock.io/en/docs/did-connect/request-nft/

> In some cases, you may need check if your DID Wallet has specific NFT or VC, like if you've been to ArcBlock devcon 2021, follow this article to learn how to request some NFT or VC with DID Connect.

The basic process is consistent with the "Quick Start" chapter, change the code in the handler as follows:

```javascript
const { fromPublicKey } = require('@ocap/wallet');
const { toAddress, fromBase58, toBuffer } = require('@ocap/util');
const { toTypeInfo } = require('@arcblock/did');

const { verifyAssetClaim } = require('../../libs/utils');
const { wallet } = require('../../libs/auth');
const logger = require('../../libs/logger');

const validateAgentProof = (claim) => {
  const ownerDid = toAddress(claim.ownerDid);
  const ownerPk = fromBase58(claim.ownerPk);
  if (!claim.agentProof) {
    throw new Error('agent proof is empty');
  }

  if (typeof claim.agentProof === 'string') {
    claim.agentProof = JSON.parse(claim.agentProof);
  }

  logger.info('claim.agentProof.nonce', claim.agentProof.nonce);
  logger.info('claim.agentProof.signature', claim.agentProof.signature);

  const { nonce } = claim.agentProof;
  if (nonce < Math.ceil(Date.now() / 1000) - 5 * 60) {
    throw new Error('agent proof is expired: ttl is 5 minutes');
  }

  const message = Buffer.concat([toBuffer(nonce.toString()), toBuffer(wallet.address)]);
  const signer = fromPublicKey(ownerPk, toTypeInfo(ownerDid));
  const signature = fromBase58(claim.agentProof.signature);

  if (claim.type === 'asset') {
    if (!signer.verify(message, signature)) {
      throw new Error('agent proof is invalid for asset');
    }
  }

  if (claim.type === 'verifiableCredential') {
    if (!signer.verify(message, signature)) {
      throw new Error('agent proof is invalid for vc');
    }
  }
};

const action = 'request-nft';

module.exports = {
  action,

onConnect() {

  return​ {

    assetOrVC: () => {

      return {

        description: 'Please provide NFT or VC to continue',

        filters: [

          {

            type: ['NFTBadge', 'NFTCertificate'],

            trustedIssuers: [

              // wallet.address,

              'zNKXAEjKYXEnf2hf18NjTQsa1JajA9gJ3haY',

            ],

          },

        ],

      };

    },

  };

},​
  onAuth: async ({ claims, challenge, updateSession }) => {
    const asset = claims.find((x) => x.type === 'asset');

    if (!asset) {
      throw new Error('Neither NFT nor VC is provided');
    }

    logger.info(`${action}.onAuth.asset`, asset);

    validateAgentProof(asset, challenge);

    const assetState = await verifyAssetClaim({ claim: asset, challenge });
    updateSession({
      result: asset,
    });
    return { successMessage: `You provided asset: ${assetState.address}` };
  },
};

```

Change the front-end part calling the DID Connect code to the following:

```javascript
connectApi.open({
  locale: 'en',
  action: 'request-nft',
  onSuccess({ result }) {
    // NFT data will be in result
  },
  messages: {
    title: 'Request NFT',
    scan: 'Please provide a NFT to continue',
  },
});

```

---

## Request payment

URL: https://www.arcblock.io/en/docs/did-connect/request-payment/

> In some cases, you may need to pay some fees to a Blocklet, <em>follow this article to learn how to request payment with DID Connect.</em>

The basic process is consistent with the "Quick Start" chapter, change the code in the handler as follows:

```javascript
/* eslint-disable no-console */
const { fromTokenToUnit } = require('@ocap/util');
const { fromAddress } = require('@ocap/wallet');

const { wallet, client } = require('../../libs/auth');
const { getTokenInfo, pickGasPayerHeaders } = require('../../libs/utils');
const env = require('../../libs/env');
const logger = require('../../libs/logger');

const action = 'request-payment';
module.exports = {
  action,

onConnect() {

  return {

    signature: async ({ userDid, userPk }) => {

      const amount = 1;

      const token = await getTokenInfo();

      return {

        type: 'TransferV2Tx',

        data: {

          from: userDid,

          pk: userPk,

          itx: {

            to: wallet.address,

            tokens: [

              {

                address: env.localTokenId,

                value: fromTokenToUnit(amount, token.decimal).toString(),

              },

            ],

          },

        },

        description: `Please pay ${amount} ${token.symbol} to application`,

      };

    },

  };

},
  onAuth: async ({ req, claims, userDid, updateSession }) => {
    try {
      const claim = claims.find((x) => x.type === 'signature');
      const tx = client.decodeTx(claim.origin);
      const user = fromAddress(userDid);
      if (claim.from) {
        tx.from = claim.from;
      }
      if (claim.delegator) {
        tx.delegator = claim.delegator;
      }
      const hash = await client.sendTransferV2Tx(
        {
          tx,
          wallet: user,
          signature: claim.sig,
        },
        pickGasPayerHeaders(req),
      );

      logger.info(`${action}.onAuth`, { claims, userDid, hash });
      updateSession({
        result: {
          hash,
          tx,
          origin: claim.origin,
          sig: claim.sig,
        },
      });
      return { hash, tx: claim.origin };
    } catch (err) {
      logger.info(`${action}.onAuth.error`, err);
      throw new Error('Send token failed!');
    }
  },
};
```

You can find `token.address` in here [https://explorer.abtnetwork.io/explorer/tokens](https://explorer.abtnetwork.io/explorer/tokens)

Change the front-end part calling the DID Connect code to the following:

```javascript
connectApi.open({
  locale: 'en',
  action: 'request-payment',
  onSuccess({ result }) {
    // payment data will be in result
  },
  messages: {
    title: 'Request Payment',
    scan: 'Please sign the transaction to continue',
  },
});
```

---

## Request for signature

URL: https://www.arcblock.io/en/docs/did-connect/request-text-signature/

> In some cases, you may need to use your DID Wallet to sign some data, this signature can be verified by your DID Wallet, follow this article to learn how to generate a signature with DID Connect.

The basic process is consistent with the "Quick Start" chapter, change the code in the handler as follows:

```javascript
/* eslint-disable no-console */
const { toTypeInfo } = require('@arcblock/did');
const { fromPublicKey } = require('@ocap/wallet');
const { fromBase58 } = require('@ocap/util');
const { getRandomBytes } = require('@ocap/mcrypto');

const getRandomMessage = (len = 16) => {
  const hex = getRandomBytes(len);
  return hex.replace(/^0x/, '').toUpperCase();
};

const action = 'request-text-signature';
module.exports = {
  action,

onConnect() {

  return {

    signature: () => {

      const data = getRandomMessage();

      return {

        description: 'Please sign the text',

        type: 'mime:text/plain',

        data,

      };

    },

  };

},

  // eslint-disable-next-line consistent-return
  onAuth: ({ userDid, userPk, claims, updateSession }) => {
    const type = toTypeInfo(userDid);
    const user = fromPublicKey(userPk, type);
    const claim = claims.find((x) => x.type === 'signature');

    logger.info(`${action}.onAuth`, { userPk, userDid, claim });

    if (claim.origin) {
      if (user.verify(claim.origin, claim.sig, claim.method !== 'none') === false) {
        throw new Error('Origin signature error');
      }
    }

    updateSession({
      result: {
        origin: fromBase58(claim.origin).toString(),
        sig: claim.sig,
      },
    });
  },
};
```

Change the front-end part calling the DID Connect code to the following:

```javascript
connectApi.open({
  locale: 'en',
  action: 'request-text-signature',
  onSuccess({ result }) {
    // signatue data will be in result
  },
  messages: {
    title: 'Request Text Signature',
    scan: 'Please sign some text to continue',
  },
});

```

---

## How to manage storage?

URL: https://www.arcblock.io/en/docs/did-connect/storage-management/

1. Click on the personal avatar in the upper right corner of the website, click to show the menu, and click on the personal center button ![image.png](https://media.arcblock.io/lib/a6/a6699b49580a91fe8f8cfc5a9752e3f9.w1600.webp).

1. On the user center page, click the settings button, and open the storage management tab ![image.png](https://media.arcblock.io/lib/f6/f6394b9fdfce0bf21bbd33b12333dba8.w1600.webp)
2. On this page, you can view the current connected DID Spaces apps, or re-connect the current app to other DID Spaces apps.

---

## Subscribe to DID Connect Events

URL: https://www.arcblock.io/en/docs/did-connect/subscribe-to-events/

## Overview

In this section, you will learn how to use `@arcblock/did-connect` to subscribe to events such as login, logout, and successful connection to a DID Space.

## Prerequisites

- The easiest way to integrate DID Connect is by creating a Blocklet. For instructions on creating a Blocklet, please refer to the [Create Blocklet documentation](/en/docs/createblocklet/welcome2/).
- Ensure your application uses `SessionProvider`. See: [https://www.arcblock.io/docs/blocklet-developer/user-and-passport#login](/en/docs/blocklet-developer/user-and-passport/#login)

## Code Examples

### Subscribe to Login Events

This event is triggered upon successful user login.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.LOGIN, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}​
```

Following event is triggered when the user cancels login.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.CANCEL_LOGIN, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

### Subscribe to Logout Events

This event is triggered when the user logs out.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.LOGOUT, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}​

```

### Subscribe to Profile Events

When the user switches profiles, this event is triggered.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.SWITCH_PROFILE, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

When a user cancels switching profiles, this event is triggered.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.CANCEL_SWITCH_PROFILE, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

### Subscribe to Passport Events

This event is triggered when the user switches Passports.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.SWITCH_PASSPORT, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

When the user cancels switching passports, this event will be triggered.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.CANCEL_SWITCH_PASSPORT, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

### Subscribe to DID Wallet Events

When a user's account is linked to a DID Wallet, this event is triggered.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.BIND_WALLET, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

When a user unbinds their DID Wallet, this event is triggered.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.CANCEL_BIND_WALLET, (...args) => {

console.log(args);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}
```

### Subscribe to the DID Space Events

This event is triggered when a user successfully connects to a DID Space.

```javascript
import { EVENTS } from '@arcblock/did-connect/lib/Session';

function Example() {

const { events } = useSessionContext();

  useEffect(() => {
    events.on(EVENTS.DID_SPACE_CONNECTED, (response, decryptFunc) => {
      console.log(response, decryptFunc);
      // coding...
    });
  }, []);

  return <div>Example</div>;
}​
```

---

## How to change my passport?

URL: https://www.arcblock.io/en/docs/did-connect/switch-passport/

During the process of accessing the blocklet, you may encounter some page prompts indicating that you do not have permission to access it. This means that the passport you are currently using to log in is insufficient. You may consider switching accounts or passports to increase the permissions of the current account.

1. Open any site (e.g.  [https://www.arcblock.io/en](https://www.arcblock.io/en) ), click on the person's avatar in the upper right corner ![image.png](https://media.arcblock.io/lib/a6/a6699b49580a91fe8f8cfc5a9752e3f9.w1600.webp)
2. Click on the personal center to jump to the personal center page
3. Click the passport button on the page to switch passports ![image.png](https://media.arcblock.io/lib/22/22b9147657fb64c9ad0c48c5d2f9ad37.w1600.webp)

---

## How do I update profile?

URL: https://www.arcblock.io/en/docs/did-connect/switch-profile/

1. Open any site (such as [https://www.arcblock.io/en](https://www.arcblock.io/en) ), click on the person's profile picture in the upper right corner ![image.png](https://media.arcblock.io/lib/a6/a6699b49580a91fe8f8cfc5a9752e3f9.w1600.webp)
2. Click on the personal center to navigate to the personal center page.
3. Click on the avatar on the page to switch personal information ![image.png](https://media.arcblock.io/lib/b8/b8825b7eb7e329c2864171fe55706a74.w1600.webp)

---

## Type cheatsheet

URL: https://www.arcblock.io/en/docs/did-connect/type-cheatsheet/

## Agreement

```javascript
interface TAgreementRequest {
  chainInfo?: TChainInfo;
  description: string;
  digest: string;
  meta?: any;
  method?: 'keccak' | 'sha3' | 'keccak_384' | 'sha3_384' | 'keccak_512' | 'sha3_512' | 'sha2';
  type: 'agreement';
  uri: string;
}

interface TAgreementResponse {
  agreed: boolean;
  meta?: any;
  sig?: string;
  type: 'agreement';
}

```

## Asset

```javascript
interface TAssetRequest {
  address?: string;
  chainInfo?: TChainInfo;
  description: string;
  filters?: {
    address?: string;
    tag?: string;
    trustedIssuers?: (
      | {
          did: string;
          endpoint: string;
        }
      | string
    )[];
    trustedParents?: string[];
  }[];
  meta?: any;
  optional?: boolean;
  tag?: string;
  trustedIssuers?: (
    | {
        did: string;
        endpoint: string;
      }
    | string
  )[];
  trustedParents?: string[];
  type: 'asset';
}

interface TAssetResponse {
  asset: string;
  meta?: any;
  ownerDid: string;
  ownerPk: string;
  ownerProof: string;
  type: 'asset';
}

```

## AuthPrincipal

```javascript
interface TAuthPrincipalRequest {
  chainInfo?: TChainInfo;
  declareParams?: {
    issuer: string;
    moniker: string;
  };
  description: string;
  meta?: any;
  supervised?: boolean;
  target?: string;
  targetType?: {
    hash: 'keccak' | 'sha3' | 'keccak_384' | 'sha3_384' | 'keccak_512' | 'sha3_512' | 'sha2';
    key: 'ed25519' | 'secp256k1' | 'ethereum';
    role:
      | 'account'
      | 'node'
      | 'device'
      | 'application'
      | 'contract'
      | 'bot'
      | 'asset'
      | 'stake'
      | 'validator'
      | 'group'
      | 'tx'
      | 'tether'
      | 'swap'
      | 'delegation'
      | 'vc'
      | 'blocklet'
      | 'registry'
      | 'token'
      | 'factory'
      | 'rollup'
      | 'any';
  };
  type: 'authPrincipal';
}

interface TAuthPrincipalResponse {
  meta?: any;
  type: 'authPrincipal';
  userDid: string;
  userPk: string;
}

```

## PrepareTx (Request Payment)

```javascript
interface TPrepareTxRequest {
  chainInfo?: TChainInfo;
  description: string;
  display?: string;
  meta?: any;
  partialTx: string;
  requirement: {
    assets?: {
      address?: string[];
      issuer?: string[];
      parent?: string[];
    };
    tokens: {
      address: string;
      value: string;
    }[];
  };
  type: 'prepareTx';
}

interface TPrepareTxResponse {
  finalTx: string;
  meta?: any;
  type: 'prepareTx';
}

```

## Profile

```javascript
interface TProfileRequest {
  chainInfo?: TChainInfo;
  description: string;
  items?: ('fullName' | 'email' | 'phone' | 'signature' | 'avatar' | 'birthday')[];
  meta?: any;
  type: 'profile';
}

interface TProfileResponse {
  avatar?: string;
  birthday?: string;
  email?: string;
  fullName?: string;
  meta?: any;
  phone?: string;
  signature?: string;
  type: 'profile';
}

```

## Signature (Sign Any thing from Any Blockchain)

```javascript
interface TSignatureRequest {
  chainInfo?: TChainInfo;
  description: string;
  digest?: string;
  display?: string;
  meta?: any;
  method?: 'none' | 'keccak' | 'sha3' | 'keccak_384' | 'sha3_384' | 'keccak_512' | 'sha3_512' | 'sha2';
  origin?: string;
  type: 'signature';
  typeUrl: 'fg:t:transaction' | 'mime:text/plain' | 'mime:text/html' | 'eth:transaction';
}

interface TSignatureResponse {
  meta?: any;
  sig: string;
  type: 'signature';
}

```

## Verifiable Credential

```javascript
interface TVerifiableCredentialRequest {
  chainInfo?: TChainInfo;
  description: string;
  filters?: {
    tag?: string;
    target?: string;
    trustedIssuers?: (
      | {
          did: string;
          endpoint: string;
        }
      | string
    )[];
    type?: string[];
  }[];
  item?: string[];
  meta?: any;
  optional?: boolean;
  tag?: string;
  target?: string;
  trustedIssuers?: (
    | {
        did: string;
        endpoint: string;
      }
    | string
  )[];
  type: 'verifiableCredential';
}

interface TVerifiableCredentialResponse {
  assetDid?: string;
  meta?: any;
  optional?: boolean;
  presentation?: string;
  type: 'verifiableCredential';
}

```

## DID Connect Session

```javascript
interface TSession {
  appInfo: TAppInfo;
  approveResults: any[];
  approveUrl?: string;
  authUrl: string;
  autoConnect: boolean;
  challenge: string;
  connectUrl?: string;
  currentConnected?: {
    didwallet: TWalletInfo;
    userDid: string;
    userPk: string;
  } | null;
  currentStep: number;
  error?: string;
  onlyConnect: boolean;
  previousConnected?: {
    didwallet: 'ios' | 'android' | 'web' | '';
    userDid: string;
    userPk: string;
  } | null;
  requestedClaims: TAnyRequest[][];
  responseClaims: TAnyResponse[][];
  sessionId: string;
  status:
    | 'created'
    | 'walletScanned'
    | 'walletConnected'
    | 'appConnected'
    | 'walletApproved'
    | 'appApproved'
    | 'error'
    | 'timeout'
    | 'rejected'
    | 'canceled'
    | 'completed';
  strategy: string | 'default' | 'smart';
  timeout: {
    app: number;
    relay: number;
    wallet: number;
  };
  updaterPk: string;
}

```

## DID Connect Context

```javascript
interface TContext {
  body: object;
  didwallet: TWalletInfo;
  headers: object;
  locale: string;
  previousConnected?: {
    didwallet: 'ios' | 'android' | 'web' | '';
    userDid: string;
    userPk: string;
  } | null;
  session: TSession | null;
  sessionId: string;
  signerPk: string;
  signerToken: string;
}
```

---

## How to manage login sessions?

URL: https://www.arcblock.io/en/docs/did-connect/user-session-management/

1. Click on the profile picture in the top right corner of the website, click on the menu that appears, and then click on the personal center button ![image.png](https://media.arcblock.io/lib/a6/a6699b49580a91fe8f8cfc5a9752e3f9.w1600.webp)

1. On the user center page, click on the settings button, and open the session management tab ![image.png](https://media.arcblock.io/lib/af/af6761e5f11ff021f94e604ab6a89690.w1600.webp)
2. This page displays all the login activities of the current account, including the operating system used for login, browser information, user details, first activity time, recent activity time, recent login IP address, and IP region.
3. You can also manage other login sessions on the page, forcibly logging out of a particular login session, or logging out of all login sessions except the current page. ![image.png](https://media.arcblock.io/lib/d4/d4c272dd4c015ff7a5d47e1e4cb353ef.w1600.webp)

---

## How to use DID Connect in other frameworks

URL: https://www.arcblock.io/en/docs/did-connect/work-with-other-frameworks/

DID Connect currently only supports React, Vue.js, svelte, Solid.js, AngularJS are actively under development

---

## DID Names

URL: https://www.arcblock.io/en/docs/did-domain/

---

## How to Guides

URL: https://www.arcblock.io/en/docs/did-domain/4_eIjRPxh97fX7MEPmcE-ogf/

Quick help when you have setup your domain.

- [Enable DID Domain in Blocklet Server](/en/docs/did-domain/enable-did-domain-in-blocklet-server/)

- [Upgrade DID Names Subscription](/en/docs/did-domain/upgrade-did-domain-subscription/)

---

## Bulk host domains using the didnames CLI

URL: https://www.arcblock.io/en/docs/did-domain/D7PPOwb2VXHPro-wVSsORHHG/

DID Names offers a `didnames` CLI tool to simplify managing domains hosted with other providers within the DID Names system.

This document details how to use this tool.

## Installation

```javascript
npm install -g @blocklet/didnames
```

Or run directly via `npx`, no installation required.

```javascript
npx @blocklet/didnames --version
```

## Commands

```javascript
Usage: didname [options] [command]

DID Names CLI tool

Options:
  -V, --version                 output the version number
  -h, --help                    display help for command

Commands:
  list-domains [options]        List all domains from provider
  update-nameservers [options]  Update nameservers for one or more domains
  help [command]                display help for command
```

### List all DID Names (DID Domains)

```javascript
didnames list-domains --provider <provider name> # Example: didnames list-domains --provider route53
```

### Update Name Servers

```javascript
didnames update-nameservers \
  --provider <provider> \
  --domains <domain1> <domain2> <domain3> \
  --nameservers \
    <nameserver1> \
    <nameserver2> \
    <nameserver3>
```

## Supported Domain Name Registrars

### AWS Route 53

<strong>Step 1: Set up AWS credentials</strong>

Before running the command, configure the Access Key ID and Secret Access Key as follows:

- Log in to the AWS Management Console and go to IAM.
- Create or use an existing user and assign the necessary permissions.
- Generate an Access Key ID and Secret Access Key.

Set environment variables in your terminal (recommended).

```javascript
export AWS_ACCESS_KEY_ID="你的AccessKeyId"
export AWS_SECRET_ACCESS_KEY="你的SecretAccessKey"
```

<strong>Step 2: Necessary Permissions</strong>

- List domains (AWS Route 53: `ListDomains`)
- Change nameservers: `route53domains:UpdateDomainNameservers

Policy (JSON)

```javascript
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53domains:ListDomains",
        "route53domains:UpdateDomainNameservers"
      ],
      "Resource": "*"
    }
  ]
}
```

<strong>Security Advisory</strong>

- Do not embed AWS credentials directly into scripts or codebases.
- After using it, run the following command to clear the variables:

```javascript
unset AWS_ACCESS_KEY_ID
unset AWS_SECRET_ACCESS_KEY
```

---

## FAQs

URL: https://www.arcblock.io/en/docs/did-domain/did-domain-faq/

## Overview

Here's a quick Q&A of DID Domain frequently asked questions.

### Can I purchase a top-level domain on DID Names?

It's not supported yet but planned.

### What's the difference between DID Names and ENS?

ENS is short for Ethereum naming service, it relies on the Ethereum blockchain to work, however, DID Domain only uses DID/VC to verify domain ownership.

---

## Hosting Domain

URL: https://www.arcblock.io/en/docs/did-domain/did-domain-host/

DID Names supports hosting domains registered with other registrars. After an NFT is issued for the domain, it can be used on the Blocklet platform.

This document covers:

1. Prerequisites
2. Add the domain you want to host
3. Update the nameservers for the managed domain
4. Subscribe

## 1. Prerequisites

- Hosting one or more DID Names follows the same process. This document uses the example of hosting multiple DID Names.
- The hosted domain must be a second-level domain (e.g., example.com)

## 2. Add the Domain You Want to Host

1. Access the hosted DID Names page: [https://domain.didlabs.org/app/user/domains/host](https://domain.didlabs.org/app/user/domains/host)
2. Enter the domain name you wish to host

![2a8bdef5c4f8f49cdb506011aec11e76.png](https://media.arcblock.io/lib/f8/f8934b43644ab22b4e1c250749ac1675.w1600.webp)

DID Names offers a CLI tool for bulk importing domains from other providers. See: [Using the didnames CLI for Bulk Domain Hosting](/zh/docs/did-domain/D7PPOwb2VXHPro-wVSsORHHG/)

## 3. Verify the Domain Name for Hosting

This step checks for duplicates and confirms the domain name to be hosted. If everything is correct, click Next.

![2301ce8cc96c2e8458e4e20c2815a5ed.png](https://media.arcblock.io/lib/fd/fd0bbe53334a7b8569ec1224dadcd6cb.w1600.webp)

## 4. Modify the Nameservers of the Hosted Domain (Optional)

This step can be skipped for the moment and revisited after deployment to avoid any disruption.

![72cab18e62cfdef8260ae3cf3a20716a.png](https://media.arcblock.io/lib/a6/a6a9da5352db60ef75ef8b22a6c08af2.w1600.webp)

<strong>4.1 Log in to your domain registrar</strong>

Log in to your domain registrar, locate the domain management page, and find the name server settings. You can use [ICANN](https://lookup.icann.org/) to look up your registrar.

<strong>4.2 Remove Other Nameservers</strong>

Set the name server provided by DID Names as the sole server.

<strong>4.3 Configure Name Servers using DID Names</strong>

Set the nameservers to the server addresses specified on this page and wait for the changes to propagate. Different registrars may have slightly different processes, but most offer user-friendly interfaces. See our guides for modifying nameservers with common registrars: [How to Modify Nameservers and DNS Resolution](https://www.arcblock.io/blog/docs/did-domain/zh/did-domain-modify-nameservers)

<strong>Similarly, DID Names provides a CLI for managing name servers in bulk. See:</strong> [Using the didnames CLI to Manage Domains in Bulk](/zh/docs/did-domain/D7PPOwb2VXHPro-wVSsORHHG/)

<strong>Attention:</strong>

- Because DNS propagation takes time, changes typically do not take effect immediately and can take up to 48 hours to propagate globally.
- DID Names automatically detects when they become active and notifies users via email and wallet notifications.

If you encounter any difficulties, you can ask for help from the [community](https://community.arcblock.io/).

## 5. Pay and Complete Your Subscription

Finally, you need to complete the subscription payment. Upon successful payment, a DID Names NFT will be sent to your wallet, allowing you to use the domain name on the Blocklet platform. See [Using DID Names](https://www.arcblock.io/blog/docs/did-domain/zh/use-did-domain) for more information.

<strong>* Prices are subject to market fluctuation and will be confirmed at the time of payment.</strong>

![b7acf72ddaf3da7c16bb362ca4ddbd2f.png](https://media.arcblock.io/lib/82/8249c048b0af60066edb0b3b65460027.w1600.webp)

---

## How to hosting domains from Godaddy?

URL: https://www.arcblock.io/en/docs/did-domain/did-domain-modify-nameservers/

Different registrars have different ways of making modifications. This document will demonstrate some methods for registrars to modify name servers and NS records.

## Godaddy

### Change Name Servers

1. Enter the domain list
2. Select the domain name you want to modify, and click "DNS" to enter the DNS management page.

![image.png](https://media.arcblock.io/lib/56/56c95629a69530e5b21cd44314d9f427.w1600.webp)

1. Select the "Nameservers" section
2. Click the "Change Nameservers" button

![image.png](https://media.arcblock.io/lib/4f/4f677f5a24fced451604704de3eeed49.w1600.webp)

1. Choose "I'll use my own nameservers"

![image.png](https://media.arcblock.io/lib/57/576820f7bf6eb0861f180a8a68e922a6.w1600.webp)

1. The server address specified by the input DID Domain
2. Click "Save", complete the modifications, and wait for DNS resolution to take effect.

### Add NS Record

1. Access the domain list
2. Select the domain name you want to modify, click "DNS" to enter the DNS management page.

![image.png](https://media.arcblock.io/lib/56/56c95629a69530e5b21cd44314d9f427.w1600.webp)

1. Click "Add New Record"

![image.png](https://media.arcblock.io/lib/c4/c4800bee02e4608c7fc2fe703c821e19.w1600.webp)

1. Add TXT record

![image.png](https://media.arcblock.io/lib/c0/c03893560be0041c3d014fa590e3ea11.w1600.webp)

1. Click "Save", complete the modification, and wait for DNS resolution to take effect.

---

## Enable DID Domain in Blocklet Server

URL: https://www.arcblock.io/en/docs/did-domain/enable-did-domain-in-blocklet-server/

The older version of Blocklet Server does not have DID Domain enabled by default. You need to manually configure the URL of the DID Domain service to enable it:

1. Log in to the Blocklet Server Dashboard
2. Open the "Settings -> Basic" page
3. Enter the address in the "NFT Domain URL":  [`https://domain.didlabs.org/app`](https://domain.didlabs.org/app)
4. <strong>Click "Save Changes"</strong> to apply the configuration

Now, when adding a domain to Blocklet, you can add a DID Domain domain.

![image.png](https://media.arcblock.io/lib/b8/b852313de45ccfd9621e5e24f8a1dcec.w1600.webp)

---

## Get DID Domain

URL: https://www.arcblock.io/en/docs/did-domain/get-did-domain/

Before using the DID domain name, you need to obtain a domain name. You can follow the steps below to obtain a domain name.

### Select a domain name.

1. ![image.png](https://media.arcblock.io/lib/04/044a2aad8f562d3cde562c9a93ada3ca.w1600.webp)
  1. Open the purchase page in your browser [https://www.didnames.io/app/](https://www.didnames.io/app/)
  2. Enter the desired domain name, such as 'jerry'.
  3. Click 'Search', and available domain names will be listed.

### Payment

1.
  1. Select the domain name searched in the previous step and click the 'Purchase' button.
  2. Redirect to the payment page.
  3. If not logged in, need to login first using the wallet.
  4. Then select the appropriate subscription period: <strong>Monthly</strong> or <strong>Yearly</strong> <em><strong>(there will be certain discounts for yearly subscription)</strong></em>.
  5. Click 'Subscribe', display your wallet, and follow the prompts to complete the subscription.

![image.png](https://media.arcblock.io/lib/9f/9f5d09cf9ec83b298301b7898b8f221d.w1600.webp)

After completing these steps, the domain NFT will be sent to your DID wallet.

---

## How to host a domain from Namecheap on DID Names

URL: https://www.arcblock.io/en/docs/did-domain/hosting-domain-from-namecheap/

If you purchased your domain on Namecheap, please consult the following documentation to update your nameservers.

### 1. Obtain Nameservers

After entering the domain name you want to host, you will be prompted to configure the necessary nameservers: Host Domain Name

![72cab18e62cfdef8260ae3cf3a20716a.png](https://media.arcblock.io/lib/a6/a6a9da5352db60ef75ef8b22a6c08af2.w1600.webp)

### 3. Configure Custom Nameservers

You must own the domain to change its custom DNS settings on Namecheap.

![image.png](https://media.arcblock.io/lib/ce/ce71ecd9458ec02f2bddff81cd4e6ebe.w1600.webp)

For more information, please visit namecheap.com.

[How to Change DNS For a Domain - Domains - Namecheap.com](https://www.namecheap.com/support/knowledgebase/article.aspx/767/10/how-to-change-dns-for-a-domain/)

### 4. Configure Payments and Hosting

Upon successful payment, an NFT will be minted and sent to your DID Wallet.

![b7acf72ddaf3da7c16bb362ca4ddbd2f.png](https://media.arcblock.io/lib/82/8249c048b0af60066edb0b3b65460027.w1600.webp)

### 5. Connect Your Domain/Subdomain to Your Blocklet

Then, when you bind a subdomain to a Blocklet, all subdomains are automatically managed: [Manage DID Names](/en/docs/did-domain/use-did-domain/)

---

## Introduction

URL: https://www.arcblock.io/en/docs/did-domain/introduction/

### What Is a DID Name?

DID names are a naming service provided by ArcBlock as part of the DID Names infrastructure. They leverage DID, NFT, and VC technologies to simplify domain issuance, authorization, and management.

Any application running on a Blocklet Server, whether self-hosted or ArcBlock-hosted, can have any number of DID names associated with it.

You can learn how to acquire and use DID names in the following tutorials:

- [Get DID Domain](/en/docs/did-domain/get-did-domain/)
- [Use DID Domain](/en/docs/did-domain/use-did-domain/)
- [Hosting Domain](/en/docs/did-domain/did-domain-host/)

---

## Terminology

URL: https://www.arcblock.io/en/docs/did-domain/terminology/

<strong>What is the relationship between DID Domain and DID Names?</strong>

A DID Domain name is a type of DID Name Service.

<strong>Standardize the terms "top-level domain," "second-level domain," and "subdomain" used throughout this document</strong>

Because of differing interpretations of top-level domains, second-level domains, and subdomains, this document provides a unified explanation:

- Top-level domain (TLD), such as .com and .top.
- Second-level domain (SLD), such as example.com or example.top
- Subdomain, a subdomain of a second-level domain, for example, shop.example.com and shop.example.top.

<em>This description applies only to this document and other documentation on the Blocklet platform.</em>.

<strong>"Name Server" and "Domain Name Server"</strong>

The terms "name server" and "domain name server" may have different translations depending on the registrar, but they are used interchangeably in this document.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/did-domain/TiGZYeOXuUt7RLvaCyD3izta/

Step-by-step instructions on how to get and use a domain on the blocklet platform:

- [Terminology](/en/docs/did-domain/terminology/)

- [Get DID Domain](/en/docs/did-domain/get-did-domain/)

- [Use DID Domain](/en/docs/did-domain/use-did-domain/)

- [Hosting Domain](/en/docs/did-domain/did-domain-host/)

---

## Upgrade DID Names Subscription

URL: https://www.arcblock.io/en/docs/did-domain/upgrade-did-domain-subscription/

If you want to update your DID Names subscription, from monthly to yearly billing, checkout video below:

<video src="https://media.arcblock.io/lib/f8/f85118d7827a143296ca82a90cbef396.mp4" controls></video>

---

## Use DID Domain

URL: https://www.arcblock.io/en/docs/did-domain/use-did-domain/

There are two ways to add your DID domain to a running Blocklet:

- Add a DID Domain during the application launch process
- Add a domain in the Blocklet Dashboard

## Add a DID Domain during the application launch process

1. After installing the Blocklet, go to the '<strong>Launch Application -> Domain</strong>' stage
2. Input the DID domain name and click the "<strong>Configure existing domain</strong>" button.
3. Use the DID wallet to scan the code and present the NFT for this domain.
4. Adding completed

After adding, the HTTPS certificate will be generated automatically.

![image.png](https://media.arcblock.io/lib/04/04fc5714ad4bccabf75f7c28f33382db.w1600.webp)

## Add the domain name in the Blocklet Dashboard

1. Log in to the Blocklet Dashboard
2. Enter the "<strong>Website -> Domains</strong>" page
3. Click the "<strong>Add</strong>" button in the upper right corner of the domain list, and a "<strong>Configure existing domain</strong>" window will pop up.
4. Input the DID domain name and click the "<strong>Add</strong>" button.
5. Use the DID wallet to scan the code and present the NFT for this domain.
6. Adding completed.

Similarly, after adding, the HTTPS certificate will be automatically generated.

![image.png](https://media.arcblock.io/lib/92/92f4534a2af7f3ea3a41ebccf5c604fa.w1600.webp)

![image.png](https://media.arcblock.io/lib/c1/c15ff31b64e25706d57153ed0eb31dfe.w1600.webp)

---

## DID Space SDK (Node.js)

URL: https://www.arcblock.io/en/docs/did-space-js/

---

## API Reference

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-c19e7c/

Welcome to the complete API reference for the DID Space Client SDK. This section provides detailed documentation for every class, method, and command available. It's designed to be a comprehensive resource, helping you find specific information quickly and understand the full capabilities of the SDK.

Whether you're looking for constructor options, method signatures, or command parameters, you'll find it here. The API is organized into logical groups to help you navigate efficiently.

::::card-group
::link-card{title="SpaceClient" description="The main entry point for interacting with the SDK. This section details its constructor options and the `send` method." icon="box" href="/en/docs/did-space-js/api-reference-space-client-c19e7c/"}
::link-card{title="Object Commands" description="Commands for performing CRUD (Create, Read, Update, Delete) operations on individual files or objects within a DID Space." icon="file" href="/en/docs/did-space-js/api-reference-object-commands-c19e7c/"}
::link-card{title="Sync Commands" description="High-level commands for synchronizing the state between a local folder and a remote directory in a DID Space." icon="refresh" href="/en/docs/did-space-js/api-reference-sync-commands-c19e7c/"}
::link-card{title="NFT Commands" description="Specialized commands for handling NFT-related assets and their associated DID Documents." icon="star" href="/en/docs/did-space-js/api-reference-nft-commands-c19e7c/"}
::::

For most use cases, the best place to start is the [SpaceClient](/en/docs/did-space-js/api-reference-space-client-c19e7c/) documentation, as it is the central component for sending all commands. From there, you can dive into the specific command set that matches your needs.

---

## NFT Commands

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-nft-commands-c19e7c/

Specialized commands for handling NFT-related assets and their associated DID Documents. These commands streamline the process of storing digital assets represented as Non-Fungible Tokens (NFTs) in your DID Space.

A key feature of these commands is their integrated handling of both the asset file itself (e.g., an image, video, or audio file) and its corresponding DID Document. The DID Document contains verifiable metadata about the asset, such as its creator, ownership history, and other important attributes. This approach ensures that the asset and its provenance information are stored together, maintaining a strong, verifiable link between the digital object and its identity.

The commands in this section are built upon the core concepts of Decentralized Identifiers (DIDs) and Verifiable Credentials. For a deeper understanding of the underlying principles, please refer to our guide on [Request Signing](/en/docs/did-space-js/core-concepts-request-signing-c19e7c/).

## Available Commands

Click on a command to view its detailed API reference, including parameters, return values, and complete code examples.

::::card-group
::link-card{title="PutNftObjectCommand" description="Uploads an NFT asset and its corresponding DID Document, linking them together in your DID Space." icon="star" href="/en/docs/did-space-js/api-reference-nft-commands-put-nft-object-c19e7c/"}
::::

## Next Steps

To begin storing your NFT assets, proceed to the detailed guide for the `PutNftObjectCommand`.

- <strong>Explore the</strong> [<strong>PutNftObjectCommand</strong>](/en/docs/did-space-js/api-reference-nft-commands-put-nft-object-c19e7c/) <strong>reference</strong> for detailed parameters and code examples.
- <strong>Compare with</strong> [<strong>Object Commands</strong>](/en/docs/did-space-js/api-reference-object-commands-c19e7c/) if you are working with standard, non-NFT files.

---

## PutNftObjectCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-nft-commands-put-nft-object-c19e7c/

The `PutNftObjectCommand` is a specialized command designed to upload a digital asset (like an image, video, or audio file) and simultaneously create or update its associated DID Document. This process effectively links a decentralized identifier (DID) to a specific piece of data, a crucial step in managing Non-Fungible Tokens (NFTs) and other verifiable digital assets within DID Spaces.

This command automates several complex steps: it calculates the hash of the asset, constructs a valid DID Document specifying the asset's location and integrity hash, and signs the document using a controller wallet to prove ownership. It then bundles the asset and the signed document into a single request to the DID Space.

### Workflow Overview

The following diagram illustrates the typical workflow when using `PutNftObjectCommand`:

![PutNftObjectCommand](https://media.arcblock.io/lib/20/2064190782fc7859.w1600.webp)

### Input

The `PutNftObjectCommand` requires the following input parameters to be provided to its constructor.

- **did** `string` *(required)* — The DID of the asset. This is the identifier that the uploaded object and DID Document will be associated with.

- **controller** `WalletObject` *(required)* — The wallet object that has control over the asset's DID. This wallet will be used to sign the generated DID Document, proving ownership.

- **chainHost** `string` *(required)* — The base URL for the blockchain explorer API (e.g., 'https://beta.abtnetwork.io/api/'). This is used to construct the explorer service endpoint in the DID Document.

- **display** `object` *(required)* — An object containing the configuration for the display asset.
  - **key** `string` *(required)* — The filename of the asset (e.g., 'my-nft-image.png'). This should not include any path.
  - **data** `Readable` *(required)* — A readable stream representing the content of the asset file.

### Output

The command returns a standard output object.

- **statusCode** `number` — The HTTP status code of the response. A value of `200` indicates that the NFT object and its DID document were successfully uploaded.

- **data** `void` — On a successful request, the data field is empty.

### Example

Here is a complete example of how to use `PutNftObjectCommand` to upload an NFT asset.

First, ensure you have a file to upload, for example, `my-nft.png`.

**Example**

```typescript
import { SpaceClient, PutNftObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import * as fs from 'fs';
import * as path from 'path';

async function uploadNftAsset() {
  const wallet = getWallet(); // Assumes a wallet is available in the environment

  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet: wallet,
  });

  // 1. Prepare the file stream for the NFT asset
  const filePath = path.join(__dirname, 'my-nft.png');
  // Ensure the file exists before creating a stream
  if (!fs.existsSync(filePath)) {
    console.error(`File not found: ${filePath}`);
    // As a placeholder, create a dummy file for the example to run
    fs.writeFileSync(filePath, 'This is a dummy NFT file.');
  }
  const fileStream = fs.createReadStream(filePath);

  // 2. Define the command input
  const commandInput = {
    // The DID of the asset you are uploading
    did: 'z8iZnaYxnkMD5AKRjTKiCb8pQr1ut8UantAcf',
    // The wallet that controls this asset DID
    controller: wallet,
    // The host of the blockchain explorer
    chainHost: 'https://beta.abtnetwork.io/api/',
    display: {
      key: 'my-nft.png',
      data: fileStream,
    },
  };

  // 3. Create and send the command
  const command = new PutNftObjectCommand(commandInput);
  const output = await client.send(command);

  // 4. Check the result
  if (output.statusCode === 200) {
    console.log('NFT asset uploaded successfully!');
  } else {
    console.error('Failed to upload NFT asset:', output);
  }
}

uploadNftAsset();
```

### Best Practices

#### DID Document Automation

The primary advantage of `PutNftObjectCommand` is its automation of DID Document creation and signing. When you send the command, it performs the following actions internally:

::::steps
:::step{title="Hashing"}
It reads the `data` stream and computes the SHA3-256 hash of the file content. This hash is embedded in the DID Document to guarantee the integrity of the asset.
:::

:::step{title="Document Construction"}
It assembles a DID Document containing essential metadata, including service endpoints for accessing the display asset and viewing it on a block explorer.
:::

:::step{title="Signing"}
It signs the entire DID Document using the provided `controller` wallet's private key. This cryptographic signature is verifiable and proves that the controller authorized this specific version of the document.
:::
::::

#### Controller Wallet

The `controller` wallet is fundamental to the security and ownership model. Ensure that the wallet provided has the authority to manage the specified asset `did`. This wallet's public key is included in the DID Document's `verificationMethod`, allowing anyone to verify the signature.

---

## Object Commands

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-object-commands-c19e7c/

Object Commands are the core tools for interacting with individual files (or "objects") within a DID Space. They provide the fundamental building blocks for all CRUD (Create, Read, Update, Delete) operations, allowing you to upload, download, list, and delete files programmatically.

Each command is designed as a self-contained unit that you send via the `SpaceClient`. This section provides an overview of the available object commands. Click on any command to view its detailed API reference, including parameters, return values, and code examples.

::::card-group
::link-card{title="PutObjectCommand" description="Uploads a new file or overwrites an existing file in your space. Use this for all file creation and update operations." icon="upload" href="/en/docs/did-space-js/api-reference-object-commands-put-object-c19e7c/"}
::link-card{title="GetObjectCommand" description="Retrieves an object from your space. This command downloads the raw content of the file as a readable stream." icon="download" href="/en/docs/did-space-js/api-reference-object-commands-get-object-c19e7c/"}
::link-card{title="DeleteObjectCommand" description="Permanently deletes a specified object from your space. This action is irreversible." icon="trash" href="/en/docs/did-space-js/api-reference-object-commands-delete-object-c19e7c/"}
::link-card{title="ListObjectsCommand" description="Lists the objects and common prefixes (subdirectories) under a specified path within your space." icon="list" href="/en/docs/did-space-js/api-reference-object-commands-list-objects-c19e7c/"}
::link-card{title="HeadObjectCommand" description="Retrieves metadata from an object without returning the object itself. Useful for checking existence, size, or last-modified date." icon="file"}
::link-card{title="PreviewObjectCommand" description="Manages the preview for an object. You can set, get, or remove a custom preview image for any file." icon="image"}
::::

These commands provide granular control over individual objects. For higher-level operations, such as synchronizing an entire local folder with a remote directory, explore the [Sync Commands](/en/docs/did-space-js/api-reference-sync-commands-c19e7c/).

---

## DeleteObjectCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-object-commands-delete-object-c19e7c/

The `DeleteObjectCommand` is used to permanently delete an object from your DID Space. This action is irreversible.

This command is the standard method for removing individual files. To delete multiple objects, you must issue a separate `DeleteObjectCommand` for each object.

## Input

The command requires the `key` of the object you wish to delete.

- **key** `string` *(required)* — The unique identifier for the object within the space. This is typically the object's path, for example, path/to/your/file.txt.

## Output

The output indicates the success of the operation via the HTTP status code. A successful deletion will return a `200` status code.

- **statusCode** `number` — The HTTP status code of the response. A value of 200 indicates success.
- **statusMessage** `string` — The HTTP status message corresponding to the status code.
- **data** `void` — This field is undefined for a successful DeleteObjectCommand operation.

## Usage Example

The following example demonstrates how to initialize a `SpaceClient` and use `DeleteObjectCommand` to delete a file named `notes.txt` from the root directory of your space.

**delete-file.ts**

```typescript
import { SpaceClient, DeleteObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function deleteFile() {
  // Initialize the SpaceClient
  const client = new SpaceClient({
    auth: {
      endpoint: 'https://www.didspaces.com/app/api/space/...', // Your space endpoint
      wallet: getWallet(),
    },
  });

  // Specify the key of the object to be deleted
  const fileKey = 'notes.txt';

  // Create and send the delete command
  const command = new DeleteObjectCommand({ key: fileKey });
  const output = await client.send(command);

  // Verify the result
  if (output.statusCode === 200) {
    console.log(`Successfully deleted object: ${fileKey}`);
  } else {
    console.error(`Failed to delete object. Status: ${output.statusCode} - ${output.statusMessage}`);
  }
}

deleteFile();
```

In this example, we first create an instance of `SpaceClient` with the necessary authentication details. We then instantiate `DeleteObjectCommand`, providing the `key` of the object to be removed. After sending the command, we check the `statusCode` of the response to confirm that the deletion was successful.

## Best Practices and Common Patterns

### Confirm Deletion

Since deleting an object is a permanent action, it's crucial to ensure your application logic correctly identifies the object to be deleted. Consider implementing a confirmation step in user-facing applications before executing this command.

### Handling "Not Found" Errors

Attempting to delete an object that does not exist will result in an error (typically a `404 Not Found` status). Your application should handle this gracefully. You might want to check if an object exists using `ListObjectsCommand` before attempting to delete it if the object's existence is uncertain. This can help prevent unnecessary API calls and errors.

---

## GetObjectCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-object-commands-get-object-c19e7c/

The `GetObjectCommand` is used to retrieve or download an object from your DID Space. The content of the object is returned as a readable stream, making it efficient for handling files of any size without consuming excessive memory.

This is the command you'll use for any download functionality in your application.

## Input

The command requires a single parameter to specify which object to retrieve.

- **key** `string` *(required)* — The unique key (path and filename) of the object to be downloaded. For example, 'photos/profile.jpg' or 'documents/report.pdf'.

## Output

Upon a successful request, the command returns an object with the status, headers, and the object's content as a data stream.

- **statusCode** `number` — The HTTP status code of the response. A value of 200 indicates success.
- **statusMessage** `string` — The HTTP status message corresponding to the status code.
- **headers** `RawAxiosResponseHeaders | AxiosResponseHeaders` — An object containing the HTTP response headers. This can include metadata like 'content-type', 'content-length', etc.
- **data** `Readable` — A Node.js Readable stream containing the object's data. You can pipe this stream to a file, another stream, or process its chunks directly.

## Usage Example

This example demonstrates how to download an object from your DID Space and save it as a local file. It uses the `pipeline` function from Node.js's `stream/promises` module for a more concise and robust way to handle streams.

**Downloading an Object with Pipeline**

```typescript
import { SpaceClient, GetObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import fs from 'fs';
import path from 'path';
import { pipeline } from 'stream/promises';

// 1. Initialize the SpaceClient
const client = new SpaceClient({
  auth: {
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet: getWallet(),
  },
});

// 2. Define the key of the object to download and the local file path
const objectKey = 'path/to/your/file.txt';
const localFilePath = path.join(__dirname, 'downloaded_file.txt');

async function downloadObject() {
  try {
    // 3. Create and send the GetObjectCommand
    const command = new GetObjectCommand({ key: objectKey });
    const output = await client.send(command);

    // 4. Check if the request was successful
    if (output.statusCode === 200 && output.data) {
      console.log(`Successfully started downloading ${objectKey}`);

      // 5. Create a writable stream to save the file
      const writer = fs.createWriteStream(localFilePath);

      // 6. Use pipeline to efficiently transfer data and handle errors
      await pipeline(output.data, writer);

      console.log(`File downloaded successfully and saved to ${localFilePath}`);
    } else {
      // Throw an error if the download failed to be caught by the catch block
      throw new Error(`Failed to download object. Status: ${output.statusCode}, Message: ${output.statusMessage}`);
    }
  } catch (err) {
    console.error('An error occurred during the download process:', err);
  }
}

downloadObject();
```

### Example Response (on success)

The `output` variable in the code above would look like this. Note that `data` is a stream object, not the actual file content.

**Response Structure**

```json
{
  "statusCode": 200,
  "statusMessage": "OK",
  "headers": {
    "x-amz-id-2": "...",
    "x-amz-request-id": "...",
    "date": "Wed, 29 May 2024 08:30:00 GMT",
    "last-modified": "Tue, 28 May 2024 10:15:00 GMT",
    "etag": "\"...\"",
    "x-amz-server-side-encryption": "AES256",
    "accept-ranges": "bytes",
    "content-type": "application/octet-stream",
    "server": "SpaceServer",
    "content-length": "1024"
  },
  "data": "<ReadableStream>"
}
```

## Best Practices

### Handling Streams

The primary advantage of `GetObjectCommand` is its use of streaming. This is particularly important for large files, as it prevents your application from loading the entire file into memory at once. Always consume the `data` stream by piping it to a destination.

### Error Management

For robust stream handling, we strongly recommend using the `pipeline` function from Node.js's `stream/promises` module, as shown in the example. It simplifies the code by automatically managing the data flow, handling backpressure, and propagating errors from any part of the stream chain. This eliminates the need for manual event listeners for `error` and `finish`, allowing you to use a standard `try...catch` block for cleaner and more reliable error management.

---

## ListObjectsCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-object-commands-list-objects-c19e7c/

The `ListObjectsCommand` is used to retrieve a list of objects, which can be files or directories, from a specified path within your DID Space. It offers flexibility through options for both flat (listing only immediate children) and recursive (listing all nested items) directory traversal.

This command is essential for applications that need to display folder contents, build a file browser, or iterate over all files in a specific part of the storage.

## Use Case

Common scenarios for using `ListObjectsCommand` include:

- Building a file explorer interface for users to navigate their stored files.
- Synchronizing a local directory with a remote one by first listing the remote objects.
- Performing batch operations on all files within a specific folder.
- Verifying the contents of a directory after an upload or a series of file operations.

## Input Parameters

The command constructor accepts an object with the following properties:

- **key** `string` (default: `/`) — The path of the directory whose contents you want to list. If omitted, it defaults to the root directory ('/').

- **recursive** `boolean` — If set to true, the command will list all objects under the given key recursively. If false or not provided, it performs a flat listing of only the immediate children.

- **ignoreDirectories** `boolean` — If set to true, directories will be excluded from the result set. This option is only effective when 'recursive' is false.

## Output

The `send` method returns a promise that resolves to an object containing the command's output.

- **statusCode** `number` — The HTTP status code of the response. A value of 200 indicates success.

- **data** `Object[]` — An array of objects representing the files and directories found at the specified key.
  - **key** `string` — The full path and name of the object.
  - **type** `'object' | 'directory'` — The type of the item.
  - **size** `number` — The size of the object in bytes. For directories, this is typically 0.
  - **lastModified** `string` — An ISO 8601 formatted date string indicating when the object was last modified.

### Example Response (Success)

**Example Success Response**

```json
{
  "statusCode": 200,
  "data": [
    {
      "key": "/photos/summer/beach.jpg",
      "type": "object",
      "size": 2048576,
      "lastModified": "2023-10-27T10:00:00.000Z"
    },
    {
      "key": "/photos/summer/mountains/",
      "type": "directory",
      "size": 0,
      "lastModified": "2023-10-26T15:30:00.000Z"
    }
  ]
}
```

## Code Example

This example demonstrates how to initialize the `SpaceClient` and use the `ListObjectsCommand` to list the contents of a directory.

**Example**

```typescript
import { SpaceClient, ListObjectsCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function listMyFiles() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/', // Specify the directory to list
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully listed objects:');
    if (output.data.length > 0) {
      output.data.forEach((item) => {
        console.log(`- [${item.type}] ${item.key} (Size: ${item.size} bytes)`);
      });
    } else {
      console.log('The directory is empty.');
    }
  } else {
    console.error('Failed to list objects:', output);
  }
}

listMyFiles();
```

### Recursive Listing

To list all files and subdirectories within `/shared-documents/`, set the `recursive` option to `true`.

**Recursive Listing**

```typescript
async function listAllFilesRecursively() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/',
    recursive: true,
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('All nested objects:');
    output.data.forEach((item) => {
      console.log(`- ${item.key}`);
    });
  } else {
    console.error('Recursive listing failed:', output);
  }
}

listAllFilesRecursively();
```

## Best Practices & Common Patterns

- <strong>Performance</strong>: For large directories, avoid recursive listing unless necessary. A flat listing is significantly faster as it retrieves less data.
- <strong>Building a File Tree</strong>: To construct a UI file tree, you can start with a non-recursive call for the root level. Then, make subsequent non-recursive calls for each subdirectory as the user expands them. Alternatively, a single recursive call can fetch the entire tree state at once if the total number of objects is manageable.
- <strong>Filtering Files</strong>: If you only need to process files in a specific directory (and not subdirectories), combine a non-recursive call with `ignoreDirectories: true` for an efficient, file-only list.

---

## PutObjectCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-object-commands-put-object-c19e7c/

The `PutObjectCommand` is used to upload a new object or update an existing object in your DID Space. This command is versatile and can handle various data types, such as files, strings, or buffers, making it the primary method for adding content to your space.

## Usage Scenario

You should use `PutObjectCommand` whenever you need to:

- Upload a new file (e.g., an image, a document, or a configuration file).
- Create a folder by providing a key that ends with a `/` and no data.
- Update the content or metadata of an existing file.

## Input

The `PutObjectCommand` requires the following input parameters to specify the object's location, content, and metadata.

- **key** `string` *(required)* — The unique identifier for the object, which can be a file path or a folder name. For example, 'path/to/my-file.txt' or 'my-folder/'.

- **data** `Data` — The content of the object. This can be a string, Buffer, Blob, or any other compatible data type. This field is optional if you are creating an empty folder.

- **hash** `string` — An optional hash of the object's content, typically an IPFS v1 CID. This can be used to verify data integrity upon upload.

- **metadata** `Record<string, any>` — An optional object to store custom metadata associated with the object. This is useful for storing application-specific information like content type, author, or custom tags.

## Output

The command returns a standard output object after the operation is complete.

- **statusCode** `number` — The HTTP status code of the response. A value of 200 indicates a successful upload.

- **statusMessage** `string` — The HTTP status message corresponding to the status code.

- **data** `void` — This command does not return any data in the response body.

## Example: Uploading a Text File

Here's a complete example of how to initialize the `SpaceClient` and use `PutObjectCommand` to upload a simple text file.

**Example: Uploading a file**

```typescript
import { SpaceClient, PutObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function uploadFile() {
  const client = new SpaceClient({
    auth: {
      endpoint: 'https://www.didspaces.com/app/api/space/...',
      wallet: getWallet(),
    },
  });

  const command = new PutObjectCommand({
    key: 'greetings.txt',
    data: 'Hello, DID Space!',
    metadata: {
      contentType: 'text/plain',
      source: 'my-application',
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('File uploaded successfully!');
  } else {
    console.error(`Failed to upload file: ${output.statusCode} ${output.statusMessage}`);
  }
}

uploadFile();
```

<strong>Example Response</strong>

**Response**

```json
{
  "statusCode": 200,
  "statusMessage": "OK",
  "data": undefined
}
```

In this example, a file named `greetings.txt` with the content "Hello, DID Space!" is uploaded to the root of the space. We also include custom metadata to specify the content type and the source application.

## Best Practices

- <strong>Use Metadata</strong>: Attaching metadata to your objects is a great way to store additional context without altering the object's content. This can be very useful for filtering, organizing, and processing files later on.
- <strong>Handling Large Files</strong>: The SDK handles the complexities of multipart uploads for you. Simply provide the data, and the client will manage the streaming and transfer efficiently.
- <strong>Error Handling</strong>: Always check the `statusCode` in the output to confirm that the upload was successful. A `200` status code means success, while other codes indicate potential issues that your application should handle.

---

## SpaceClient

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-space-client-c19e7c/

The `SpaceClient` is the primary interface for interacting with the DID Space API. It's the main entry point for the SDK, responsible for handling configuration, authentication, and dispatching commands to your DID Space.

## Constructor

To begin, you need to create an instance of the `SpaceClient`. The constructor accepts a single `options` object to configure its behavior, including authentication credentials and endpoint details.

**Client Initialization**

```typescript
import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();

const client = new SpaceClient({
  auth: {
    wallet: wallet,
    endpoint: 'https://www.didspaces.com/app/api/space/...',
  },
});
```

### Options (SpaceClientOptions)

The constructor accepts an object with the following properties:

- **auth** `object` — The recommended way to provide authentication credentials. It can be one of several types.
  - **EndpointAuth** `object` — Authentication using a wallet and a specific space endpoint.
    - **wallet** `WalletObject` *(required)* — The wallet object for signing requests, typically from '@blocklet/sdk/lib/wallet'.
    - **endpoint** `string` *(required)* — The full API endpoint for your DID Space application.
  - **AuthorizationAuth** `object` — Authentication using a pre-generated authorization token.
    - **authorization** `string` *(required)* — The authorization token.
  - **AccessKeyAuth** `object` — Authentication using a secret key.
    - **secretKey** `string` *(required)* — The secret access key.

- **wallet** `WalletObject` *(deprecated)* — The wallet object. It is recommended to use the `auth` object instead.

- **endpoint** `string` *(deprecated)* — The DID Space endpoint URL. It is recommended to use the `auth` object instead.

- **url** `string` (default: `https://www.didspaces.com`) — The base URL for the DID Spaces service. The client automatically resolves the correct application mount point.

- **delegation** `string` — A JWT token that certifies the requester is authorized to access the space.

- **componentDid** `string` — The DID of the component making the request.

- **abortController** `AbortController` — An AbortController instance to cancel in-flight requests.

## Methods

### send

The `send` method is the universal way to execute any command against your DID Space. You pass an instance of a command object, and it returns a promise that resolves with the command's output.

**Sending a Command**

```typescript
import { SpaceClient, PutNftObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import { fileURLToPath } from 'url';
import path from 'path';
import fs from 'fs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function uploadNft() {
  const wallet = getWallet();
  const client = new SpaceClient({
    auth: {
      wallet: wallet,
      endpoint: 'https://www.didspaces.com/app/api/space/...',
    },
  });

  const filePath = path.join(__dirname, 'my-nft-image.png');
  const fileStream = fs.createReadStream(filePath);
  const fileStat = fs.statSync(filePath);

  const command = new PutNftObjectCommand({
    name: 'My First NFT',
    description: 'This is a description of my NFT.',
    body: fileStream,
    contentLength: fileStat.size,
    contentType: 'image/png',
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('NFT uploaded successfully!', output.data);
  } else {
    console.error('Upload failed:', output.statusMessage);
  }
}

uploadNft();
```

<strong>Parameters</strong>

- **command** `CommandProtocol<Input, Output>` *(required)* — An instance of a command class, such as PutObjectCommand or ListObjectsCommand.

<strong>Returns</strong>

A `Promise` that resolves to the command's output object.

- **Output** `Promise<CommandOutput>` — The result of the command execution.
  - **statusCode** `number` *(required)* — The HTTP status code of the response (e.g., 200 for success).
  - **statusMessage** `string` — An error message if the request failed.
  - **stack** `string` — The stack trace if an error occurred.
  - **data** `any` *(required)* — The data returned by the command, which varies depending on the command executed.

## Static Methods

These are utility functions available directly on the `SpaceClient` class.

### getBaseUrl

Extracts the base URL of a DID Space from a full endpoint URL.

```typescript
import { SpaceClient } from '@blocklet/did-space-js';

const endpoint = 'https://.../app/api/space/z3T.../app/zNK.../object/';
const baseUrl = await SpaceClient.getBaseUrl(endpoint);
console.log(baseUrl); // 'https://.../app'
```

### getDisplayUrl

Constructs a public-facing URL to view an object within a DID Space.

```typescript
import { SpaceClient } from '@blocklet/did-space-js';

const endpoint = 'https://.../app/api/space/z3T.../app/zNK.../object/';
const objectDid = 'z3T...'; // The DID of the object
const displayUrl = await SpaceClient.getDisplayUrl(endpoint, objectDid);
console.log(displayUrl);
// 'https://.../app/resolve/z3T.../display'
```

### getSpaceEndpointContext

Parses a full endpoint URL to extract contextual information like the Space DID and Application DID.

```typescript
import { SpaceClient } from '@blocklet/did-space-js';

const endpoint =
  'https://.../api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/object/';
const context = await SpaceClient.getSpaceEndpointContext(endpoint);

console.log(context.spaceDid); // 'z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr'
console.log(context.appDid); // 'zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F'
```

<strong>Returns</strong>

A `Promise` resolving to a `SpaceEndpointContext` object.
- **context** `Promise<SpaceEndpointContext>` — Contextual information parsed from the endpoint.
- **baseUrl** `string` *(required)* — The base URL of the space.
- **spaceDid** `string` *(required)* — The DID of the space.
- **appDid** `string` *(required)* — The DID of the application within the space.

## Next Steps

Now that you know how to initialize the client and send commands, you can explore the available commands for interacting with your space:

::::card-group
::link-card{title="Object Commands" description="Learn how to perform CRUD operations on individual files (objects)." icon="file" href="/en/docs/did-space-js/api-reference-object-commands-c19e7c/"}
::link-card{title="Sync Commands" description="Discover high-level commands for synchronizing local and remote folders." icon="file" href="/en/docs/did-space-js/api-reference-sync-commands-c19e7c/"}
::::

---

## Sync Commands

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-sync-commands-c19e7c/

High-level commands for synchronizing the state between a local folder and a remote directory in a DID Space. These commands simplify the complex process of keeping directories in sync by automatically detecting differences and executing the necessary operations.

Instead of manually tracking which files have been added, modified, or deleted, you can use a single Sync Command to apply all changes in one go. The SDK handles the comparison logic, determining the most efficient way to bring the target directory's state in line with the source directory's state.

Two primary commands are available for synchronization, depending on the direction of the data flow:

::::card-group
::link-card{title="SyncFolderPushCommand" description="Pushes changes from a local folder to a remote directory. This is ideal for scenarios where your local file system is the source of truth, such as uploading a static website or backing up a project folder." icon="upload" href="/en/docs/did-space-js/api-reference-sync-commands-sync-folder-push-c19e7c/"}
::link-card{title="SyncFolderPullCommand" description="Pulls changes from a remote directory to a local folder. This is useful when the DID Space contains the authoritative version of the files and you need to download updates to a local machine." icon="download" href="/en/docs/did-space-js/api-reference-sync-commands-sync-folder-pull-c19e7c/"}
::::

Click on one of the commands above to see a detailed API reference, including input parameters, output structure, and complete, ready-to-use code examples.

---

## SyncFolderPullCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-sync-commands-sync-folder-pull-c19e7c/

The `SyncFolderPullCommand` is a high-level command designed to synchronize a remote directory from a DID Space to a local folder. It intelligently compares the files between the remote source and the local target, downloading only new or updated files. This ensures your local directory is an up-to-date mirror of the remote data efficiently.

This command is the counterpart to the [`SyncFolderPushCommand`](/en/docs/did-space-js/api-reference-sync-commands-sync-folder-push-c19e7c/), which is used for uploading local changes to a remote directory.

## Use Case

This command is ideal for scenarios where you need to retrieve a collection of files from a user's Space. Common use cases include:

- Downloading a user's photo gallery to a local application.
- Restoring a backup of application data from the Space to a local machine.
- Keeping a local workspace synchronized with a master version stored in the Space.

## Input Parameters

The command's constructor accepts a single object with the following fields:

- **source** `string` *(required)* — The source directory path in your DID Space from which to pull files. The path should end with a '/'.

- **target** `string` *(required)* — The destination path on your local file system where files will be downloaded. The command will automatically create this directory if it does not exist.

- **concurrency** `number` (default: `4`) — The number of files to download in parallel. Increasing this value can speed up the process for directories with many small files. The maximum value is capped by the number of available CPU cores.

- **retryCount** `number` (default: `3`) — The number of times to retry a failed download for a specific file before marking it as an error. The maximum value is 10.

- **filter** `(object: Object) => boolean` — A function that is called for each remote object. Return true to include the object in the sync process, or false to skip it. This is useful for selectively downloading files based on their properties, like name or size.

- **onProgress** `(params: OnProgressInput) => void` — A callback function that is triggered as each file begins its download process. It receives an object with the current progress.
  - **completed** `number` — The number of files that have started downloading.
  - **total** `number` — The total number of files to be downloaded.
  - **key** `string` — The key (relative path) of the file currently being processed.

- **onAfterUpload** `(params: OnAfterUploadInput) => void` — A callback function that is triggered after each file is successfully downloaded. Note: Despite the name 'onAfterUpload', for a pull command, it signifies the completion of a download.
  - **completed** `number` — The number of files successfully downloaded so far.
  - **total** `number` — The total number of files to be downloaded.
  - **key** `string` — The key (relative path) of the file that just finished downloading.

- **debug** `boolean` (default: `false`) — Set to true to enable verbose logging in the console, which can be helpful for debugging the synchronization process.

- **strictSync** `boolean` (default: `false`) — This parameter has no effect for SyncFolderPullCommand. The command is designed to be non-destructive to the local directory and will not delete local files that are absent from the remote source.

## Output

The `spaceClient.send()` method returns a promise that resolves to an object containing the result of the operation.

- **statusCode** `number` — Indicates the outcome of the request. A value of 200 means the entire sync operation completed successfully.

- **data** `object` — An object containing a summary of the sync operation.
  - **count** `number` — The total number of files that were scheduled for download.
  - **errorCount** `number` — The number of files that failed to download after all retries.
  - **size** `number` — The total size in bytes of all successfully downloaded files.
  - **duration** `number` — The total time taken for the operation, in seconds.

- **statusMessage** `string` — An error message if the entire command failed to execute (e.g., due to authentication issues).

- **stack** `string` — The stack trace if an unrecoverable error occurred.

## Example

Here's how to use `SyncFolderPullCommand` to download a remote directory to a local folder and track its progress.

**Example**

```typescript
import { SpaceClient, SyncFolderPullCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import { ensureDirSync, removeSync } from 'fs-extra';
import path from 'path';

const main = async () => {
  // 1. Initialize SpaceClient
  const wallet = getWallet();
  const spaceClient = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  // 2. Prepare local directory for the download
  const localTarget = path.join(__dirname, 'my-pulled-assets');
  removeSync(localTarget); // Clean up previous runs for this example
  ensureDirSync(localTarget);
  console.log(`Downloading files to: ${localTarget}`);

  // 3. Create and send the command
  const command = new SyncFolderPullCommand({
    source: '/shared-media/', // The directory in your Space to pull from
    target: localTarget, // The local directory to download to
    onProgress: ({ completed, total, key }) => {
      const progress = total > 0 ? ((completed / total) * 100).toFixed(2) : 0;
      console.log(`Progress: ${progress}% (${completed}/${total}) - Starting download for: ${key}`);
    },
  });

  const output = await spaceClient.send(command);

  // 4. Handle the output
  if (output.statusCode === 200) {
    console.log('\nFolder pull completed successfully!');
    console.log(`Total files synchronized: ${output.data.count}`);
    console.log(`Total size: ${(output.data.size / 1024).toFixed(2)} KB`);
    console.log(`Duration: ${output.data.duration.toFixed(2)}s`);
    console.log(`Errors: ${output.data.errorCount}`);
  } else {
    console.error(`Folder pull failed with status ${output.statusCode}:`, output.statusMessage);
  }
};

main().catch(console.error);
```

### Example Response (Success)

**Response**

```json
{
  "statusCode": 200,
  "data": {
    "errorCount": 0,
    "count": 15,
    "duration": 5.432,
    "size": 2048576
  }
}
```

## Best Practices

### Filtering Files

To save bandwidth and time, use the `filter` function to download only the files you need. For instance, to download only JPEG and PNG images:

**Filtering Example**

```javascript
const command = new SyncFolderPullCommand({
  source: '/photos/',
  target: './downloaded_images',
  filter: (object) => {
    // Skip directories and non-image files
    if (object.isDir) return false;
    const lowerCaseKey = object.key.toLowerCase();
    return lowerCaseKey.endsWith('.jpg') || lowerCaseKey.endsWith('.png');
  },
});
```

### Understanding Sync Logic

`SyncFolderPullCommand` performs a safe, one-way synchronization. It compares files based on size and last modification time. If a remote file is newer or has a different size than its local counterpart, it will be downloaded. If a file exists remotely but not locally, it will be created locally. Crucially, this command <strong>will not delete</strong> any local files, even if they don't exist in the remote source directory. This makes it a non-destructive way to keep a local folder up-to-date.

---

## SyncFolderPushCommand

URL: https://www.arcblock.io/en/docs/did-space-js/api-reference-sync-commands-sync-folder-push-c19e7c/

The `SyncFolderPushCommand` is a high-level command designed to efficiently synchronize a local directory with a remote directory in your DID Space. It intelligently compares the local and remote states, uploading new or modified files and, optionally, deleting remote files that no longer exist locally. This command simplifies common tasks like deploying static websites, backing up important data, or distributing digital assets.

It handles complexities like concurrency, retries, and consistency checks, providing a robust and straightforward way to manage folder synchronization.

## Use Cases

- <strong>Deploying Static Websites</strong>: Push your local build directory (e.g., `./dist`, `./build`) to a public folder in your DID Space to deploy or update a website.
- <strong>Data Backup</strong>: Regularly sync a local folder containing important documents or user data to your DID Space for a secure backup.
- <strong>Asset Distribution</strong>: Upload a folder of images, videos, or other assets that your application needs to serve to users.

## Input Parameters

The `SyncFolderPushCommand` accepts the following parameters in its input object.

- **source** `string | SourceObject[]` *(required)* — Specifies the local source to sync from. This can be a string representing a local directory path, or an array of objects for more granular control.
- **target** `string` *(required)* — The destination path in your DID Space where the files will be synced. It should end with a '/'.
- **metadata** `ObjectMetadata` — Custom metadata to attach to the target folder object.
- **preview** `PreviewTemplate` — A preview template to set for the target folder. See the guide on [Managing Folder Previews](./guides-manage-previews.md) for more details.
- **strictSync** `boolean` (default: `false`) — If true, files that exist in the remote target but not in the local source will be deleted. Use with caution.
- **filter** `(object: Object) => boolean` — A function to filter which local objects should be included in the synchronization. Return true to include the object, false to exclude it.
- **onProgress** `(progress: OnProgressInput) => void` — A callback function that is triggered periodically to report the synchronization progress.
- **onAfterUpload** `(result: OnAfterUploadInput) => void` — A callback function that is triggered after each individual file upload is completed.
- **concurrency** `number` (default: `4`) — The number of files to upload in parallel. The maximum is the number of CPU cores.
- **retryCount** `number` (default: `3`) — The number of times to retry a failed upload for a single file. The maximum is 10.
- **tmpDir** `string` — Path to a temporary directory for processing files. Defaults to a system-generated temporary directory.
- **debug** `boolean` (default: `false`) — If true, enables detailed debug logging to the console.

## Output

The command returns a `Promise` that resolves to the following object.

- **statusCode** `number` — The HTTP status code of the overall operation. 200 indicates success.
- **statusMessage** `string` — A message providing more details about the outcome of the operation.
- **data** `object` — An object containing the results of the synchronization process.
- **size** `number` — The total size of all successfully uploaded files, in bytes.
- **count** `number` — The total number of operations attempted (uploads and deletes).
- **errorCount** `number` — The number of operations that failed.
- **duration** `number` — The total time taken for the synchronization, in seconds.

## Example

This example demonstrates how to sync a local folder named `./my-blog-dist` to the `/blog/` directory in a DID Space.

**Syncing a Local Folder**

```typescript
import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import path from 'path';
import fs from 'fs-extra';

// Ensure the source directory and some files exist for the example
const sourceDir = path.join(__dirname, 'my-blog-dist');
fs.ensureDirSync(sourceDir);
fs.writeFileSync(path.join(sourceDir, 'index.html'), '<h1>Hello World</h1>');
fs.ensureDirSync(path.join(sourceDir, 'assets'));
fs.writeFileSync(path.join(sourceDir, 'assets', 'style.css'), 'body { color: #333; }');

async function syncWebsite() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new SyncFolderPushCommand({
    source: sourceDir,
    target: '/blog/',
    strictSync: true, // Delete remote files not in the source
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? ((completed / total) * 100).toFixed(2) : 0;
      console.log(`Sync progress: ${completed}/${total} files (${percentage}%)`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Sync completed successfully!');
    console.log(`Total files processed: ${output.data.count}`);
    console.log(`Errors: ${output.data.errorCount}`);
    console.log(`Duration: ${output.data.duration}s`);
  } else {
    console.error('Sync failed:', output.statusMessage);
  }

  // Clean up the created directory
  fs.removeSync(sourceDir);
}

syncWebsite();
```

### Example Response (Success)

**Response Data**

```json
{
  "statusCode": 200,
  "data": {
    "size": 48,
    "errorCount": 0,
    "count": 2,
    "duration": 1.25
  }
}
```

## Best Practices

### Ensuring Data Consistency

When syncing files, especially from a directory that might be actively written to, there's a risk of uploading an incomplete or corrupted file. To prevent this, the `SyncFolderPushCommand` first copies each file to a temporary directory before uploading. This ensures that a stable snapshot of the file is used for the upload, safeguarding against `Unexpected end of form` errors and ensuring data integrity.

### Using strictSync Safely

The `strictSync: true` option is powerful for ensuring the remote directory is an exact mirror of the local source. However, it is a destructive operation. Any file on the remote server that is not present in the local source directory will be permanently deleted. Always double-check your `source` and `target` paths before enabling this option.

### Custom Filtering

You can use the `filter` function to gain fine-grained control over which files are synchronized. For example, you can exclude dotfiles, log files, or specific directories.

**Filtering Files**

```typescript
const command = new SyncFolderPushCommand({
  source: './project',
  target: '/my-project/',
  filter: (object) => {
    // Exclude all files starting with a dot (e.g., .DS_Store, .env)
    if (object.name.startsWith('.')) {
      return false;
    }
    // Exclude the node_modules directory
    if (object.key.includes('/node_modules/')) {
      return false;
    }
    return true;
  },
});
```

---

## Client Initialization & Auth

URL: https://www.arcblock.io/en/docs/did-space-js/core-concepts-authentication-c19e7c/

The `SpaceClient` is the primary interface for interacting with the DID Space network. Before you can upload files or manage data, you must first create an instance of the client with the correct configuration and authentication credentials. This guide will walk you through the various strategies for initializing and authenticating the `SpaceClient`.

All configuration is passed to the client through a single `SpaceClientOptions` object in its constructor.

**Initializing the Client**

```typescript
import { SpaceClient } from '@blocklet/did-space-js';

const spaceClient = new SpaceClient({
  // ... your options go here
});
```

The most critical part of this configuration is the `auth` object, which determines how your requests will be authenticated.

## Authentication Strategies

The SDK offers three primary methods for authentication, designed to fit different use cases. You should choose the one that best suits your application's environment and security requirements.

### 1. Using Endpoint & Wallet (Recommended)

This is the most common and secure method, especially when developing within a Blocklet environment where a user's wallet is readily available. It uses the user's wallet to sign requests, providing a robust, decentralized authentication mechanism.

This method corresponds to the `SpaceClientOptionsEndpointAuth` interface.

<strong>Configuration</strong>

- **auth** `object` *(required)* — Authentication details using wallet and endpoint.
  - **wallet** `WalletObject` *(required)* — The wallet object, typically retrieved from the Blocklet SDK, used for signing requests.
  - **endpoint** `string` *(required)* — The specific API endpoint for the user's DID Space and application.

<strong>Example</strong>

**Initializing with Wallet and Endpoint**

```typescript
import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// In a Blocklet environment, the wallet is easily accessible.
const wallet = getWallet();

// The endpoint is specific to a user's space and the app's DID.
const endpoint =
  'https://cedcaa27-znkomkclejcfbjaxw9knzzebmzmqrxjnn9bb.did.abtnet.io/api/space/z3T6EHN7sLhH5cty1PshDeSipeG7JNxEVaRFS/app/zNKabhhwdvVmXjtRTtSHk2YQz4pdDPStV289/';

const spaceClient = new SpaceClient({
  auth: {
    wallet: wallet,
    endpoint: endpoint,
  },
});

// The client is now ready to send signed requests.
```

### 2. Using an Authorization Token

This method is suitable for scenarios where you have a short-lived bearer token. This is common in traditional web applications or for server-to-server communication where a wallet might not be present.

This method corresponds to the `SpaceClientOptionsAuthorizationAuth` interface.

<strong>Configuration</strong>

- **auth** `object` *(required)* — Authentication details using an authorization token.
  - **authorization** `string` *(required)* — The authorization token (e.g., a JWT) to be sent with requests.

<strong>Example</strong>

**Initializing with an Authorization Token**

```typescript
import { SpaceClient } from '@blocklet/did-space-js';

const authToken = 'your-secure-authorization-token';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    authorization: authToken,
  },
});

// The client will now use the token for authentication.
```

### 3. Using an Access Key

This method is designed for backend services or automated scripts that need long-term access to a DID Space. It uses a secret key for authentication, similar to how many cloud services grant API access.

This method corresponds to the `SpaceClientOptionsAccessKeyAuth` interface.

<strong>Configuration</strong>

- **auth** `object` *(required)* — Authentication details using a secret access key.
  - **secretKey** `string` *(required)* — The secret key for authenticating requests.

<strong>Example</strong>

**Initializing with a Secret Key**

```typescript
import { SpaceClient } from '@blocklet/did-space-js';

const secretKey = 'your-long-term-secret-key';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    secretKey: secretKey,
  },
});

// The client is configured for server-side or automated access.
```

## Other Important Options

Besides authentication, the `SpaceClientOptions` object accepts a few other useful parameters.

- **url** `string` (default: `https://www.didspaces.com`) — The base URL of the DID Spaces service. The SDK automatically resolves the correct application mount point. It's usually not necessary to change this.
- **delegation** `string` — A JWT token that certifies the requester is authorized to access the space on behalf of another DID.
- **abortController** `AbortController` — An AbortController instance to allow for request cancellation.

Now that you understand how to initialize and authenticate the `SpaceClient`, the next logical step is to learn how the SDK secures your requests under the hood. To dive deeper into the security model, please proceed to the [Request Signing](/en/docs/did-space-js/core-concepts-request-signing-c19e7c/) documentation.

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/did-space-js/core-concepts-c19e7c/

This section delves into the fundamental principles and architectural patterns that power the `@blocklet/did-space-js` SDK. Understanding these concepts will help you use the library more effectively and troubleshoot issues with greater confidence. The SDK is built on three main pillars: a robust Command Pattern, flexible Authentication methods, and a secure Request Signing mechanism.

## The Command Pattern

Instead of having dozens of methods on the main `SpaceClient` object, the SDK adopts the Command Pattern. This design choice offers a clean and scalable architecture.

<strong>How it works:</strong>

::::steps
:::step{title="Encapsulation"}
Every distinct operation (like uploading a file or listing a directory) is encapsulated into its own `Command` class. For example, to upload a file, you use `PutObjectCommand`.
:::

:::step{title="Standardization"}
Each command has a standardized structure, accepting an `input` object for its parameters and returning a structured `output` object.
:::

:::step{title="Execution"}
The `SpaceClient` acts as a universal executor. You create an instance of a command and then pass it to the `client.send()` method, which handles the underlying logic of authentication, request signing, and HTTP communication.
:::
::::

This separation of concerns—the command defining <em>what</em> to do and the client handling <em>how</em> to do it—makes the SDK predictable and easy to extend.

![Core Concepts](https://media.arcblock.io/lib/63/63efd9488d6dad4f.w1600.webp)

## Client Initialization & Authentication

Before you can send any commands, you must initialize a `SpaceClient` instance with the proper configuration and authentication credentials. The SDK is designed to be flexible, supporting multiple authentication strategies to fit different use cases, from server-side applications to client-side components.

The primary way to configure the client is through the `SpaceClientOptions` object passed to its constructor. This object specifies the target DID Space and the credentials needed to access it.

::link-card{title="Client Initialization & Auth" description="Learn about the different methods for initializing the SpaceClient, including using a wallet, a secret key, or an authorization token." icon="key" href="/en/docs/did-space-js/core-concepts-authentication-c19e7c/"}

## Secure by Design: Request Signing

Security is a cornerstone of DID Spaces. Every API request sent by the SDK is cryptographically signed to ensure its authenticity and integrity. This prevents unauthorized access and tampering with data in transit.

Here’s a high-level overview of the process:

1. When you call `client.send(command)`, the SDK constructs the full HTTP request.
2. It then creates a unique digital signature for that specific request by hashing its contents (URL, method, body) and signing the hash with the private key from your wallet.
3. This signature, along with your public key, is sent as part of the request headers.
4. The DID Space server receives the request, re-calculates the signature on its end, and verifies it against the one you sent using your public key.

If the signatures match, the server knows the request is authentic and came from you. If not, it rejects the request.

::link-card{title="Request Signing" description="Dive deeper into the security model, exploring how requests are cryptographically signed and verified to guarantee data integrity." icon="shield-check" href="/en/docs/did-space-js/core-concepts-request-signing-c19e7c/"}

## Next Steps

Now that you have a high-level understanding of the core concepts, you can explore them in more detail or move on to practical guides.

::::card-group
::link-card{title="Client Initialization & Auth" description="Learn the specifics of configuring and authenticating your client." icon="key" href="/en/docs/did-space-js/core-concepts-authentication-c19e7c/"}
::link-card{title="Request Signing" description="Understand the cryptographic security behind every API call." icon="shield-check" href="/en/docs/did-space-js/core-concepts-request-signing-c19e7c/"}
::link-card{title="Guides" description="Follow step-by-step tutorials for common tasks like syncing folders." icon="book-open" href="/en/docs/did-space-js/guides-c19e7c/"}
::link-card{title="API Reference" description="Browse the detailed documentation for every available command and class." icon="code" href="/en/docs/did-space-js/api-reference-c19e7c/"}
::::

---

## Request Signing

URL: https://www.arcblock.io/en/docs/did-space-js/core-concepts-request-signing-c19e7c/

To ensure the security and integrity of every interaction with your DID Space, all API requests are protected by a robust cryptographic signing mechanism. This process guarantees that requests are authentic—sent by the claimed identity—and have not been tampered with in transit.

While the `@blocklet/did-space-js` SDK handles this process automatically when you use the `SpaceClient`, understanding how it works is key to building secure applications and troubleshooting potential issues. This process involves two main parts: signing the request on the client-side and verifying it on the server-side.

## The Signing Process (Client-Side)

Before any command is sent to the DID Space API, the SDK performs a series of steps to create a cryptographic signature. This ensures the server can validate the request's origin and integrity.

![Request Signing](https://media.arcblock.io/lib/be/be7494b9eaa66a2d.w1600.webp)

Here's a breakdown of the steps:

1. <strong>Create a Digest</strong>: The SDK first creates a unique and consistent fingerprint of the request payload. It takes the request's URL, HTTP method, and data, then serializes them into a stable JSON string. This string is then hashed using SHA3-256. This digest ensures that even a single character change in the request will result in a completely different signature.
2. <strong>Create a JWT</strong>: A JSON Web Token (JWT) is assembled. This token's payload includes the digest created in the previous step, the issuer's DID (from the wallet), and an expiration timestamp (typically one hour) to prevent replay attacks.
3. <strong>Sign the JWT</strong>: The entire JWT is then cryptographically signed using the `secretKey` from the provided wallet object. This signature proves that the request was initiated by the owner of that wallet.
4. <strong>Attach HTTP Headers</strong>: Finally, the SDK attaches the signature and related information to the outgoing HTTP request using the following headers:
5.
  - `x-app-did`: The DID of the application's wallet.
  - `x-app-pk`: The public key corresponding to the wallet that signed the request.
  - `x-app-token`: The signed JWT created in the previous steps.
  - `x-app-delegation` (Optional): A token used for delegated authority, explained below.

## The Verification Process (Server-Side)

When the DID Space API server receives a request, it performs the reverse process to verify its authenticity and integrity before processing it.

Here are the server's validation steps:

::::steps
:::step{title="Extract Headers"}
The server reads the `x-app-did`, `x-app-pk`, and `x-app-token` headers from the incoming request.
:::

:::step{title="Verify Identity"}
It confirms that the provided `x-app-did` corresponds to the `x-app-pk`. This ensures the public key is a valid key for the given DID.
:::

:::step{title="Verify Token Signature"}
Using the `x-app-pk` (the public key), the server verifies the signature of the `x-app-token`. A successful verification proves that the token was signed by the holder of the corresponding private key.
:::

:::step{title="Verify Payload Integrity"}
The server independently re-calculates the SHA3-256 digest from the request's URL, method, and data, using the exact same process as the client. It then compares this newly calculated digest with the `digest` found inside the verified JWT payload. If they match, the server can be certain that the request content has not been altered since it was signed.
:::
::::

If all these checks pass, the server considers the request valid and proceeds to execute it.

## Delegated Authority

A powerful feature of the security model is delegation. This allows a primary wallet (e.g., a user's wallet) to grant temporary, specific permissions to another wallet (e.g., a service or application) to act on its behalf.

This is accomplished using the `x-app-delegation` header, which contains another JWT. This delegation token is signed by the user and specifies:

- `from`: The user's DID (the delegator).
- `to`: The application's DID (the delegatee).
- `permissions`: An array of permissions being granted, which must include `DIDSpaceAgent` for this context.

When the server verifies a request with a delegation header, it confirms that the application (`delegatee`) is authorized to act for the user (`delegator`). The request is then processed with the user's authority.

## Core Functions

While you won't call them directly when using `SpaceClient`, the following functions from the `@arcblock/jwt` and `@ocap/mcrypto` packages form the foundation of this security model.

### signRequest

This function is used internally by the client to assemble the signature and headers.

**signRequest Signature**

```typescript
async function signRequest({
  url,
  method,
  data,
  headers,
  wallet,
  delegation,
}: {
  url: string;
  method: Method;
  data: any;
  headers: { [key: string]: string };
  wallet?: WalletObject;
  delegation?: string;
}): Promise<{ url: string; method: Method; data: any; headers: Headers }>;
```

### verifyRequest

This function represents the logic the server uses to validate an incoming request.

**verifyRequest Signature**

```typescript
async function verifyRequest({
  url,
  method,
  data,
  headers,
}: {
  url: string;
  method: Method;
  data: any;
  headers: Headers;
}): Promise<string>; // Returns the authenticated app DID
```

Understanding this request signing and verification flow provides insight into the robust security measures protecting your data in DID Space. Now that you understand the core security model, you can explore how to apply these concepts in practical scenarios.

::::card-group
::link-card{title="Client Initialization & Auth" description="Learn how to initialize the SpaceClient with a wallet to enable automatic request signing." icon="key" href="/en/docs/did-space-js/core-concepts-authentication-c19e7c/"}
::link-card{title="Guides" description="Move on to practical guides to see how signed requests are used to perform tasks like syncing folders." icon="book-open" href="/en/docs/did-space-js/guides-c19e7c/"}
::::

---

## Getting Started

URL: https://www.arcblock.io/en/docs/did-space-js/getting-started-c19e7c/

Welcome to the DID Space Client SDK! This guide will walk you through the essential steps to get the SDK installed, configured, and to perform your first file upload. You'll be up and running in just a few minutes.

## Prerequisites

Before you begin, ensure you have the following:

- A Blocklet project set up.
- A DID Space endpoint URL. To learn how to get one, see [Connect to DID Spaces](/en/docs/did-spaces/connect-to-did-spaces/).

## Step 1: Install the SDK

First, add the `@blocklet/did-space-js` package to your project using your preferred package manager.

**Install with npm**

```bash
npm install @blocklet/did-space-js
```

**Install with yarn**

```bash
yarn add @blocklet/did-space-js
```

## Step 2: Initialize the SpaceClient

The `SpaceClient` is the main entry point for interacting with the SDK. To initialize it, you need to provide authentication credentials. In a Blocklet environment, the easiest way is to use the current Blocklet's wallet and your space endpoint.

**Initialize Client**

```typescript
import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// This retrieves the wallet managed by the Blocklet environment.
const wallet = getWallet();

// Replace with your actual DID Space endpoint.
const endpoint = 'https://your-space-endpoint.did.abtnet.io/api/space/...';

const spaceClient = new SpaceClient({
  auth: {
    wallet,
    endpoint,
  },
});
```

## Step 3: Upload a File

With the client initialized, you can now send commands. We'll use the `PutObjectCommand` to upload a simple text file.

Commands follow a consistent pattern: you create an instance of the command with its required input, then pass it to the `spaceClient.send()` method.

The `send` method returns an output object containing the status of the request. A `statusCode` of `200` indicates success.

**Upload a File**

```typescript
import { PutObjectCommand } from '@blocklet/did-space-js';
import { Buffer } from 'buffer';

async function uploadFile() {
  const command = new PutObjectCommand({
    // The name of the file (or object key) in your DID Space.
    key: 'greeting.txt',
    // The content of the file. It's best to use a Buffer.
    data: Buffer.from('Hello from the DID Space SDK!'),
  });

  const output = await spaceClient.send(command);

  if (output.statusCode === 200) {
    console.log('Success! Your file has been uploaded.');
  } else {
    console.error(`Upload failed with status ${output.statusCode}: ${output.statusMessage}`);
  }
}

uploadFile();
```

## Complete Example

Here is a complete, ready-to-run example that combines all the steps above. You can place this code inside an async function in your Blocklet project.

**Full Example**

```typescript
import { SpaceClient, PutObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import { Buffer } from 'buffer';

async function run() {
  // 1. Initialize the client
  const wallet = getWallet();
  const endpoint = 'https://your-space-endpoint.did.abtnet.io/api/space/...'; // TODO: Replace with your endpoint

  const spaceClient = new SpaceClient({
    auth: {
      wallet,
      endpoint,
    },
  });

  console.log('Client initialized. Preparing to upload file...');

  // 2. Create and send the upload command
  const command = new PutObjectCommand({
    key: 'greeting.txt',
    data: Buffer.from('Hello from the DID Space SDK!'),
  });

  const output = await spaceClient.send(command);

  // 3. Check the result
  if (output.statusCode === 200) {
    console.log('Success! Your file has been uploaded.');
  } else {
    console.error(`Upload failed with status ${output.statusCode}: ${output.statusMessage}`);
    console.error('Stack trace:', output.stack);
  }
}

run().catch(console.error);
```

After running this code, you should see the `greeting.txt` file in your DID Space.

## Next Steps

Congratulations! You've successfully uploaded your first file using the DID Space Client SDK.

Now that you have the basics down, you can explore more advanced topics:

::::card-group
::link-card{title="Core Concepts" description="Understand the fundamental principles behind the SDK, including the command pattern and authentication." icon="award" href="/en/docs/did-space-js/core-concepts-c19e7c/"}
::link-card{title="API Reference" description="Dive into the detailed documentation for every available command and class." icon="book-open" href="/en/docs/did-space-js/api-reference-c19e7c/"}
::::

---

## Guides

URL: https://www.arcblock.io/en/docs/did-space-js/guides-c19e7c/

Welcome to the Guides section. Here you'll find practical, step-by-step tutorials designed to help you accomplish common tasks and implement specific features using the DID Space Client SDK. Each guide focuses on a real-world workflow, providing complete code examples and best practices.

Select a guide below to get started.

::::card-group
::link-card{title="Synchronizing Folders" description="Follow a complete guide on how to keep a local directory in sync with a remote directory in your DID Space using SyncFolderPush and SyncFolderPull commands." icon="folder" href="/en/docs/did-space-js/guides-sync-folders-c19e7c/"}
::link-card{title="Managing Folder Previews" description="Learn how to set, retrieve, and remove custom previews for folders, enhancing the user experience of your application." icon="image" href="/en/docs/did-space-js/guides-manage-previews-c19e7c/"}
::::

If you're looking for detailed information on specific commands or classes, head over to the [API Reference](/en/docs/did-space-js/api-reference-c19e7c/).

---

## Managing Folder Previews

URL: https://www.arcblock.io/en/docs/did-space-js/guides-manage-previews-c19e7c/

DID Space allows you to set a custom preview for any folder. This feature enables you to define how a folder is presented in applications, turning a simple file listing into a rich, interactive experience like a gallery, a document preview, or even a mini-application. This is managed by a special `preview.yml` file inside the folder's `.meta` directory.

This guide will walk you through the three primary operations for managing folder previews using the SDK:

- <strong>Setting a Preview</strong>: Create or update a folder's preview configuration and upload its associated assets (e.g., `index.html`, CSS, JavaScript files) in a single operation.
- <strong>Retrieving a Preview</strong>: Fetch the preview configuration for a specific folder.
- <strong>Deleting a Preview</strong>: Remove the custom preview from a folder.

## Setting a Folder Preview

To set or update a folder's preview, you use the `PutPreviewObjectCommand`. This powerful command not only writes the `preview.yml` configuration but also uploads all the necessary resource files (like HTML, CSS, and JS) that the preview will use.

### Input Parameters

- **key** `string` *(required)* — The path to the folder. It must end with a trailing slash (/).
- **data** `PreviewTemplate` *(required)* — An object containing the preview configuration. This will be converted to YAML and stored in .meta/preview.yml.
- **name** `string` *(required)* — The name of the preview.
- **description** `string` — A short description of the preview.
- **entry** `string` *(required)* — The entry file for the preview, typically an index.html file.
- **resources** `PutObjectCommandInput[]` (default: `[]`) — An array of file objects to upload as part of the preview. Each resource key must be prefixed with the folder's key.
- **metadata** `object` (default: `{}`) — A record of custom metadata to associate with the preview.
- **hash** `string` — The IPFS CID v1 hash of the object, used for data integrity verification.

### Example

The following example demonstrates how to create a simple HTML preview for a folder named `my-gallery/`. We will upload an `index.html` and a `style.css` file along with the preview configuration.

**Set a Folder Preview**

```typescript
import { SpaceClient, PutPreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function setFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const folderKey = 'my-gallery/';

  const input = {
    key: folderKey,
    // This 'data' object will become the content of '.meta/preview.yml'
    data: {
      name: 'My Image Gallery',
      description: 'A simple preview for my image collection.',
      entry: 'index.html', // The entry point for the preview
    },
    // Upload the preview assets in the same command
    resources: [
      {
        key: `${folderKey}index.html`,
        body: Buffer.from(
          '<!DOCTYPE html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>Welcome to My Gallery</h1></body></html>'
        ),
        contentType: 'text/html',
      },
      {
        key: `${folderKey}style.css`,
        body: Buffer.from('body { background-color: #f0f0f0; color: #333; }'),
        contentType: 'text/css',
      },
    ],
  };

  const command = new PutPreviewObjectCommand(input);
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully set folder preview!');
  } else {
    console.error('Failed to set folder preview:', output.statusMessage);
  }
}

setFolderPreview();
```

After this command executes, the `my-gallery/` folder will have a `.meta/preview.yml` file and will contain `index.html` and `style.css`.

## Retrieving a Folder Preview

To get the configuration of an existing folder preview, use the `GetPreviewObjectCommand`. This command reads the `.meta/preview.yml` file and returns its parsed content.

### Input Parameters

- **key** `string` *(required)* — The path to the folder. It must end with a trailing slash (/).

### Output

The command's output contains the parsed `PreviewTemplate` object in the `data` property.

- **data** `PreviewTemplate` — The parsed content of the .meta/preview.yml file.

### Example

**Get a Folder Preview**

```typescript
import { SpaceClient, GetPreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function getFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new GetPreviewObjectCommand({ key: 'my-gallery/' });
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Preview configuration:', output.data);
  } else {
    console.error('Failed to get folder preview:', output.statusMessage);
  }
}

getFolderPreview();
```

### Example Response

If the command is successful, the `output.data` would look like this:

**Example Response**

```json
{
  "name": "My Image Gallery",
  "description": "A simple preview for my image collection.",
  "entry": "index.html"
}
```

## Deleting a Folder Preview

If you want to remove a custom preview and revert a folder to its default appearance, use the `DeletePreviewObjectCommand`. This command deletes the `.meta/preview.yml` file but does <strong>not</strong> affect any other files in the folder, including the resource files you may have uploaded.

### Input Parameters

- **key** `string` *(required)* — The path to the folder. It must end with a trailing slash (/).

### Example

**Delete a Folder Preview**

```typescript
import { SpaceClient, DeletePreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function deleteFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new DeletePreviewObjectCommand({ key: 'my-gallery/' });
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully deleted folder preview!');
  } else {
    console.error('Failed to delete folder preview:', output.statusMessage);
  }
}

deleteFolderPreview();
```

By using these three commands, you can fully manage custom folder previews to create richer and more engaging user experiences in your DID Space-powered applications.

---

## Synchronizing Folders

URL: https://www.arcblock.io/en/docs/did-space-js/guides-sync-folders-c19e7c/

Keeping a local directory in sync with a remote one in your DID Space is a common requirement for applications like static website hosting, data backup, or collaborative asset management. The DID Space Client SDK simplifies this process with two powerful, high-level commands: `SyncFolderPushCommand` and `SyncFolderPullCommand`.

This guide will walk you through practical examples of how to use these commands. For a detailed breakdown of all available parameters and options, please refer to the [SyncFolderPushCommand](/en/docs/did-space-js/api-reference-sync-commands-sync-folder-push-c19e7c/) and [SyncFolderPullCommand](/en/docs/did-space-js/api-reference-sync-commands-sync-folder-pull-c19e7c/) API references.

## How Synchronization Works

At its core, the synchronization process intelligently determines which files need to be transferred. When a sync command is executed, it performs a comparison between the source and target directories. A file is marked for synchronization if any of the following conditions are met:

- The file exists in the source but not in the target.
- The file exists in both, but their sizes differ.
- The file exists in both with the same size, but the source file has a more recent modification time.

By default, the sync commands will only add or update files. You can enable `strictSync` mode to also delete files in the target directory that do not exist in the source, ensuring an exact mirror.

## Pushing a Local Folder to DID Space

Use `SyncFolderPushCommand` when you want to upload or update the contents of a local directory to a remote directory in your DID Space. This is perfect for deploying a static website or backing up local files.

### Step 1: Initialize the Client and Command

First, set up your `SpaceClient` and import the `SyncFolderPushCommand`.

**Initialize Client**

```typescript
import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// Initialize the wallet and client
const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...', // Use your Space endpoint
  wallet,
});
```

### Step 2: Define Command Inputs

To push a folder, you need to specify the local `source` path and the remote `target` path.

- **source** `string` *(required)* — The path to the local directory you want to upload. It's recommended to end the path with a '/'.
- **target** `string` *(required)* — The destination path in your DID Space. This should also end with a '/'.
- **strictSync** `boolean` (default: `false`) — If true, files on the remote that are not present in the local source will be deleted.
- **onProgress** `function` — An optional callback function to monitor the upload progress.

### Step 3: Execute the Push Command

Now, create an instance of the command with your inputs and send it using the client.

**Push a Folder**

```typescript
async function pushMyWebsite() {
  const command = new SyncFolderPushCommand({
    source: './build/', // Path to your local build folder
    target: '/public/my-website/', // Destination in DID Space
    strictSync: true, // Mirror the local folder exactly
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? (completed / total) * 100 : 0;
      console.log(`Upload progress: ${percentage.toFixed(2)}%`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Push successful!');
    console.log(`Total files synced: ${output.data.count}`);
    console.log(`Total size: ${output.data.size} bytes`);
    console.log(`Duration: ${output.data.duration} seconds`);
  } else {
    console.error('Push failed:', output.statusMessage);
  }
}

pushMyWebsite();
```

This example uploads the contents of the local `./build/` directory to `/public/my-website/` in your Space. Because `strictSync` is `true`, any files in the remote directory that aren't in `./build/` will be removed.

## Pulling a Remote Folder from DID Space

Use `SyncFolderPullCommand` to download the contents of a remote directory from your DID Space to your local file system. This is useful for restoring a backup or retrieving a shared project.

### Step 1: Define Command Inputs

The inputs for pulling are similar to pushing, but the roles of `source` and `target` are reversed.

- **source** `string` *(required)* — The path to the remote directory in your DID Space that you want to download.
- **target** `string` *(required)* — The local destination path where files will be saved.
- **strictSync** `boolean` (default: `false`) — If true, the command will identify local files that are not on the remote. However, for safety, the pull command currently does not perform deletions.

### Step 2: Execute the Pull Command

Create the `SyncFolderPullCommand` instance and send it.

**Pull a Folder**

```typescript
import { SpaceClient, SyncFolderPullCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function pullMyBackup() {
  const command = new SyncFolderPullCommand({
    source: '/backups/latest/', // Path in your DID Space
    target: './restored-backup/', // Local destination folder
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? (completed / total) * 100 : 0;
      console.log(`Download progress: ${percentage.toFixed(2)}%`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Pull successful!');
    console.log(`Total files synced: ${output.data.count}`);
    console.log(`Total size: ${output.data.size} bytes`);
  } else {
    console.error('Pull failed:', output.statusMessage);
  }
}

pullMyBackup();
```

This script downloads files from `/backups/latest/` in your Space to the local `./restored-backup/` directory. Note that even if `strictSync` were enabled, this command will not delete any extra files you might have in the local directory.

## Best Practices

- <strong>File Integrity:</strong> During a `push` operation, files are first copied to a temporary directory before uploading. This ensures that even if a file is modified locally during the sync process, a consistent version is uploaded, preventing data corruption.
- <strong>Performance:</strong> You can adjust the `concurrency` parameter in either command to control how many files are transferred simultaneously. The default is `4`. Increasing this value may improve speed on fast networks, while decreasing it can reduce load on slower connections.
- <strong>Filtering:</strong> Both commands accept a `filter` function in their input. You can use this to selectively include or exclude files from the synchronization process based on their properties, such as name or path.

## Next Steps

You now have a solid understanding of how to synchronize folders between your local machine and DID Space. To further enhance your application, you might want to explore how to manage folder appearances.

::::card-group
::link-card{title="Managing Folder Previews" description="Learn how to set custom thumbnails and metadata for your folders." icon="image" href="/en/docs/did-space-js/guides-manage-previews-c19e7c/"}
::link-card{title="Sync Commands API Reference" description="Dive deep into all the configuration options for sync commands." icon="book-open" href="/en/docs/did-space-js/api-reference-sync-commands-c19e7c/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/did-space-js/overview-c19e7c/

Welcome to the DID Space Client SDK for JavaScript! This is a powerful, modern library designed for Node.js environments, enabling you to seamlessly interact with DID Spaces. If you're building applications where users truly own and control their data, you're in the right place.

This SDK provides a simple yet comprehensive interface for managing files, synchronizing folders, and handling other data objects in a decentralized storage system that is cryptographically secure and user-centric.

## Key Features

::::card-group
::link-card{title="Complete Object Management" description="Perform all essential CRUD (Create, Read, Update, Delete) operations on individual files and data objects with a suite of intuitive commands." icon="file"}
::link-card{title="Powerful Folder Synchronization" description="Effortlessly keep local directories in sync with remote directories in a DID Space using high-level `SyncFolderPush` and `SyncFolderPull` commands." icon="git-merge"}
::link-card{title="Specialized NFT Storage" description="Handle NFT assets with a dedicated command that simplifies uploading the asset file and its associated DID Document, ensuring data integrity." icon="star"}
::link-card{title="Secure by Design" description="All API requests are cryptographically signed using a wallet, ensuring that every operation is authenticated and verifiable, protecting data from unauthorized access." icon="shield-check"}
::::

## Core Architecture

The SDK is built on a simple and robust command-based architecture. You interact with the API through two primary components:

::::steps
:::step{title="`SpaceClient`"}
The main entry point of the SDK. You instantiate it with your configuration and authentication credentials.
:::

:::step{title="Commands"}
These are classes that represent specific actions you want to perform, such as uploading a file or listing a directory's contents. Each command encapsulates the parameters and logic for its respective operation.
:::
::::

Your application creates a command object, populates it with the necessary input, and then passes it to the `SpaceClient`'s `send` method to execute the request.

**SDK Usage Pattern**

```typescript
import { SpaceClient, PutObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function uploadFile() {
  // 1. Initialize the client with authentication details
  const client = new SpaceClient({
    auth: {
      endpoint: 'https://www.didspaces.com/app/api/space/...',
      wallet: getWallet(),
    },
  });

  // 2. Create a command with its specific input
  const command = new PutObjectCommand({
    key: 'documents/hello.txt',
    data: 'Hello, DID Space!',
  });

  // 3. Send the command and receive the output
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('File uploaded successfully!');
  } else {
    console.error('Upload failed:', output.statusMessage);
  }
}

uploadFile();
```

This design pattern makes the SDK highly modular and easy to extend. Each command is self-contained, making your code clean and organized.

![Overview](https://media.arcblock.io/lib/a8/a883977eb5aaf281.w1600.webp)

## How to Navigate This Documentation

This documentation is structured to help you find the information you need, whether you're just starting or looking for specific details.

::::card-group
::link-card{title="Getting Started" description="A step-by-step tutorial to get you up and running in minutes. Start here if you're new to the SDK." icon="rocket" href="/en/docs/did-space-js/getting-started-c19e7c/"}
::link-card{title="Core Concepts" description="Understand the fundamental principles behind the SDK, such as the command pattern and request signing." icon="brain" href="/en/docs/did-space-js/core-concepts-c19e7c/"}
::link-card{title="Guides" description="Practical, task-oriented guides to help you accomplish common workflows like synchronizing folders." icon="book-open" href="/en/docs/did-space-js/guides-c19e7c/"}
::link-card{title="API Reference" description="A detailed, comprehensive reference for every class, method, and command available in the SDK." icon="book-open" href="/en/docs/did-space-js/api-reference-c19e7c/"}
::::

## Next Steps

Ready to start building? The best way to learn is by doing. Follow our Getting Started guide to install the SDK and make your first API call.

:::action-card{title="Go to Getting Started" description="Install the SDK, initialize the client, and perform your first file upload." icon="arrow-right"}
::action{label="Start Tutorial" href="/en/docs/did-space-js/getting-started-c19e7c/" variant="primary"}
:::

---

## Utilities

URL: https://www.arcblock.io/en/docs/did-space-js/utilities-c19e7c/

The `@blocklet/did-space-js` library exports a collection of utility functions designed to simplify common tasks you'll encounter while building your application. These helpers handle operations like DID formatting, URL normalization, encoding, and error parsing, allowing you to focus on your core application logic.

You can import these utilities directly from the package:

**Import Utilities**

```typescript
import {
  toABTDid,
  toDid,
  normalizeEndpoint,
  getSpaceServiceEndpoint,
  encode,
  getErrorMessage,
  getErrorStatusCode,
} from '@blocklet/did-space-js';
```

## DID Formatting

DID Space uses DIDs with a `did:abt:` prefix. These utilities help you convert between standard DIDs and the ABT-specific format, ensuring compatibility and proper validation.

### toABTDid

Adds the `did:abt:` prefix to a valid DID string. This is useful when you need to construct a full ABT DID from a base DID.

<strong>Parameters</strong>
- **did** `string` *(required)* — A valid standard DID string.

<strong>Returns</strong>
- **abtDid** `string` — The DID string prefixed with 'did:abt:'

<strong>Example</strong>

**toABTDid Example**

```typescript
import { toABTDid } from '@blocklet/did-space-js';

const baseDid = 'z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr';
const abtDid = toABTDid(baseDid);

console.log(abtDid); // "did:abt:z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr"

try {
  toABTDid('invalid-did');
} catch (error) {
  console.error(error.message); // "did(invalid-did) is not a valid did"
}
```

### toDid

Removes the `did:abt:` prefix from a DID string, returning the base DID. It also validates that the resulting string is a valid DID.

<strong>Parameters</strong>
- **did** `string` *(required)* — A DID string, typically with the 'did:abt:' prefix.

<strong>Returns</strong>
- **baseDid** `string` — The base DID string without the prefix.

<strong>Example</strong>

**toDid Example**

```typescript
import { toDid } from '@blocklet/did-space-js';

const abtDid = 'did:abt:z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr';
const baseDid = toDid(abtDid);

console.log(baseDid); // "z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr"

try {
  toDid('did:abt:invalid-did');
} catch (error) {
  console.error(error.message); // "did(invalid-did) is not a valid did"
}
```

## Endpoint & URL Utilities

These functions help you manage and resolve the endpoints required to communicate with a DID Space.

### normalizeEndpoint

Cleans up a DID Space endpoint URL by removing query parameters and any trailing `/object/` segment. This ensures you have a consistent base URL for API calls.

<strong>Parameters</strong>
- **endpoint** `string` *(required)* — A full DID Space endpoint URL.

<strong>Returns</strong>
- **normalizedEndpoint** `string` — The cleaned-up base endpoint URL.

<strong>Example</strong>

**normalizeEndpoint Example**

```typescript
import { normalizeEndpoint } from '@blocklet/did-space-js';

const fullEndpoint =
  'https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/object/?some=query';
const normalized = normalizeEndpoint(fullEndpoint);

console.log(normalized); // "https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/"
```

### getSpaceServiceEndpoint

Resolves the actual service endpoint for a given DID Space. Some spaces may use a gateway URL that redirects to a different service URL for file operations. This function handles that resolution for you.

<strong>Parameters</strong>
- **normalizedEndpoint** `string` *(required)* — A normalized DID Space endpoint URL, typically from normalizeEndpoint.
- **defaultValue** `string` — A fallback value to return if the endpoint cannot be resolved. Defaults to the normalizedEndpoint itself.

<strong>Returns</strong>
- **serviceEndpoint** `Promise<string>` — A promise that resolves to the actual service endpoint URL.

<strong>Example</strong>

**getSpaceServiceEndpoint Example**

```typescript
import { getSpaceServiceEndpoint } from '@blocklet/did-space-js';

async function resolveEndpoint(endpoint: string) {
  const serviceEndpoint = await getSpaceServiceEndpoint(endpoint);
  console.log(`Service URL for ${endpoint} is ${serviceEndpoint}`);
}

const spaceUrl =
  'https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/';
resolveEndpoint(spaceUrl);
```

## Encoding

### encode

Encodes a string into a URL-safe Base64 format. This is particularly useful for encoding file paths or keys that will be used in a URL, ensuring that special characters do not cause issues.

<strong>Parameters</strong>
- **key** `string` *(required)* — The string to be encoded, such as a file path.

<strong>Returns</strong>
- **encodedKey** `string` — The URL-safe Base64 encoded string.

<strong>Example</strong>

**encode Example**

```typescript
import { encode } from '@blocklet/did-space-js';

const filePath = 'path/to/my important file.txt';
const encodedPath = encode(filePath);

console.log(encodedPath); // "cGF0aC90by9teSBpbXBvcnRhbnQgZmlsZS50eHQ"
```

## Error Handling

When an API call fails, the SDK throws an error. These utility functions help you parse the error object to extract a human-readable message and the HTTP status code, simplifying your error handling logic.

### getErrorMessage

Extracts the most relevant error message from various types of error objects that can be thrown by the underlying HTTP client (`got`).

<strong>Parameters</strong>
- **error** `Error | RequestError` *(required)* — The error object caught in a catch block.

<strong>Returns</strong>
- **errorMessage** `string` — A user-friendly error message.

### getErrorStatusCode

Extracts the HTTP status code from an HTTP error object.

<strong>Parameters</strong>
- **error** `HTTPError` *(required)* — The error object caught in a catch block.

<strong>Returns</strong>
- **statusCode** `number` — The HTTP status code (e.g., 404, 500).

<strong>Example</strong>

**Error Handling Example**

```typescript
import { SpaceClient, GetObjectCommand } from '@blocklet/did-space-js';
import { getErrorMessage, getErrorStatusCode } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function fetchNonExistentFile() {
  try {
    const command = new GetObjectCommand({ key: 'non-existent-file.txt' });
    await client.send(command);
  } catch (error) {
    const message = getErrorMessage(error);
    const statusCode = getErrorStatusCode(error);

    console.error(`Operation failed with status ${statusCode}: ${message}`);
    // Expected output might be: "Operation failed with status 404: Not Found"
  }
}

fetchNonExistentFile();
```

This example shows how to use `getErrorMessage` and `getErrorStatusCode` within a `try...catch` block to gracefully handle an API error, such as a file not being found.

With these utilities, you can handle many of the common data transformations and error-handling scenarios required when interacting with DID Space. To see how these might be used in more complex scenarios, check out the [API Reference](/en/docs/did-space-js/api-reference-c19e7c/).

---

## DID Spaces Guide

URL: https://www.arcblock.io/en/docs/did-spaces/

---

## DID Spaces UI (React)

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/

---

## API Reference

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/api-reference-01a073/

This section serves as a reference for the key TypeScript types and interfaces used as props in the `DIDSpaceConnect` and `DIDSpaceConnection` components. Understanding these data structures is essential for developers to leverage the full power of the library, ensure type safety, and correctly configure the components in a TypeScript environment.

Before diving into the types, you might want to review the [Components documentation](/en/docs/did-spaces-react-components/components-01a073/) to see how they are used in practice.

Our components rely on a set of well-defined data structures to manage state and configuration. The core types you will encounter include:

- `DIDSpaceGateway`: Represents the connection details for a specific DID Space.
- `DIDSpaceStatus`: An enum that tracks the current connection status (`CONNECTED`, `DISCONNECTED`, etc.).
- `AuthorizeConnect`: Defines the configuration for the connection authorization modal.
- `GatewayAuthOptions`: Specifies options for authenticating with a DID Space gateway.

For detailed information on each type, including all properties and their descriptions, please refer to the Types documentation.

:::action-card{title="Types" description="Dive into the detailed documentation of key data types like DIDSpaceGateway, DIDSpaceStatus, AuthorizeConnect, and other interfaces used throughout the component library's props. This is essential for robust TypeScript development." icon="file"}
::action{label="View Type Details" href="/en/docs/did-spaces-react-components/api-reference-types-01a073/" variant="primary"}
:::

After reviewing the type definitions, a great next step is to see them in action within the component examples. Return to the [Components](/en/docs/did-spaces-react-components/components-01a073/) section to apply what you've learned.

---

## Types

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/api-reference-types-01a073/

This section provides a detailed reference for the core TypeScript types and interfaces used throughout the DID Space component library. Understanding these data structures is essential for correctly typing component props and managing state in your application.

## DIDSpaceStatus

An enum representing the various connection states of a DID Space. This is used by components like `DIDSpaceConnection` to display the current status visually.

**DIDSpaceStatus Enum**

```typescript
export enum DIDSpaceStatus {
  LOADING = 'loading',
  CONNECTED = 'connected',
  DISCONNECTED = 'disconnected',
  /** Not available, related to subscription status, e.g., expired, overdue, insufficient usage, etc. */
  UNAVAILABLE = 'unavailable',
}
```

| Member  | Value  | Description  |
|---|---|---|
| `LOADING`  | `'loading'`  | The component is currently attempting to connect or fetch the space status.  |
| `CONNECTED`  | `'connected'`  | A successful and active connection to the DID Space is established.  |
| `DISCONNECTED`  | `'disconnected'`  | The component is not connected to the DID Space.  |
| `UNAVAILABLE`  | `'unavailable'`  | The DID Space cannot be accessed due to an issue like an expired subscription or insufficient usage.  |

## DIDSpaceGateway

This interface defines the structure for an object containing all the necessary information about a DID Space gateway. It is a key prop for components like `DIDSpaceConnection` to render space details.

**DIDSpaceGateway Interface**

```typescript
export interface DIDSpaceGateway {
  did: string;
  name: string;
  url: string;
  endpoint: string;
  ownerDid: string;
  protected?: boolean;
  loading?: boolean;
}
```

- **did** `string` *(required)* — The unique Decentralized Identifier (DID) of the space.
- **name** `string` *(required)* — The display name of the space.
- **url** `string` *(required)* — The base URL for the space's web interface (e.g., https://spaces.arcblock.io/app).
- **endpoint** `string` *(required)* — The API endpoint URL for interacting with the space.
- **ownerDid** `string` *(required)* — The DID of the space's owner.
- **protected** `boolean` — Indicates if the space requires authentication for access.
- **loading** `boolean` — A flag to indicate if the space data is currently being fetched.

## AuthorizeConnect

This interface defines the configuration options for the authentication modal that appears when a user initiates a connection.

**AuthorizeConnect Interface**

```typescript
export interface AuthorizeConnect {
  open: boolean;
  action: string;
  checkFn: Function;
  messages: {
    title: string;
    scan: string;
    confirm: string;
    success: React.ReactNode;
  };
  prefix?: string;
  baseUrl?: string;
  webWalletUrl?: string;
  maxIdleTime?: number;
  checkTimeout?: number;
  extraParams?: Record<string, any>;
}
```

- **open** `boolean` *(required)* — Controls the visibility of the connection modal.
- **action** `string` *(required)* — The action type for the authentication request (e.g., 'connect').
- **checkFn** `Function` *(required)* — A function used to poll or verify the authentication status.
- **messages** `object` *(required)* — Custom text and content to display in the authentication modal.
  - **title** `string` *(required)* — The title of the modal.
  - **scan** `string` *(required)* — Instructions for the scanning step.
  - **confirm** `string` *(required)* — Instructions for the confirmation step.
  - **success** `React.ReactNode` *(required)* — Content to display upon successful connection.
- **prefix** `string` — URL prefix for the DID Connect endpoint.
- **baseUrl** `string` — The base URL for the DID Connect service.
- **webWalletUrl** `string` — The URL of the web wallet to use for the connection.
- **maxIdleTime** `number` — Maximum idle time in milliseconds before the session times out.
- **checkTimeout** `number` — The timeout in milliseconds for the status check function.
- **extraParams** `Record<string, any>` — Additional parameters to include in the authentication request.

## Authentication Options

These interfaces define the options available for customizing the authentication process when connecting to a DID Space.

### BaseAuthOptions

Provides a set of common options for any authentication request, used to configure callbacks and session parameters.

**BaseAuthOptions Interface**

```typescript
export interface BaseAuthOptions {
  action?: string;
  checkFn?: Function;
  extraParams?: Record<string, string>;
  checkTimeout?: number;
  onSuccess?: (response: Record<string, string>, decrypt: Function) => Promise<void>;
  onClose?: () => void;
}
```

- **action** `string` — The specific action for the authentication request (e.g., 'login').
- **checkFn** `Function` — A custom function to poll or verify the authentication status.
- **extraParams** `Record<string, string>` — Extra parameters to include in the authentication request.
- **checkTimeout** `number` — The timeout in milliseconds for the status check function.
- **onSuccess** `Function` — A callback function that executes upon successful authentication.
- **onClose** `Function` — A callback function that executes when the authentication dialog is closed.

### GatewayAuthOptions

Extends `BaseAuthOptions` with additional properties required for connecting specifically to a DID Space gateway.

**GatewayAuthOptions Interface**

```typescript
export interface GatewayAuthOptions extends BaseAuthOptions {
  spaceDid?: string;
  spaceGatewayUrl?: string;
}
```

- **spaceDid** `string` — The DID of the target DID Space.
- **spaceGatewayUrl** `string` — The URL of the gateway for the DID Space.

This interface inherits all properties from `BaseAuthOptions`.

## Type Aliases

For convenience and backward compatibility, the following type aliases are provided. It is recommended to use the primary types in new code.

**Compatibility Aliases**

```typescript
// For compatibility
export type SpaceGateway = DIDSpaceGateway;
export const SpaceStatus = DIDSpaceStatus;
```

- `SpaceGateway` is an alias for `DIDSpaceGateway`.
- `SpaceStatus` is an alias for the `DIDSpaceStatus` enum.

## Next Steps

Now that you are familiar with the core data structures, you can explore how they are used as props in the main components:

::::card-group
::link-card{title="DIDSpaceConnect" description="Learn how to use the connection button component and its props." icon="zap" href="/en/docs/did-spaces-react-components/components-didspaceconnect-01a073/"}
::link-card{title="DIDSpaceConnection" description="See how to display the space status and information using these types." icon="check-circle" href="/en/docs/did-spaces-react-components/components-didspaceconnection-01a073/"}
::::

---

## Components

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/components-01a073/

The DID Space React library provides a set of core components to streamline the process of connecting to and interacting with DID Spaces. These components encapsulate complex logic for authentication, status checking, and data display, allowing you to build feature-rich applications with ease.

The two primary components are `DIDSpaceConnect` and `DIDSpaceConnection`.

::::card-group
:::action-card{title="DIDSpaceConnect" description="A versatile button component that handles the complete authentication and connection flow for DID Spaces. It supports various connection modes, including initial connection, reconnection, and session-based flows." icon="zap"}
::action{label="View Details" href="/en/docs/did-spaces-react-components/components-didspaceconnect-01a073/" variant="primary"}
:::
:::action-card{title="DIDSpaceConnection" description="A display card that presents essential information about a DID Space, such as its name, DID, and NFT avatar. It dynamically shows the connection status (Connected, Disconnected, Error) and provides slots for custom actions." icon="user"}
::action{label="View Details" href="/en/docs/did-spaces-react-components/components-didspaceconnection-01a073/" variant="primary"}
:::
::::

## How They Work Together

While these components can be used independently, they are designed to work powerfully together. A common pattern is to use the `DIDSpaceConnection` component to display a list of available Spaces, and embed a `DIDSpaceConnect` component within its `action` prop to provide users with a "Connect" or "Reconnect" button for each space.

This diagram illustrates a typical user interaction flow:

![Components](https://media.arcblock.io/lib/0c/0cddb9b6aad83dba.w1600.webp)

To get started, dive into the detailed documentation for each component. We recommend starting with the `DIDSpaceConnect` component to understand the connection process.

Next, learn about the [DIDSpaceConnect](/en/docs/did-spaces-react-components/components-didspaceconnect-01a073/) component in detail.

---

## DIDSpaceConnect

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/components-didspaceconnect-01a073/

The `DIDSpaceConnect` component provides a versatile button for initiating connections to a DID Space. It simplifies various authentication flows, including initial connections and reconnections, and can be integrated with a user session for persistent storage.

## How It Works

The component renders a split button that gives the user two primary ways to connect:

::::steps
:::step{title="Use Wallet"}
This initiates a connection process via the user's DID Wallet, which is the recommended and most common method.
:::

:::step{title="Use Space Gateway"}
This allows the user to manually enter the URL of their DID Space gateway to establish a connection.
:::
::::

Upon a successful connection, the component returns a `spaceGateway` object containing essential details about the connected space.

![DIDSpaceConnect](https://media.arcblock.io/lib/aa/aab8920251840b0e.w1600.webp)

## Props

The `DIDSpaceConnect` component is highly customizable through its props.

- **session** `object` — An optional session object from @arcblock/did-connect-react. If provided, the connected spaceGateway is automatically saved to the user's session, and session.refresh() is called.
- **reconnect** `boolean` (default: `false`) — If true, the component renders as a reconnect button. This mode requires spaceDid and spaceGatewayUrl to be set.
- **spaceDid** `string` — The DID of the space to reconnect to. Required when reconnect is true.
- **spaceGatewayUrl** `string` — The gateway URL of the space to reconnect to. Required when reconnect is true.
- **options** `DIDSpaceConnectOptions` — Additional options to pass to the underlying authentication process.
- **connectScope** `'user' | 'app'` (default: `'user'`) — The scope of the connection, determining how the connection is handled and stored.
- **connectText** `string | React.ReactNode` — Custom text or element to display on the main connect button.
- **onSuccess** `function` — Callback executed on successful connection. It receives an object containing spaceGateway, the raw response, and a decrypt function.
- **onError** `(error: Error) => void` — Callback executed when an error occurs during the connection process.
- **...rest** `ButtonProps` — Any other props from Material-UI's Button component are passed down to customize the button's appearance.

## Usage Scenarios

### 1. Basic Connection (Stateless)

This is the most direct use case. The component is used to establish a connection and retrieve the `spaceGateway` object via the `onSuccess` callback. The application is then responsible for managing this object.

**Demo.tsx**

```tsx
import Toast from '@arcblock/ux/lib/Toast';
import { DIDSpaceConnect, type DIDSpaceGateway } from '@blocklet/did-space-react';
import { useState } from 'react';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function Demo() {
  const [spaceGateway, setSpaceGateway] = useState<DIDSpaceGateway | null>(null);

  const handleSuccess = async ({ spaceGateway: gw }: { spaceGateway: DIDSpaceGateway }) => {
    try {
      // Store or use the spaceGateway object as needed
      setSpaceGateway(gw);
      Toast.success(`Connected to ${gw.name}`);
      console.log('Connected Space Gateway:', gw);
    } catch (error: any) {
      console.error(error);
      Toast.error(error.message);
    }
  };

  const handleDisconnect = () => {
    setSpaceGateway(null);
    Toast.info('Disconnected.');
  };

  if (spaceGateway) {
    return (
      <Box>
        <Typography>Connected to: {spaceGateway.name} ({spaceGateway.did})</Typography>
        <Button onClick={handleDisconnect} variant="outlined" sx={{ mt: 2 }}>
          Disconnect
        </Button>
      </Box>
    );
  }

  return <DIDSpaceConnect onSuccess={handleSuccess} variant="contained" />;
}
```

### 2. Connecting and Saving to User Session

By providing the `session` prop, the component will automatically save the connection details to the user's session upon a successful connection and then trigger a session refresh. This is the recommended approach for applications with user accounts.

**SessionDemo.tsx**

```tsx
import { DIDSpaceConnect } from '@blocklet/did-space-react';
import { useSessionContext } from '@arcblock/did-connect-react';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function SessionDemo() {
  const session = useSessionContext();

  // The user's connected space will be available in session.user.didSpace
  const connectedSpace = session.user?.didSpace;

  if (connectedSpace) {
    return (
      <Box>
        <Typography variant="h6">Welcome, {session.user.name}!</Typography>
        <Typography>Your connected space is: {connectedSpace.name}</Typography>
        <Typography variant="caption">DID: {connectedSpace.did}</Typography>
      </Box>
    );
  }

  return (
    <div>
      <p>You have not connected a DID Space yet.</p>
      <DIDSpaceConnect session={session} variant="contained" />
    </div>
  );
}
```

### 3. Reconnecting to a Previously Linked Space

If a user has already connected a DID Space (e.g., stored in their session), you can provide a way for them to re-establish a connection. Set the `reconnect` prop to `true` and provide the `spaceDid` and `spaceGatewayUrl` from the stored connection details. The component will render a dedicated reconnect button.

**ReconnectDemo.tsx**

```tsx
import { DIDSpaceConnect } from '@blocklet/did-space-react';
import { useSessionContext } from '@arcblock/did-connect-react';
import Toast from '@arcblock/ux/lib/Toast';
import { useState } from 'react';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function ReconnectDemo() {
  const session = useSessionContext();
  const { did, url } = session.user?.didSpace ?? {};
  const [isConnected, setIsConnected] = useState(true); // Assume initially connected

  const handleSuccess = () => {
    setIsConnected(true);
    Toast.success('Successfully reconnected!');
  };

  const handleDisconnect = () => {
    // In a real app, you would clear the invalid session/token here
    setIsConnected(false);
    Toast.info('Connection lost. Please reconnect.');
  };

  if (!did || !url) {
    // If no space is linked, show the initial connection button instead.
    return <DIDSpaceConnect session={session} variant="contained" />;
  }

  if (!isConnected) {
    return (
      <Box>
        <Typography color="error">Connection to {did} has been lost.</Typography>
        <DIDSpaceConnect
          reconnect
          spaceDid={did}
          spaceGatewayUrl={url}
          session={session}
          onSuccess={handleSuccess}
          onError={(err) => Toast.error(`Reconnection failed: ${err.message}`)}
          variant="outlined"
          sx={{ mt: 1 }}
        />
      </Box>
    );
  }

  return (
    <Box>
      <Typography color="primary">Connected to space: {did}</Typography>
      <Button onClick={handleDisconnect} variant="text" color="warning" sx={{ mt: 1 }}>
        Simulate Disconnect
      </Button>
    </Box>
  );
}
```

## Next Steps

After establishing a connection, you'll likely want to display information about the connected DID Space. The `DIDSpaceConnection` component is designed for this purpose.

:::action-card{title="DIDSpaceConnection" description="A display card that shows information and connection status for a DID Space, with options for customization." icon="zap"}
::action{label="View Component" href="/en/docs/did-spaces-react-components/components-didspaceconnection-01a073/" variant="primary"}
:::

---

## DIDSpaceConnection

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/components-didspaceconnection-01a073/

The `DIDSpaceConnection` component is a versatile UI card designed to display key information about a connected DID Space. It provides a clear and interactive way to present the space's details, including its NFT avatar, name, DID, and current connection status.

This component is highly customizable, allowing you to add custom actions and footer content to tailor the user experience to your application's needs.

## Props

- **endpoint** `string` *(required)* — The API endpoint URL for the DID Space object. Example: https://example.com/app/api/space/{spaceDid}/app/{appDid}/object/.
- **selected** `boolean` (default: `false`) — If true, the card will have a highlight border and display the connection status.
- **compat** `boolean` — If true, enforces a compact layout. If undefined, it automatically switches to a compact layout on mobile devices.
- **action** `React.ReactNode | ((props: DIDSpaceConnectionContext) => React.ReactNode)` (default: `null`) — Custom content or a component to render in the action area of the card.
- **footer** `boolean | React.ReactNode | ((props: DIDSpaceConnectionContext & { originalFooter: React.ReactNode }) => React.ReactNode)` (default: `false`) — Custom content for the footer. If set to true, it displays the latest audit log by default.
- **deps** `any[]` (default: `[]`) — An array of dependencies that, when changed, will trigger a refresh of the DID Space information.

### Context Types

When using function props for `action` or `footer`, you receive a context object with the following shape:

<strong>DIDSpaceConnectionContext</strong>

- **spaceGateway** `DIDSpaceGateway` *(required)* — Contains essential information about the connected DID Space.
- **spaceStatus** `DIDSpaceStatus` *(required)* — The current connection status of the DID Space.
- **errorCode** `number` *(required)* — A specific error code if the spaceStatus is 'unavailable'.
- **selected** `boolean` *(required)* — The value of the selected prop passed to the component.
- **compat** `boolean` *(required)* — Indicates if the component is in compact mode.
- **refresh** `() => void` *(required)* — A function to manually trigger a refresh of the space information and status.

<strong>DIDSpaceGateway</strong>

- **did** `string` *(required)* — The DID of the space.
- **name** `string` *(required)* — The name of the space.
- **url** `string` *(required)* — The base URL of the DID Space gateway (e.g., https://spaces.arcblock.io).
- **endpoint** `string` *(required)* — The full object endpoint URL.
- **ownerDid** `string` *(required)* — The DID of the space owner.

<strong>DIDSpaceStatus</strong>

- **DIDSpaceStatus** `enum` — An enum representing the connection status. Possible values include: loading, connected, disconnected, unavailable.

## Basic Usage

To display a DID Space, you only need to provide the `endpoint` prop. The component will handle fetching and displaying the necessary information.

**Basic DIDSpaceConnection Example**

```tsx
import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} />;
}
```

## Usage Scenarios

### Selected State and Status

Set the `selected` prop to `true` to apply a highlight border and display the connection status. This is useful for indicating the currently active or selected DID Space in a list.

**Selected DIDSpaceConnection**

```tsx
import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected />;
}
```

### Compact Layout

Use the `compat` prop to render a more condensed version of the card, which is ideal for lists or mobile views.

**Compact DIDSpaceConnection**

```tsx
import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected compat />;
}
```

### Custom Actions

You can add custom interactive elements like buttons or links using the `action` prop. Pass a function to access the connection context, including the `spaceGateway` details and the `refresh` function.

#### Example 1: Reconnect a Disconnected Space

A common use case is to provide a way for users to reconnect if their session becomes disconnected. You can check the `spaceStatus` and render a `DIDSpaceConnect` component to initiate the reconnection flow. The `DIDSpaceConnect` component renders a button by default.

**DIDSpaceConnection with Reconnect Action**

```tsx
import { DIDSpaceConnection, DIDSpaceConnect, DIDSpaceStatus } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      action={({ spaceStatus, spaceGateway, refresh }) => {
        if (spaceStatus === DIDSpaceStatus.DISCONNECTED) {
          return (
            <DIDSpaceConnect
              reconnect
              spaceDid={spaceGateway.did}
              spaceGatewayUrl={spaceGateway.url}
              onSuccess={refresh} // Refresh the card after successful reconnection
            />
          );
        }
        return null;
      }}
    />
  );
}
```

#### Example 2: Open DID Space Site

This example adds an icon button that links to the DID Space's public page.

**DIDSpaceConnection with Custom Action**

```tsx
import { DIDSpaceConnection } from '@blocklet/did-space-react';
import { IconButton, Link } from '@mui/material';
import OpenInNewIcon from '@mui/icons-material/OpenInNew';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      action={({ spaceGateway }) => (
        <IconButton
          size="small"
          component={Link}
          href={`${spaceGateway.url}/space/${spaceGateway.did}`}
          target="_blank"
        >
          <OpenInNewIcon />
        </IconButton>
      )}
    />
  );
}
```

### Custom Footer

The `footer` prop allows for powerful customization. You can enable the default audit log display or render completely custom content.

#### Displaying Default Audit Log

Set `footer` to `true` to automatically fetch and display the latest audit log entry for the application within that DID Space.

**DIDSpaceConnection with Audit Log Footer**

```tsx
import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected footer />;
}
```

#### Adding Custom Footer Content

Provide a function to the `footer` prop to render custom components. The function receives the connection context and the `originalFooter` (the default audit log bar), allowing you to compose your own layout.

**DIDSpaceConnection with Custom Footer Content**

```tsx
import { DIDSpaceConnection } from '@blocklet/did-space-react';
import { Box, Typography } from '@mui/material';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      footer={({ spaceGateway, originalFooter }) => (
        <>
          {/* Display the default audit log */}
          {originalFooter}
          {/* Display additional custom info */}
          <Box display="flex" alignItems="center" mt={1}>
            <Typography variant="caption">Owner: {spaceGateway.ownerDid}</Typography>
          </Box>
        </>
      )}
    />
  );
}
```

## Connection Statuses

The component visually represents the state of the connection to the DID Space. Understanding these statuses can help in debugging and providing better user feedback.

- <strong>Loading</strong>: The component is initially in a loading state while it fetches information about the DID Space. Skeleton loaders are displayed during this phase.
- <strong>Connected</strong>: Indicates a successful and active connection. The application has the necessary permissions and the DID Space is fully operational. It is displayed with a 'Connected' tag and a success icon.
- <strong>Disconnected</strong>: The application is not authorized to access the DID Space. This typically means the user needs to go through a connection flow to grant permissions. It is displayed with a 'Disconnected' tag and a neutral icon.
- <strong>Unavailable</strong>: The DID Space cannot be reached or used due to an issue. This status is shown with an error tag and icon. When unavailable, a tooltip provides more details on hover. Common reasons include:
-
  - <strong>Subscription Expired/Past Due</strong>: The subscription for the DID Space has expired.
  - <strong>Usage Limit Exceeded</strong>: The DID Space has reached its usage limits.
  - <strong>Incompatible Version</strong>: The DID Space version is not compatible with the component library's requirements.
  - <strong>CORS Blocked</strong>: A Cross-Origin Resource Sharing (CORS) error is preventing the connection. This usually requires a configuration change on the DID Space host.
  - <strong>Network Error</strong>: The component could not reach the DID Space endpoint due to a network issue like a timeout or DNS failure.

Now that you know how to display DID Space information, you may want to dive deeper into the data structures used by the components. For more details, please see the [API Reference for Types](/en/docs/did-spaces-react-components/api-reference-types-01a073/).

---

## Getting Started

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/getting-started-01a073/

This guide will walk you through the essential steps to integrate DID Space functionality into your React application. You'll learn how to install the necessary package and implement a basic component that allows users to connect to their DID Space and view its details.

## Step 1: Installation

First, you need to add the `@blocklet/did-space-react` package to your project. You can do this using npm or your preferred package manager.

**Terminal**

```bash
npm install @blocklet/did-space-react
```

## Step 2: Create a Connection Component

Now, let's create a simple React component that demonstrates the core functionality. This example will use the `DIDSpaceConnect` component to establish a connection and the `DIDSpaceConnection` component to display the space's information once connected.

We will use React's `useState` hook to manage the connection state.

**GettingStartedExample.tsx**

```tsx
import React, { useState } from 'react';
import Toast from '@arcblock/ux/lib/Toast';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';
import { DIDSpaceConnect, DIDSpaceConnection, type DIDSpaceGateway } from '@blocklet/did-space-react';

// A helper function to format errors
const formatError = (error: any): string => {
  return error.message || 'An unknown error occurred.';
};

export default function GettingStartedExample() {
  const [spaceGateway, setSpaceGateway] = useState<DIDSpaceGateway | null>(null);

  const handleSuccess = async ({ spaceGateway: gateway }: { spaceGateway: DIDSpaceGateway }) => {
    try {
      console.log('Successfully connected to DID Space:', gateway);
      setSpaceGateway(gateway);
      Toast.success('Successfully connected to DID Space!');
    } catch (error) {
      console.error(error);
      Toast.error(formatError(error));
    }
  };

  const handleError = (error: Error) => {
    console.error('Connection failed:', error);
    Toast.error(formatError(error));
  };

  const handleDisconnect = () => {
    setSpaceGateway(null);
    Toast.info('Disconnected from DID Space.');
  };

  return (
    <Box sx={{ padding: 2, border: '1px solid #e0e0e0', borderRadius: '8px' }}>
      <Typography variant="h6" gutterBottom>
        DID Space Connection
      </Typography>
      {spaceGateway ? (
        <Box>
          <DIDSpaceConnection endpoint={spaceGateway.endpoint} selected sx={{ marginBottom: 2 }} />
          <Button onClick={handleDisconnect} variant="outlined">
            Disconnect
          </Button>
        </Box>
      ) : (
        <DIDSpaceConnect
          onSuccess={handleSuccess}
          onError={handleError}
          variant="contained"
        />
      )}
    </Box>
  );
}
```

### How It Works

::::steps
:::step{title="State Management"}
We use `useState<DIDSpaceGateway | null>(null)` to keep track of the connected DID Space. Initially, it's `null`, indicating no connection.
:::

:::step{title="Connecting"}
The `DIDSpaceConnect` component renders a button. When a user clicks it and successfully connects, the `onSuccess` callback is triggered. This callback receives a `spaceGateway` object containing details about the user's DID Space.
:::

:::step{title="Updating State"}
Inside `handleSuccess`, we call `setSpaceGateway(gateway)` to store the connection details in our component's state. This causes the component to re-render.
:::

:::step{title="Displaying Information"}
After the re-render, the `spaceGateway` state is no longer `null`. The component now displays the `DIDSpaceConnection` card, passing the `endpoint` from our `spaceGateway` object. This card fetches and shows the DID Space's name, DID, and connection status.
:::

:::step{title="Disconnecting"}
We've added a "Disconnect" button that resets the state to `null`, which brings the `DIDSpaceConnect` button back, allowing the user to connect to another space.
:::
::::

## Next Steps

You have now implemented a basic DID Space connection flow. To explore more advanced features and customizations, proceed to the detailed component documentation.

::::card-group
::link-card{title="DIDSpaceConnect" description="Learn about all the props and usage scenarios for the connection button, including session management and reconnection flows." icon="zap" href="/en/docs/did-spaces-react-components/components-didspaceconnect-01a073/"}
::link-card{title="DIDSpaceConnection" description="Discover how to customize the display card with custom actions, footers, and different layouts." icon="credit-card" href="/en/docs/did-spaces-react-components/components-didspaceconnection-01a073/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/did-spaces-react-components/overview-01a073/

Welcome to the documentation for `@blocklet/did-space-react`. This library provides a set of React components designed to streamline the integration of DID Space into your applications. With these tools, you can effortlessly enable users to connect their DID Space and display relevant information, creating a seamless and decentralized user experience.

The primary goal of this package is to abstract away the complexities of DID Space interactions, offering simple, reusable components that handle connection flows, data display, and status updates.

## Core Components

This package is built around two central components that cover the essential functionalities for DID Space integration:

::::card-group
::link-card{title="DIDSpaceConnect" description="A button component that initiates the connection process to a DID Space. It manages authentication flows and handles both initial connections and reconnections for users." icon="zap"}
::link-card{title="DIDSpaceConnection" description="A versatile display card for showcasing the details of a connected DID Space, including its name, DID, connection status, and other relevant information. It is designed to be easily customizable." icon="user"}
::::

## How It Works

The components work together to provide a complete user journey. The `DIDSpaceConnect` component handles the authentication and connection logic, while the `DIDSpaceConnection` component visualizes the result of that connection.

![Overview](https://media.arcblock.io/lib/1f/1f33bf7c0d8b1484.w1600.webp)

## Key Features

- <strong>Simplified Integration</strong>: Get up and running quickly with minimal configuration.
- <strong>Built-in UI</strong>: Provides ready-to-use components for connection and display, saving development time.
- <strong>Flexible & Customizable</strong>: Easily tailor the appearance and functionality of components, such as adding custom action buttons or footer content to the `DIDSpaceConnection` card.
- <strong>Session-Aware</strong>: Automatically associates the connected DID Space with the user's session, simplifying data persistence.
- <strong>Responsive Design</strong>: Components are designed to work seamlessly across both desktop and mobile devices.

## Next Steps

Now that you have an overview of what `@blocklet/did-space-react` offers, you're ready to start building. Head over to the [Getting Started](/en/docs/did-spaces-react-components/getting-started-01a073/) guide for a step-by-step tutorial on installing the package and implementing your first DID Space connection.

---

## Prod Spaces data retention policy updated

URL: https://www.arcblock.io/en/docs/did-spaces/3ZzoUtM8foAlyYGxINj0E70i/

Welcome to the ArcBlock community! Here, we are committed to providing you with a platform to share insights, report issues, seek help, and inspire innovation. To optimize resources and continue to provide high-quality services, we plan to start managing data retention for expired DID Spaces on [Prod Spaces site](https://www.didspaces.com/en) that have been expired for over six months from 12:00 AM on December 1, 2024 (UTC time). Specifically, expired DID Spaces that have not been renewed for over six months will enter an automatic cleaning process, and they will not be recoverable at that time.

To ensure that your experience on the Prod Spaces site is not affected, please pay attention to the following points:

1. Check the expiry date of DID Space: Please check the expiry date of the DID Space service you purchased to ensure necessary [renewal](/en/docs/did-spaces/how-to-resubscribe-did-space/) is completed before December 1, 2024 to prevent your data from being purged.
2. Renewal Reminder: If you need to continue using the expired DID Space, please be sure to complete [Renewal](/en/docs/did-spaces/how-to-resubscribe-did-space/) by December 1, 2024.
3. Data Backup: If you no longer continue your subscription, please make sure to back up the data you need to keep to avoid data loss.
4. Stay connected: Stay tuned for notifications and announcements from the ArcBlock community for the latest information and support.

If you have any questions or need further assistance, please feel free to ask in the community or contact our support team. We are more than happy to help you!

[ArcBlock Community](https://community.arcblock.io/?locale=en)

---

## AIGNE

URL: https://www.arcblock.io/en/docs/did-spaces/ai-studio-case/

## Scenario

AIGNE is an AI application for creating prompt templates.

While AIGNE supports importing and synchronizing projects with GitHub, this process can be challenging for non-technical users. To simplify workflows, AIGNE now integrates with DID Spaces. Upon initial login, users will be prompted to provide a DID Space, which will then be used to store and synchronize project data. This also enables project data to be imported from the designated DID Space into other AIGNE instances.

## Solutions

- Upon first launching the application, users are prompted to connect to their DID Space. See [Obtaining the DID Space Endpoint During the Installation and Startup Process](/zh/docs/did-spaces/VICtqBi2LhykP4g54S7nEwqB/)
- Access DID Spaces using [@blocklet/did-space-js](https://www.npmjs.com/package/@blocklet/did-space-js?activeTab=readme). See [Use @blocklet/did-space-js to read and write DID Space](/zh/docs/did-spaces/24293819-b746-4ae1-89be-07e9477b04f9/)

## Showcase

- First login requires connecting to a DID Space.

When first logging in to AIGNE, users must connect to a DID Space:

<video src="https://media.arcblock.io/lib/24/2475b1d3bd33351fdf8bb1b50c682b16.mp4" controls></video>

- Sync with DID Spaces

When saving data, users can choose to automatically synchronize project data to their DID Space or synchronize it manually.

![image.png](https://media.arcblock.io/lib/51/51e68d76fe8beb927f3f94a87ccdc827.w1600.webp)

- Import project from DID Spaces

When you click import, select the DID Space source you wish to import and follow the instructions to complete the import process.

<video src="https://media.arcblock.io/lib/93/930a53fcfba93226ef52083a0f046690.mp4" controls></video>

---

## Application Example

URL: https://www.arcblock.io/en/docs/did-spaces/app-examples/

To help developers understand how to integrate DID Spaces and ensure they function correctly, we have prepared the following examples.

- [Todo List --> 待办事项列表](/en/docs/did-spaces/todo-list-example/)

---

## DID Spaces v0.5.83: OAuth integrated DID Space

URL: https://www.arcblock.io/en/docs/did-spaces/aVNIUFvC_7I86v8b4VF9EADk/

The updates introduce the following new features:

- <strong>OAuth Account Integration in DID Space</strong>
- <strong>Supports the display of data in specific domains (NFT/Passport/Profile)</strong>
- <strong>Launch of the front-end component for DID Spaces: @blocklet/did-space-react</strong>

Additionally, there are some enhancements and adjustments made in response to community feedback.

## New Features

- <strong>OAuth Account Integration with DID Space</strong>

OAuth accounts can now present DID Space without needing to rely on a DID Wallet, streamlining your service experience for greater convenience and efficiency. (Known limitation: In Prod Spaces, OAuth accounts cannot initiate a bind with a DID Wallet. However, you can still use a DID Wallet to bind an OAuth account that hasn't logged into Prod Spaces yet.)

-
  - New users showcase their DID Space in Aigne

<video src="https://media.arcblock.io/lib/ba/ba9ad0c586e87680ad896227f6cd5127.mp4" controls></video>

-
  - Provide DID Space for application backup

<video src="https://media.arcblock.io/lib/bf/bf65aa2dc00bf96bce7ec89f3877c6eb.mp4" controls></video>

- <strong>Supports displaying data in specific domains (NFT/Passport/Profile)</strong>

In the latest version, we'll tailor the presentation of NFTs, passports, and profiles stored within your DID Space. These will be featured on the Overview page of the Space:

![image.png](https://media.arcblock.io/lib/23/23cd558b61f08e9a18430e4be80e4936.w1600.webp)

will also be shown on the app's Overview page:

![image.png](https://media.arcblock.io/lib/7b/7bf1a3a0453a74f9df012012381febff.w1600.webp)

Additionally, we provide support for developers to write these templates using the SDK. For more details, please refer to: [PutPreviewObjectCommand](/zh/docs/did-spaces/13RBPjH225hSwZ6s-R1Zs1vF/)

- <strong>Frontend Components for Releasing DID Spaces</strong> [<strong>@blocklet/did-space-react</strong>](https://www.npmjs.com/package/@blocklet/did-space-react)

To provide a better display of DID Space status information, we have introduced the front-end component <strong>@blocklet/did-space-react</strong>. For more details on usage, please refer to: [https://www.npmjs.com/package/@blocklet/did-space-react?activeTab=readme](https://www.npmjs.com/package/@blocklet/did-space-react?activeTab=readme)

![image.png](https://media.arcblock.io/lib/77/77c3cbc246ba09d58e336be8e82e57a5.w1600.webp)

## Enhancements

- <strong>An Enhanced Connection Experience</strong>
-
  - Automatic backups will be halted if an error occurs during the subscription process.
  - When encountering connection issues with DID Spaces, offer more detailed prompts to guide users towards resolution, for example:

![image.png](https://media.arcblock.io/lib/c2/c29abf5d5b2ce9a65027dcb2fc3b652c.w1600.webp)

![image.png](https://media.arcblock.io/lib/61/617fda12036dbbd8c6017882cc59f088.w1600.webp)

![image.png](https://media.arcblock.io/lib/11/118a14d300a158840023493b9ecbe81e.w1600.webp)

- <strong>NPM package name change:</strong> [<strong>@did-space/client</strong>](https://www.npmjs.com/package/@did-space/client) <strong>has been renamed to</strong> [<strong>@blocklet/did-space-js</strong>](https://www.npmjs.com/package/@blocklet/did-space-js)

To ensure more consistent management of official package names on NPM, we have renamed the former @did-space/client to @blocklet/did-space-js. If you're currently using @did-space/client, please transition to @blocklet/did-space-js at your earliest convenience.

- <strong>Enhancing the Query Performance of Application Audit Logs</strong>

We have optimized the internal storage structure for application audit logs, greatly boosting query performance.

## Repair

- <strong>Community Feedback on the Issue of Failing to Open a New Window on iOS Devices</strong>

We place great importance on feedback from the community. Recently, we addressed and resolved the issue with iOS devices where new windows could not be opened when restoring applications[ promptly after receiving reports.](https://community.arcblock.io/discussions/523780f6-2298-4dfb-9e6e-6b5dda2c67ee#c29575da-fcba-4152-955b-5a0c9c42c904)

## Join the Bug Bounty Program to help us enhance our platform

If you have any needs, suggestions, or questions while using our services, please visit the [ArcBlock Community](https://community.arcblock.io/) to provide feedback. We will make every effort to assist you. Additionally, you can join our Bug Bounty program to help us enhance the product experience of DID Spaces.

[ArcBlock 202412 Bug Bounty](https://community.arcblock.io/earn/activity/518711772660629504)

---

## Reading and Writing to DID Space Using @blocklet/did-space-js

URL: https://www.arcblock.io/en/docs/did-spaces/backup-blocklet/

## Overview

Most applications generally require the ability to read and write user data stored on DID Spaces. By first obtaining a DID Space's endpoint and then integrating the [@blocklet/did-space-js](https://www.npmjs.com/package/@blocklet/did-space-js?activeTab=readme) SDK, developers can effortlessly perform these read and write operations on the DID Space.

## Prerequisites

- You now understand how to guide users in connecting to DID Spaces within your application and successfully obtaining the DID Space endpoint. Refer to:[Get the endpoint of DID Space](/en/docs/did-spaces/connect-to-did-spaces/)

## Code Example

You can create a to-do list template integrated with DID Spaces by running the `blocklet create` command locally. Alternatively, you can refer to the code repository: [https://github.com/blocklet/create-blocklet/tree/main/packages/create-app/templates/todo-list-example](https://github.com/blocklet/create-blocklet/tree/main/packages/create-app/templates/todo-list-example).

```javascript
╰─➤  blocklet create
blocklet create v1.16.37-beta-20250108-010153-e4bcd256
Need to install the following packages:
create-blocklet@0.9.14
Ok to proceed? (y) y

(node:82979) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)

                 Powered By
     _             ____  _            _
    / \   _ __ ___| __ )| | ___   ___| | __
   / _ \ | '__/ __|  _ \| |/ _ \ / __| |/ /
  / ___ \| | | (__| |_) | | (_) | (__|   <
 /_/   \_\_|  \___|____/|_|\___/ \___|_|\_\

            Create Blocklet v0.9.14

✔ Project name: … todo-list
? Choose one or more blocklet templates: ›
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  [dapp] react + express.js
◯  [dapp] react + express + typescript
◯  [dapp: did-wallet] Full stack app (react.js + express.js) with DID Wallet integration
◉  [dapp: todo-list] react + express + typescript + DID Spaces // select did spaces template
◯  [dapp: did-connect] Full stack app (react.js + express.js) with DID Connect integration
◯  [dapp] solid + express.js
◯  [dapp] vue3 + express.js
◯  [dapp] svelte + express.js
◯  [static] react
◯  [static] solidjs
```

## Workflow

### Install @blocklet/did-space-js

```javascript
yarn add @blocklet/did-space-js
// pnpm install @blocklet/did-space-js
// npm install @blocklet/did-space-js
```

### Write Data

Using the following code, you can write data to the user's DID Space:

```javascript
  const { SpaceClient, PutObjectCommand } = require('@blocklet/did-space-js');

  const spaceClient = new SpaceClient({
    endpoint,
    wallet,
  });

  await spaceClient.send(
    new PutObjectCommand({
      key: 'test.txt',
      data: 'hello world!',
    })
  );
```

Once the data has been successfully written, you can navigate to the root directory of the application's component (<strong>z8iZmWXt56EZqA5Y2VcmUX6qFhZaj5w7pFQx9</strong>) on DID Space to view the recently recorded data:

![image.png](https://media.arcblock.io/lib/ef/ef05bab5661722a85a107a42002ed1fb.w1600.webp)

### Read Data

Using the following code, you can read user data from DID Space:

```javascript
  const { SpaceClient, GetObjectCommand } = require('@blocklet/did-space-js');

  const spaceClient = new SpaceClient({
    endpoint, // DID Space endpoint
    wallet, // Blocklet Wallet
  });

  const { data } = await spaceClient.send(
    new GetObjectCommand({
      key: 'test.txt',
    })
  );

  console.log(await streamToString(data)); // 'hello world!'
```

After the data is successfully read, a data object will be returned. You can then use this object to access the data.

### Delete Data

Using the following code, you can delete user data from DID Space:

```javascript
  const { SpaceClient, DeleteObjectCommand } = require('@blocklet/did-space-js');

  const spaceClient = new SpaceClient({
    endpoint,
    wallet,
  });

  await spaceClient.send(
    new DeleteObjectCommand({
      key: 'test.txt',
    })
  );
```

## More

For more on its usage, please refer to [https://www.arcblock.io/docs/did-space-js](https://www.arcblock.io/docs/did-space-js).

---

## Backup Blocklet to DID Space.

URL: https://www.arcblock.io/en/docs/did-spaces/backup-to-did-space/

## Overview

Data is often an application's most valuable asset. To protect this data and enable seamless migration between different Serverless environments or Blocklet Servers, you can back up an entire Blocklet to DID Spaces and restore it as needed.

## Prerequisites

- A usable DID Space can be obtained by [obtaining a DID Space](/en/docs/did-spaces/buy-a-did-space/)

## Sign in to your app

Visit your application homepage, click the icon in the top right corner, and log in as either Owner or Admin.

![image.png](https://media.arcblock.io/lib/62/6258f909235f76e53f3d3fbfcc19ad6e.w1600.webp)

After successfully logging in, click the user avatar in the upper right corner, and then click <strong>Dashboard</strong> to access the user management interface.

![image.png](https://media.arcblock.io/lib/22/22b9784e6a477030a7b3093348810f25.w1600.webp)

Click the <strong>Dashboard</strong> on the left, then the <strong>DID Spaces</strong> tab. This is where you configure application backups.

![image.png](https://media.arcblock.io/lib/2e/2edd73c973ec4aa959aba071e4180402.w1600.webp)

## Back Up Your App

Click **Connect with DID Wallet** in the upper right corner to connect your DID Space. Confirm to authorize.

![image.png](https://media.arcblock.io/lib/ba/ba61662e2e4aea7abdab7141afdc93ee.w1600.webp)

After a successful connection, you can click the **Backup Now** button to create a backup immediately:

![image.png](https://media.arcblock.io/lib/09/093791f223d0504b1f3323a942306b31.w1600.webp)

You can also enable automatic backups. By default, the application triggers a backup every two hours. A backup is also triggered one minute after any change in application status (such as starting, stopping, or modifying configurations).

![image.png](https://media.arcblock.io/lib/15/158136d3e69136bad48cbaa2dbc44978.w1600.webp)

---

## Get DID Space

URL: https://www.arcblock.io/en/docs/did-spaces/buy-a-did-space/

## Overview

To use DID Spaces services, you must have a DID Space. You can obtain a free DID Space directly from [DID Spaces](https://www.didspaces.com/) or install a decentralized Personal DID Spaces instance to create your own.

## Claim Your DID Space

You can get a DID Space through the following methods:

- [Receive DID Space for free](/en/docs/did-spaces/get-did-spaces-for-free/)

- [Create a DID Space by installing Personal DID Spaces.](/en/docs/did-spaces/get-did-space-by-personal/)

---

## Get the endpoint of the DID Space when logging into the application for the first time.

URL: https://www.arcblock.io/en/docs/did-spaces/connect-did-space-on-login/

## Overview

When you want the application to store each user's data in their respective DID Space, you can configure it to require users to connect their DID Space upon first login and authorize the application to access it.

## Prerequisites

- Ensure you have a DID Space available for debugging. If not, refer to [Get a DID Space](/zh/docs/did-spaces/UZBBuVlRcxHY8wppr7S7iwYI/).
- Your app's `blocklet.yml` configuration file sets the `capabilities.didSpace` property to `requiredOnConnect`. This means users must provide their DID Space to log in.

## Procedure

### Users are required to connect their DID Space.

When users first log in to your application, they must present their DID Space NFT to access their DID Space.

![image.png](https://media.arcblock.io/lib/79/79a46228c935bd7e7983beb94e3ac67e.w1600.webp)

After successfully connecting to their DID Space, users can access it by clicking their avatar in the upper right corner, then clicking DID Spaces.

![image.png](https://media.arcblock.io/lib/6e/6e88f745d199c7986a8f5248d6f75d40.w1600.webp)

![image.png](https://media.arcblock.io/lib/be/bec11a9d3d71efba3e930993c507f68a.w1600.webp)

### Applications retrieve the user's DID Space endpoint

During application runtime, the user's DID Space endpoint can be retrieved with the following backend code:

```javascript
const AuthService = require('@blocklet/sdk/service/auth');

const authService = new AuthService();
const { user } = await authService.getUser(userDid);

console.log(user.didSpace.endpoint);
// 输出形如: https://space.team.arcblock.io/app/api/space/zNKhe8jwgNZX2z7ZUfwNddNECxSe3wyg7VtS/app/zNKfEK9actwBeLhfVvc9U1p1CqVWxtivVxo6/object/
```

After retrieving the DID Space endpoint, your application can read and write data within this DID Space. For more information, see: [Using @blocklet/did-space-js to read and write DID Space.](/zh/docs/did-spaces/24293819-b746-4ae1-89be-07e9477b04f9/)

---

## Get the endpoint of DID Space

URL: https://www.arcblock.io/en/docs/did-spaces/connect-to-did-spaces/

## Overview

To enable applications to read and write data to a user's DID Space, the user must first authorize the application to connect to their DID Space and provide the corresponding endpoint. Applications can only access data within a user's DID Space via this endpoint.

## Subject

You can access a user's DID Space and retrieve its endpoint using the following steps.

- [Get the endpoint of the DID Space during the installation startup process.](/en/docs/did-spaces/connect-to-did-spaces-on-setup/)

- [Get the endpoint of the DID Space when logging into the application for the first time.](/en/docs/did-spaces/connect-did-space-on-login/)

---

## Get the endpoint of the DID Space during the installation startup process.

URL: https://www.arcblock.io/en/docs/did-spaces/connect-to-did-spaces-on-setup/

## Overview

If you want your application to store all data in a specific DID Space (typically the owner's DID Space) upon installation and startup, this tutorial will guide you through the process.

A prime example of this DID Spaces connection method is [NFT Maker](https://store.blocklet.dev/blocklets/z8ia2birZzhjbXqKnxPUUivmqErdsf3724tr6?tab=info).  NFT Maker connects to DID Spaces during its installation and startup process, obtaining the endpoint of the owner's DID Space. All NFTs subsequently generated on the NFT Maker platform are stored in this DID Space.

## Prerequisites

- Ensure you have a DID Space available for testing. If you don't, you can [get one](/en/docs/did-spaces/buy-a-did-space/).
- Your application's <strong>blocklet.yml</strong> configuration file sets `capabilities.didSpace` to `requiredOnSetup`, meaning the application requires a connection to the DID Spaces service during installation.

## Procedure

### Owner Links DID Space

During the initial setup process, the system will prompt you to connect to a DID Space. Please select the DID Space to connect to:

![image.png](https://media.arcblock.io/lib/7d/7dbc8a2e2ef77064c3be3ddcc5502c75.w1600.webp)

After the connection is successful, click Continue. The installation is complete.

![image.png](https://media.arcblock.io/lib/89/89572a27edf4d09014f31bdd2b79d338.w1600.webp)

### Application accesses user's DID Space endpoint

Your running application can now access the DID Space endpoint via the `BLOCKLET_APP_SPACE_ENDPOINT` environment variable.  This variable will have the following format:

```javascript
console.log(process.env.BLOCKLET_APP_SPACE_ENDPOINT);
// 输出形如: https://space.team.arcblock.io/app/api/space/zNKhe8jwgNZX2z7ZUfwNddNECxSe3wyg7VtS/app/zNKfEK9actwBeLhfVvc9U1p1CqVWxtivVxo6/object/
```

After obtaining the DID Space endpoint, your application can read and write data to this DID Space. See: [Using @blocklet/did-space-js to read and write DID Space.](/en/docs/did-spaces/backup-blocklet/)

---

## Data retention policy

URL: https://www.arcblock.io/en/docs/did-spaces/data-retention-policy-uSgig/

## Overview

Since December 1, 2024, at 0:00 (UTC), in order to improve the efficiency and quality of service, expired DID Space data on [https://www.didspaces.com](https://www.didspaces.com/) that has not been renewed for more than 180 days will no longer be retained, and the data will not be recoverable.

## Scope of impact

This data retention policy only applies to DID Spaces obtained through purchase and with an expiration time of over 180 days. Even if this data is no longer retained, NFTs can still be displayed normally. Personal DID Spaces and DID Spaces obtained through DID Wallet [Free giveaway](/zh/docs/did-spaces/uFtIs6t7if6HWLwKFiCNVZ2I/) will not be affected.

## User operation guide.

If you wish to keep the data, please check the subscription status on [https://www.didspaces.com/app/space/](https://www.didspaces.com/app/space/) promptly and complete [Renewal operation](/en/docs/did-spaces/how-to-resubscribe-did-space/) as needed. If you do not need to retain the data, you can ignore it.

## Get help

We understand that any change can bring inconvenience, so our support team is always ready to help you. If you have any questions or need further assistance, please feel free to ask in the community or contact our support team directly. We are happy to assist you in transitioning smoothly to the new management strategy.

[ArcBlock Community](https://community.arcblock.io/?locale=en)

---

## Best Practices for Developers

URL: https://www.arcblock.io/en/docs/did-spaces/did-space-developer-best-practice/

Here are some guidelines for using DID Spaces.

<strong>Respect storage space.</strong> Storage space is a limited resource that users must manage effectively. Use DID Spaces to store information they create and interpret, avoiding its use for application resources or reproducible content. Minimize space consumption by carefully selecting the content to be stored.

<strong>Ensure your app functions correctly when DID Spaces is unavailable</strong>. If the user manually disconnects their space or loses connection, you don't need to display a prompt alerting them to the unavailability. However, you can subtly inform the user that changes made will not appear on other devices until the connection is restored.

<strong>Integrate your Blocklet seamlessly with DID Spaces</strong>. Users connect to DID Spaces upon login and expect Blocklets to function automatically. If you anticipate users might prefer to choose whether or not to utilize DID Spaces within your application, present a simple option upon the Blocklet's initial launch, allowing them to either process all data using DID Spaces or to bypass it entirely.

<strong>Avoid asking users which files they want to keep in DID Spaces</strong>. Most people want all their files accessible within their personal space and prefer not to manage individual documents. Consider how your Blocklet can process and present content, and try to automate file management tasks as much as possible.

<strong>Keep content up-to-date whenever possible</strong>. In a Blocklet that supports DID Spaces, providing users with access to the latest content is considered best practice. However, you need to balance this need with device storage and bandwidth limitations. If your Blocklet handles very large documents, it may be better to let users decide when to download updated content. In this case, design a mechanism to indicate within their DID Space that a document update is available. When a document is updating, provide subtle feedback if the download takes more than a few seconds.

<strong>Consequences of Deleting a Document</strong>. In DID Spaces-enabled applications, deleting a document removes it from the user's DID Space and all other devices.  Display a warning and request confirmation before deletion.

<strong>Ensure swift and straightforward conflict resolution</strong>. Aim for automatic detection and resolution of version conflicts. If automatic resolution is not feasible, provide discreet notifications to help users readily distinguish and select between conflicting versions. Ideally, conflicts should be resolved early to prevent wasted time on the incorrect version.

<strong>Include DID Space content in search results</strong>. People expect their content in personal spaces to be widely accessible and want search results to reflect this.

---

## Install the DID wallet

URL: https://www.arcblock.io/en/docs/did-spaces/did-spaces-did-wallet/

You can refer to [https://support.didwallet.io/howToDownload](https://support.didwallet.io/howToDownload) for completing the wallet download and installation.

---

## Frequently Asked Questions

URL: https://www.arcblock.io/en/docs/did-spaces/did-spaces-frequently-asked-questions/

- [Data retention policy](/en/docs/did-spaces/data-retention-policy-uSgig/)

- [Draft: Default Space How to upgrade by payment?](/en/docs/did-spaces/Hh9dckin6wJs_YQDSb_8pZ-6/)

- [How to re-subscribe to an expired DID Space](/en/docs/did-spaces/how-to-resubscribe-did-space/)

- [Connecting to the DID Space using the Gateway Address](/en/docs/did-spaces/how-to-obtain-space-gateway-url/)

- [Switch the DID Space bound to NFT Blender.](/en/docs/did-spaces/L2PAqN_1CEHciNdPE4JefSYh/)

- [The automatic backup of Blocklet is stuck, how can it be quickly restored?](/en/docs/did-spaces/how-to-repair-auto-backup/)

- [Fix CORS error when connecting DID Space](/en/docs/did-spaces/fixing-cors-errors-when-connecting-to-space/)

- [Pricing policy](/en/docs/did-spaces/pricing-policy-hhnsg/)

---

## User Guide

URL: https://www.arcblock.io/en/docs/did-spaces/did-spaces-getting-started/

## Overview

This guide explains how to obtain a DID Space and use it to back up application data and restore a Blocklet. Let’s begin.

- [Install the DID wallet](/en/docs/did-spaces/did-spaces-did-wallet/)

- [Get DID Space](/en/docs/did-spaces/buy-a-did-space/)

- [Backup Blocklet to DID Space.](/en/docs/did-spaces/backup-to-did-space/)

- [Restore Blocklet](/en/docs/did-spaces/restore-blocklet/)

- [Store the data of the DID Wallet.](/en/docs/did-spaces/MXp8eADQTiX3La3Rzg80RSC_/)

- [Store personal data](/en/docs/did-spaces/storage-your-data/)

- [The application connects to the DID Space to store and display personalized data.](/en/docs/did-spaces/plTvVwQp4m7b-q_3uJQ3aXD_/)

---

## Developer Guide

URL: https://www.arcblock.io/en/docs/did-spaces/did-spaces-how-to-guides/

## Overview

We can also allow applications to integrate with the DID Spaces service programmatically. Subject to user authorization, these applications can connect to each user's respective DID Space.

Leveraging the capabilities of [@blocklet/did-space-js](https://www.npmjs.com/package/@blocklet/did-space-js?activeTab=readme), one can read and write data in DID Space from a Node.js environment.

Leveraging the capabilities of [blocklet/did-space-react](https://www.arcblock.io/docs/did-spaces-react-components), UI development in React can be simplified.

Alternatively, you can learn more from the guide below:

- [Best Practices for Developers](/en/docs/did-spaces/did-space-developer-best-practice/)

- [Get the endpoint of DID Space](/en/docs/did-spaces/connect-to-did-spaces/)

- [Reading and Writing to DID Space Using @blocklet/did-space-js](/en/docs/did-spaces/backup-blocklet/)

- [Application Example](/en/docs/did-spaces/app-examples/)

- [Application case](/en/docs/did-spaces/xHZTKQuliZMqA_n3RBVLk7wv/)

- [MCP服务器

MCP Server](/en/docs/did-spaces/did-spaces-mcp-server/)

---

## MCP服务器  MCP Server

URL: https://www.arcblock.io/en/docs/did-spaces/did-spaces-mcp-server/

## Overview

DID Spaces supports Streamable HTTP MCP for seamless AI integration.

## My setup

MCP Desktop: Cursor

## Prerequisites

- Ensure you have your own DID Space.

## Procedure

### Configuring MCP

Log in to [https://www.didspaces.com/](https://www.didspaces.com/) and access your profile page by clicking "Profile" in the upper right corner.

![image.png](https://media.arcblock.io/lib/5d/5d04b5b7f12551d7a90c1c709c7b30f0.w1600.webp)

Select Settings

![image.png](https://media.arcblock.io/lib/ed/ed758a59dd3c48d5191312725559dbfe.w1600.webp)

Click "Generate Command," then select "Cursor" to generate the MCP command line:

![image.png](https://media.arcblock.io/lib/01/01b7e9fc2838f27ed4646e9906b59c9b.w1600.webp)

Copy the command line and paste it into your terminal to execute it:

![image.png](https://media.arcblock.io/lib/0e/0e7817882462eb85281ca394355a6575.w1600.webp)

![image.png](https://media.arcblock.io/lib/55/55c97888489e49ef6792b40ec790aa8a.w1600.webp)

Preview in Cursor:

![image.png](https://media.arcblock.io/lib/cb/cb98d095dbd7326e60c1e3cf67b5ccdb.w1600.webp)

## Integrating with @aigne/framework

If you want to integrate the DID Spaces MCP into @aigne/framework, you can refer to the [MCPAgent](/en/docs/aigne-framework/aigne-framework-concepts-mcp-agent-md/#creating-mcp-agent-from-streamablehttp-api) documentation.

---

## Welcome

URL: https://www.arcblock.io/en/docs/did-spaces/did-spaces-welcome/

## Overview

DID Spaces, the foundation of Blocklet ecosystem storage, can:

- Offering a decentralized personal space where you can freely create and manage digital assets, giving you greater freedom and control, and making your digital space more secure, private, and reliable.
- Make your digital life more convenient, secure, and organized! Support for data storage, backup, and migration is provided, along with the ability to share and interconnect space data. A wide range of applications aggregates your bookmarks, backups, notes, and health data, further enriching your digital life!

### What Does a DID Space Offer?

<strong>Your Gateway to a Personalized Digital Space</strong>: DID Spaces keeps your digital information organized.  Consolidate your personal bookmarks, wallet backups, multimedia notes, and health data, and customize the display and your homepage according to your preferences.

<strong>A Host of Apps to Enrich Your Digital Life</strong>: DID Spaces supports extensible integration protocols, allowing you to freely combine widgets and apps such as photo albums, notes, blogs, and contact lists—making your space truly your own.

<strong>Control Your Digital Space: Storage Solutions Simplified</strong>: DID Spaces supports flexible, portable storage options, including local and cloud storage, and integrates seamlessly with Blocklets and the DID ecosystem.  This provides a smooth experience for authorization, data backup, and restoration, ensuring data security and reliability.

<strong>Supports cross-organizational sharing and data interconnection</strong>: Share space data with trusted partners through DID Spaces, making multi-party collaboration easier. Examples include team projects, family management, and shared spaces for couples.

### Key Features of DID Spaces

<strong>Decentralized</strong>: Built on ArcBlock's Blocklet OS, DID Spaces offers decentralized identity (SSI/DID) and decentralized computing. Using DID Wallet, users manage access to storage and data sharing. DID Spaces preserves a full range of off-chain data, from transaction records to NFT data. This gives users complete control over their data, enabling them to migrate and grant access as needed. Data remains private unless explicitly authorized by the user.

<strong>Personalized Spaces</strong>: DID Spaces can store and display users' personal information, such as files, images, music, videos, and articles, as well as contact information and social network links, enabling easier management and sharing.

<strong>Data Security</strong>: DID Spaces store user interaction data within applications, enabling users to fully manage their personal data by restricting access permissions and defining access rules. Data is encrypted and access is strictly controlled, giving users granular control over who can access what, and providing unparalleled data privacy protection.

<strong>Composable and Extensible</strong>: DID Spaces, built with composable Blocklets, offers limitless possibilities for your digital space. Unlike traditional platforms, it seamlessly integrates with other composable applications and supports various underlying storage methods, making it the new desktop of your digital life.

#####

### Supported Features

- Back up the Blocklet (including data and the entire application state)
- Restore a Blocklet (This simplifies application migration)
- Store NFTs (persistently store user NFTs)
- Storing DID Wallet data
- Store your data
- Integrating DID Spaces
- More features are coming soon...

You can learn more about DID Spaces through the following link:

## Get Support

Having trouble? You can find assistance through the following channels:

- [FAQ](/zh/docs/did-spaces/did-spaces-frequently-asked-questions/) Find answers to frequently asked questions here.
- [https://community.arcblock.io/](https://community.arcblock.io/)This is our community forum, where you can post questions and receive support from our team.

---

## Fix CORS error when connecting DID Space

URL: https://www.arcblock.io/en/docs/did-spaces/fixing-cors-errors-when-connecting-to-space/

## Overview

When connecting to a DID Space, you may encounter CORS errors.

![image.png](https://media.arcblock.io/lib/ad/ad63e2b3c3b426f4b9c74e53db8e956e.w1600.webp)

The reason is that the target DID Space has disallowed cross-origin requests from this server. To resolve this issue, the DID Space administrator needs to modify the security configuration in the backend.

## Prerequisites

- Access to the DID Spaces Dashboard requires Owner or Admin permissions.

## Procedure

Access the DID Space console:

![image.png](https://media.arcblock.io/lib/8f/8f33eb0dcff4d6eeef434d81c9a16231.w1600.webp)

Locate the security rule configuration and the name of the currently active response header policy.

![image.png](https://media.arcblock.io/lib/5a/5aa04809e7afad590a66300e237e9e94.w1600.webp)

Open the edit page for the response header policy:

![image.png](https://media.arcblock.io/lib/47/47f6e212401a2d447b362b8604a91ad7.w1600.webp)

Configure Origin:

![image.png](https://media.arcblock.io/lib/d3/d337e394872280b2175b1fc1eaa61299.w1600.webp)

As shown above, the Origin only includes one address, and it’s not the Blocklet Server address used previously.  Consequently, connections from the Blocklet Server to the DID Space will be blocked by CORS.  We can add the Blocklet Server’s address to the Origin, or set the Origin to `*` (to allow any cross-origin requests):

![image.png](https://media.arcblock.io/lib/6d/6db0d28ae95f36411ffbe7727508fb80.w1600.webp)

You can then connect to the DID Space:

![image.png](https://media.arcblock.io/lib/a2/a26ab853c8864ea90098670a56b84b81.w1600.webp)

---

## Create a DID Space by installing Personal DID Spaces.

URL: https://www.arcblock.io/en/docs/did-spaces/get-did-space-by-personal/

## Summary

In addition to claiming a free DID Space directly from [DID Spaces](https://www.didspaces.com/), you can also set up your own Blocklet Server, install a personal, decentralized DID Space, and receive a DID Space.

## Prerequisites

- Install your own Blocklet Server,[Learn more](/zh/docs/blocklet-developer/install-blocklet-cli/)

## Set Up a Personal DID Space

### Log in to the Blocklet Server

Sign in to your Blocklet Server

![image.png](https://media.arcblock.io/lib/87/8787850f852a5e350d9066693abe38db.w1600.webp)

### Install a Blocklet

After successfully logging in to Blocklet Server, you can select **Store** in the left-hand menu and search for and install Personal DID Spaces under **Official Store**.

![image.png](https://media.arcblock.io/lib/b6/b616ec8bf64d365a5920e3b67fa354a0.w1600.webp)

Follow the installation guide to complete the installation of your personal DID Space. Upon successful installation, you will see the following page:

![image.png](https://media.arcblock.io/lib/80/807d79de9b7ff0f601095815e82dfe73.w1600.webp)

## Create a DID Space

Access the Personal DID Space you just installed and log in.

![image.png](https://media.arcblock.io/lib/ad/add6e5cea2381c44acd685dcd93799ea.w1600.webp)

We currently do not have a DID Space. Click <strong>Receive free space</strong> to create one.

![image.png](https://media.arcblock.io/lib/d7/d7763e85fba3bf3e3b41a40083212a8f.w1600.webp)

Once created, you have a functional DID Space that is decentralized and under your exclusive control.

![image.png](https://media.arcblock.io/lib/0c/0cc0e3d3b68017a0022452b34432d1c4.w1600.webp)

---

## Receive DID Space for free

URL: https://www.arcblock.io/en/docs/did-spaces/get-did-spaces-for-free/

## Overview

This article explains how to obtain a free DID Space. To help users manage their personal data more easily, ArcBlock provides a free, permanently available DID Space to every user who has installed DID Wallet.

## Prerequisites

- You have successfully installed DID Wallet. See [Install the DID wallet](/en/docs/did-spaces/did-spaces-did-wallet/)

## Procedure

After installing DID Wallet, you will automatically receive a free DID Space that you can use permanently.

You can view this DID Space by following these steps:

![image.png](https://media.arcblock.io/lib/a6/a61b9f9c856a6b507fa11be87cbeafdc.w1600.webp)

![image.png](https://media.arcblock.io/lib/2f/2f08b865c240d76fdbd7885d325e6b6a.w1600.webp)

At this point, you can access the DID Space page and manage this DID Space.

![image.png](https://media.arcblock.io/lib/05/05b89dfafbbe3aa748c92bbaf0d569bd.w1600.webp)

---

## Draft: Purchase DID Space

URL: https://www.arcblock.io/en/docs/did-spaces/gTndeHO7NRldrWuv3WV2_BjH/

## Overview

When you need to use DID Spaces services, you can purchase a DID Space on [Prod DID Spaces](https://www.didspaces.com/) or install a personal DID Space. The following explains how to purchase a DID Space on Prod DID Spaces.

## Log in to Production Spaces

Use your device to visit [Prod DID Spaces](https://www.didspaces.com/), then click the icon in the top right corner to log in.

![image.png](https://media.arcblock.io/lib/42/42df220fcaa7f33b89d55781166bb12a.w1600.webp)

## Buy a DID Space

Click the **Purchase new space** button in DID Spaces to go to the purchase page.

![image.png](https://media.arcblock.io/lib/3c/3cafefeab2c0ad4eefae2a4fcc01bfbb.w1600.webp)

Fill in the relevant information<strong>,</strong> then click <strong>Subscribe</strong> to proceed with payment.

![image.png](https://media.arcblock.io/lib/2b/2bb8366b2661d99c19a8fc15d4988341.w1600.webp)

After successful payment, the page will automatically redirect to the home page of the newly purchased DID Space. You can now begin using DID Spaces.

![image.png](https://media.arcblock.io/lib/87/876ba48221d98d0f44655d2f8e2c7b2c.w1600.webp)

---

## Reference Terminology

URL: https://www.arcblock.io/en/docs/did-spaces/Ha8x7mO69jChmW80qiqCKOWB/

## DID Spaces

When we describe the product or service, we call it DID Spaces.

## DID Space

When referring to a single user's Space, the term used is DID Space.

---

## Draft: Default Space How to upgrade by payment?

URL: https://www.arcblock.io/en/docs/did-spaces/Hh9dckin6wJs_YQDSb_8pZ-6/

> This is just a draft, to be perfected.

# Overview

Every DID user can get a Default Space by answering questions in the DID Wallet. The system will give away 10 units for each Default Space for free use. If you want to get more units, you don't have to worry. You can upgrade Default Space by paying. The system will charge based on the number of units used (the gifted units will neither disappear nor incur charges).

# Preconditions.

- You have obtained the Default Space through answering questions in DID Wallet.

# Operation Process

---

## Connecting to the DID Space using the Gateway Address

URL: https://www.arcblock.io/en/docs/did-spaces/how-to-obtain-space-gateway-url/

## Overview

You can use the DID Space gateway address to connect to your DID Space, particularly if you own multiple DID Spaces. This avoids having to select from numerous NFTs when connecting through DID Wallet.

## Prerequisites

- A DID Space ([You can purchase a DID Space or obtain one through Personal DID Spaces.](/en/docs/did-spaces/buy-a-did-space/)).

## Copy DID Space Gateway URL

Visit your DID Space site. In the overview page's upper-right corner, you'll find a copy button. Click this button to copy the DID Space gateway address.

![image.png](https://media.arcblock.io/lib/7f/7f7cb3a1f4631c5619e59e190f36153a.w1600.webp)

## Using the DID Space Gateway Address

Connect using the DID Space gateway.

![image.png](https://media.arcblock.io/lib/b4/b4e36f89d2950d35c6f23a08e838df43.w1600.webp)

Paste the copied address into the input box and click OK.

![image.png](https://media.arcblock.io/lib/dd/ddc02ebbfebeb9100241c171ec2bb637.w1600.webp)

---

## The automatic backup of Blocklet is stuck, how can it be quickly restored?

URL: https://www.arcblock.io/en/docs/did-spaces/how-to-repair-auto-backup/

# Overview

If a Blocklet backup to a DID Space is interrupted by an anomaly, preventing the scheduled backup task from completing, this article will help you quickly resolve the issue.

# Prerequisites

- Access to the Blocklet Dashboard is required.

# Procedure

## Access the Blocklet Store

We need to access the Blocklet's Dashboard, then navigate to the Storage page. There, we can confirm that the automatic backup status is indeed abnormal. Also, ensure that automatic backup is enabled (note: the following is an incorrect example).

![image.png](https://media.arcblock.io/lib/90/9076cf01dc8f7e21390f0c43ca9e118c.w1600.webp)

![image.png](https://media.arcblock.io/lib/19/1929a85eeacd6e104c7092eb8edf17ba.w1600.webp)

## Any change to a Blocklet's configuration triggers an automatic backup.

We access the Blocklet's Configuration page, make an arbitrary edit to the configuration, and confirm the change. A backup should be automatically triggered after one minute.

![image.png](https://media.arcblock.io/lib/58/5811505e3f5a90ed1a6ebe24fd05c186.w1600.webp)

## Wait for the automatic backup to trigger and verify its success.

Return to the Blocklet's Storage page. After one minute, the automatic backup should be successfully triggered.

![image.png](https://media.arcblock.io/lib/93/9329a42ed52f5a58ae3208306be5014c.w1600.webp)

The automatic backup process is now working normally.

---

## How to re-subscribe to an expired DID Space

URL: https://www.arcblock.io/en/docs/did-spaces/how-to-resubscribe-did-space/

# Overview

When your DID Space expires, its corresponding subscription is canceled. The DID Space becomes unavailable and can no longer store data.

If you wish to continue using this DID Space, you can reactivate it by resubscribing.

# Prerequisites

- Your DID Space subscription has expired.

# Procedure

## Resubscribe from the DID Space home page

Navigate to the DID Space homepage, click the tag in the upper right corner, and then click "Resubscribe." This will redirect you to the DID Space subscription purchase page.

![image.png](https://media.arcblock.io/lib/08/084b338ebf0317188b98989e4f1045a8.w1600.webp)

## Renew Subscription

On the purchase page, click Subscribe and complete the payment. The page will then redirect to the DID Space homepage.

![image.png](https://media.arcblock.io/lib/0f/0f6632d1b208bc76beec9154be467ad3.w1600.webp)

## Check DID Space Subscription Status

Your subscription status will be restored in the upper right corner of the DID Space homepage, allowing you to store your data in the DID Space.

![image.png](https://media.arcblock.io/lib/81/8189289de86118de2d1ea9354f0f7935.w1600.webp)

---

## Switch the DID Space bound to NFT Blender.

URL: https://www.arcblock.io/en/docs/did-spaces/L2PAqN_1CEHciNdPE4JefSYh/

## Overview

NFT Blender requires users to link a DID Space upon first installation and launch. All NFT data generated by the application will be stored in this DID Space.

If you want to connect NFT Studio to a different DID Space during the process, this article can help you.

## Prerequisites

- Please make sure you have installed the [NFT Blender](https://store.blocklet.dev/blocklets/z8ia1ieY5KhEC4LMRETzS5nUwD7PvAND8qkfX?server-url=https://bbqatfv33tomzgjt6oatnom3zriyvxvvjr6554whcli.did.abtnet.io/admin/) app.

## Procedure

### Access the DID Spaces configuration page

To switch DID Spaces, access the application's component interface.  Begin by clicking the avatar in the upper right corner, then select Dashboard to enter the DID Spaces configuration page.

![image.png](https://media.arcblock.io/lib/29/29b1007b717fe1f497a6ab06f841a838.w1600.webp)

### Switch DID Spaces

Under the DID Space configuration page, click the Storage section, and then click the **Connect with DID Wallet** button below to switch DID Spaces.

![image.png](https://media.arcblock.io/lib/91/91c6302094f73867a60608e0ebe22066.w1600.webp)

---

## DID Spaces v0.4.26 released: subscription fully adopts pay-as-you-go & supports paid upgrade Default Space

URL: https://www.arcblock.io/en/docs/did-spaces/MJsBv7wkBk7mIwRYfPjTJnGu/

Through the relentless efforts of engineers, DID Spaces officially released a new version v0.4.26. The main features of this update include subscription fully adopting pay-as-you-go, officially supporting paid upgrades for Default Space, and new user Default Space creation under a unified login account. There are also some improvements in user experience.

## New feature

- Subscribe to comprehensive pay-as-you-go usage.

The subscribed DID Space is fully implemented with pay-as-you-go (charged by units, for more payment details, please be sure to check our [Pricing policy](/zh/docs/did-spaces/QNgF6HmakZC2ito-JnaEK3Dv/)), and will migrate the billing method of all users' subscriptions to pay-as-you-go.

![image.png](https://media.arcblock.io/lib/45/459d820b68913fc07c88df215013f473.w1600.webp)

- Formal support for paid upgrade Default Space

Under the pay-as-you-go rules, the system will provide 10 units for free for each Default Space, even if you upgrade the plan, they will not disappear. Users can upgrade Default Space by paying to exceed the unit limit and expand the capabilities of Default Space. This also means that using Default Space is more cost-effective than directly purchasing DID Space (we recommend users to only use Default Space). There are two ways to upgrade Default Space for a fee, you can choose to upgrade according to your own usage situation:

- 操作步骤: 进入到 Default Space 的首页 -> 点击右上角的图标 -> 点击 Pay to upgrade，支付成功后升级 Default Space 就会自动升级了。
  - Upgrade Default Space on the webpage.

![image.png](https://media.arcblock.io/lib/41/4169059cb141ac25c0d0cbbb9cf71d7c.w1600.webp)

-
  - Upgrade Default Space on the DID Wallet (please note the official release of the DID Wallet client version).

Operation steps: Enter the DID Wallet homepage -> Click on the upper right corner menu -> Click on DID Spaces -> Enter the exclusive page of DID Spaces -> Click Upgrade DID Spaces -> Click Upgrade, complete the upgrade after successful payment.

<video src="https://media.arcblock.io/lib/8a/8a5847797772e4437e5febf0e5aefadc.mp4" controls></video>

- The Default Space for new users is created under a unified login account (please note the official release of the DID Wallet client).

Before when users logged into Prod DID Spaces, they always had to switch the site to Prod DID Spaces in order to view the Default Space. Now, Default Space created by new users will be created under a unified login account, so there is no need to switch sites when viewing, making the experience smoother. The Default Space of existing users will also be automatically migrated after entering the DID Wallet mobile app (only the data of DID Wallet itself, data from other apps will not be deleted and can still be read).

## improvement

- Personal DID Spaces no longer rely on Pages kit

Recently, we received [User Feedback](https://community.arcblock.io/discussions/5cf28d7b-c41a-42c9-9293-10659186dc07): Installing Personal DID Spaces without selecting the installation of related components, when users access the application homepage, an error will occur. This is because Pages Kit is not installed or mounted to the / mount point, so this error appears. Personal DID Spaces is not mandatory to bind pages kit, so we decided to remove the Pages Kit dependency from Personal DID Spaces. However, users can still combine blocklets according to their own needs.

- Prefer to use the jump method for login, prohibit automatic pop-up windows when logging in.

Due to browser restrictions on pop-ups, the DID Wallet login pop-up on the webpage cannot automatically appear, which may cause users to not see the login pop-up after clicking the login button. Therefore, the login method for the DID Spaces site has been changed to redirect login, rather than automatically popping up the login pop-up.

- Support displaying the DID Wallet icon by default.

After the DID Wallet is connected to the DID Space, the icon of the DID Wallet can be displayed on the DID Space.

![image.png](https://media.arcblock.io/lib/b0/b0b02b9d8a79198008a24b33aff4b91d.w1600.webp)

## Participate in the Bug Bounty program and help us improve

If you have any needs, suggestions or problems during use, please visit the ArcBlock community to provide feedback, we will do our best to help. You can also participate in our  [Bug Bounty Program](https://community.arcblock.io/discussions/b72261d3-693c-4f50-afa8-01913a7b6f79) to help us improve the product experience of DID Spaces.

[Bug Bounty Program V2 - Bigger Rewards, Bolder Challenges!](https://community.arcblock.io/discussions/b72261d3-693c-4f50-afa8-01913a7b6f79)

---

## Store the data of the DID Wallet.

URL: https://www.arcblock.io/en/docs/did-spaces/MXp8eADQTiX3La3Rzg80RSC_/

## Overview

DID Wallet comes with DID Spaces built-in.  Every DID Wallet account receives a free DID Space upon initialization on [DID Spaces](https://www.didspaces.com/en?locale=en). By default, DID Wallet automatically synchronizes application access logs to this free DID Space.

## Prerequisites

- You need to install a DID Wallet. See [https://support.didwallet.io/howToDownload](https://support.didwallet.io/howToDownload) for instructions.

## Procedure

Click the <strong>Settings</strong> icon in the top right corner to access the settings page:

![image.png](https://media.arcblock.io/lib/6c/6cec1b9699f728d6d744770c2ba90b78.w1600.webp)

Click DID Spaces to view its details.

![image.png](https://media.arcblock.io/lib/5c/5cb63efc9fa1064344555475d3ad2d27.w1600.webp)

You should now see the DID Spaces modules and can immediately synchronize your application access records to your DID Space. (DID Wallet also automatically synchronizes this data periodically.)

![image.png](https://media.arcblock.io/lib/8c/8cef58801cf82d479868ccbf5779e5bf.w1600.webp)

---

## NFT Maker

URL: https://www.arcblock.io/en/docs/did-spaces/nft-maker-case/

## Scenario

NFT Studio is an application that facilitates NFT creation.

User-minted NFTs are initially stored within the NFT Studio instance. As the number of NFTs grows, storage demands increase, presenting several challenges.

- Instance storage is not easily scalable (especially in serverless environments, where storage capacity may be limited)
- NFTs require on-chain display and are highly dependent on the operational status of the NFT Studio.
- The cost of storing NFT data should be the responsibility of the site owner.

To address these issues, NFT Maker offloads NFT storage to DID Spaces, decoupling computation and storage.

## Solutions

- When first setting up NFT Studio, users bind a DID Space.  All subsequent user NFTs will be stored on this DID Space.  See [Connect to DID Space on Blocklet Setup](/en/docs/did-spaces/connect-to-did-spaces-on-setup/)
- Read and write data to a DID Space using [@blocklet/did-space-js](https://www.npmjs.com/package/@blocklet/did-space-js?activeTab=readme). See [Use @blocklet/did-space-js to read and write DID Space.](/en/docs/did-spaces/backup-blocklet/) for more information.

## Showcase

- Installation

Install [NFT Maker](https://store.blocklet.dev/blocklets/z8ia2birZzhjbXqKnxPUUivmqErdsf3724tr6) from the [Prod Store](https://).  Connecting to a DID Space is required during the installation process.

![image.png](https://media.arcblock.io/lib/a5/a5ed0f714a706ed4ef78a1440fc01b35.w1600.webp)

- Using

With NFT Studio, you can create an NFT Collection.  NFTs minted within this collection will be stored in the DID Space connected during setup (e.g., [https://main.abtnetwork.io/explorer/assets/zjdi6qhgYdt2V5v4vGYMT186p8ve6usnD5Gv](https://main.abtnetwork.io/explorer/assets/zjdi6qhgYdt2V5v4vGYMT186p8ve6usnD5Gv); data is stored in [DID Spaces](https://www.didspaces.com/)).

<video src="https://media.arcblock.io/lib/d1/d146eeaf981ffe0e6ce6e4db4a069580.mp4" controls></video>

---

## The application connects to the DID Space to store and display personalized data.

URL: https://www.arcblock.io/en/docs/did-spaces/plTvVwQp4m7b-q_3uJQ3aXD_/

## Overview

Some applications (such as [Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu)) automatically save personalized user data to the user's DID Space upon connection. This personalized data is then displayed within the DID Space.

## Requirements

- For information on acquiring a DID Space, see: [Acquiring a DID Space](/zh/docs/did-spaces/UZBBuVlRcxHY8wppr7S7iwYI/)

## Procedure

> This walkthrough demonstrates personalized data display using Discuss Kit. This can be done using the [Community](https://community.arcblock.io/) site or your own Discuss Kit installation.

### Connecting to a DID Space

After logging into Discuss Kit, click your avatar in the top right corner, then click Profile:

![image.png](https://media.arcblock.io/lib/34/3401c7d53226de82ec915e4aa7e773c1.w1600.webp)

Click the DID Spaces tab, then click Connect to DID Spaces to connect your DID Space.

![image.png](https://media.arcblock.io/lib/ed/ed5980690d797e0f232319656b4cb870.w1600.webp)

### Generate Personalized Data Automatically

Whenever you create or edit posts, blogs, bookmarks, or documents in an app connected to your DID Space, the app automatically saves this data to your DID Space and displays it in a personalized manner.

![image.png](https://media.arcblock.io/lib/89/89b6ce6252a29e7a43569ec03cd81cb3.w1600.webp)

![image.png](https://media.arcblock.io/lib/92/92207ec5dc834a04347c183fa92694be.w1600.webp)

---

## Pricing policy

URL: https://www.arcblock.io/en/docs/did-spaces/pricing-policy-hhnsg/

## Overview

Unlike traditional billing methods, DID Spaces charges based on usage, with the unit of billing referred to as a unit. Following successful [Subscribe to DID Spaces](https://www.didspaces.com/app), a certain fee will be charged daily based on the number of units used by the user.

It is worth noting that the Default Space created by [DID Wallet](https://www.didwallet.io/) (which is a gift from ArcBlock's official DID Spaces service to all wallet users) will be given 10 units for free (note that this may change as the company policy changes), even if you upgrade it for a fee, the given units will not disappear.

## Chargeable items

DID Spaces will convert into different units based on the stored project, here is the conversion table (please note that projects may be updated in the future):

| Chargeable items  | Number of units  | Explanation  |
|---|---|---|
| 1 native app  | * 1   | Each connected native application (such as DID Wallet, Aistro), unit number + 1.  |
| 1 application backup  | * 1   | Every time an app is backed up, the unit count increases by 1.  |
| Components in one application  | * Number of components  | If there are a total of 5 components under this application, with 3 components writing data to DID Space, then the unit count + 3.  |
| 1 GiB of storage space  | * 1   | Round up, every 1 GiB, unit number + 1. If less than 1 GiB, billing will be calculated as 1 GiB.  |
| 1 Profile  | * 1   | Each DID Wallet Profile contains one additional unit.  |

Example: If you are in a certain day

- Connected DID Wallet (+1 unit)
- Backed up 5 applications (+ 5 units)
- Wrote data with 3 components to DID Spaces (+ 3 units)
- Storage space used 8.88 GiB (+9 units)

So you need to pay a total of (1 + 5 + 3 + 9 = 18) units of fees.

If your DID Space happens to be the Default Space, then you only need to pay for 8 units (18 - 10, 10 units are free bonus units).

## Declaration

The free units and pricing items we give to Default Space are not set in stone, they will change with changes in company policy.

---

## Restore Blocklet

URL: https://www.arcblock.io/en/docs/did-spaces/restore-blocklet/

## Overview

If your application has been backed up to DID Spaces, you can restore it to the Blocklet Launcher or any Blocklet Server at any time.

## Prerequisites

- You have backed up the app to DID Spaces, and you are its owner.

## Procedure

Now you can restore your application to the Blocklet Launcher or Blocklet Server using the following methods:

- [Restore Blocklet to Launcher](/en/docs/did-spaces/restore-to-launcher/)

- [Restore the Blocklet to the Blocklet Server.](/en/docs/did-spaces/restore-to-blocklet-server/)

---

## Restore the Blocklet to the Blocklet Server.

URL: https://www.arcblock.io/en/docs/did-spaces/restore-to-blocklet-server/

## Overview

If you have your own Blocklet Server, you can restore applications backed up to DID Spaces.

## Prerequisites

- You have backed up the app to DID Spaces, and you are the owner of this app.

## Procedure

### Sign in to Blocklet Server

Sign in to your Blocklet Server

![image.png](https://media.arcblock.io/lib/4b/4b0b24cda42207b0453861a117a637c9.w1600.webp)

Go to the **Blocklets** page, click the split button in the top right corner, and then click **Restore from DID Spaces** to access the application restoration page.

![image.png](https://media.arcblock.io/lib/33/330da1524e80a9a035d0c7983965797d.w1600.webp)

### Connecting to DID Spaces

Select your DID Spaces service site (the application you want to restore should be on this site), click <strong>Connect Now</strong> to connect to DID Spaces.

![image.png](https://media.arcblock.io/lib/0e/0eab64092a09b3fc8f1c9076cf9f45ea.w1600.webp)

Select the application you want to restore, and click <strong>Restore</strong> to continue.

![image.png](https://media.arcblock.io/lib/f0/f029f947164a25b1eb388d09c7f730a9.w1600.webp)

### Authorize Blocklet Server Restoration

Restoring this application requires your authorization. Please grant authorization and provide the encryption password to proceed.

![image.png](https://media.arcblock.io/lib/ba/ba542c4fe61df69680e5384057e7579c.w1600.webp)

After authorization, the application will begin restoring to your Blocklet Server. Shortly thereafter, the restoration will complete, and the application will be visible on the blocklets page of your Blocklet Server.

![image.png](https://media.arcblock.io/lib/50/501301c8bb214dde6a9f9c2a5d0ef155.w1600.webp)

### Verify the Integrity of the Restoration

After a successful restoration, the restored Blocklet should appear and be running on the Blocklets interface. Click Visit:

![image.png](https://media.arcblock.io/lib/6b/6b49bb3d3d299dbadf6cc20bd72f01fd.w1600.webp)

You can see that the application data has been fully restored:

![image.png](https://media.arcblock.io/lib/07/07d7b5e264eafa5b07336085891867c3.w1600.webp)

---

## Restore Blocklet to Launcher

URL: https://www.arcblock.io/en/docs/did-spaces/restore-to-launcher/

## Overview

If you have your own Blocklet Server, you can restore applications backed up to DID Spaces to it.

## Prerequisites

- You have backed up the app to DID Spaces, and you are its owner.

## Procedure

### Sign in to DID Spaces

Log in to [DID Spaces](https://www.didspaces.com/en?locale=en) and click <strong>Access My Spaces.</strong>

![image.png](https://media.arcblock.io/lib/49/490caed16d9d09fae12b5f22c9c5106f.w1600.webp)

Click the Connected menu on the left, select the application to be restored, locate and click "Restore with Blocklet Launcher" in the Audit Logs. A new tab will open in the browser, initiating the restoration process.

![image.png](https://media.arcblock.io/lib/23/23fc85b84477993bf0f4fd858cbdfd78.w1600.webp)

### Restore to Blocklet Launcher

Restoring to the Blocklet Launcher requires purchasing a DID Space. Please select a suitable plan and complete the payment.

![image.png](https://media.arcblock.io/lib/fa/faff7e0dfa79f65a58ee24fc4e15fb05.w1600.webp)

After successful payment, please present your Owner credential to continue the restoration process.

![image.png](https://media.arcblock.io/lib/7f/7f08269b894fecd02bfc1a3ef9f5cea4.w1600.webp)

After successful authorization, the application will begin restoring to your Blocklet Space:

![image.png](https://media.arcblock.io/lib/1a/1a94a423cca3e3fffa62942b56f19f6e.w1600.webp)

After a brief wait, the application successfully restored to Blocklet Launcher:

![image.png](https://media.arcblock.io/lib/3d/3d9461075574b761b95b6a9c6e334037.w1600.webp)

---

## Store personal data

URL: https://www.arcblock.io/en/docs/did-spaces/storage-your-data/

## Overview

Beyond offering Blocklet backup and restoration, DID Spaces also empower you to securely store and manage your personal data, providing convenient uploading and access.

## Prerequisites

- An available DID Space, see: [Get DID Space](/zh/docs/did-spaces/UZBBuVlRcxHY8wppr7S7iwYI/)

## Process

### Log In to DID Spaces

Log in to your DID Spaces site, then navigate to the DID Space homepage:

![image.png](https://media.arcblock.io/lib/f6/f6ee7a37c14699f7ccf10a86e8b62119.w1600.webp)

Click the "Storage" tab on the left -> the upload icon in the top right corner -> "Browse Files". Once you've selected the file(s) you want to upload, click "Upload File":

![image.png](https://media.arcblock.io/lib/87/8772e92bad2d965fc51f392fb5e47dcb.w1600.webp)

![image.png](https://media.arcblock.io/lib/98/984bb49ddc376cc6e8d6f12b003ef580.w1600.webp)

Once uploaded successfully, you can view the new files in Explore.

![image.png](https://media.arcblock.io/lib/7a/7a03c174320ccdc05287f496cff6fb99.w1600.webp)

---

## DID Spaces v0.3.75 released: Supports reading and writing component spaces

URL: https://www.arcblock.io/en/docs/did-spaces/support-read-write-component-space/

As of now, the new version v0.3.75 of DID Spaces has been released. This update includes added read and write component space functionality, as well as some other improvements and fixes.

## New feature

- Support read-write component space

In this version, we have added support for read and write operations on component spaces. This means that after users complete authorization, applications can read and write components in the DID Spaces, greatly expanding developers' capabilities after integrating DID Spaces into their applications.

In order to demonstrate this ability, we have prepared a Todo List sample project. You can visit the following link to learn more:

[Todo List](/en/docs/did-spaces/todo-list-example/)

You can also use this ability:

- Store user's billing information.
- Store user posts (and import them into any application instance)
- Store user activity records.
- Store user's AI prompts.
- Storing any valuable data generated by users...

If you want to know more about the implementation details, you can also refer to:
[Obtain the endpoint of DID Space.](/en/docs/did-spaces/connect-to-did-spaces/)

## Improve

- Subscription details page supports viewing DID Space

On the subscription details page, we support the function of jumping to view DID Space on the subscription interface, allowing users to experience the subscription function of DID Spaces more smoothly.

![image.png](https://media.arcblock.io/lib/c2/c276ed7ed24e6e396392a48884aca4c7.w1600.webp)

- Display QR code

Displaying the Qrcode on the details page of DID Spaces makes it convenient for users to recharge their accounts and conduct transactions.

![image.png](https://media.arcblock.io/lib/66/6605e58714af9967812a2ce122dc9378.w1600.webp)

##  Repair

- Prohibit DID Spaces from connecting to the site itself

We gathered [User feedback](https://community.arcblock.io/discussions/e5513c4d-bf03-42dd-935e-1351a987d63a) information and discovered that connecting from DID Spaces to the site itself, backing up data to the site itself, and then restoring DID Spaces backups to other Blocklet Servers have led to many unexpected problems. Considering that backing up oneself is uncommon and not the best backup practice, we have decided to prohibit DID Spaces from connecting to the site itself and prohibit DID Spaces from backing up data to the site itself.

## Participate in the Bug Bounty program and help us improve

Please participate in our [Bug Bounty Program](https://community.arcblock.io/discussions/b72261d3-693c-4f50-afa8-01913a7b6f79), help us improve the product experience of DID Spaces. If you have any needs, suggestions or issues during usage, please visit the ArcBlock community for feedback. We will do our best to assist.

[ArcBlock Community](https://community.arcblock.io/)

---

## Todo List --> 待办事项列表

URL: https://www.arcblock.io/en/docs/did-spaces/todo-list-example/

## Overview

When you need to store each user's personal data in their own DID Space, this tutorial will help you.

This is a Todo List application built using Typescript, React, Express, and DID Spaces. Users connect to their DID Space upon initial login. All subsequent Todo List data is then persisted within each user's respective DID Space.

## Prerequisites

- Install the To-Do List app

[Todo List](https://dev.store.blocklet.dev/blocklets/z2qZxf2VrwCM35aotK62w9NRDs2hmVDrMML8C)

## Demonstration

### Connecting to a DID Space for the First Time

Connecting to a DID Space is required upon initial login to grant the application read and write access.

![image.png](https://media.arcblock.io/lib/36/3661be600d922025cb49c59879c23c4b.w1600.webp)

### Creating a To-Do List

Next, you can add tasks to your to-do list and mark some as complete:

![image.png](https://media.arcblock.io/lib/bb/bb2870d3a9742ff64654788ca011ac1d.w1600.webp)

### Persistent Storage

As you edit your Todo List, the data is automatically saved to your DID Space. Even if the page refreshes, the data is retained, and you can view the raw data stored in your DID Space.

![image.png](https://media.arcblock.io/lib/43/43992b34651af28bd5e467928ea7f2a0.w1600.webp)

## Implementation Details

For specific implementation details, please refer to our code repository.

[GitHub - blocklet/todo-list-example](https://github.com/blocklet/todo-list-example)

---

## DID Spaces v1.0.48: 支持预览 post/bookmark/blog/doc

URL: https://www.arcblock.io/en/docs/did-spaces/UfsJ7NwMaF5QtYgE8xKcZZm1/

## 执行摘要

DID Spaces推出了一项重要更新，引入了功能和增强功能，优化用户体验并提高整体性能。以下是新功能：

- <strong>文档预览</strong>：用户现在可以在访问文档之前预览它们，提高可用性。
- <strong>时间记录控制</strong>：能够启用或禁用时间记录，让用户对其活动跟踪拥有更多控制权。
- <strong>备份统计修复</strong>: 修正了备份统计数据不准确的问题，确保用户拥有可靠的数据。
- <strong>改进的内存管理</strong>：优化导致降低内存消耗，提升性能。
- <strong>主题支持</strong>：平台现在支持服务主题，允许更大的定制化。

这次更新不仅关注新功能，还修复了一些错误并增强了系统的可靠性。

## 特色亮点

### 新功能

- <strong>预览文件</strong>：用户现在可以直接在 DID Spaces 中预览文档。此功能使得在完全打开文件之前评估内容变得更加简单，节省时间并简化工作流程。
- <strong>时间记录控制</strong>：最近的更新允许用户切换时间记录的开启和关闭。这种灵活性确保用户可以根据自己的喜好管理他们的活动跟踪，使平台更适应个体需求。
- <strong>增强的存储和预览功能</strong>：您现在可以直接在个性化的数字空间中存储和预览帖子、博客和书签。此增强功能简化了不同内容类型的管理，使您的数字组织更加高效。

### 用户体验改进

- <strong>备份统计准确性</strong>：关键修复了备份统计中的不准确性。用户现在可以相信报告的数据反映了实际的增量变化，从而实现更有效的数据管理，并确保在依赖备份报告时心怀安宁。
- <strong>服务支持主题</strong>: 添加主题支持允许用户对用户空间进行更多的可视化定制。用户现在可以选择与其个人风格 resonating 的主题，使他们的数字环境感觉独特并反映他们的偏好。

### 错误修复

- <strong>钱包中的单位计数问题</strong>：当钱包中的单位计数较低时，数据写入问题的修复确保用户可以放心前行，他们知道即使在限制条件下，其数据也将被正确处理。
- <strong>标签长度错误</strong>：解决了保存超过字符限制的标签时出现的错误。用户现在可以添加更长的标签而不会遇到问题，增强了数据组织的灵活性。
- <strong>预览标题字符串长度</strong>：预览模板标题的最大长度已扩展。此更改允许更具描述性的标题，帮助用户更好地分类和识别其内容。

### 性能和可靠性增强

- <strong>优化内存消耗</strong>：最新更新改善了运行时内存管理。通过降低整体内存占用量，系统运行更加流畅，提升整体用户体验。
- <strong>改进的错误处理</strong>：用户在连接失败或问题出现时将会注意到更清晰的错误消息，提升支持体验并减少故障排除过程中的挫折感。

### 文档更新

用户可以访问更新的文档，帮助他们了解新功能和改进。这确保了所有用户都能充分利用 DID 空间。

## 接下来是什么

在展望未来时，团队正在积极努力进一步完善 DID Spaces。目前正在进行有关以下内容的讨论：

- <strong>更易扩展的应用集成</strong>：计划引入更多可无缝集成到 DID Spaces 中的应用程序，丰富用户体验并扩展功能。
- <strong>增强跨组织共享</strong>：专注于改进能够促进用户之间更好协作的功能，特别是对团队和家庭来说。
- <strong>用户反馈整合</strong>：团队致力于倾听用户反馈，以便识别和优先考虑未来的更新和功能。

通过与社区保持开放对话，我们的目标是构建一个始终满足用户需求和期望的平台。

## 资源

要获取更多信息、指导和更新，请查阅以下链接：

- [Documentation](https://www.arcblock.io/docs/did-spaces/)
- [Community Forum](https://community.arcblock.io)
- [Product Page](https://store.blocklet.dev/blocklets/z8iZnaYxnkMD5AKRjTKiCb8pQr1ut8UantAcf)

DID Spaces 旨在成为您个性化的数字绿洲，使您的数字生活更有条理、更安全、更连贯。最新的更新仅是实现这一目标的一小步。感谢您成为我们旅程的一部分！

---

## DID Spaces v0.6.0: OAuth Integration in DID Spaces

URL: https://www.arcblock.io/en/docs/did-spaces/VEp60mUb0dJ-mxHmbMPHPXBA/

The key feature of this update is the <strong>integration of OAuth accounts with DID Spaces</strong>. Additionally, there are several enhancements and fixes responding to community feedback.

## <strong>OAuth Account Integration with DID Spaces</strong>

In the latest version,[Prod Spaces](https://www.didspaces.com/) will automatically provide each OAuth account with a permanently free Default Space. This allows OAuth accounts to display their Default Space anywhere without the need for DID Wallet involvement. This update is designed to offer you a more convenient and efficient service experience. (<strong>Note</strong>: Currently, in Prod Spaces, OAuth accounts cannot actively link to a DID Wallet, but you can still link OAuth accounts that have not yet logged into Prod Spaces using the DID Wallet.)

This feature encompasses the following scenarios:

- A newly created OAuth account showcases DID Space in AIGNE

<video src="https://media.arcblock.io/lib/56/56f4a0920f193221e79f76829974d3b2.mp4" controls></video>

- Switch the DID Space on the Profile page

<video src="https://media.arcblock.io/lib/56/5684f6643e436da48f62ab90e8a5d0f8.mp4" controls></video>

- Display DID Space during application backup

<video src="https://media.arcblock.io/lib/55/55af458038dac9a8cfc233758f790463.mp4" controls></video>

### How can an application initiate OAuth login?

If your application needs to enable OAuth login, you can refer to our tutorial:[Set Up OAuth Login](/zh/docs/did-connect/OtyR-OiASp4sJe0CYQ1TmHg0/)

## Enhancements

- <strong>NPM package name change:</strong> [<strong>@did-space/client</strong>](https://www.npmjs.com/package/@did-space/client) <strong>has been renamed to</strong> [<strong>@blocklet/did-space-js</strong>](https://www.npmjs.com/package/@blocklet/did-space-js)

To better standardize the management of official package names on NPM, we have renamed the original @did-space/client to @blocklet/did-space-js. If you are currently using @did-space/client, please transition to @blocklet/did-space-js at your earliest convenience.

- <strong>Enhancing Query Performance of Application Audit Logs</strong>

We have refined the internal storage structure for application audit logs, greatly boosting the efficiency of query performance.

## Fix

- <strong>Community Feedback on Issues with Opening New Windows on iOS Devices</strong>

We greatly value community feedback. Recently, concerning the issue of not being able to open new windows when restoring apps on iOS devices[, we immediately addressed and resolved this problem upon receiving the feedback.](https://community.arcblock.io/discussions/523780f6-2298-4dfb-9e6e-6b5dda2c67ee#c29575da-fcba-4152-955b-5a0c9c42c904)

## Join the Bug Bounty Program to help us improve

If you have any needs, suggestions, or questions while using our services, please visit the [ArcBlock Community](https://community.arcblock.io/) to share your feedback. We will strive to assist you. You can also join our Bug Bounty program to help enhance the product experience of DID Spaces.

[ArcBlock 202412 Bug Bounty](https://community.arcblock.io/earn/activity/518711772660629504)

---

## Change log

URL: https://www.arcblock.io/en/docs/did-spaces/wvRR_Ry_cjfOfAmjE72Os41M/

- [Draft: Purchase DID Space](/en/docs/did-spaces/gTndeHO7NRldrWuv3WV2_BjH/)

- [DID Spaces v0.6.0: OAuth Integration in DID Spaces](/en/docs/did-spaces/VEp60mUb0dJ-mxHmbMPHPXBA/)

- [DID Spaces v0.5.83: OAuth integrated DID Space](/en/docs/did-spaces/aVNIUFvC_7I86v8b4VF9EADk/)

- [Prod Spaces data retention policy updated](/en/docs/did-spaces/3ZzoUtM8foAlyYGxINj0E70i/)

- [DID Spaces v0.4.26 released: subscription fully adopts pay-as-you-go & supports paid upgrade Default Space](/en/docs/did-spaces/MJsBv7wkBk7mIwRYfPjTJnGu/)

- [DID Spaces v0.3.75 released: Supports reading and writing component spaces](/en/docs/did-spaces/support-read-write-component-space/)

- [DID Spaces v1.0.48: 支持预览 post/bookmark/blog/doc](/en/docs/did-spaces/UfsJ7NwMaF5QtYgE8xKcZZm1/)

- [Reference Terminology](/en/docs/did-spaces/Ha8x7mO69jChmW80qiqCKOWB/)

---

## Application case

URL: https://www.arcblock.io/en/docs/did-spaces/xHZTKQuliZMqA_n3RBVLk7wv/

Currently, several online applications have integrated with DID Spaces and are operating successfully. These applications include:

- NFT Studio
- AIGNE

You can learn more about DID Spaces use cases through the application examples below:

- [NFT Maker](/en/docs/did-spaces/nft-maker-case/)

- [AIGNE](/en/docs/did-spaces/ai-studio-case/)

---

## DID Wallet Guide

URL: https://www.arcblock.io/en/docs/did-wallet/

---

## Get Started

URL: https://www.arcblock.io/en/docs/did-wallet/get-started/

- [What is DID wallet？](/en/docs/did-wallet/what-is-did-wallet/)

- [What is DID?](/en/docs/did-wallet/what-is-did/)

- [How to download DID Wallet?](/en/docs/did-wallet/how-to-download-did-wallet/)

- [Which chains and tokens are supported?](/en/docs/did-wallet/which-chains-and-tokens-are-supported/)

- [What is mnemonic code?](/en/docs/did-wallet/what-is-mnemonic-code/)

---

## How to add a chain?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-add-a-chain/

1. Open your wallet and go to the home page
2. Click the upper right corner to enter <strong>My</strong>, and then click the upper right corner <strong>Settings</strong>
3. Click the <strong>Chain Manage</strong>
4. In <strong>ArcBlock</strong> can manage the <strong>Beta</strong> chain show or hide
5. Display hiding of Ropsten, Rinkeby, Goerli, Kovan, Binance Smart Chain, Binance Smart Chain Testnet can be managed under <strong>Ethereum Chain</strong>

---

## How to add a token?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-add-a-token/

> [Which chains and tokens are supported?](https://support.didwallet.io/en/supportedChainAndTokens)
>

Tokens of different chains are added in different ways:

### ArcBlock Chain Tokens

Tokens on ArcBlock Chain do not need to be manually added. If you have the balance of the token in your account, the account and balance of the token will be automatically synchronized to your token list. You can hide and display them on the token management page.

### Ethereum Mainnet Tokens

On the Ethereum Main chain, DID Wallet supports all tokens on [https://token-data.arcblock.io/](https://token-data.arcblock.io/) These tokens are [https://coinmarketcap.com/](https://coinmarketcap.com/) on market value is higher, contracts are still in the running of scrip.

You can also click the menu button in the upper right corner, click <strong>Add Token By Contract</strong>, fill in the Contract address and add it manually.

> Note: ETH and ABT Token cannot be hidden.
>

### Other EVM Chain Tokens

On the token management page, click the menu button in the upper right corner and click <strong>Add Token By Contract</strong>. After filling in the Contract address, the wallet will automatically query the information of token on the chain. After the query is successful, just click the save button and this token will be added to your token list.

---

## How to add ERC721 NFT?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-add-erc721-nft/

1. On the token list page, find the EVM token (depending on which chain your NFT is on) and enter the token details page;
2. Select your account with ERC721 NFT and click 'More' to go to the account details page;
3. Click the button in the upper right corner of the details page, and select Add ERC721.
4. On the page that is displayed, enter the NFT contract address and tokenId, and click Add. If this NFT belongs to your account, it can be added to your collection list.

---

## How to backup mnemonic code?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-backup-mnemonic-code/

Open DID Wallet and go to the home page of assets. Click the icon in the upper right corner to enter the Settings page. Continue to click the icon in the upper right corner to enter the settings page.

![Image](https://support.didwallet.io/content/uploads/1ae464a9be015f6b09bcee1b42f6a880.png?imageFilter=resize&w=307&q=75&f=webp)![Image](https://support.didwallet.io/content/uploads/e29b41815e027b3040bbf46d2df07d53.png?imageFilter=resize&w=306&q=75&f=webp)

If no password is set, you will be prompted to set a password. Click Confirm to set a password right now.

After you set the password, continue to click on the settings page to view the mnemonic. If biometric (Face ID or Touch ID) is enabled, the biometric interface will pop up. If not, the password input page will pop up to ensure wallet security.

Once you have authenticated, you will see your mnemonic, click copy and save it in a safe place.

> Note that if your wallet was created and initialized prior to version V4, you may not be able to support the view mnemonic code, but this will not prevent you from continuing to use the latest DID wallet.
>

---

## How to Connect Dapp?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-connect-dapp/

DID Wallet supports three ways to connect to DApps:

- DID Connect
- Wallet Connect
- Web3 Browser Connect

Below, we look at each of the three Connect modes.

### 1. DID Connect

DID Connect is the official Dapp Connect protocol of DID Wallet. [Please click on the detailed explanation of the technical implementation scheme.](https://github.com/ArcBlock/abt-did-spec#abt-did-authentication-protocol)

At present, official ArcBlock dapps all support DID Connect, such as the following sites:

- [ArcBlock website](https://www.arcblock.io/zh)
- [DID Wallet website](https://www.didwallet.io/)
- [Blocklet Store](https://store.blocklet.dev/)

Each of the sites above has a Connect button in the upper right corner that you can click to scan with DID Wallet or automate the Connect process.

In addition, if you want to experience all of the DID Connect use cases in their entirety, there is a full-fledged online experience app available: [Wallet Playground](https://playground.staging.arcblock.io/), there are all DID Wallet support DID Connect type can be online experience.

### 2. Wallet Connect

DID Wallet fully supports the Wallet Connect protocol and has joined the Wallet Connect organization, [Click on the Wallet Connect Site](https://walletconnect.com/registry?search=did+wallet).

Now, DID Wallet can be connected with all dApps that support Wallet Connect protocol, and there is no problem with the signature of the mainstream Dapp.

You can also use DID Wallet to visit Wallet Connect's official trial site: [https://example.walletconnect.org/](https://example.walletconnect.org/)

### 3. Web3 Browser Connect

DID Wallet has a powerful built-in browser that makes it easy to connect to ArcBlock ecosystem dApps or Ethereum ecosystem DApps.

When connecting to the Dapp of the ArcBlock ecosystem, the DID Connect process is automatically invoked.

Web3j will be automatically blocked when connecting to the Ethereum Ecosystem Dapp.

Wallet has built-in [Dapp Explore](https://explore.didwallet.io/) dapp, the dapp in the official screening of a batch of mainstream Dapp, for everybody all can in wallet built-in browser open and connection.

---

## How to create a bridge?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-create-a-bridge/

### Which accounts can initiate Bridge Move

1. In the token list, click on a token that can initiate a Bridge, such as ABT of ArcBlock Main chain
2. Select an Ethereum-style account. When the bottom Bridge button is clickable, you can initiate the Bridge

### How do I perform a Bridge Move In

1. Under an account that can initiate Bridge, click the Bridge button;
2. Select a Bridge, such as Ethereum Mainnet and ArcBlock Main;
3. View the current Bridge status, cost, balance and other information, and click the Start button after confirming the error;
4. Click the middle transition arrow and select the Bridge direction as switch-in (from Ethereum to ArcBlock);
5. Enter the number to be transferred, must be larger than the minimum number of transfers, smaller than the maximum number of transfers;
6. Click Next to confirm the required Ethereum network Gas charges;
7. Click OK, and the Bridge overview page will pop up. After confirming the transfer quantity, ArcBlock network handling fee and Gas fee, slide to transfer the Bridge;
8. After entering the Bridge details page, you can exit the page and the Bridge service will run automatically in the background. You can also go to the Bridge History page and enter the Bridge details page again to view the current progress.

### How do I perform a Bridge Move Out

1. Under an account that can initiate Bridge, click the Bridge button;
2. Select a Bridge, such as Ethereum Mainnet and ArcBlock Main;
3. View the current Bridge status, cost, balance and other information, and click the Start button after confirming the error;
4. Click the middle transition arrow and select the Bridge direction as Ethereum (from ArcBlock to Ethereum);
5. Input the quantity you want to transfer, check the transfer cost and time, and choose Fast WithDraw (with high handling fee but Fast speed).
6. Click Next, confirm the transfer quantity and handling fee, and slide the Bridge out;
7. Enter the Bridge details page, wait for ArcBlock network to lock the transferred token and synchronization state, click Claim button, select Gas fee, confirm and wait for Ethereum network Claim token to succeed, then the Bridge exchange can be completed. You can go to the corresponding token page to check the token number change.

---

## How to create wallet?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-create-wallet/

The creation process of DID wallet is very simple in design. It only needs one click to complete the creation process of wallet.

![Image](https://support.didwallet.io/content/uploads/d0f8a2902418fcdc3061b8867e64bd28.png?imageFilter=resize&w=272&q=75&f=webp)

In the create page, if you don't like the generated address, you can also randomly generate a new one by shaking the phone or clicking on <strong>New One</strong> button.

When you click the <strong>I Like It</strong> button, it means that the wallet creation process has been completed, and you will come to the home page of the wallet.

---

## How to download DID Wallet?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-download-did-wallet/

DID Wallet currently supports installation on multiple client platforms.

### iOS

[App Store](https://apps.apple.com/app/id1460083542)

### Android

[Google Play](https://play.google.com/store/apps/details?id=com.arcblock.wallet.app.product)

> Please do not trust any unofficial installation packages
>

### Web

[https://web.abtwallet.io/](https://web.abtwallet.io/)

> Please check the domain name carefully and ensure that the web page is protected by HTTPS protocol
>

### Browser Extension

[Chrome Web App Store](https://chrome.google.com/webstore/detail/did-wallet/ibjflpbmadchofnbpppegdbnifdgincp)

> We will support more app stores in the future.
>

---

## How to turn on Face ID?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-enable-face-id/

### 1. Enter menu page

![WeChat1c828a5aa4ff0068ca313acb6dda9c13.png](https://media.arcblock.io/lib/fa/fa0278953f1316382ade2fab71542154.w1600.webp)

### 2. Click Face ID Switch

##### Tips: If you have not set a wallet password currently, you will be prompted and guided here to set a wallet password.

![WeChate4dd1e16b67f160f56b3bc1b9e11dbcd.png](https://media.arcblock.io/lib/6d/6d2ba40967ef42afaa2ff36c1c69f932.w1600.webp)

### 3. Enter your wallet password

![WeChat89b45620402411fc4b7b7c003db0a788.png](https://media.arcblock.io/lib/12/128c796b3579fa428bff452560b04475.w1600.webp)

### 4. Click Allow Face ID

![WeChatf3b684edf62409821fe281088316245b.png](https://media.arcblock.io/lib/6c/6c8074c7454f7816ccb0943fc910d0c5.w1600.webp)

---

## How to find the hash of a bridge transaction?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-find-bridge-hash/

- Find the account for your bridge transactions, click "View in Block Explorer"

![image.png](https://media.arcblock.io/lib/ce/cebddc52c88f60fc1ab1cc4d427662ae.w1600.webp)

![image.png](https://media.arcblock.io/lib/1b/1b9fa06185dc97c2c334486e99e63ccd.w1600.webp)

- Find transactions of type Withdraw Token

![image.png](https://media.arcblock.io/lib/f6/f62b2faf51d275eadd0ba8989ff6f04f.w1600.webp)

- Click to enter transaction details, click to copy this hash

![image.png](https://media.arcblock.io/lib/3a/3a6ffe0dfcc489c2c27225854bb5d665.w1600.webp)

---

## How to generate backup file?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-generate-backup-file/

Backup files are one way to fully restore a wallet. For more information about how to restore a wallet, refer to other help documents.

You can go to the backup function page and click the backup button to make a backup for the current wallet immediately. If the backup is successful, the file address generated by the backup file will be displayed. The backup file is a <strong>encrypted document</strong> saved in the file system of the mobile phone.

In addition, the wallet automatically generates a backup file every 7 days by default (Note: the backup requires opening the wallet, meaning that if you do not actively open the wallet, you cannot trigger the automatic backup logic every 7 days). You can also turn this off on the backup feature page.

---

## How to get native ABT?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-get-native-abt/

Currently, there is only one way to get [Native ABT](https://main.abtnetwork.io/explorer/tokens/z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD/txs): <strong>first get ERC20 ABT assets on the Ethereum mainnet, then exchange ERC20 ABT to native ABT via ArcBridge, the cross-chain bridge built into the DID wallet</strong>.

Here are the detailed steps.

### 1. Initialize the wallet and find the wallet's ethereum address

Click the receive button on the wallet home page to open the wallet default address popup.

![Image](https://support.didwallet.io/content/uploads/a27a6bcfa2baf73ebfaafa5105066a2f.png?imageFilter=resize&w=340&q=75&f=webp)

Switch to Ethereum in the popup and then click on the address and copy it.

![Image](https://support.didwallet.io/content/uploads/2af3c40ded9dffd09287ac7619376960.png?imageFilter=resize&w=346&q=75&f=webp)

### 2. Transfer the ERC20 ABT to the address starting with 0x copied above

> Make sure the correct network is selected: <strong>Ethernet main network</strong>.
>

If you have a Coinbase account, you can complete the ERC20 ABT purchase process from within your wallet, for detailed steps please see.

[How to buy cryptocurrency via Coinbase Pay from within DID Wallet](/en/articles/buy-crypto-within-did-wallet/)

You can also do this on your own by going to an exchange or another wallet, with the following caveats.

1. make sure the chain you are transferring to is <strong>Ethernet mainnet</strong>
2. make sure the receiving address is the address inside your own DID wallet, transferring the wrong address may cause irreparable damage

### 3. transfer a certain amount of ETH to the address starting with 0x address above

The steps are the same as the previous step, because later we need to initiate a swap-in operation through the cross-chain bridge ArcBridge, this step will send a transaction in the Ethernet network, requiring a certain amount of ETH to pay for the gas fee.

### 4. Wait for on-chain transactions to complete, go to DID wallet to sync assets

After the exchange or other wallets confirm the transaction has been successful, go back to the DID wallet home page to do an active pull-down refresh and wait for the asset sync to complete.

![Image](https://support.didwallet.io/content/uploads/09f7dbcb080164b2d5f38dcf4027d959.png?imageFilter=resize&w=406&q=75&f=webp)

### 5. After confirming that the asset has been transferred, the bridge request can be initiated

![Image](https://support.didwallet.io/content/uploads/10dabf083b45a9635548f22ecfddc164.png?imageFilter=resize&w=419&q=75&f=webp)

1. switch to Ethereum Mainnet
2. Select the account to be bridgeed
3. Click the bridge button at the bottom to initiate the bridge request

### 6. Initiate the bridge request

![Image](https://support.didwallet.io/content/uploads/fd6f5abd8c60e01be284c77a89014778.png?imageFilter=resize&w=428&q=75&f=webp)

Click move in and go to the next step

![Image](https://support.didwallet.io/content/uploads/a2fc0a98ff62d85c2684556f344a7401.png?imageFilter=resize&w=422&q=75&f=webp)

Enter the number of ABTs you want to move in, and click to go to the next step

![Image](https://support.didwallet.io/content/uploads/3148a07f5f4f5427e5d83d6efb4845f9.png?imageFilter=resize&w=431&q=75&f=webp)

After setting the appropriate gas cost, officially launch the move in and go to the bridge details and wait for the bridge to complete.

![Image](https://support.didwallet.io/content/uploads/e17ad7946144fb589fe0105334e49603.png?imageFilter=resize&w=443&q=75&f=webp)

Waiting for the chain process to finish will complete the move in.

![Image](https://support.didwallet.io/content/uploads/de8a1640a7c4420d4619bf4f701692dd.png?imageFilter=resize&w=452&q=75&f=webp)

### 7. At this point we can go under the ArcBlock Main chain and check if the assets we just swapped in have arrived

On the details page of the account, scroll down and refresh, wait a moment, and you will see that the assets you just swapped in have arrived.

![Image](https://support.didwallet.io/content/uploads/051ca1bb1dd591769eb1a3840a46b6c0.png?imageFilter=resize&w=466&q=75&f=webp)

This completes the process of getting the native ABT

---

## How to provide your NFT/Passport to a Dapp

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-provide-nft-passport-to-dapp/

### Where is your NFT

Your NFT is displayed in the Collectibles section on the DID Wallet homepage. You can tap on the specific NFT to expand it and see more info about it.

![Untitled.png](https://media.arcblock.io/lib/db/db0811b8e61340af77bc9c0a18ef15a2.w1600.webp)

### How to provide a NFT to Dapp

When you are asked to present an NFT, a popup will appear in DID Wallet. If you have multiple eligible NFTs, choose which one to provide and slide to show it.

![1.png](https://media.arcblock.io/lib/ca/ca7d8b3043a8cdc15d930ec8543a73a7.w1600.webp)

### Notice: your NFT will not be sent to Dapp

---

## How to provide a profile to a Dapp

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-provide-profile-to-dapp/

### How to create a profile

Click the Add button on the fourth tab to create a new Profile.

![Create Profile.png](https://media.arcblock.io/lib/bd/bd9b2101302df21c1329021f210a39f5.w1600.webp)

### Make sure Dapp request infomations and confirm it

When you provide your Profile, please make sure you are not asked to provide information that you do not want to disclose. Then select a Profile and slide to provide it.![Untitled](https://prod-files-secure.s3.us-west-2.amazonaws.com/b7193f06-90ed-45e9-9dd7-6d1750cd739a/fcac7cd5-1273-4064-a43e-707acf4ff492/Untitled.png)

![Provide Profile.png](https://media.arcblock.io/lib/14/146c85dae18720fd77e633db41fa0d49.w1600.webp)

### How to change profile in Dapp

### How to edit profile in Dapp

Step1: Click the “More” button on the profile card.

Step2: Select “Edit” from the popup menu.

![Edit Profile.png](https://media.arcblock.io/lib/23/23f683622c5d5cc023d75a2732ba4f79.w1600.webp)

---

## How to recover bridge(deposit/withdraw) history?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-recover-bridge-history/

We currently only support recovery <strong>withdrawal</strong> history.

### How to recover withdrawal history:

- Enter the wallet homepage, click on ABT

![image.png](https://media.arcblock.io/lib/32/3215e520d947609360dfaa740ff89555.w1600.webp)

- Click <strong>Bridge</strong>.

![image.png](https://media.arcblock.io/lib/cd/cd7fe25cfa7b2b9e16a9fbd4e62ea720.w1600.webp)

- Click the + button and enter the bridge transaction hash to restore the transaction history. [(How to find the hash of a bridge transaction?)](/en/docs/did-wallet/how-to-find-bridge-hash/)

![image.png](https://media.arcblock.io/lib/ce/cea3e4a1e33261050d46b39fc0e5b4d4.w1600.webp)

---

## How to recovery a passport from a Dapp?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-recover-passport-from-dapp/

### From Dapp web

### From DID Wallet

---

## How to recover the wallet?

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-recover-the-wallet/

DID Wallet supports two ways to recover your Wallet:

Open DID Wallet with two buttons <strong>Create New Wallet</strong> and <strong>Restore Wallet</strong>. Select <strong>Restore Wallet</strong>. There are two options when you go to the Restore Wallet page.

### 1. Mnemonic recovery:

Enter your 12 mnemonic words, or paste 12 mnemonic words (separated by space in the middle), if the mnemonic words meet the rules, you can click next, enter the password setting page, set the wallet unlock password can be restored successfully.

### 2. Backup file recovery:

If you have a backup file that ends in `.abt`, you can select the corresponding. Abt file to restore the backup. After selecting the file, you will be asked to input the password. The password is the wallet unlock password that was used during the backup. If the password is correct, the restoration succeeds.

---

## How to swap ABT to Ethereum Mainnet

URL: https://www.arcblock.io/en/docs/did-wallet/how-to-swap-abt-to-ethereum-mainnet/

Currently, there is only one way to transfer your native ABT to Crypto Exchange.

Here are the detailed steps.

### 1. Open the wallet and go to the ABT token page

Click the ABT column on the wallet home page

![image.png](https://media.arcblock.io/lib/1b/1b55cd980323a8000a16439f92fdb56e.w1600.webp)

### 2. Click the 'Bridge' button

- Make sure you select the ArcBlock Main chain
- Make sure your ABT is on an address with a '0x' prefix (EVM format)
-
  - If your ABT is not on an EVM format address, you need first transfer it to this address
- Make sure this address is the address you want to bridge to
- Make sure this address has enough ETH on the Ethereum Mainnet for the bridge gas fee

![image.png](https://media.arcblock.io/lib/13/133f127db6377af66de0657d4f641a2c.w1600.webp)

### 3. Just click 'Withdraw' to the next step

![image.png](https://media.arcblock.io/lib/d5/d5ae1b40bea6fa330146808818cc68e9.w1600.webp)

### 4. Input the amount you want to withdraw

- You can input the amount you want to withdraw
- You can choose whether or not to use Fast Withdraw
-
  - Normal Withdraw:  Your transaction will be packaged with other users, which costs less but takes longer
  - Fast Withdraw:  Your transaction will be packaged immediately, with a pre-charge fee, and any unused fees will be refunded upon completion of the transaction

![image.png](https://media.arcblock.io/lib/be/be6ad0ecb990ba67cfec9cff3d6f5706.w1600.webp)

### 5. You need to manually claim the ABT Token to the Ethereum Mainnet

- Click the 'Claim' button, choose the gas and after the ETH transaction is confirmed, you can go to Ethereum Mainnet to view your token.

![image.png](https://media.arcblock.io/lib/b6/b699038d06007947dc05fe426b42ab1a.w1600.webp)

### 6. Transfer your token to your crypto exchange address or other wallet address

- Make sure you select Ethereum Mainnet
- Click the 'Send' button and then send to your address.

![image.png](https://media.arcblock.io/lib/1c/1c7ac5ceeff07e44e17eca353bf513d4.w1600.webp)the

---

## Manage Asset

URL: https://www.arcblock.io/en/docs/did-wallet/manage-asset/

- [How to add a token?](/en/docs/did-wallet/how-to-add-a-token/)

- [How to add a chain?](/en/docs/did-wallet/how-to-add-a-chain/)

- [How to create a bridge?](/en/docs/did-wallet/how-to-create-a-bridge/)

- [How to add ERC721 NFT?](/en/docs/did-wallet/how-to-add-erc721-nft/)

- [How to get native ABT?](/en/docs/did-wallet/how-to-get-native-abt/)

- [How to hide/show assets](/en/docs/did-wallet/how-to-hide-or-show-assets/)

- [How to swap ABT to Ethereum Mainnet](/en/docs/did-wallet/how-to-swap-abt-to-ethereum-mainnet/)

---

## Manage Wallet

URL: https://www.arcblock.io/en/docs/did-wallet/manage-wallet/

- [How to turn on Face ID?](/en/docs/did-wallet/how-to-enable-face-id/)

- [How to create wallet?](/en/docs/did-wallet/how-to-create-wallet/)

- [How to backup mnemonic code?](/en/docs/did-wallet/how-to-backup-mnemonic-code/)

- [How to generate backup file?](/en/docs/did-wallet/how-to-generate-backup-file/)

- [How to recover the wallet?](/en/docs/did-wallet/how-to-recover-the-wallet/)

- [How to Connect Dapp?](/en/docs/did-wallet/how-to-connect-dapp/)

- [How to provide a profile to a Dapp](/en/docs/did-wallet/how-to-provide-profile-to-dapp/)

- [How to provide your NFT/Passport to a Dapp](/en/docs/did-wallet/how-to-provide-nft-passport-to-dapp/)

- [How to recovery a passport from a Dapp?](/en/docs/did-wallet/how-to-recover-passport-from-dapp/)

- [How to manage multiple wallets](/en/docs/did-wallet/how-to-manage-multiple-wallets/)

- [What can the scanning function do?](/en/docs/did-wallet/what-can-the-scanning-function-do/)

---

## Q&A

URL: https://www.arcblock.io/en/docs/did-wallet/qanda/

- [How to find the hash of a bridge transaction?](/en/docs/did-wallet/how-to-find-bridge-hash/)

- [How to recover bridge(deposit/withdraw) history?](/en/docs/did-wallet/how-to-recover-bridge-history/)

- [What is stake?](/en/docs/did-wallet/what-is-stake/)

- [What is slasher?](/en/docs/did-wallet/what-is-slasher/)

- [What is revoke waiting period?](/en/docs/did-wallet/what-is-revoke-waiting-period/)

- [What if I forget wallet password?](/en/docs/did-wallet/what-if-i-forget-wallet-password/)

- [Why wallet has multiple addresses?](/en/docs/did-wallet/why-wallet-has-multiple-addresses/)

---

## What can the scanning function do?

URL: https://www.arcblock.io/en/docs/did-wallet/what-can-the-scanning-function-do/

DID Connect, is the most important function of scanning the DID Connect QR code and performing subsequent operations.

- Please note: connecting DID Connect will not disclose your private key to third parties.

Wallet Connect, scanning the Wallet Connect QR code can connect to Wallet Connect and perform corresponding operations;

- Please note: connecting Wallet Connect will not leak your private key to third parties.

You can try scanning their QR codes to get various on-chain information.

Based on ArcBlock Chain, you can scan the QR code on the chain to obtain various information about the DID. This includes the time it first appeared on the chain, its DID type, its account balance, your transactions with the account, and a convenient way for you to add it as a contact or transfer funds to it.

When you scan a DID QR code of an Account/Application:

![2011716303320_.pic.jpg](https://media.arcblock.io/lib/2a/2a14c866e1b88f205d9761ea28f3c0c3.w1600.webp)

When you scan a Factory's DID QR code:

![2001716303318_.pic.jpg](https://media.arcblock.io/lib/ad/ad1a6b700f52b7c24774e592f263c47e.w1600.webp)

When you scan a Token's DID QR code:

![2021716303321_.pic.jpg](https://media.arcblock.io/lib/55/551e907c1091e7530f40531b2f4a6c79.w1600.webp)

When you scan a NFT's DID QR code:

![2031716303322_.pic.jpg](https://media.arcblock.io/lib/4c/4c37e918d95bcf7871b95d0880372156.w1600.webp)

When you scan a Delegate's DID QR code:

![2041716303323_.pic.jpg](https://media.arcblock.io/lib/05/051481c9e7e7760080c3cfae12ce2ff9.w1600.webp)

When you scan a Stake DID QR code:

![2051716303324_.pic.jpg](https://media.arcblock.io/lib/4b/4b5ae7415bc41ed556a6bf389ca520af.w1600.webp)

When scanning a QR code for a transfer request:

- Please make sure you know the account or the account holder.
- Please ensure the amount you want to transfer.

![2061716303325_.pic.jpg](https://media.arcblock.io/lib/9a/9acfeb07d850a37d006dd2ad2a3ca194.w1600.webp)

Based on the EVM chain, you can scan the QR code on the chain to obtain various information about that address. This includes the time of its first appearance on the chain, its DID type, its account balance, ENS, and whether it is on the USDT contract blacklist.

When you scan a normal wallet address:

![2081716303327_.pic.jpg](https://media.arcblock.io/lib/34/34e55c20f819210ac1e432a174a6e9c9.w1600.webp)

When you scan a wallet address that is on the blacklist:

- Please note: It is dangerous to interact with addresses on the blacklist.

![2071716303326_.pic.jpg](https://media.arcblock.io/lib/b4/b4b7ea685df785de3f8e7c731c84d1d9.w1600.webp)is

---

## What if I forget wallet password?

URL: https://www.arcblock.io/en/docs/did-wallet/what-if-i-forget-wallet-password/

The DID wallet is a non-custodial wallet that does not store any information elsewhere. If your password is lost or forgotten, we can <strong>NOT</strong> help you get it back. The only possible option is resetting it with the mnemonic (if you backed up them).

---

## What is DID?

URL: https://www.arcblock.io/en/docs/did-wallet/what-is-did/

The experience and use of decentralized identities implemented by DID technology is very different from traditional digital identities: First of all, you will not only have one DID, but will have numerous DIDs according to the needs of identity occasions. Each DID will give you a separate private channel with life-long encryption to communicate with other individuals, organizations or things. Therefore, you can better choose your identity to communicate and better protect your privacy. The phenomenon of "human flesh" of traditional Internet will no longer occur; DID will be used not only to prove identity, but also to exchange verifiable digital certificates; Best of all, each DID is registered directly on the blockchain or distributed network, without applying to a central registry.

Decentralized identity agreement has been fully supported in DID wallet. Wallet users do not need to pay attention to this detail, and users only need to know that DID wallet can naturally obtain privacy protection, which is not available in other digital wallets.

---

## What is DID wallet？

URL: https://www.arcblock.io/en/docs/did-wallet/what-is-did-wallet/

<strong>DID Wallet</strong> is an advanced digital wallet that supports both centralized identity and digital asset management.

![Image](https://media.arcblock.io/lib/f1/f196ad4969c3abe79ec0aeebe4388d94.w1600.webp)

DID wallet supports ArcBlock Asset Chain, Ethereum, Binance Smart Chain， and Arbitrum. And more other blockchains and layer 2 chains will be supported in the future.

Unlike many other crypto wallets, DID wallet supports multiple blockchains simultaneously, and all the digital assets on multiple blockchains can be managed at the same time.

![Image](https://support.didwallet.io/content/uploads/daad0f9fe4ed9427ec1c054667bfb469.png?imageFilter=resize&w=247&q=75&f=webp)

DID wallet also comes with a rich and extensible in-wallet app that allows you to use the convenience of app extensions without leaving your wallet. Go to the central exchange, cross-chain bridge to all kinds of applications.

![Image](https://support.didwallet.io/content/uploads/5e71be971cc2c262f6b4e2a4a0991e04.png?imageFilter=resize&w=288&q=75&f=webp)

DID wallet also supports multiple connection protocols, so a single wallet can connect to different Web3 applications in a variety of blockchain ecosystems without the hassle of replacement.

![Image](https://support.didwallet.io/content/uploads/453381f1fc563584c017feaa057506cf.png?imageFilter=resize&w=290&q=75&f=webp)![Image](https://support.didwallet.io/content/uploads/acd40ba0cf87ca76b4d42fc0f587f0d6.png?imageFilter=resize&w=290&q=75&f=webp)

---

## What is mnemonic code?

URL: https://www.arcblock.io/en/docs/did-wallet/what-is-mnemonic-code/

Mnemonic is another form of plaintext private key, which was first proposed by BIP39, and its purpose is to help users remember complex private keys.

Mnemonic words are generally composed of 12, 15, 18 and 21 words, all of which are taken from a fixed word base and generated in a certain order according to a certain algorithm, so users do not need to worry about randomly entering 12 words will generate an address. Anyone who gets your mnemonic can easily take your assets, so it's important to keep your mnemonic.

Notes for mnemonic preservation:

1. Use physical backup as far as possible, such as writing on paper with a pen. Do not take screenshots or photos and put them in the device connected to the Internet to prevent hackers from stealing and losing assets;
2. The first preservation must verify the backup of the mnemonic is correct, once copied wrong one or two words, then it will be a great difficulty to find the correct mnemonic;
3. Remember to take good care of the backup mnemonic and take anti-theft measures.

---

## What is revoke waiting period?

URL: https://www.arcblock.io/en/docs/did-wallet/what-is-revoke-waiting-period/

### Revoke Waiting period

On the Arcblock blockchain, revoke a [stake](/en/docs/did-wallet/what-is-stake/)  is divided into two steps:
	1. Initiate a transaction to release the pledge.
	2. After the cooling-off period ends, initiate a transaction to withdraw the assets, and only after the transaction is successful can the assets be withdrawn.

The design of the revoke waiting period is aimed at protecting the system and Blocklets from attacks by malicious actors. Malicious actors may stake the required assets and engage in improper behavior, then immediately revoke the stakes in an attempt to evade punishment. The revoke waiting period makes this evasion behavior more difficult. Blocklets should specify a reasonable revoke waiting period to ensure there is enough time to detect and respond to malicious behavior.

---

## What is slasher?

URL: https://www.arcblock.io/en/docs/did-wallet/what-is-slasher/

### Slasher

The slasher is the account responsible for carrying out the slash operation in the stake. In Arcblock's blockchain [staking](/en/docs/did-wallet/what-is-stake/) system, the slashers must be specified when staking. When a staker attempts to violate the rules or act maliciously, the slashers can confiscate all or part of the assets staked by them. The shashers is usually an operator of a Blocklet or a node staker, whose interests are closely related to maintaining a good trading environment. Therefore, they are motivated to maintain the trading environment and ensure the overall network develops in a positive direction.

The destination of slashed assets is declared by the staking arrangement. It is not automatically the slasher’s account. For Stake for Gas, slashed ABT goes to the community pool; other uses of Stake for X follow their declared rules.

---

## What is stake?

URL: https://www.arcblock.io/en/docs/did-wallet/what-is-stake/

In the Arcblock blockchain system, staking is a way to gain benefits privileges and prevent malicious behavior. Simply put, staking is like temporarily locking your assets in a specific account to gain certain advantages or privileges, while also serving as a deterrent. Specifically, users need to lock some assets into a designated DID account and specify [slashers](/en/docs/did-wallet/what-is-slasher/) and a [revoke waiting period](/en/docs/did-wallet/what-is-revoke-waiting-period/). Staking is similar to a deposit; users can choose to stake a certain amount of ABT tokens to gain the following benefits:

1. [Gas Fee Exemption](/zh/articles/what-is-staking-and-slashing-how-arcblock-move-it-to-the-ne/): By staking ABT tokens, users can enjoy transaction fee exemptions, similar to how banks waive certain service fees for account holders with significant deposits.
2. Application Deployment: When users want to publish their own applications in the Blocklet Store, they also need to stake a certain amount of ABT. This ensures that if the application is found to be malicious, the staked ABT tokens will be forfeited, similar to how a deposit is forfeited if a contract is breached.

   In Blocklets developed on the Arcblock platform, developers can design staking scenarios to offer benefits or discounts to stakers, verify users' asset holdings, or restrict service provision to users to prevent malicious behavior.

### Which Assets Can Be Staked?

Any asset on the Arcblock chain can be staked. This includes native tokens like ABT as well as user-issued NFTs (non-fungible tokens).

### Where Are Staked Assets Stored?

Staked assets are stored in a dedicated address generated based on the DID: ABT protocol. The staked assets cannot be transferred to other accounts and can only be withdrawn by the original account or forfeited by the designated [slasher](/en/docs/did-wallet/what-is-slasher/) account.

### Who Can Unstake Assets?

The account that initiated the staking can unstake assets at any time, but withdrawing the funds requires a [revoke waiting period](/en/docs/did-wallet/what-is-revoke-waiting-period/). This is similar to fixed-term deposits in banks, where funds cannot be withdrawn immediately to prevent hasty withdrawals after malicious actions.

---

## Which chains and tokens are supported?

URL: https://www.arcblock.io/en/docs/did-wallet/which-chains-and-tokens-are-supported/

DID Wallet supports ArcBlock Chain, Ethereum Mainnet, EVM Compatible Chain (like BNB Smart Chain), and more different chains in the future.

### ArcBlock Chain

| Chain Name  | Type  | Supported Tokens  |
|---|---|---|
| ArcBlock Main  | Main  | ArcBlock Chain standard tokens  |
| ArcBlock Beta  | Test  | ArcBlock Chain standard tokens  |

### Ethereum Chain

| Chain Name  | Type  | Supported Tokens  |
|---|---|---|
| Ethereum Mainnet  | Main  | ETH, ERC20 standard tokens, ERC721 tokens  |
| Ethereum Classic  | Main  | ETC, ERC20 standard tokens, ERC721 tokens  |
| Ropsten  | Test  | ROP, ERC20 standard tokens, ERC721 tokens  |
| Rinkeby  | Test  | RIN, ERC20 standard tokens, ERC721 tokens  |
| Goerli  | Test  | GOR, ERC20 standard tokens, ERC721 tokens  |
| Kovan  | Test  | KOV, ERC20 standard tokens, ERC721 tokens  |
| Ethereum Classic Mordor  | Test  | METC, ERC20 standard tokens, ERC721 tokens  |

### EVM Compatible Chain

| Chain Name  | Type  | Supported Tokens  |
|---|---|---|
| Binance Smart Chain  | Main  | BNB、BEP20 standard tokens  |
| Binance Smart Test Chain  | Test  | tBNB、BEP20 standard tokens  |

### Layer2 Chain

| Chain Name  | Type  | Supported Tokens  |
|---|---|---|
| Arbitrum  | Main  | ETH, ERC20 standard tokens  |
| Arbitrum Test Chain  | Test  | ETH, ERC20 standard tokens  |

### Solana Chain

| Chain Name  | Type  | Supported Tokens  |
|---|---|---|
| Solana Mainnet  | Main  | SOL  |
| Solana Devnet  | Test  | SOL  |
| Solana Testnet  | Test  | SOL  |

---

## Why wallet has multiple addresses?

URL: https://www.arcblock.io/en/docs/did-wallet/why-wallet-has-multiple-addresses/

When a new DID Wallet is initialized, there are three addresses by default. Respectively is:

- Default DID address
- The Ethereum address generated by the default DID derivation rule
- The Ethereum address generated by ethereum derivation rule

Let's go through them one by one.

### Default DID address

1. The seeds generated by the wallet's mnemonic are generated based on the `m/44'/260'/S1'/S2'/0` derivation rules, see the detail generation rules [Create Extended DID](https://github.com/ArcBlock/abt-did-spec#create-extended-did)
2. Generate the DID KeyPair and generate the DID address based on the generated private key.

### The Ethereum address generated by the default DID derivation rule

1. Step 1 is exactly the same as step 1 above
2. ECKeyPair is generated based on the generated private key and an Ethereum address is generated from it

### The Ethereum address generated by ethereum derivation rule

1. The seed generated with the wallet's mnemonic generates ECKeyPair based on the `m/44'/60'/0'/0/0` derivation rule
2. Generate the Ethereum address using ECKeyPair

> You will also see this address when you use the wallet's mnemonic to recover in other wallets.
>

In the future, as you use the wallet to interact with different ArcBlock ecosystem applications via DID Connect, more addresses will be generated, and those addresses will generate similar derived rules.

## So why does a DID wallet generate multiple addresses?

Current mainstream wallet only one basic default address of Ethereum, in this case, when you use your wallet to respectively and the application A, B connection, when some record on the chain, so because the data chain is open, then your visit record is open, this will cause your access behavior are analyzed using, thus privacy leak.

The implementation scheme of DID wallet is to derive rules based on DID address, add the unique identifier of the application with the same seed, and automatically generate the corresponding account address (including the public and private key pair behind) and application interaction every time the wallet connects with different applications. In this way, different apps are isolated from each other, and the data on the chain does not show that two addresses are from the same wallet, thus ensuring user privacy.

---

## AIGNE DocSmith

URL: https://www.arcblock.io/en/docs/docsmith/

---

## Configuration Reference

URL: https://www.arcblock.io/en/docs/docsmith/configuration-21ae40/

The `config.yaml` file is the core control panel for your documentation generation. By adjusting its settings, you can control how AI generates documentation, including document structure, content style, and language support. This guide provides detailed explanations for each configuration field to help you fine-tune according to your project needs.

## Overview

The `config.yaml` file is the primary configuration file for AIGNE DocSmith. It stores all configuration parameters in YAML format. When you run commands such as `create`, `update`, or `translate`, DocSmith reads this file to understand your configuration requirements.

- <strong>File name:</strong> `config.yaml`
- <strong>Location:</strong> `.aigne/doc-smith/config.yaml` (relative to your project root)
- <strong>Format:</strong> YAML (UTF-8)

Through this file, you can set documentation goals, target readers, content generation rules, document structure, multilingual support, and publishing settings.

### Creating and Updating Configuration

The `config.yaml` file is automatically created when you first use DocSmith.

<strong>Creating:</strong>

You can create this file in two ways:

::::steps
:::step{title="During initial generation:"}
Running `aigne doc create` in a new project will launch an interactive wizard to create the `config.yaml` file before starting the generation process.
:::

:::step{title="Create separately:"}
Running `aigne doc init` will launch the same wizard to create the configuration file without immediately generating documentation.
:::
::::

**aigne doc init**

```sh
aigne doc init
```

<strong>Updating:</strong>

You can update your configuration using one of the following methods:

::::steps
:::step{title="Edit the file directly:"}
Open `.aigne/doc-smith/config.yaml` in a text editor and modify the fields.
:::

:::step{title="Use the interactive wizard:"}
Run `aigne doc init` again. The wizard will load your existing settings and guide you through updates.
:::
::::

## Configuration Parameters

Fields in `config.yaml` are organized by functional groups. The following sections explain each parameter in detail.

### Project Basics

These fields define basic project information used for document branding, search engine optimization, and social media sharing.

- **projectName** `string` *(required)* — The display name of your project, which appears in document titles, navigation bars, and other branding elements. It is recommended to keep it under 50 characters to ensure it displays completely in various interfaces.
- **projectDesc** `string` *(required)* — A brief description of your project, used for search engine optimization and social sharing preview text. It is recommended to keep it under 150 characters, clearly and concisely describing the core value of your project.
- **projectLogo** `string` — The URL or local file path to your project logo. The logo will be displayed in document website headers, browser tab icons, and social media sharing previews. Supports full URLs (e.g., https://example.com/logo.png) or relative paths (e.g., ./assets/logo.png).

### AI Thinking Configuration

These settings control the depth of AI thinking and processing intensity when generating document content, affecting the balance between generation quality and speed.

- **thinking** `object` — Configure AI reasoning intensity.
  - **effort** `string` (default: `standard`) — Control AI thinking intensity. Options: lite (fast mode, suitable for simple documentation), standard (standard mode, recommended for most scenarios), pro (deep mode, suitable for complex documentation but with longer generation times).

### Documentation Strategy

These settings define documentation generation strategy, including document goals, reader types, content depth, etc., directly affecting how AI organizes and generates content.

- **documentPurpose** `array` *(required)* — Define the primary goals of the documentation (multiple selection allowed). Options include: getStarted (quick start guide), completeTasks (task operation manual), findAnswers (reference query manual), understandSystem (system understanding documentation), solveProblems (troubleshooting guide), and mixedPurpose (comprehensive documentation). Choosing different goals affects document structure and content organization.
- **targetAudienceTypes** `array` *(required)* — Specify target reader types (multiple selection allowed). Options include: endUsers (general users), developers (developers), devops (operations engineers), decisionMakers (technical decision makers), supportTeams (technical support teams), and mixedTechnical (mixed technical backgrounds). Choosing different reader types affects document language style, technical depth, and example types.
- **readerKnowledgeLevel** `string` *(required)* — Set the technical knowledge level of target readers. Options include: completeBeginners (complete novices, need detailed explanations), domainFamiliar (familiar with related domains but first-time users of this tool), experiencedUsers (experienced users, need reference manuals), emergencyTroubleshooting (emergency troubleshooting, need quick solutions), and exploringEvaluating (evaluating suitability, need quick understanding).
- **documentationDepth** `string` *(required)* — Control the level of detail in documentation. Options include: essentialOnly (core features only, concise version), balancedCoverage (balanced coverage, recommended for most projects), comprehensive (comprehensive coverage, including all features and edge cases), and aiDecide (automatically decided by AI based on code complexity).
- **targetAudience** `string` — A detailed description of target readers, used to supplement targetAudienceTypes settings. Can describe readers' specific backgrounds, use cases, tech stacks, or special requirements. Supports multi-line text, helping AI better understand reader needs.
- **rules** `string` — Provide detailed generation rules and guidance for AI, including content structure, writing style, format requirements, etc. This is one of the most important configuration fields, directly affecting the quality and style of generated documentation. Supports Markdown format, allowing multi-line rules. It is recommended to specify your specific requirements in detail, such as: "avoid using vague words", "must include code examples", etc.

### Language

Configure the primary language and any additional languages for translation.

- **locale** `string` (default: `en`) — The primary language of the documentation, using standard language codes. Common values include: en (English), zh (Simplified Chinese), zh-TW (Traditional Chinese), ja (Japanese), etc. Documentation will first be generated in this language, then can be translated to other languages.
- **translateLanguages** `array` — A list of target languages for translation (multiple selection allowed). Each language code will generate a complete set of translated documentation. For example, setting ["zh", "ja"] will generate Simplified Chinese and Japanese versions of the documentation. Note: Do not include language codes that are the same as locale.

### Data Sources

These settings specify the reference materials used by AI when analyzing source code and documentation, directly affecting the quality and accuracy of generated documentation.

- **sourcesPath** `array` *(required)* — A list of source code and documentation paths for AI analysis. This is the most important configuration field because AI will only generate documentation based on content in these paths. It is recommended to include: README files, main source code directories, configuration files (such as package.json, aigne.yaml), existing documentation directories, etc. Supports multiple formats: directory paths (e.g., ./src), file paths (e.g., ./README.md), glob patterns (e.g., src/**/*.js), and remote URLs.

### Output and Deployment

Configure the save location for generated documentation and the publishing address.

- **docsDir** `string` (default: `./aigne/doc-smith/docs`) — The directory where generated documentation is saved. All generated Markdown files will be saved in this directory. If the directory does not exist, DocSmith will automatically create it. It is recommended to use relative paths for easier project migration.
- **appUrl** `string` — The access address after documentation is published. After running the publish command, DocSmith will automatically update this field. Usually does not need to be set manually unless you want to specify a particular publishing address.

### Media and Display

These settings control how media assets such as images are handled.

- **media** `object` — Media file processing settings.
  - **minImageWidth** `integer` (default: `800`) — Minimum width (in pixels) for images to be included in documentation. Only images wider than this value will be used, helping to filter out low-quality or too-small images. Recommended values: 600-800 pixels (balance quality and quantity), 800-1000 pixels (high-quality requirements).

### Diagramming Configuration

Control diagram generation behavior and AI effort level.

- **diagramming** `object` — Diagram generation configuration.
  - **effort** `integer` (default: `5`) — AI effort level when generating diagrams, range 0-10. Higher values result in fewer diagrams. Recommended settings: 0-3 (generate many diagrams, suitable for documentation requiring rich visual explanations), 4-6 (balanced mode, recommended), 7-10 (generate few diagrams, focus more on text content).

### System-Managed Fields

These fields are automatically managed by DocSmith and generally do not require manual editing. Modifying these fields may cause unexpected issues.

- **lastGitHead** `string` — The Git commit hash from the last documentation generation. DocSmith uses this value to determine which files have changed, enabling incremental updates. Do not modify manually.
- **boardId** `string` — The unique identifier for the documentation publishing board, automatically generated by the system. Do not modify manually, otherwise it will disconnect the project from its publishing history and may lose published documentation.
- **checkoutId** `string` — A temporary identifier used during document deployment, automatically managed by the system. Do not modify manually.
- **shouldSyncBranding** `string` — A temporary variable controlling whether to sync branding, automatically managed by the system. Do not modify manually.

## Applying Changes

After modifying the `config.yaml` file, you need to run the corresponding commands for the changes to take effect. Different fields require different commands, as shown in the table below.

| Field  | Command to Apply Changes  | Description  |
|---|---|---|
| `documentPurpose`, `targetAudienceTypes`, `readerKnowledgeLevel`, `documentationDepth`, `locale`  | `aigne doc clear && aigne doc create`  | These fields affect the overall document structure and require clearing old documentation and regenerating.  |
| `rules`, `targetAudience`, `media.minImageWidth`, `thinking.effort`, `diagramming.effort`  | `aigne doc update`  | These fields only affect content generation methods and can directly update existing documentation without regeneration.  |
| `sourcesPath`  | `aigne doc clear && aigne doc create` or `aigne doc update`  | After adding new data sources, you can choose to fully regenerate or incrementally update. It is recommended to use `create` when adding for the first time, and `update` for subsequent additions.  |
| `translateLanguages`  | `aigne doc translate`  | After adding new translation languages, run this command to generate documentation versions in the corresponding languages.  |
| `projectName`, `projectDesc`, `projectLogo`, `appUrl`  | `aigne doc publish`  | These fields are mainly used for metadata during publishing. After modification, republish to take effect.  |
| `docsDir`  | `aigne doc create`  | After modifying the output directory, the next documentation generation will save to the new directory.  |

## Complete Configuration Example

Below is the complete `config.yaml` file from the AIGNE DocSmith project itself, demonstrating a real-world configuration.

**config.yaml**

```yaml
# Project information for documentation publishing
projectName: AIGNE DocSmith
projectDesc: AIGNE DocSmith is a powerful, AI-driven documentation creation tool built on the AIGNE Framework. It automates the creation of detailed, structured, and multi-language documentation directly from your source code.
projectLogo: https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg

# =============================================================================
# Documentation Configuration
# =============================================================================

# Purpose: What's the main outcome you want readers to achieve?
documentPurpose:
  - getStarted
  - completeTasks

# Target Audience: Who will be reading this most often?
targetAudienceTypes:
  - endUsers

# Reader Knowledge Level: What do readers typically know when they arrive?
readerKnowledgeLevel: completeBeginners

# Documentation Depth: How comprehensive should the documentation be?
documentationDepth: comprehensive

# Custom Rules: Define specific documentation generation rules and requirements
rules: |
  Avoid using vague or empty words that don't provide measurable or specific details, such as 'intelligently', 'seamlessly', 'comprehensive', or 'high-quality'. Focus on concrete, verifiable facts and information.
  Focus on concrete, verifiable facts and information.
  Must cover all subcommands of DocSmith

# Target Audience: Describe your specific target audience and their characteristics
targetAudience: |

locale: en
translateLanguages:
  - zh
  - zh-TW
  - ja
docsDir: .aigne/doc-smith/docs
sourcesPath:
  - ./README.md
  - ./CHANGELOG.md
  - ./aigne.yaml
  - ./agents
  - ./.aigne/doc-smith/config.yaml
  - ./assets/screenshots
lastGitHead: d9d2584f23aee352485f369f60142949db601283
# ⚠️ Warning: boardId is auto-generated by system, please do not edit manually
boardId: "docsmith"
appUrl: https://docsmith.aigne.io
# Checkout ID for document deployment service
checkoutId: ""

diagramming:
  effort: 5 # AI effort level for diagramming, 0-10, large is less diagram
# AI Thinking Configuration
# thinking.effort: Determines the depth of reasoning and cognitive effort the AI uses when responding, available options:
#   - lite: Fast responses with basic reasoning
#   - standard: Balanced speed and reasoning capability
#   - pro: In-depth reasoning with longer response times
thinking:
  effort: standard
# Should sync branding for documentation
shouldSyncBranding: ""
```

## Summary

The `config.yaml` file is the core of controlling documentation generation. By properly configuring project information, documentation strategy, and data sources, you can guide AI to generate high-quality documentation that meets your project needs. It is recommended to start with basic configuration and gradually adjust parameters based on actual results.

---

## Initial Setup

URL: https://www.arcblock.io/en/docs/docsmith/configuration-initial-setup-21ae40/

This guide provides a step-by-step walkthrough of the interactive setup process for AIGNE DocSmith. This procedure runs automatically the first time you execute `aigne doc create`, but you can also start it manually. The goal is to create a `config.yaml` file, which stores your preferences for generating documents.

## How to Start the Setup Process

To begin the configuration manually, navigate to your project's root directory in a terminal and run the following command:

**aigne doc init**

```sh
aigne doc init
```

This command starts a 9-step interactive questionnaire to configure your documents settings.

## Configuration Steps

The setup process will prompt you with a series of questions. The following sections detail each step.

### Step 1: Define Document Purpose

The first step is to establish the primary goals for your documents. This selection influences the tone, structure, and focus of the generated content.

<strong>Prompt:</strong> `📝 [1/9]: What should your documents help readers achieve?`

You can select one or more options from the following list:

| Option  | Name  | Description  |
|---|---|---|
| `getStarted`  | Get started quickly  | Help new users go from zero to working in under 30 minutes.  |
| `completeTasks`  | Complete specific tasks  | Guide users through common workflows and use cases.  |
| `findAnswers`  | Find answers fast  | Provide a searchable reference for all features and APIs.  |
| `understandSystem`  | Understand the system  | Explain how it works and the reasoning behind design decisions.  |
| `solveProblems`  | Solve problems  | Help users troubleshoot and fix issues.  |
| `mixedPurpose`  | Mix of above  | Cover multiple needs comprehensively.  |

### Step 2: Identify Target Audience

Next, specify the primary readers of your documents. This helps to adjust the language and technical depth to an appropriate level.

<strong>Prompt:</strong> `👥 [2/9]: Who will be reading your documents?`

You may select multiple audiences from this list:

| Option  | Name  | Description  |
|---|---|---|
| `endUsers`  | End users (non-technical)  | People who use the product but do not write code.  |
| `developers`  | Developers integrating  | Engineers adding the product to their projects.  |
| `devops`  | DevOps/Infrastructure  | Teams deploying, monitoring, and maintaining systems.  |
| `decisionMakers`  | Technical decision makers  | Architects or leads evaluating the technology for implementation.  |
| `supportTeams`  | Support teams  | People helping others use the product.  |
| `mixedTechnical`  | Mixed technical audience  | A combination of developers, DevOps, and other technical users.  |

### Step 3: Specify Reader Knowledge Level

Indicate the assumed knowledge level of your audience. This ensures the content is presented effectively, avoiding information that is either too basic or too complex.

<strong>Prompt:</strong> `🧠 [3/9]: How much do your readers already know about your project?`

Select the option that best describes your readers:

| Option  | Name  | Description  |
|---|---|---|
| `completeBeginners`  | Complete beginners  | New to the domain or technology entirely.  |
| `domainFamiliar`  | Domain-familiar, tool-new  | Know the problem space but are new to this specific solution.  |
| `experiencedUsers`  | Experienced users  | Regular users who need reference material or advanced topics.  |
| `emergencyTroubleshooting`  | Emergency/troubleshooting  | Users who have encountered a problem and need to fix it quickly.  |
| `exploringEvaluating`  | Exploring/evaluating  | Users trying to determine if the tool fits their needs.  |

### Step 4: Set Document Depth

Choose how detailed the documents should be. This parameter determines the scope and level of detail in the generated content.

<strong>Prompt:</strong> `📊 [4/9]: How detailed should your documents be?`

Select one of the following levels:

| Option  | Name  | Description  |
|---|---|---|
| `essentialOnly`  | Essential only  | Covers the most common 80% of use cases concisely.  |
| `balancedCoverage`  | Balanced coverage  | Provides good depth with practical examples.  |
| `comprehensive`  | Comprehensive  | Covers all features, edge cases, and advanced scenarios.  |
| `aiDecide`  | Let AI decide  | The tool analyzes code complexity to suggest an appropriate depth.  |

### Step 5: Select Primary Language

Choose the main language for your documents. The system will detect your operating system's language and suggest it as the default.

<strong>Prompt:</strong> `🌐 [5/9]: What is the main language of your documents?`

You can select from a list of 12 supported languages, including English, Chinese (Simplified), and Spanish.

### Step 6: Choose Translation Languages

Select any additional languages into which you want the documents to be translated.

<strong>Prompt:</strong> `🔄 [6/9]: What languages should we translate to?`

You can choose multiple languages from the supported options, excluding the primary language selected in the previous step.

### Step 7: Define Document Directory

Specify the folder where the created document files will be saved.

<strong>Prompt:</strong> `📁 [7/9]: Where should we save your documents?`

The default path is `.aigne/doc-smith/docs`. You can accept this default or provide a different path.

### Step 8: Specify Content Sources

Indicate which files, folders, or URLs the tool should analyze to generate documents. You can add multiple paths and use glob patterns for more specific file matching.

<strong>Prompt:</strong> `🔍 [8/9]: Data Sources`

You will be prompted to enter file paths (e.g., `./src`), glob patterns (e.g., `src/**/*.js`), or URLs (e.g., `https://example.com/openapi.yaml`). If no paths are provided, the tool will analyze the entire project directory by default.

### Step 9: Provide Custom Rules

This optional step allows you to provide specific instructions or constraints for the AI to follow during content creation.

<strong>Prompt:</strong> `📋 [9/9]: Do you have any custom rules or requirements for your documents? (Optional, press Enter to skip)`

You can input any requirements, such as tone, style, or content to exclude. For example: "Focus on technical accuracy and avoid marketing terminology."

## The config.yaml File

After you answer all the questions, DocSmith saves your responses to a configuration file named `config.yaml`, located in the `.aigne/doc-smith/` directory of your project. This file acts as the blueprint for all future document creation and can be manually edited at any time.

Below is an example of a generated `config.yaml` file:

**config.yaml**

```yaml
# Project information for documentation publishing
projectName: AIGNE DocSmith
projectDesc: AIGNE DocSmith is a powerful, AI-driven documentation creation tool...
projectLogo: https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg

# AI Thinking Configuration
thinking:
  effort: standard

# =============================================================================
# Documentation Configuration
# =============================================================================

# Purpose: What's the main outcome you want readers to achieve?
documentPurpose:
  - getStarted
  - completeTasks

# Target Audience: Who will be reading this most often?
targetAudienceTypes:
  - endUsers

# Reader Knowledge Level: What do readers typically know when they arrive?
readerKnowledgeLevel: completeBeginners

# Documentation Depth: How comprehensive should the documentation be?
documentationDepth: comprehensive

# Custom Rules: Define specific documentation creation rules and requirements
rules: |
  Avoid using vague or empty words that don't provide measurable or specific details...

# Target Audience: Describe your specific target audience and their characteristics
targetAudience: |

# Language settings
locale: en
translateLanguages:
  - zh
  - zh-TW
  - ja

# Paths
docsDir: ./docs  # The directory where the created documents will be saved.
sourcesPath:  # The source code paths to analyze.
  - ./README.md
  - ./agents

# Image filtering settings
media:
  minImageWidth: 800
```

## Summary and Next Steps

Once the setup is complete, you will see a confirmation message displaying the path to your new configuration file.

![Setup Complete](https://media.arcblock.io/lib/docsmith/screenshots/doc-complete-setup.png)

With your initial configuration saved, you are now prepared to create your documents.

::::card-group
::link-card{title="Create Document" description="Learn how to run the creation process to create your first set of documents." icon="file-text" href="/en/docs/docsmith/guides-generating-documentation-21ae40/"}
::link-card{title="Manage Preferences" description="Find out how to view and modify your saved configuration at any time." icon="settings" href="/en/docs/docsmith/configuration-managing-preferences-21ae40/"}
::::

---

## Manage Preferences

URL: https://www.arcblock.io/en/docs/docsmith/configuration-managing-preferences-21ae40/

Have you ever wished your AI assistant would remember your instructions? This guide explains how to view, remove, and toggle your saved preferences for document creation, giving you fine-grained control over the AI's output and ensuring it consistently follows your project's specific style.

When you generate or update documents, you can provide feedback using the `--feedback` flag. This feedback is saved as a "preference" to be reused in future sessions, ensuring the AI maintains consistency with your previous instructions. The `aigne doc prefs` command provides a direct way to manage these saved preferences.

This guide details how to list, remove, and toggle the active status of your saved preferences. The diagram below illustrates the workflow for managing these preferences.

![Manage Preferences](https://media.arcblock.io/lib/75/75933ac1d3e173e0.w1600.webp)

## Viewing Saved Preferences

To review all saved preferences, use the `--list` flag. This command displays each preference with its status, scope, unique ID, and content.

```bash
aigne doc prefs --list
```

### Understanding the Output

The list is formatted to provide clear information about each preference rule:

- <strong>Status</strong>: Indicates if a preference is active or inactive.
-
  - `🟢`: Active. The rule will be applied during documentation creation.
  - `⚪`: Inactive. The rule is saved but will be ignored.
- <strong>Scope</strong>: The context in which the preference applies (e.g., `global`, `document`).
- <strong>ID</strong>: A unique identifier for the preference, used for removing or toggling.
- <strong>Paths</strong>: If the preference applies only to specific files, their paths are listed here.
- <strong>Rule Content</strong>: The text of the preference rule itself.

<strong>Example Output:</strong>

```
# User Preferences

**Format explanation:**
- 🟢 = Active preference, ⚪ = Inactive preference
- [scope] = Preference scope (global, structure, document, translation)
- ID = Unique preference identifier
- Paths = Specific file paths (if applicable)

🟢 [document] pref_a1b2c3d4e5f6a7b8 | Paths: /guides/generating-documentation.md
   Focus on concrete, verifiable facts and information. Avoid using vague or empty words that don't provide measurable or specific d...

⚪ [global] pref_b8a7f6e5d4c3b2a1
   Use a formal and academic tone throughout the documentation.
```

## Removing Preferences

When a preference is no longer needed, you can permanently delete it using the `--remove` flag. You can remove preferences either by specifying their IDs or through an interactive menu.

### Interactive Mode (Beta)

To select preferences from a list, run the command without any IDs. This will open an interactive prompt where you can check the items you wish to delete.

```bash
aigne doc prefs --remove
```

A checklist will appear, allowing you to select one or more preferences. This is the recommended method for ensuring you remove the correct items.

### Direct Mode

If you already know the unique IDs of the preferences you want to remove, you can specify them using the `--id` flag. This is faster if you are certain about which items to delete.

```bash
# Remove a single preference
aigne doc prefs --remove --id pref_a1b2c3d4e5f6a7b8

# Remove multiple preferences
aigne doc prefs --remove --id pref_a1b2c3d4e5f6a7b8 --id pref_b8a7f6e5d4c3b2a1
```

## Toggling Preferences

Instead of permanently deleting a preference, you can temporarily enable or disable it. This is useful when you want to suspend a rule for a specific task without losing it. Use the `--toggle` flag to change a preference's active status.

### Interactive Mode (Beta)

Running the command without IDs will launch an interactive checklist, similar to the remove command.

```bash
aigne doc prefs --toggle
```

You can select the preferences you wish to activate or deactivate. The status icon (`🟢`/`⚪`) will update to reflect the new state.

### Direct Mode

To toggle specific preferences directly, use the `--id` flag.

```bash
# Toggle a single preference
aigne doc prefs --toggle --id pref_a1b2c3d4e5f6a7b8

# Toggle multiple preferences
aigne doc prefs --toggle --id pref_a1b2c3d4e5f6a7b8 --id pref_b8a7f6e5d4c3b2a1
```

By managing your preferences, you can maintain fine-grained control over the document creation process, ensuring that the output consistently aligns with your project's specific requirements and style.

---

## Troubleshooting

URL: https://www.arcblock.io/en/docs/docsmith/configuration-troubleshooting-21ae40/

This guide helps you diagnose and fix common issues when using AIGNE DocSmith. If you encounter problems during generation, publishing, or configuration, please check the solutions for the following scenarios.

## Configuration Issues

### Issue 1: Configuration File Format Error

<strong>Error messages:</strong>

```
Error: Failed to parse config file: Implicit map keys need to be followed by map values at line 112, column 1:

lastGitHead: d9d2584f23aee352485f369f60142949db601283
appUrl： https://docsmith.aigne.io
```

```
Error: Failed to parse config file: Map keys must be unique at line 116, column 1:

docsDir: .aigne/doc-smith/docs
appUrl: https://docsmith.aigne.io
^
```

<strong>Possible causes:</strong> YAML syntax errors in the configuration file, common issues include:

- Using tabs instead of spaces for indentation
- Using Chinese colons（：）instead of English colons（:）
- Missing necessary quotes
- Duplicate configuration items

<strong>Solutions:</strong>

1. Check the line number in the error message to locate the problem
2. Verify that the indentation is correct (use spaces, not tabs)
3. Ensure colons are English half-width colons（:）, not Chinese full-width colons（：）
4. Use an online YAML validator to check syntax
5. After fixing, run `aigne doc publish` again

> <strong>Tip:</strong> In addition to fixing configuration file format errors, if certain parameters are not correctly configured, the system will automatically use default values, which will not affect basic functionality.
>

## Generation Issues

### Issue 2: Generated Content Doesn't Meet Expectations

<strong>You may encounter:</strong>

- Generated content tone doesn't match your requirements
- Document structure doesn't match your expectations
- Missing some important information

<strong>Possible causes:</strong>

1. The `rules` description in the configuration is not detailed or clear enough
2. `targetAudienceTypes` settings don't match the actual target audience
3. Too few or irrelevant reference documents in `sourcesPath`

<strong>How to fix:</strong>

1. <strong>Enrich</strong> <strong>`rules`</strong><strong>:</strong> Add detailed guidance in `config.yaml`: ```yaml rules: |   ### Documentation Structure Requirements   1. Each document must include:      * Clear title and overview      * Step-by-step instructions      * Code examples where applicable      * Troubleshooting section      ### Content Tone   - Use clear, concise language   - Include concrete data and examples   - Avoid marketing terminology   - Focus on actionable information ```
2. <strong>Adjust audience:</strong> Ensure `targetAudienceTypes` matches the actual audience: ```yaml targetAudienceTypes:   - endUsers      # For end users   - developers     # For technical audience ```
3. <strong>Add more sources:</strong> Include relevant documents in `sourcesPath`: ```yaml sourcesPath:   - ./README.md   - ./docs   - ./CHANGELOG.md   - ./src   - ./package.json ```

### Issue 3: Low Quality or Missing Images

<strong>You may encounter:</strong>

- Images in generated documentation are not clear enough
- Expected images don't appear

<strong>Cause:</strong> The `media.minImageWidth` setting value is too high, filtering out some images.

<strong>How to fix:</strong>

1. Open the `config.yaml` file and find the `media` configuration: ```yaml media:   minImageWidth: 800  # Current threshold ```
2. Adjust this value according to your needs:
3.
  - <strong>400-600</strong>: Will include more images, but may include some lower quality images
  - <strong>600-800</strong>: Balanced quality and quantity (recommended setting)
  - <strong>800-1000</strong>: Only high-quality images, fewer in number
4. After saving the file, run the update command: ```bash aigne doc update ```

### Issue 4: Missing or Incomplete Documentation

<strong>You may encounter:</strong>

- Some expected documents are not generated
- Generated documents are incomplete

<strong>Possible causes:</strong>

1. `sourcesPath` doesn't include all necessary source files
2. Source files are not accessible or have permission issues
3. `documentationDepth` is set too low

<strong>How to fix:</strong>

1. <strong>Check source paths:</strong> Verify all necessary files are included: ```yaml sourcesPath:   - ./README.md   - ./src              # Include source code directories   - ./docs             # Include existing documentation   - ./package.json      # Include configuration files ```
2. <strong>Increase documentation depth:</strong> If you need comprehensive documentation: ```yaml documentationDepth: comprehensive  # Instead of essentialOnly ```
3. <strong>Verify file permissions:</strong> Ensure DocSmith has read access to all files in `sourcesPath`

## Translation Issues

### Issue 5: Translation Fails or Produces Poor Quality

<strong>You may encounter:</strong>

- Translation command fails
- Translated content has poor quality or errors

<strong>Possible causes:</strong>

1. `locale` and `translateLanguages` have conflicting settings
2. Source documentation has syntax errors
3. Network issues during translation

<strong>How to fix:</strong>

1. <strong>Check language settings:</strong> Ensure `translateLanguages` doesn't include the same language as `locale`: ```yaml locale: en translateLanguages:   - zh        # OK   - ja        # OK   # - en      # ❌ Don't include locale language ```
2. <strong>Fix source documentation:</strong> Ensure source documents are valid before translation: ```bash # First verify source documents are correct aigne doc create  # Then translate aigne doc translate ```
3. <strong>Retry translation:</strong> If network issues occur, simply run the command again: ```bash aigne doc translate ```

## Publishing Issues

### Issue 6: Publishing Fails with Invalid URL Error

<strong>Error message:</strong>

```
Error: ⚠️  The provided URL is not a valid ArcBlock-powered website

💡 Solution: To host your documentation, you can get a website from the ArcBlock store:
```

<strong>Cause:</strong> The `appUrl` in the configuration is empty or points to an invalid website address.

<strong>How to fix:</strong> Set the correct deployment address in `config.yaml`:

```yaml
# Enter your website address
appUrl: https://your-site.user.aigne.io

# If you don't have a website yet, you can leave this empty for now
# appUrl: ""
```

Alternatively, you can specify the URL when publishing:

```bash
aigne doc publish --appUrl https://your-docs-website.com
```

### Issue 7: Publishing Fails with Authorization Error

<strong>Error messages:</strong>

```
❌ Publishing failed due to an authorization error:
💡 Please run aigne doc clear to reset your credentials and try again.
```

```
❌ Publishing failed due to an authorization error:
💡 You're not the creator of this document (Board ID: docsmith). You can change the board ID and try again.
💡  Or run aigne doc clear to reset your credentials and try again.
```

<strong>Cause:</strong> Your login credentials have expired or you don't have permission to publish to the specified board.

<strong>How to fix:</strong> Run the following commands in order:

```bash
# First clear old authorization information
aigne doc clear

# Then republish, the system will prompt you to log in again
aigne doc publish
```

When running `aigne doc clear`, select to clear authentication tokens. Afterward, run `aigne doc publish` again and you will be prompted to re-authenticate.

### Issue 8: Publishing Fails Due to Network Issues

<strong>Error message:</strong>

```
❌ Could not connect to: https://your-site.com

Possible causes:
• There may be a network issue.
• The server may be temporarily unavailable.
• The URL may be incorrect.

Suggestion: Please check your network connection and the URL, then try again.
```

<strong>How to fix:</strong>

1. <strong>Check network connection:</strong> Ensure your network can access the target URL
2. <strong>Verify URL:</strong> Confirm the `appUrl` is correct and accessible
3. <strong>Retry:</strong> Network issues are often temporary, try again after a few moments: ```bash aigne doc publish ```

## How to Recover

### Method 1: Using Git to Restore

If you use Git to manage your code, you can quickly restore to a previously working configuration:

```bash
# Stash current changes
git stash
```

Then regenerate documentation:

```bash
aigne doc create
```

> <strong>Tip:</strong> If you want to restore the stashed changes later, you can run `git stash pop`
>

### Method 2: Clear and Regenerate

If you encounter issues that cannot be located, you can clear all generated files and regenerate from scratch:

```bash
# Clear all generated files, then regenerate
aigne doc clear && aigne doc create
```

> <strong>Note:</strong> This will delete all generated content, but will not affect your configuration file. After execution, the system will regenerate documentation based on the current configuration.
>

### Method 3: Reset Configuration

If configuration issues persist, you can reset the configuration file:

```bash
# Clear configuration (select config file when prompted)
aigne doc clear

# Then reinitialize
aigne doc init
```

> <strong>Warning:</strong> This will remove your current configuration. Make sure to back up important settings before proceeding.
>

## Best Practices

Here are some practical suggestions to help you avoid common issues:

::::steps
:::step{title="Save modification history:"}
If using Git, commit after each configuration file modification so you can easily revert to previous versions if problems occur
:::

:::step{title="Backup before modifying:"}
Before modifying important configurations, copy the configuration file as a backup, just in case
:::

:::step{title="Test immediately after modification:"}
After each configuration modification, immediately run `aigne doc create` or `aigne doc update` to test, so problems can be discovered early
:::

:::step{title="Check format correctness:"}
After modifying YAML files, use online tools to check if the format has errors
:::

:::step{title="Start simple:"}
Start with the simplest configuration, confirm everything works, then gradually add more complex features
:::

:::step{title="Record your modifications:"}
Simply record what you modified each time and why, making it easier to find the cause when problems occur later
:::

:::step{title="Keep sources updated:"}
Regularly update `sourcesPath` to include new source files and documentation
:::

:::step{title="Review generated content:"}
After generation, review the output to ensure it meets expectations before publishing
:::
::::

## Getting More Help

If the above methods cannot solve your problem, you can try:

::::steps
:::step{title="Consult configuration documentation:"}
Check [Configuration Reference](/en/docs/docsmith/configuration-21ae40/) to understand detailed explanations of each configuration item
:::

:::step{title="Check command documentation:"}
Refer to command documentation to understand detailed usage of commands
:::

:::step{title="Review error logs:"}
Carefully read the error messages displayed in the terminal, which usually contain specific hints
:::

:::step{title="Use AIGNE Observability:"}
Use the AIGNE Observability tool described below to get detailed execution records
:::

:::step{title="Seek community help:"}
Visit [AIGNE Community](https://community.arcblock.io/discussions/boards/aigne) to ask questions, other users or developers may help you
:::
::::

## Using AIGNE Observability for Troubleshooting

When you encounter complex issues that require in-depth troubleshooting, or need to report problems to the community, you can use <strong>AIGNE Observability</strong>. It records every step of the execution process in detail, helping you or technical support quickly locate the problem.

### Starting the Observability Server

Run the following command to start the local Observability server:

**Start Observability Server**

```bash
aigne observe
```

You will see output showing:

- Database path: Where tracking data is saved
- Server address: Open this address in your browser to view the Observability dashboard

![Observability Command](https://media.arcblock.io/lib/docsmith/screenshots/doc-aigne-observe.png)

### Viewing Execution Records

1. <strong>Open the dashboard:</strong> Click the server address shown in the output, or open it in your browser
2. <strong>View operation records:</strong> The dashboard will display all DocSmith operations, including:
3.
  - Input and output data
  - Time spent on each step
  - Executed operation steps and results
  - Detailed error messages

![Observability Dashboard](https://media.arcblock.io/lib/docsmith/screenshots/doc-observe-dashboard.png)

### Using Observability to Report Issues

When reporting problems to the community:

1. <strong>Capture tracking:</strong> Keep the Observability server running during the problematic operation
2. <strong>Export tracking data:</strong> Export relevant execution records from the dashboard
3. <strong>Report the issue:</strong> Visit [AIGNE Community](https://community.arcblock.io/discussions/boards/aigne) and include:
4.
  - Problem description
  - Reproduction steps
  - Exported tracking file
  - Your configuration (if relevant)

> <strong>Tip:</strong> Tracking records contain complete information about DocSmith execution, including every operation and result. Providing this information to technical support or the community can greatly improve problem resolution efficiency.
>

---

## Getting Started

URL: https://www.arcblock.io/en/docs/docsmith/getting-started-21ae40/

This guide provides a direct, step-by-step procedure for installing AIGNE DocSmith and generating your first set of documents. The process is designed to be completed in a few minutes, enabling you to produce documents from your project files with minimal setup.

The following diagram illustrates the key steps from installation to creation:

![Getting Started](https://media.arcblock.io/lib/27/270289d6986d30a7.w1600.webp)

## Prerequisites

Before proceeding with the installation, ensure your system meets the following requirement:

- <strong>Node.js</strong>: Version 20 or newer is required. AIGNE DocSmith is installed using the Node Package Manager (npm), which is included with the Node.js installation. To install Node.js, visit the official [Node.js website](https://nodejs.org/) and follow the instructions for your operating system. You can verify the installation by opening your terminal and running `node -v` and `npm -v`.

No API keys are required to begin. By default, DocSmith uses the AIGNE Hub service for AI-powered creation, which provides access to various large language models without direct configuration.

## Installation

The tool is distributed as part of the AIGNE command-line interface (CLI). The installation involves two main steps.

### Step 1: Install the AIGNE CLI

To install the AIGNE CLI globally on your system, execute the following command in your terminal. This makes the `aigne` command accessible from any directory.

**Install AIGNE CLI**

```bash
npm install -g @aigne/cli
```

### Step 2: Verify the Installation

After the installation is complete, you can confirm its success by running the help command for the documentation tool.

**Verify Installation**

```bash
aigne doc --help
```

A successful installation will result in a displayed list of available DocSmith commands and their options.

## Generating Your First Documents

Follow these steps to analyze your project and create a complete set of documents.

### Step 1: Navigate to Your Project Directory

Open your terminal and use the `cd` command to change the current directory to the root of the project you intend to document.

**Change Directory**

```bash
cd /path/to/your/project
```

### Step 2: Run the Create Command

Execute the `create` command. This single command initiates the entire document creation process, from project analysis to content creation.

**Run Create Command**

```bash
aigne doc create
```

### Step 3: Complete the Interactive Setup

When you run the `create` command for the first time in a project, DocSmith launches a one-time interactive setup process. You will be guided through a series of questions to configure preferences for your documents, such as their purpose, target audience, and primary language.

![Screenshot of the interactive setup process](https://media.arcblock.io/lib/docsmith/screenshots/doc-complete-setup.png)

These settings are saved to a `config.yaml` file located in the `.aigne/doc-smith` directory, which you can modify manually at any time.

### Step 4: Await Creation

After the setup is complete, DocSmith will automatically perform the following actions:

::::steps
:::step{title="Analyze Codebase"}
Scans your source files to understand the project's structure and logic.
:::

:::step{title="Plan Structure"}
Creates a logical outline for the documents, defining sections and topics.
:::

:::step{title="Generate Content"}
Writes the documents based on the analysis and your specified configuration.
:::
::::

Upon completion, a confirmation message will be displayed. The created files will be available in the output directory specified during setup, which defaults to `.aigne/doc-smith/docs`.

![Screenshot of the success message after creation](https://media.arcblock.io/lib/docsmith/screenshots/doc-generated-successfully.png)

## What's Next?

You have now successfully created your first set of documents. The following are common next steps for managing and enhancing your documents:

::::card-group
::link-card{title="Update Document" description="Modify or regenerate specific parts of your documents to reflect code changes or incorporate new feedback." icon="refresh" href="/en/docs/docsmith/guides-updating-documentation-21ae40/"}
::link-card{title="Localize Document" description="Translate your documents into any of the 12 supported languages, including Chinese, Spanish, and German." icon="globe" href="/en/docs/docsmith/guides-translating-documentation-21ae40/"}
::link-card{title="Publish Documents" description="Make your documents accessible online for your team or the public." icon="rocket" href="/en/docs/docsmith/guides-publishing-your-docs-21ae40/"}
::link-card{title="Review Configuration" description="Review and modify the `config.yaml` file created during the initial setup to adjust your preferences." icon="settings" href="/en/docs/docsmith/configuration-initial-setup-21ae40/"}
::::

---

## Guides

URL: https://www.arcblock.io/en/docs/docsmith/guides-21ae40/

This section provides structured, step-by-step instructions for performing common document tasks with AIGNE DocSmith. Each guide is designed to walk you through a specific workflow, from initial creation to final publication.

Select a guide below to learn about a specific command and its functions.

::::card-group
::link-card{title="Create Document" description="Walks through the process of creating a new set of documents from your source files from start to finish." icon="file-plus" href="/en/docs/docsmith/guides-generating-documentation-21ae40/"}
::link-card{title="Update Document" description="Explains how to modify existing documents based on code changes or new feedback." icon="edit" href="/en/docs/docsmith/guides-updating-documentation-21ae40/"}
::link-card{title="Localize Document" description="Details the steps to translate your documents into multiple supported languages." icon="globe" href="/en/docs/docsmith/guides-translating-documentation-21ae40/"}
::link-card{title="Publish Documents" description="Shows how to make your created documents live and accessible online." icon="send" href="/en/docs/docsmith/guides-publishing-your-docs-21ae40/"}
::link-card{title="Manage Update History" description="Shows how to view the history of updates made to your documents." icon="clock" href="/en/docs/docsmith/guides-managing-history-21ae40/"}
::link-card{title="Evaluate Documents" description="Details how to use the evaluation command to assess the quality and completeness of your created documents." icon="clipboard-check" href="/en/docs/docsmith/guides-evaluating-documents-21ae40/"}
::link-card{title="Cleanup Workspace" description="Provides instructions on how to use the clear command to remove created files, configurations, and cached data." icon="trash" href="/en/docs/docsmith/guides-cleaning-up-21ae40/"}
::link-card{title="Interactive Mode" description="Explains how to use the interactive mode to generate, modify, and manage your documents." icon="bot" href="/en/docs/docsmith/guides-interactive-chat-21ae40/"}
::::

---

## Add a Document

URL: https://www.arcblock.io/en/docs/docsmith/guides-adding-a-document-21ae40/

Ever find your documentation has a gap? The `aigne doc add-document` command provides a straightforward, interactive way to introduce new topics into your existing documentation structure, ensuring your content grows alongside your project.

The `aigne doc add-document` command, also available via the alias `aigne doc add`, initiates an interactive session to add one or more new documents to your project's documentation structure. It not only adds the new files but also intelligently updates existing documents with relevant links to ensure the new content is discoverable.

## Command Usage

To start the process, navigate to your project's root directory and run the following command:

**aigne doc add-document**

```sh
aigne doc add-document
```

Alternatively, you can use the shorter alias `add`:

**aigne doc add**

```sh
aigne doc add
```

This command launches an interactive wizard that guides you through the process.

## The Process

The command follows a structured, step-by-step process to integrate new documents seamlessly.

### 1. Add New Documents Interactively

The command first displays the current documentation structure and then prompts you to specify new documents. You can describe your request in natural language. You can add documents one by one. After each addition, the tool displays the updated structure and prompts you to add another. To finish adding documents, simply press `Enter` without typing anything.

```sh
Current Document Structure:
  - /overview
  - /getting-started
  - /guides
    - /guides/generating-documentation
    - /guides/updating-documentation

You can add a new document.
  • e.g. Add a new document 'Troubleshooting'

Press Enter to finish: Add a 'Deployment Guide' under 'Guides'
```

### 2. Review and Link to Existing Documents

After you finish adding documents, DocSmith analyzes the existing content and identifies which documents would benefit from linking to the new ones. It then presents a list of these documents for you to review and select which ones the tool should modify. This step gives you full control over changes to your existing content.

By default, all suggested documents are selected. You can press `Space` to unselect items and `Enter` to confirm your selection.

```sh
? Select documents that need new links added (all selected by default, press Enter to confirm, or unselect all to skip):
❯ ◯ Overview (overview.md)
  ◯ Getting Started (getting-started.md)
  ◉ Guides (guides.md)
```

### 3. Content Generation and Translation

After confirmation, the system proceeds with two main tasks in parallel:

- <strong>Generates Content:</strong> Creates the full content for the new documents you added.
- <strong>Updates Links:</strong> Modifies the selected existing documents to include links to the new pages.

If you have configured multiple languages, both the new documents and the updated ones are automatically added to the translation queue.

### 4. Summary Report

Finally, the command prints a summary of the operations performed. This report includes a list of all newly created documents and a list of all existing documents that were updated with new links.

```text
📊 Summary

✨ Added Documents:
   Total: 1 document(s)

   1. /guides/deployment-guide - Deployment Guide

✅ Documents updated (Added new links):
   Total: 2 document(s)

   1. /overview - Overview
      New links added: /guides/deployment-guide

   2. /getting-started - Getting Started
      New links added: /guides/deployment-guide
```

This structured process ensures that new documentation is not just created but is also woven into the fabric of your existing content, improving navigation and discoverability.

## Related Guides

For other document management tasks, refer to the following guides:

::::card-group
::link-card{title="Remove a Document" description="Learn how to remove documents from your project." icon="file-minus" href="/en/docs/docsmith/guides-removing-a-document-21ae40/"}
::link-card{title="Update Content" description="See how to modify the content of existing documents." icon="edit" href="/en/docs/docsmith/guides-updating-document-21ae40/"}
::::

---

## Cleanup Workspace

URL: https://www.arcblock.io/en/docs/docsmith/guides-cleaning-up-21ae40/

Need to reset your project or remove sensitive data? This guide explains how to use the `aigne doc clear` command to safely remove generated files, configuration settings, and cached information, helping you maintain a clean and organized workspace.

The `clear` command offers two modes: an interactive wizard for guided cleanup and a non-interactive mode for quick, specific actions.

## Command Usage

To begin the cleanup process, execute the following command in your project's root directory:

**aigne doc clear**

```sh
aigne doc clear
```

Running the command without any arguments starts an interactive wizard, which will prompt you to select the items you wish to remove.

For faster, non-interactive cleanup, you can specify one or more targets directly using the `--targets` flag.

**aigne doc clear --targets generatedDocs**

```sh
aigne doc clear --targets <target1> <target2>
```

## Cleanup Options

The interactive wizard presents a checklist of items you can remove. The table below details each available option, which can also be used as a target in non-interactive mode.

| Target  | Description  |
|---|---|
| <strong>`generatedDocs`</strong>  | Allows you to select and delete specific generated documents from your output directory (e.g., `./docs`). The overall document structure is preserved.  |
| <strong>`documentStructure`</strong>  | Deletes all generated document files and the structure plan file (e.g., `.aigne/doc-smith/output/structure-plan.json`).  |
| <strong>`documentConfig`</strong>  | Removes the main project configuration file (e.g., `.aigne/doc-smith/config.yaml`). After deleting it, you will need to run `aigne doc init` to create a new one.  |
| <strong>`authTokens`</strong>  | Deletes saved authorization credentials used for publishing (e.g., from `~/.aigne/doc-smith-connected.yaml`). You will be prompted to select which site authorizations to clear.  |
| <strong>`deploymentConfig`</strong>  | Removes only the `appUrl` key from your project's configuration file, leaving all other settings intact.  |
| <strong>`mediaDescription`</strong>  | Deletes the cache of AI-generated descriptions for your project's media files (e.g., `.aigne/doc-smith/media-description.yaml`). These will be automatically regenerated the next time they are needed.  |

## Examples

### Interactive Cleanup

For a guided experience, run the command without any arguments. You will be presented with a checklist. Use the arrow keys to navigate, the spacebar to select or deselect items, and the Enter key to confirm your selections and proceed with the cleanup.

**aigne doc clear**

```sh
aigne doc clear
```

### Non-Interactive Cleanup

To clear specific items without prompts, use the `--targets` flag followed by the names of the targets you wish to remove.

#### Clear Created Documents Only

This command deletes the created document files but preserves the `structure-plan.json` file, allowing you to regenerate the content later.

**aigne doc clear --targets generatedDocs**

```sh
aigne doc clear --targets generatedDocs
```

#### Clear Structure and Configuration

This command performs a more thorough cleanup by removing all created documents, the structure plan, and the main configuration file.

**aigne doc clear --targets documentStructure documentConfig**

```sh
aigne doc clear --targets documentStructure documentConfig
```

## Summary

The `clear` command provides a straightforward method for managing your project's created assets and configuration. Use the interactive mode for a safe, guided process or specify targets directly for automated workflows. Since these actions permanently delete files, it is advisable to back up any important data before proceeding.

---

## Evaluate Documents

URL: https://www.arcblock.io/en/docs/docsmith/guides-evaluating-documents-21ae40/

Wondering if your documents hit the mark? This guide introduces the `evaluate` command, a powerful tool that systematically assesses your documents quality and completeness, providing a clear, actionable report to guide your improvements. You'll learn how to run an evaluation and interpret its results.

## The Evaluation Process

The `evaluate` command performs a comprehensive, two-stage analysis to give you a complete picture of your documents health. It checks both the high-level organization and the fine-grained details of each file.

::::steps
:::step{title="Structure Evaluation"}
First, the tool inspects the overall architecture of your documents. It verifies that the hierarchy of topics is logical and fully covers the goals, audience, and depth you defined during the initial setup.
:::

:::step{title="Content Evaluation"}
Next, it drills down into each individual document. This stage assesses the quality of the written content based on dimensions like readability, coherence, and alignment with your stated purpose. It also validates any code snippets for correctness.
:::
::::

After both stages are complete, the findings are compiled into a detailed HTML report that provides scores, identifies specific issues, and offers actionable feedback.

## How to Run an Evaluation

To start the evaluation process, you simply need to run a single command from your project's root directory.

### Execute the Command

Open your terminal and execute the `evaluate` command.

**aigne doc evaluate**

```bash
aigne doc evaluate
```

By default, the command will automatically open the generated HTML report in your web browser upon completion. To prevent this, you can add the `--open false` flag.

**aigne doc evaluate --open false**

```bash
aigne doc evaluate --open false
```

### Review the Output

As the command runs, it will display its progress. Once finished, a confirmation message will appear in the terminal, providing the paths to the report files.

```text
✔ Generate evaluation report
Evaluation report generated successfully.
- JSON Report: .aigc/evaluate/20240520114500/integrity-report.json
- HTML Report: .aigc/evaluate/20240520114500/report.html
```

You can open the `report.html` file directly in your browser to view the detailed analysis.

## Understanding the Evaluation Report

The report is structured to provide a clear and organized breakdown of the evaluation results, making it easy to pinpoint areas that need attention.

### Structure Evaluation Details

This section focuses on the high-level organization of your documents. It assesses how well the document structure aligns with the project's defined objectives.

| Dimension  | Description  |
|---|---|
| <strong>Purpose Coverage</strong>  | Assesses if the document structure adequately supports the primary goals, such as "Get started quickly" or "Complete specific tasks."  |
| <strong>Audience Coverage</strong>  | Determines if the structure is organized logically for the intended target audience, like "End users (non-technical)."  |
| <strong>Depth Coverage</strong>  | Checks if the level of detail implied by the structure matches the selected content depth, for example, "Covers all parameters."  |

### Document Content Evaluation Details

This section provides a file-by-file analysis of content quality. Each document is scored against a set of standardized criteria to ensure it meets quality standards.

| Dimension  | Description  |
|---|---|
| <strong>Readability</strong>  | Measures how easy the text is to read and comprehend.  |
| <strong>Coherence</strong>  | Evaluates the logical flow and organization of topics within the document.  |
| <strong>Content Quality</strong>  | Assesses the accuracy, relevance, and clarity of the information provided.  |
| <strong>Consistency</strong>  | Checks for uniform use of terminology, formatting, and style across all documents.  |
| <strong>Purpose Alignment</strong>  | Determines how well the content achieves the specified document goals.  |
| <strong>Audience Alignment</strong>  | Assesses whether the language, tone, and examples are appropriate for the target audience.  |
| <strong>Knowledge Level Alignment</strong>  | Verifies that the content's complexity matches the defined reader knowledge level.  |

## Summary

Regularly using the `evaluate` command is a key practice for maintaining high-quality documents. It provides objective metrics and specific feedback, allowing you to refine your content methodically. After reviewing the report, you can make targeted improvements to ensure your documents are as clear and effective as possible.

For detailed instructions on how to apply the feedback from the report, see the [Update Document](/en/docs/docsmith/guides-updating-documentation-21ae40/) guide.

---

## Create Document

URL: https://www.arcblock.io/en/docs/docsmith/guides-generating-documentation-21ae40/

This guide walks you through creating a complete set of documents from your project's source files using a single command. The process is designed to be straightforward, moving from initial analysis to final content creation, with an interactive review step to ensure the output is structured exactly as you need.

## The Creation Process

When you run `aigne doc create`, the tool executes a sequence of steps to analyze your project and produce documents. This section provides a factual breakdown of that workflow.

### Step 1: Initiating the Command

The process begins by running the `create` command in your project's root directory. This command orchestrates the entire workflow from analysis to content creation.

**Terminal**

```bash
aigne doc create
```

For efficiency, you can also use the aliases `gen` or `g`.

### Step 2: Source Code Analysis and Structure Planning

Upon initiation, DocSmith performs an analysis of your project's source files. It identifies the components, logic, and relationships within the codebase to propose an initial document structure. This plan outlines a logical hierarchy of documents, such as "Overview," "Getting Started," and "API Reference," tailored to the detected content.

### Step 3: Interactive Structure Review

After the initial structure is planned, it is displayed in the terminal for your review. This step allows you to approve or modify the document organization before any content is written.

You have two options:

::::steps
:::step{title="Accept the structure:"}
If the proposed organization is satisfactory, you can approve it to proceed.
:::

:::step{title="Provide feedback for refinement:"}
You can input plain-text instructions to modify the structure.
:::
::::

![Interactive prompt to refine the document structure.](https://media.arcblock.io/lib/docsmith/screenshots/doc-generate-feedback.png)

Examples of feedback include:

- "Rename 'Getting Started' to 'Quick Start'."
- "Add a new document titled 'Troubleshooting'."
- "Move 'API Reference' to be under a 'Guides' section."

The tool revises the structure based on your feedback and presents it for another review. This iterative process continues until the structure meets your requirements.

### Step 4: Content Generation

Once the document structure is finalized and approved, DocSmith begins generating the content for each document in the plan. It processes the relevant source files to write detailed explanations and code examples. This operation is performed for every document, ensuring complete coverage according to the approved structure.

### Step 5: Completion

After all documents have been created, a confirmation message is displayed in the terminal. The output files are saved to the directory specified in your configuration, which defaults to `.aigne/doc-smith/docs`.

![Success notification banner indicating document creation is complete.](https://media.arcblock.io/lib/docsmith/screenshots/doc-generated-successfully.png)

## Command Options

The `create` command includes optional flags to control its behavior. These flags allow for more specific actions during the creation process.

| Option  | Description  |
|---|---|
| `--forceRegenerate`  | Rebuilds all documents from the source files, overwriting any existing documents. This is useful for a complete refresh after significant code changes.  |
| `--glossary <path>`  | Specifies the path to a glossary file (e.g., `@glossary.md`). Using a glossary ensures that key terms are used consistently throughout the documents.  |

### Example: Forced Recreation

To discard existing documents and generate a new set from scratch, use the `--forceRegenerate` flag.

**Terminal**

```bash
aigne doc create --forceRegenerate
```

### Example: Using a Glossary

To maintain terminological consistency, provide a path to a glossary file.

**Terminal**

```bash
aigne doc create --glossary @./project-glossary.md
```

## Summary

This guide has detailed the systematic process for generating a new set of documents. The workflow proceeds from command initiation and source analysis to an interactive structure review, followed by content creation.

With your documents created, you may proceed to [Update Existing Documents](/en/docs/docsmith/guides-updating-documentation-21ae40/) or [Publish Your Documents](/en/docs/docsmith/guides-publishing-your-docs-21ae40/).

---

## Interactive Mode (Beta)

URL: https://www.arcblock.io/en/docs/docsmith/guides-interactive-chat-21ae40/

Feeling overwhelmed by command-line options? This guide explains how to use the interactive mode, a conversational interface that simplifies every step of the document process. By the end, you will be able to generate, update, translate, and publish your documents using simple, natural language instructions.

The interactive mode is the recommended method for managing your documents, as it provides a guided workflow that eliminates the need to memorize specific commands and their parameters.

## Starting an Interactive Session

To launch the interactive mode, execute the `chat` command from your project's root directory.

**aigne doc chat**

```bash
aigne doc chat
```

This command starts the interactive session, and the assistant will prompt you for instructions.

## Core Capabilities

The interactive mode streamlines the entire document lifecycle by integrating several core functions into a single conversational interface. You can state your goal in plain language, and the assistant will execute the necessary steps.

::::card-group
::link-card{title="Create Document" description="Create a complete document structure and initial content by analyzing your project's source code." icon="file-plus"}
::link-card{title="Update and Refine" description="Modify specific documents or entire sections based on your feedback or recent changes in the source code." icon="edit"}
::link-card{title="Translate Content" description="Translate your documents into multiple supported languages to serve a global audience." icon="globe"}
::link-card{title="Publish Your Documents" description="Follow a guided process to publish your documents and make it available online." icon="upload"}
::::

## Interaction Methods

You can interact with the assistant in two primary ways:

::::steps
:::step{title="Natural Language Instructions"}
Describe the task you want to accomplish. The assistant interprets your request and initiates the appropriate workflow. For example, you can type "generate documents for the project" or "translate the installation guide into German and French."
:::

:::step{title="Direct Commands"}
You can also invoke a specific function by typing its command name directly into the chat prompt, such as `update` or `publish`.
:::
::::

## Available Commands

The interactive mode understands a set of commands that correspond to its primary functions. While you can trigger these functions using natural language, you may also use the commands directly.

| Command  | Description  |
|---|---|
| `create`  | Initiates the workflow to create a new document structure and content from source files.  |
| `update`  | Starts the process of modifying existing documents based on code changes or user feedback.  |
| `localize`  | Begins the process of translating documents into one or more supported languages.  |
| `publish`  | Guides you through the steps to publish your documents online.  |
| `init`  | Helps create the initial configuration file (`docsmith.config.js`) for the project.  |
| `clear`  | Removes created files, configurations, and cached data from your project.  |
| `prefs`  | Allows you to view and manage saved preferences for document creation.  |
| `evaluate`  | Assesses the quality and completeness of your created documents and provides a report.  |
| `history`  | Displays the history of updates and changes made to your documents.  |
| `exit`  | Terminates the interactive session and returns to the standard terminal prompt.  |

## Example Interaction

The following transcript demonstrates a typical workflow for generating new documents using the interactive mode.

```text
You:
> I need to create documents for this project.

AI Assistant:
Understood. I will start the document creation process for the current directory.
First, I will analyze your project to propose a document structure. This may take a few moments...
...
Analysis complete. I have created a proposed structure. Would you like to review it before I generate the content? (yes/no)

You:
> yes

AI Assistant:
(The proposed document structure is displayed here for your review.)
...
You can request changes, such as 'add a guide for API authentication' or 'merge the installation and setup guides'. If the structure is correct, simply type 'continue'.

You:
> continue

AI Assistant:
Great. I will now proceed with generating the content for each document. This may take some time depending on the size of your project.
```

This interaction shows how the assistant guides the user through analysis, review, and content creation, requiring only simple text-based responses.

## Summary

The interactive mode provides a systematic and guided method for managing documents. It consolidates the tool's complete functionality into a single, conversational interface, ensuring a precise and efficient workflow.

To see a practical application of the interactive mode, refer to the [Create Document](/en/docs/docsmith/guides-generating-documentation-21ae40/) guide for a step-by-step walkthrough.

---

## Manage Update History

URL: https://www.arcblock.io/en/docs/docsmith/guides-managing-history-21ae40/

Ever wondered what changes were made to your documents and when? AIGNE DocSmith keeps a detailed log of every update. This guide will show you how to access and read this history, so you can easily track the evolution of your documents.

## Viewing Update History

To see the log of all document updates, you can use the `history view` command. This command provides a compact, one-line summary for each change, much like a version control system log.

Run the following command from your project's root directory:

**View History Log**

```bash
aigne doc history view
```

### Command Aliases

For convenience, the `history` command includes two aliases for the `view` subcommand: `log` and `list`. These commands perform the exact same function and will produce the identical output.

You can use either of the following commands as a shortcut:

```bash
aigne doc history log
```

```bash
aigne doc history list
```

If you haven't made any updates yet, the tool will inform you with the message: `No update history found`.

## Understanding the History Output

The output from the `history` command is designed to give you a clear overview of each update at a glance. Every line in the log represents a single update event.

The format for each entry is broken down as follows:

| Component  | Description  |
|---|---|
| <strong>Short Hash</strong>  | A unique 8-character identifier created document from the update's timestamp. This hash is deterministic, meaning the same timestamp will always produce the same hash.  |
| <strong>Date</strong>  | A relative timestamp showing when the update occurred (e.g., "5 minutes ago," "2 days ago"). For entries older than a week, a specific date is displayed.  |
| <strong>Operation</strong>  | The type of action performed, such as `generate_document` or `update_document_detail`.  |
| <strong>Document Path</strong>  | The path of the document that was modified, if the operation was specific to a single file. This is shown in parentheses for clarity.  |
| <strong>Feedback</strong>  | The summary or feedback message that was provided when the update was made.  |

### Example Output

Here is a sample of what you might see when you run the `aigne doc history view` command. This example shows how different types of updates are recorded in the log.

```bash
📜 Update History

e5a4f8b1 2 hours ago update_document_detail (/guides/generating-documentation): Added a new section on advanced configuration options.
a3b1c9d2 1 day ago  update_document_detail (/overview): Refined the introduction to be more concise.
f8d2e0c3 3 days ago generate_document (/guides/managing-history): Initial creation of the history management guide.
```

This log provides an orderly and scannable record of all changes, making it a useful tool for tracking progress and reviewing your documentation's history.

---

## Publish Documents

URL: https://www.arcblock.io/en/docs/docsmith/guides-publishing-your-docs-21ae40/

Once your documents are created, the final step is to make them available online. This document provides a step-by-step guide on how to publish your documents using the `aigne doc publish` command, making them accessible to your audience.

## The Publish Command

The `aigne doc publish` command uploads your created document files to a web service, allowing users to view them in a web browser. For efficiency, you can use the main command or its shorter aliases.

**Command Aliases**

```bash
# Full command
aigne doc publish

# Short alias
aigne doc pub

# Shorter alias
aigne doc p
```

Executing this command for the first time will start an interactive setup process, guiding you to select a publishing platform for your documents.

![A screenshot of the command-line interface prompting the user to select a publishing platform.](https://media.arcblock.io/lib/docsmith/screenshots/doc-publish.png)

## Publishing Options

The tool offers several destinations for hosting your documents. During the interactive setup, you will be presented with the following choices.

### 1. DocSmith Cloud (Free Hosting)

This option publishes your documents to `docsmith.aigne.io`, a free, public hosting service provided by AIGNE.

- <strong>Best for</strong>: Open-source projects, personal portfolios, or any documents intended for public access.
- <strong>Cost</strong>: Free.
- <strong>Outcome</strong>: Your documents will be hosted on a public URL, which is provided upon successful publication.

### 2. Your Existing Website (Self-Hosted)

This option allows you to publish documents to a website you already own and operate. This requires you to run your own instance of Discuss Kit, which provides the necessary backend and front-end components for the document site.

- <strong>Best for</strong>: Integrating documents directly into an existing company website, product portal, or personal domain for complete control.
- <strong>Requirements</strong>: You must have your own hosting environment.
- <strong>Procedure</strong>:
-
  1. Select the "Your existing website" option in the prompt.
  2. Enter the full URL of your website (e.g., `https://docs.your-company.com`).
  3. To set up your own document website, you can obtain a Discuss Kit instance from the official store: [https://www.web3kit.rocks/discuss-kit](https://www.web3kit.rocks/discuss-kit).

### 3. New Website (Paid Service)

This option helps you set up a new, dedicated website for your documents through a guided process.

- <strong>Best for</strong>: Users who require a professional, standalone document portal without managing the setup themselves.
- <strong>Cost</strong>: This is a paid service.
- <strong>Procedure</strong>: The command-line tool will direct you through the necessary steps to deploy and configure a new, managed Discuss Kit instance. If you have previously started this process, an option to resume the setup will be provided.

## Automated Publishing for CI/CD

In automated environments like Continuous Integration/Continuous Deployment (CI/CD) pipelines, you can bypass the interactive prompts by specifying the destination URL directly using the `--appUrl` flag.

**Direct Publishing**

```bash
aigne doc publish --appUrl https://your-docs-website.com
```

When you publish to a specific URL for the first time, whether through the interactive prompt or the `--appUrl` flag, the tool saves this URL to your local configuration file. Subsequent runs of `aigne doc publish` will automatically use the saved URL, simplifying the update process.

## Troubleshooting

### Authorization Errors (401/403)

If the publishing process fails with an error message containing "401" or "403," it typically indicates an issue with your authentication token. The token may be invalid, expired, or lack the necessary permissions for the specified document board.

To resolve this, you can reset your local authentication credentials using the `clear` command.

**Clear Configuration**

```bash
aigne doc clear
```

This command will prompt you to select which configuration data to remove. Choose to clear the authentication tokens. Afterward, run `aigne doc publish` again. You will be prompted to re-authenticate, which will generate a new, valid token, allowing the publication to proceed.

After successfully publishing your documents, you will need to keep them current as your project evolves. Refer to the [Update Document](/en/docs/docsmith/guides-updating-documentation-21ae40/) guide for instructions on how to modify your existing documents.

---

## Remove a Document

URL: https://www.arcblock.io/en/docs/docsmith/guides-removing-a-document-21ae40/

Keeping your documentation accurate involves not just adding content, but also pruning it. This guide details how to use the `aigne doc remove-document` command to safely delete documents from your project, ensuring that your documentation set remains clean and relevant.

## Overview

The `remove-document` command provides an interactive way to select and delete one or more documents from your existing structure. A key feature of this command is its ability to handle cascading deletes; removing a parent document will also remove all of its child documents.

Furthermore, after the selected documents are removed, the tool automatically scans the remaining files for any broken links that pointed to the deleted documents. It then attempts to intelligently fix these links or remove them, ensuring the integrity of your entire documentation set.

## Command Usage

To begin the removal process, navigate to your project's root directory and execute the command:

```sh
aigne doc remove-document
```

You can also use the shorter aliases `remove` or `rm`:

```sh
aigne doc rm
```

### 1. Select and Confirm Documents

Upon running the command, you will be presented with a list of your current documents, displayed in a hierarchical tree structure. You can navigate this list using the arrow keys and select the documents you wish to remove by pressing the spacebar. Once you have selected all the documents for deletion, press `Enter` to confirm. If you decide not to remove any documents, you can press `Enter` with no selections to cancel the operation.

**Select documents to remove**

```sh
? Select documents to remove (Press Enter with no selection to finish):
❯◯ /overview
 ◯ /getting-started
 ◯ /guides
  ◯ /guides/generating-documentation
  ◯ /guides/updating-documentation
   ◉ /guides/updating-documentation/adding-a-document
   ◉ /guides/updating-documentation/removing-a-document
```

### 2. Link Verification and Fixing

After the documents are deleted, DocSmith automatically scans your remaining documentation for any links that now point to non-existent files. You will be prompted to confirm the automatic fixing of these invalid links.

**Confirm link fixing**

```sh
? Select documents with invalid links to fix (all selected by default, press Enter to confirm, or unselect all to skip):
❯◉ Update Document (/guides/updating-documentation.md) - Invalid Links(2): /guides/adding-a-document, /guides/removing-a-document
```

### 3. Review Summary

Finally, a summary is displayed in your terminal, listing all the documents that were successfully removed and detailing which documents had invalid links fixed.

**Removal summary**

```sh
---
📊 Summary

🗑️  Removed Documents:
   Total: 2 document(s)

   1. /guides/adding-a-document
   2. /guides/removing-a-document

✅ Documents fixed (Removed invalid links):
   Total: 1 document(s)

   1. /guides/updating-documentation
      Invalid links fixed: /guides/adding-a-document, /guides/removing-a-document
```

This process ensures that removing files is straightforward and does not leave behind broken references in your other documents.

## Related Guides

After tidying up your documentation, you might need to perform other updates. For more information on managing your document structure, please see the following guides:

::::card-group
::link-card{title="Add a Document" description="Learn how to add new documents to your existing documentation structure." icon="file-plus" href="/en/docs/docsmith/guides-adding-a-document-21ae40/"}
::link-card{title="Update Document" description="See how to modify the content of existing documents." icon="edit" href="/en/docs/docsmith/guides-updating-document-21ae40/"}
::::

---

## Localize Document

URL: https://www.arcblock.io/en/docs/docsmith/guides-translating-documentation-21ae40/

Making your documents available in multiple languages is essential for reaching a global audience. This guide provides a step-by-step process for using the `aigne doc localize` command to localize your content into any of the 12 supported languages, ensuring your documents are accessible and easy to understand for users everywhere.

## Translation Process Overview

The primary command for translating documents is `aigne doc localize`. This command can be executed in two modes: interactive or non-interactive (using command-line flags). Both methods are designed to be straightforward, allowing you to manage single or multi-language translations efficiently.

### Interactive Mode (Beta)

For a guided experience, run the command without any arguments. This is the recommended approach for users who are new to the translation feature or prefer a step-by-step process.

```bash
aigne doc localize
```

When you run this command, DocSmith will initiate an interactive session:

1. First, you will be prompted to select the specific documents you wish to localize from a list of all available document files in your project.
2. Next, you will be asked to choose the target languages. The system supports 12 languages, and any languages you have previously selected will be pre-checked to streamline the process.

![Executing the translate command](https://media.arcblock.io/lib/docsmith/screenshots/doc-translate.png)

After selecting the documents, you will be presented with a list of available languages to choose from.

![Selecting translation languages](https://media.arcblock.io/lib/docsmith/screenshots/doc-translate-langs.png)

Once your selections are confirmed, DocSmith will begin the translation process for each document into every language you selected.

### Command-Line Usage

For automation, scripting, or more direct control, you can provide arguments directly on the command line.

```bash
aigne doc localize [options]
```

#### Options

The `localize` command accepts the following options to specify documents, languages, and other settings.

- **--docs** `array` — Specify one or more document paths to be translated. If this option is omitted, the tool will enter interactive mode for document selection.
- **--langs** `array` — A list of target language codes (e.g., zh, ja, de). If not provided, you will be prompted to select languages interactively.
- **--glossary** `string` — Path to a glossary file (e.g., @/path/to/glossary.md). This file helps maintain consistent terminology for specific terms across all translations.
- **--feedback** `string` — Provide specific instructions to the AI to guide its translation style (e.g., "Use a formal tone and keep technical terms in English"). This feedback is also recorded in the document's history for future reference.
- **--diagram** `boolean` — Translate only diagram images without translating document content. Use this option to update text labels in diagrams while keeping the document body unchanged.

#### Examples

1. <strong>Translate specific documents into multiple languages:</strong> To translate `overview.md` and `getting-started.md` into Chinese and Japanese, use the following command: ```bash aigne doc localize --docs overview.md --docs getting-started.md --langs zh ja ```
2. <strong>Translate with a glossary and stylistic feedback:</strong> To translate `overview.md` into German while ensuring consistent terminology and a formal tone, you can include the `--glossary` and `--feedback` options: ```bash aigne doc localize --docs overview.md --langs de --feedback "Use a formal tone" --glossary @/path/to/glossary.md ```

## Supported Languages

DocSmith provides professional-grade translations for 12 languages. Use the language code from the table below when using the `--langs` flag.

| Language  | Code  |
|---|---|
| English  | `en`  |
| 简体中文  | `zh`  |
| 繁體中文  | `zh-TW`  |
| 日本語  | `ja`  |
| 한국어  | `ko`  |
| Español  | `es`  |
| Français  | `fr`  |
| Deutsch  | `de`  |
| Português  | `pt`  |
| Русский  | `ru`  |
| Italiano  | `it`  |
| العربية  | `ar`  |

## Summary

This guide has covered the use of the `aigne doc localize` command to make your documents accessible to a global audience. You can use the interactive mode for a guided process or command-line options for automation and precision.

Once your documents are translated, the next step is to publish them. For detailed instructions on this process, please see the [Publish Documents](/en/docs/docsmith/guides-publishing-your-docs-21ae40/) guide.

---

## Update Content

URL: https://www.arcblock.io/en/docs/docsmith/guides-updating-document-21ae40/

This guide explains how to use the `update` command to modify existing documents. You can update document content, add or update diagrams, and remove diagrams through feedback.

## Basic Usage

### Interactive Mode

Run the command without arguments to enter interactive mode:

```bash
aigne doc update
```

Select documents and provide feedback to update them.

### Command-Line Mode

Update documents directly with command-line flags:

```bash
aigne doc update --docs /overview --feedback "Add a more detailed explanation of the core features."
```

## Updating Diagrams

You can update diagrams in documents by providing feedback. The tool supports updating existing diagrams or adding new ones.

### Update a Specific Diagram

Provide feedback to update a diagram:

```bash
aigne doc update --docs /overview --feedback "Update the diagram to show the new architecture"
```

### Update All Diagrams

Use the `--diagram` flag to filter and select documents with diagrams:

```bash
aigne doc update --diagram
```

Or use `--diagram-all` to automatically update all documents with diagrams:

```bash
aigne doc update --diagram-all
```

### Delete a Diagram

Remove a diagram by providing feedback:

```bash
aigne doc update --docs /overview --feedback "Remove the diagram"
```

## Diagram Styles

DocSmith supports multiple diagram styles. You can specify a style in your feedback or configure a default style. The supported styles include:

### Modern

Clean, professional style with contemporary design elements.

![Modern Style](https://media.arcblock.io/lib/docsmith/diagram-styles/modern.jpg)

### Standard Flowchart

Traditional flowchart style with conventional symbols.

![Standard Flowchart Style](https://media.arcblock.io/lib/docsmith/diagram-styles/standard.jpg)

### Hand-drawn

Sketch-like style with natural, organic lines.

![Hand-drawn Style](https://media.arcblock.io/lib/docsmith/diagram-styles/hand-drawn.jpg)

### Anthropomorphic

Personified elements with vivid, human-like features.

![Anthropomorphic Style](https://media.arcblock.io/lib/docsmith/diagram-styles/anthropomorphic.jpg)

### Flat Design

Flat design without shadows or 3D effects.

![Flat Design Style](https://media.arcblock.io/lib/docsmith/diagram-styles/flat.jpg)

### Minimalist

Minimal elements with maximum clarity.

![Minimalist Style](https://media.arcblock.io/lib/docsmith/diagram-styles/minimalist.jpg)

### 3D

Three-dimensional effects with depth and perspective.

![3D Style](https://media.arcblock.io/lib/docsmith/diagram-styles/3d.jpg)

## Command Parameters

| Parameter  | Description  | Required  |
|---|---|---|
| `--docs`  | Specifies the path(s) of the document(s) to update. Can be used multiple times.  | Optional  |
| `--feedback`  | Provides textual instructions for the changes to be made.  | Optional  |
| `--reset`  | Recreate the document(s) from scratch, ignoring existing content.  | Optional  |
| `--glossary`  | Specifies the path to a glossary file (`@/path/to/glossary.md`).  | Optional  |
| `--diagram`  | Filter to show only documents with diagrams and let user select which ones to update.  | Optional  |
| `--diagram-all`  | Auto-select all documents with diagrams and update them without user selection.  | Optional  |

For information on adding or removing documents, see the [Add a Document](/en/docs/docsmith/guides-adding-a-document-21ae40/) and [Remove a Document](/en/docs/docsmith/guides-removing-a-document-21ae40/) guides.

---

## Update Document

URL: https://www.arcblock.io/en/docs/docsmith/guides-updating-documentation-21ae40/

As your project evolves, your documentation needs to keep pace. This section provides a central hub for all tasks related to modifying your documentation set, ensuring it remains accurate and relevant. Here, you'll find guidance on altering existing content, incorporating new documents, and removing outdated files.

Keeping your documentation current is a continuous process. Whether you are refining explanations based on user feedback, adding guides for new features, or restructuring content by removing obsolete pages, the tools provided help manage these changes efficiently.

For detailed instructions on each task, please refer to the specific guides below.

::::card-group
::link-card{title="Update Content" description="Learn how to modify the text, examples, and structure of your existing documents to reflect the latest changes in your project." icon="edit" href="/en/docs/docsmith/guides-updating-document-21ae40/"}
::link-card{title="Add a Document" description="Follow these steps to integrate new documentation files into your existing structure, ensuring they are correctly linked and formatted." icon="file-plus" href="/en/docs/docsmith/guides-adding-a-document-21ae40/"}
::link-card{title="Remove a Document" description="Understand the process for safely deleting documents from your project, including how to handle and update any broken links." icon="file-minus" href="/en/docs/docsmith/guides-removing-a-document-21ae40/"}
::::

## Summary

This section serves as an entry point for managing the lifecycle of your documents after their initial creation. By following the linked guides, you can confidently update, add, or remove documentation files as your project grows and changes.

For a complete walkthrough of creating a new documentation set from scratch, see the [Create Document](/en/docs/docsmith/guides-generating-documentation-21ae40/) guide.

---

## Overview

URL: https://www.arcblock.io/en/docs/docsmith/overview-21ae40/

AIGNE DocSmith is a documentation tool that uses AI to analyze your project's source code and generate documentation automatically. Built on the [AIGNE Framework](https://www.aigne.io/en/framework), it produces structured, multi-language documents that are synchronized with your codebase. This process addresses the challenges of manual documentation, which can be time-consuming, prone to becoming outdated, and inconsistent.

## How It Works

![Overview](https://media.arcblock.io/lib/9b/9b4eaa67a782e39f.w1600.webp)

DocSmith works by analyzing your project's source code to understand its structure and functionality. From this analysis, it generates a complete set of documents, including high-level guides and detailed API references.

## Core Features

DocSmith provides a set of features to handle the document lifecycle from creation to publication.

- <strong>AI-Powered Generation</strong>: Analyzes the codebase to generate a logical document structure and content that explains the code's functionality.
- <strong>Multi-Language Support</strong>: Translates documents into 12 languages, such as English, Chinese (Simplified), and Japanese, using context-aware translation to maintain technical accuracy.
- <strong>LLM Integration</strong>: Connects with multiple Large Language Models (LLMs). It uses [AIGNE Hub](https://www.aigne.io/en/hub) by default, a service for switching between models like Google Gemini and OpenAI GPT without separate API keys. You can also configure your own keys for direct provider access.
- <strong>Smart Updates</strong>: Detects source code changes and updates the corresponding document sections. You can provide feedback to refine the generated content.
- <strong>Publishing Options</strong>: Deploys documents with a single command. You can publish to the official DocSmith platform or a self-hosted instance of [Discuss Kit](https://www.web3kit.rocks/discuss-kit), a service for hosting and displaying documents.

## Available Commands

DocSmith is operated through a command-line interface. The following table provides a summary of the main commands and their functions.

| Command  | Description  |
|---|---|
| `init`  | Guides you through an interactive process to create an initial configuration file.  |
| `create`  | Creates a new set of documents from your source files.  |
| `add-document`  | Adds a new document to the existing structure.  |
| `remove-document`  | Removes a document from the existing structure.  |
| `update`  | Modifies existing documents based on code changes or new feedback.  |
| `localize`  | Translates documents into one or more of the 12 supported languages.  |
| `publish`  | Deploys your documents to a live, accessible URL.  |
| `evaluate`  | Assesses the quality and completeness of your created documents.  |
| `history`  | Views the history of updates made to your documents.  |
| `chat`  | Starts an interactive mode session to generate and manage documents.  |
| `prefs`  | Manages saved preferences and configurations for document creation.  |
| `clear`  | Removes created files, configurations, and cached data.  |

This overview provides a summary of AIGNE DocSmith's purpose and capabilities. To begin using the tool, proceed to the [Getting Started](/en/docs/docsmith/getting-started-21ae40/) guide for installation and setup instructions.

---

## Release Notes

URL: https://www.arcblock.io/en/docs/docsmith/release-notes-21ae40/

Stay up-to-date with the latest developments for AIGNE DocSmith. This page provides a chronological record of new features, performance improvements, and bug fixes for each version of the tool.

## Version 0.9.0-beta (2025-11-11)

This is a maintenance release focused on general stability and performance improvements.

## Version 0.8.16-beta.1 (2025-11-11)

### New Features

- <strong>Document Icon Generation</strong>: Added the capability to automatically generate icons for documents.
- <strong>Auto-Open Evaluation Reports</strong>: Evaluation reports can now be configured to open automatically after being generated.

### Bug Fixes

- <strong>Improved Prompts</strong>: Fine-tuned internal prompts to generate more expressive and detailed documents.

## Version 0.8.16-beta (2025-11-10)

### New Features

- <strong>Enhanced Interactive Mode</strong>: The interactive mode agent now utilizes the AIGNE File System (AFS) to access your project's context, leading to more accurate and relevant assistance.
- <strong>Title Streamlining</strong>: Implemented a function to automatically streamline and standardize document titles.

### Bug Fixes

- <strong>Model Update</strong>: The chat model has been updated from a custom hub to the official `google/gemini-2.5-pro` for improved performance.

## Version 0.8.15 (2025-11-07)

This version includes general maintenance and stability improvements.

## Version 0.8.15-beta.16 (2025-11-07)

### New Features

- <strong>Customizable Diagram Generation</strong>: You can now specify the number of diagrams to be generated for your documents.

## Version 0.8.15-beta.15 (2025-11-07)

### Bug Fixes

- <strong>Configuration System</strong>: Added a two-tier configuration system for managing the AI's "thinking effort," allowing for more granular control over creation quality and speed.

## Version 0.8.15-beta.14 (2025-11-06)

### New Features

- <strong>Reasoning Effort Configuration</strong>: Introduced a setting to adjust the AI model's reasoning effort, providing customizable control over the depth of analysis.
- <strong>Enhanced Publishing Authentication</strong>: The publishing process now provides short-link responses and more detailed error reporting for authentication issues.

### Bug Fixes

- <strong>Configuration Compatibility</strong>: Ensured that existing configurations use a default reasoning effort to maintain compatibility.

## Version 0.8.15-beta.13 (2025-11-05)

### Bug Fixes

- <strong>Publishing Stability</strong>: Improved the stability and smoothness of the paid deployment process.
- <strong>Validation and Viewing</strong>: The tool now validates the document directory during initialization and ensures the latest version is displayed after publishing.

## Version 0.8.15-beta.12 (2025-11-05)

### New Features

- <strong>Optimized Updates</strong>: Reduced token consumption during document updates by implementing intent analysis to identify necessary changes more efficiently.

## Version 0.8.15-beta.11 (2025-11-04)

### New Features

- <strong>Improved Warnings</strong>: The tool now warns users about invalid source files and provides clearer messages during translation.

### Bug Fixes

- <strong>Efficient Diagram Generation</strong>: Prevented the creation of unnecessary diagrams.
- <strong>Structure Generation</strong>: Improved the process of generating the document structure by iterating through data source chunks more effectively.

## Version 0.8.11 (2025-10-05)

This version includes general maintenance and stability improvements.

## Version 0.8.10 (2025-09-20)

This version includes general maintenance and stability improvements.

## Version 0.8.9 (2025-09-15)

### Bug Fixes

- <strong>Diagram Theme</strong>: Updated the theme color for D2 diagrams to improve visual consistency.

## Version 0.8.8 (2025-09-13)

### Bug Fixes

- <strong>UI Text</strong>: Optimized the text for inquiry feedback prompts to be clearer and more helpful.

## Version 0.8.7 (2025-09-12)

### New Features

- <strong>API Parameter Fields</strong>: Added support for defining API parameters using the `<x-field>` custom component for more structured API documents.

## Version 0.8.6 (2025-09-11)

### New Features

- <strong>Publish URL Display</strong>: The document URL is now displayed by default after a successful publishing process.

### Bug Fixes

- <strong>Deployment Logs</strong>: Ensured that logs are saved correctly during deployment to prevent data loss.

## Version 0.8.5 (2025-09-10)

### New Features

- <strong>Enterprise Publishing</strong>: Added support for publishing documents to enterprise spaces.

## Version 0.8.4 (2025-09-09)

### Bug Fixes

- <strong>Code Block Parsing</strong>: Markdown code blocks are now parsed into a custom element that supports enhanced attributes like titles and icons.
- <strong>Diagram Background</strong>: Made the background for D2 diagrams transparent for better integration with different themes.

## Version 0.8.3 (2025-09-05)

### Bug Fixes

- <strong>Image Dimensions</strong>: Added automatic dimension detection for local images to ensure they are displayed correctly without manual configuration.

## Version 0.8.1 (2025-09-03)

### New Features

- <strong>Improved D2 Charts</strong>: Enhanced D2 chart creation with more comprehensive internal examples to improve the quality and accuracy of visual outputs.

## Version 0.8.0 (2025-09-03)

### New Features

- <strong>Custom Component Guidelines</strong>: Updated the guidelines for custom components with new formatting restrictions to ensure proper rendering.

## Version 0.7.1 (2025-08-31)

### Bug Fixes

- <strong>Path Selection</strong>: Fixed a bug where using the Tab key for path selection in the command-line interface did not work as expected.

## Version 0.7.0 (2025-08-30)

### New Features

- <strong>Interactive Mode</strong>: Added interactive mode for generating and managing documents interactively. See the [Interactive Mode](/en/docs/docsmith/guides-interactive-chat-21ae40/) guide for more details.
- <strong>D2 Chart Support</strong>: Introduced support for D2 charts in the document creation and publishing workflow.
- <strong>Custom Components</strong>: Enabled support for custom components and more robust configuration handling.

## Version 0.6.0 (2025-08-27)

### New Features

- <strong>Media Processing</strong>: Implemented support for media file processing before publishing documents, ensuring images and other assets are handled correctly.

## Version 0.5.0 (2025-08-26)

### New Features

- <strong>Persistent Preferences</strong>: User feedback can now be saved as persistent preferences for future sessions. Learn more in our [Manage Preferences](/en/docs/docsmith/configuration-managing-preferences-21ae40/) guide.

### Bug Fixes

- <strong>Setup Questions</strong>: Polished the text of questions asked during the initial setup process for clarity.

## Version 0.4.0 (2025-08-20)

### New Features

- <strong>Localize Command</strong>: Introduced a new `localize` command for translating documents into multiple languages. See the [Localize Document](/en/docs/docsmith/guides-translating-documentation-21ae40/) guide to get started.

## Version 0.3.0 (2025-08-19)

### New Features

- <strong>Context Collection</strong>: Refined the workflow for collecting context during document creation, leading to more relevant output.

## Version 0.2.0 (2025-08-05)

### New Features

- <strong>Automatic Configuration</strong>: The tool will now automatically initialize the configuration if it is missing when a command is run.
- <strong>Update Command</strong>: Added a new `update` command to refresh documents when source files have changed. You can find more information in the [Update Document](/en/docs/docsmith/guides-updating-documentation-21ae40/) guide.

---

## DIF Hackathon Guide (2024)

URL: https://www.arcblock.io/en/docs/hackathon/

---

## FAQ

URL: https://www.arcblock.io/en/docs/hackathon/3U5V2c2ffFoWDuJPGQjiGl-P/

### Q1: What to do if I failed to connect to test store

- You need some TBA for staking purpose, get it from [https://faucet.abtnetwork.io/](https://faucet.abtnetwork.io/)
- You need email verification certificate, get it from: [https://test.store.blocklet.dev/.well-known/service/kyc/email](https://test.store.blocklet.dev/.well-known/service/kyc/email)

- You need to join the developer program:

[Test Store](https://test.store.blocklet.dev/join)

---

## Building on DID Connect

URL: https://www.arcblock.io/en/docs/hackathon/did-building-on-did-connect/

## Introduction

In this article, you will learn how to set up a dapp with DID Connect, which should work with DID Wallet

## Prerequisites

- Skills required: developers with a certain foundation in developing React + Express + Typescript applications
- Operating System: It is recommended to use MacOS, and Linux for development, while Windows needs   [Developing Blocklet in Docker](/en/docs/blocklet-developer/develop-blocklet-with-docker/)
- Environment: Node.js >= 20

## Getting Started

### Preparation

1. Install DID Wallet: please refer to  [Setup DID Wallet](/en/docs/blocklet-developer/setup-did-wallet/)   <video src="https://media.arcblock.io/lib/3e/3ece9961f911eb1b8082b6653971e263.mp4" controls></video>
2. Install Node.js: please refer to  [Setup Node.js](/en/docs/blocklet-developer/setup-nodejs/)
3. Install Blocklet CLI: Please refer to  [Install Blocklet CLI](/en/docs/blocklet-developer/install-blocklet-cli/)
4. Complete email verification and blocklet store setup
5.
  1. Get email verification certificate: [https://test.store.blocklet.dev/.well-known/service/kyc/email](https://test.store.blocklet.dev/.well-known/service/kyc/email)  <video src="https://media.arcblock.io/lib/e8/e8002add564fddb645d085c0d26834de.mp4" controls></video>
  2. Get TBA token for future use: [<strong>https://faucet.abtnetwork.io/</strong>](https://faucet.abtnetwork.io/)
  3. Get your developer passport on blocklet store: [https://test.store.blocklet.dev/join](https://test.store.blocklet.dev/join)
  4. Connect blocklet store and your development environment:  `blocklet connect `[`https://test.store.blocklet.dev/`](https://test.store.blocklet.dev/)					 <video src="https://media.arcblock.io/lib/7a/7a1235670bd5c91f18731c8e558b5590.mp4" controls></video>

### Create a Blocklet

1. Just use `blocklet create` command to create a template blocklet
2.
  - ![image.png](https://media.arcblock.io/lib/13/134ac82c5a835acd6578eb4d1f2aee4b.w1600.webp)
3. Follow the link to generate an app DID, finish DID Connect in the browser
4.
  - ![image.png](https://media.arcblock.io/lib/c4/c4911f978ba41ca4f9ae6dd76e8f9c61.w1600.webp)
5. Install project dependencies

### Develop Blocklet

1. Use `blocklet dev` command to start blocklet development
2. Open the URL displayed in the terminal, you will see a DID Connect playground page
3. Modify the code in the src folder and you will see the change on the page

<details>
<summary>Follow the video
</summary>

<video src="https://media.arcblock.io/lib/fd/fd837431c5b063d51b13854ecd235f5b.mp4" controls></video>

</details>

### Understanding DID Connect

> DID Connect is a bridge between DID Wallet and Blocklet, with DID Connect, Blocklet can easily get data (eg: User Profile, NFT, etc...) from DID Wallet

Follow the next steps to add DID Connect on your own Blocklet

1. Add DID Connect request in the front-end project

<details>
<summary>Full code
</summary>

```javascript
import Avatar from '@arcblock/ux/lib/Avatar';
import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
import AccountBoxOutline from '@iconify-icons/material-symbols/account-box-outline';
import CakeOutlineRoundedIcon from '@iconify-icons/material-symbols/cake-outline-rounded';
import MailOutlineRoundedIcon from '@iconify-icons/material-symbols/mail-outline-rounded';
import PhoneOutlineRoundedIcon from '@iconify-icons/material-symbols/phone-android-outline-rounded';
import { Icon } from '@iconify/react';
import { useState } from 'react';

import { useSessionContext } from '../../libs/session';
import ConnectItem from '../connect-item';
import InfoRow from '../info-row';

export default function RequestProfile() {
  const [result, setResult] = useState(null);
  const { locale, t } = useLocaleContext();
  const { connectApi } = useSessionContext();

  const requestProfile = () => {
    const action = 'request-profile';
    setResult(null);
    connectApi.open({
      locale,
      action,
      onSuccess(res) {
        if (res.result.avatar) {
          res.result.avatar = res.result.avatar.replace(/[\r\n\s]/g, '');
        }
        setResult(res.result);
      },
      messages: {
        title: t('claims.requestProfile.connect.title'),
        scan: t('claims.requestProfile.connect.scan'),
      },
    });
  };

  return (
    <ConnectItem
      title={t('claims.requestProfile.title')}
      description={t('claims.requestProfile.description')}
      onClick={requestProfile}
      result={
        result ? (
          <>
            <Avatar variant="circle" src={result.avatar} did={result.did} size={60} />
            <InfoRow
              icon={<Icon fontSize={18} icon={AccountBoxOutline} />}
              name={t('claims.requestProfile.result.fullName')}
              value={result.fullName}
            />
            <InfoRow
              icon={<Icon fontSize={18} icon={MailOutlineRoundedIcon} />}
              name={t('claims.requestProfile.result.email')}
              value={result.email}
            />
            <InfoRow
              icon={<Icon fontSize={18} icon={PhoneOutlineRoundedIcon} />}
              name={t('claims.requestProfile.result.phone')}
              value={result.phone}
            />
            <InfoRow
              icon={<Icon fontSize={18} icon={CakeOutlineRoundedIcon} />}
              name={t('claims.requestProfile.result.birthday')}
              value={result.birthday}
            />
          </>
        ) : null
      }
    />
  );
}
```

</details>

1.
  - Just use `connectApi.open` to start a DID Connect process

2. Add DID Connect handler in the back-end project

<details>
<summary>Full code
</summary>

```javascript
const omit = require('lodash/omit');
const logger = require('../../libs/logger');

const action = 'request-profile';
module.exports = {
  action,

onConnect() {

  return {

    profile: () => ({

      description: 'Please provide your full profile',

      fields: ['fullName', 'email', 'phone', 'signature', 'avatar', 'birthday'],

    }),

  };

},
​

  onAuth: ({ userDid, userPk, claims, updateSession }) => {
    const claim = claims.find((x) => x.type === 'profile');
    logger.log(`${action}.onAuth`, { userDid, userPk, claim });
    updateSession({
      result: {
        ...omit(claim, ['type', 'signature']),
        did: userDid,
        pk: userPk,
      },
    });
  },
};
```

</details>

> View full DID Connect docs in here
> [Introduction](/en/docs/did-connect/did-connect-introduction/)
>

<details>
<summary>Video
</summary>

<video src="https://media.arcblock.io/lib/b9/b97256168a951f277c4bd847eadc1c6e.mp4" controls></video>

</details>

### Deploy Blocklet on local Blocklet Server

1. Create a Blocklet container first, copy the Blocklet container DID
2. Change `deploy` script in `package.json`
3.
  - `"deploy": "npm run bundle && blocklet deploy .blocklet/bundle"` -> `"deploy": "npm run bundle && blocklet deploy .blocklet/bundle --app-id=xxxxxxx"`
4. execute `npm run deploy`
5. check the full document here  [Deploy your blocklet](/en/docs/blocklet-developer/deploy-blocklet-directly-to-the-server/)

<details>
<summary>View video
</summary>

<video src="https://media.arcblock.io/lib/45/45049f99e9f835e6ad6a93ebb741b550.mp4" controls></video>

</details>

### Publish Blocklet to Test Blocklet Store

You can complete the application's build and deployment publishing according to the following steps：

1. Bump version: `npm run bump-version`
2. Bundle: `npm run bundle`
3. Upload blocklet to Test Store: `blocklet upload`

Or you can directly use `npm run upload `	to skip bundle and blocklet upload (Step2-3)

1. Publish on store

<video src="https://media.arcblock.io/lib/29/29effe08c3978a87fa66d334cc2d726b.mp4" controls></video>

## Project Ideas

Here are some interesting and useful application ideas for your reference, but of course you can completely follow your ideas:

- <strong>Decentralized DocuSign</strong>: Develop a decentralized document signing platform similar to DocuSign that utilizes decentralized identifiers (DID) and DID-Connect for user authentication and generates verifiable credentials for each signed contract. This platform will provide a secure and transparent way to manage contractual agreements in a digital format.
- <strong>Decentralized Crowdsourcing App</strong>: Create a decentralized application for managing crowdsourcing projects that allows users to propose, fund, and manage community projects transparently. This platform will use blockchain technology to handle fund allocation, project milestones, and distributions, ensuring accountability and trust among participants.

## References

[ArcBlock Official Site](https://www.arcblock.io/docs/blocklet-developer)

[ArcBlock Community](https://community.arcblock.io/discussions/boards/hackathon-support)

For any questions or support, visit the [ArcBlock Community Hackathon Support board ](https://community.arcblock.io/discussions/boards/hackathon-support)or consult the ArcBlock Developer Documentation. Good luck with your DID Wallet Dapp development!

---

## Building with DID Wallet

URL: https://www.arcblock.io/en/docs/hackathon/did-building-on-did-wallet/

The DID Wallet Dapp template provides a powerful foundation for building decentralized identity applications. Following this guide, you can create a full-stack application that leverages decentralized identifiers (DIDs) for user authentication and data management. This template is ideal for developing applications that require secure, user-controlled identity solutions, such as decentralized social networks, secure document-sharing platforms, or blockchain-based financial services.

## Prerequisites

Developers should have the following skills and environment to start building:

- Skills requirements: JavaScript, React.js, Express.js
- Operating System: It is recommended to use MacOS, and Linux for development, while Windows needs   [Developing Blocklet in Docker](/en/docs/blocklet-developer/develop-blocklet-with-docker/)
- Environment: Node.js >= 20

## Getting Started

1. Install and setup DID Wallet from [https://didwallet.io/](https://didwallet.io/), or checkout following video to setup DID Wallet on Chrome:

<video src="https://media.arcblock.io/lib/3e/3ece9961f911eb1b8082b6653971e263.mp4" controls></video>

1. Install Node.js (v20+) from [https://nodejs.org/](https://nodejs.org/)

1. Install Blocklet CLI with `npm install -g @blocklet/cli` , for more detailed instructions please checkout   [Install Blocklet CLI](/en/docs/blocklet-developer/install-blocklet-cli/)

1. Initialize and start Blocklet Server (this is where your project will be running) with `blocklet server start -a`, for more detailed instructions please checkout  [Install Blocklet CLI](/en/docs/blocklet-developer/install-blocklet-cli/#start-blocklet-server)
2. Complete email verification and blocklet store setup
3.
  1. Get email verification certificate: [https://test.store.blocklet.dev/.well-known/service/kyc/email](https://test.store.blocklet.dev/.well-known/service/kyc/email)  <video src="https://media.arcblock.io/lib/e8/e8002add564fddb645d085c0d26834de.mp4" controls></video>
  2. Get TBA token for future use: [<strong>https://faucet.abtnetwork.io/</strong>](https://faucet.abtnetwork.io/)
  3. Get your developer passport on blocklet store: [https://test.store.blocklet.dev/join](https://test.store.blocklet.dev/join)
  4. Connect blocklet store and your development environment:  `blocklet connect `[`https://test.store.blocklet.dev/`](https://test.store.blocklet.dev/)					 <video src="https://media.arcblock.io/lib/7a/7a1235670bd5c91f18731c8e558b5590.mp4" controls></video>

1. Run `blocklet create` in the terminal, enter the project name, select the `[dapp: did-wallet] Full stack app (react.js + express.js) with DID Wallet integration` template, fill in the author and email, then press Enter:

![image.png](https://media.arcblock.io/lib/6c/6c88c044f0b0edb918181afb97899441.w1600.webp)

Connect using DID Wallet to generate app DID

![image.png](https://media.arcblock.io/lib/ea/ea8aa6c27d806a5b56c8c61cafe520b9.w1600.webp)

![image.png](https://media.arcblock.io/lib/65/65b6469af6a82e0e80dce58d2e6a12e5.w1600.webp)

After successfully generating the application DID, the terminal will output the following information.

```javascript
cd [projectName]
npm install
blocklet dev

Find more usage in README.md
```

1.  Install dependencies

```javascript
cd [projectName]
npm install
// Or use yarn or pnpm install
```

1. Start the development server

```javascript
blocklet dev
// Or use [npm/ yarn / pnpm] dev
```

<video src="https://media.arcblock.io/lib/7b/7b84f46b673d163f825ff619e842ebe1.mp4" controls></video>

## Development

Develop your DID Wallet Dapp using React.js for the front end and Express.js for the back end. The project structure is set up for you to start coding immediately

::::steps
:::step{title="User Authentication"}
:::
::::

-
  - Frontend: Use `useSessionContext` from `@blocklet/sdk/react`
  - Backend: Use` middleware.auth()` from `@blocklet/sdk`

::::steps
:::step{title="API Protection"}
:::
::::

-
  - Secure endpoints with `middleware.auth()` , see more: [https://www.arcblock.io/docs/blocklet-developer/blocklet-sdk#access](/en/docs/blocklet-developer/blocklet-sdk/#access)

::::steps
:::step{title="User Login"}
:::
::::

-
  - The created template application is divided into two main routes: `/home` and `/profile`.
  -
    - The `/home` route is accessible to all users without any authentication requirements.
    - The `/profile` route is protected and requires user authentication. If a user attempts to access this route without logging in, they will be prompted to do so.
  - If you wish to implement global authentication control across the entire application, you can uncomment the relevant code in the components/layout file. This will enable authentication checks for all routes.

![image.png](https://media.arcblock.io/lib/75/75b52f25d9e45fd8d8f2b1b981ab5561.w1600.webp)

::::steps
:::step{title="Navigation and Route Configuration"}
:::
::::

- ![image.png](https://media.arcblock.io/lib/ab/ab21a45b663226f36802f125d9bf79b8.w1600.webp)
  - Navigation: update `blocklet.yml`  to adjust the navigation structure and menu items.

-
  - Route: update `src/app.jsx`  to configure the application's routing logic.

![image.png](https://media.arcblock.io/lib/7b/7b361cc35eb5c3b9fdbf315da7c35da5.w1600.webp)

## Publish Blocklet to Test Blocklet Store

You can complete the application's build and deployment publishing according to the following steps：

1. Bump version: `npm run bump-version`
2. Bundle: `npm run bundle`
3. Upload blocklet to Test Store: `blocklet upload`

Or you can directly use `npm run upload `	to skip bundle and blocklet upload (Step2-3)

1. Publish on store

<video src="https://media.arcblock.io/lib/29/29effe08c3978a87fa66d334cc2d726b.mp4" controls></video>

## Project Ideas

Here are some interesting and useful application ideas for your reference, but of course you can completely follow your own ideas:

- <strong>Local File Transfer Web Tool</strong>: Develop a DID Wallet gated version of Snapdrop that allows users to transfer files directly between devices without relying on a central server, using WebRTC and blockchain technologies for secure, peer-to-peer communication.
- <strong>Decentralized Form Collector</strong>: Create a fully decentralized form builder and data collector similar to Typeform that uses blockchain to store form responses securely and privately.
- <strong>Decentralized Calendly Blocklet</strong>: Develop a decentralized scheduling tool akin to Calendly, where users can manage appointments without relying on a central server, using smart contracts to handle scheduling logic.
- <strong>Personal CV Builder</strong>: Develop a standalone CV builder that allows users to create, manage, and share their professional profiles and resumes in a secure and verifiable manner.

## References

[ArcBlock Official Site](https://www.arcblock.io/docs/blocklet-developer)

[ArcBlock Community](https://community.arcblock.io/discussions/boards/hackathon-support)

For any questions or support, visit the [ArcBlock Community Hackathon Support board ](https://community.arcblock.io/discussions/boards/hackathon-support)or consult the ArcBlock Developer Documentation. Good luck with your DID Wallet Dapp development!

---

## Building on AIGNE

URL: https://www.arcblock.io/en/docs/hackathon/dif-building-on-aigne-studio/

## Introduction

In this article, you will discover the process of developing and deploying an AI application on AIGNE.

AIGNE is a powerful platform for developing and deploying AI applications, offering a seamless process for users. By following the steps outlined in this article, you will learn how to create and launch your own AI application on AIGNE, unlocking its full potential for your business or project. Dive into the world of AI development with AIGNE and see the possibilities it can offer.

## Prerequisites

- Skills required: Prompt / Javascript (optional)
- Environments: Browser

## Getting Started

### Create Project

1. Go to AIGNE official site [https://www.aigne.io](https://www.aigne.io)

[AIGNE](https://www.aigne.io/)

1. Create your first AIGNE project
2.
  1. Hiit "🔥 Try Now" enter AIGNE Studio
  2. Hit "New Project"
  3. Choose a project name, such as "My First AIGNE Project"
  4. Create project

<video src="https://media.arcblock.io/lib/e4/e46494695001ff8c9878bf4d654c1c05.mp4" controls></video>

### Your first Agent

1. Click "+" to create your first Agent "Hello World"
2. You can edit the agent's prompt
3. You can debug it in the right "Debug" panel
4. Click on "Deploy" to deploy your project and receive a link to your application

<video src="https://media.arcblock.io/lib/6a/6a5d2b05d0b77ec1ebe31f539077d394.mp4" controls></video>

### Customize the agent appearance

<video src="https://media.arcblock.io/lib/a6/a68af5b17b08c739172323630689ce47.mp4" controls></video>

1. Add appearance outputs for your agent
2. Choose the component you want for each output and set the corresponding parameters
3. Update your deployment and you can preview the new appearance

### Use Image Blender render template image

1. Create an agent "Certificate"
2. Switch the agent processing to the "Image Blender"
3. Choose a blender template and fill it's parameters
4. Run the agent in the debug view to obtain the final rendered image

<video src="https://media.arcblock.io/lib/61/61bc1c6de629edfc13cb3b386918bf4b.mp4" controls></video>

### Issue VC in the agent

1. In the "Certificate" agent
2. Add an output named "issuedVC" and fill the inputs
3.
  1. The 'Name' field must be letters or numbers and cannot contain spaces or other characters
  2. The 'Display URL' field uses images rendered by Blender `{{$images.0.url}}`
4. Run the Agent, and you can see the detailed data returned for the issued VC

<video src="https://media.arcblock.io/lib/d5/d5a590df0f23ddebbb61adb4a5262a80.mp4" controls></video>

### QA Test Agent

1. Add a "Conversation History" input
2. Add a system prompt and enter QA-related prompts
3. Add an output named "isFinished" with description "Is the QA Test finished?" (The AI will automatically determine whether the test has ended)
4. Add an output named "certificate", it will call "Certificate" agent when `{{isFinished}}` is truth value
5. Add an output named "vc"
6.
  1. Set it's <strong>From -> Template</strong> to `{{certificate.issuedVC.vc}}`
  2. Choose an appearance rendering component 'VC' for it
7. Add "Opening Question" and "Opening Message" outputs
8. Deploy it and initiate the QA test, a VC will be provided upon completion of the test

<video src="https://media.arcblock.io/lib/0c/0c6138cfd2dd8cf558dab8bc244f2c0e.mp4" controls></video>

### Various types of agents

- <strong>LLM (Large Language Model)</strong> is a type of artificial intelligence that uses a large amount of data to generate human-like text. It can be used for various tasks such as language translation, text generation, and content creation. LLMs have been criticized for their potential to spread misinformation and bias.
- <strong>Image Generation</strong> is a type of agent used to generate images based on certain parameters or inputs. It can be used to create realistic images, generate new artwork, or even enhance existing images.
- <strong>Image Blender</strong> supports rendering images using Blender templates
- <strong>Logic</strong> is an agent that supports coding. You can program it using Javascript/Typescript.
- <strong>API</strong> type Agent allows calling an http interface.
- <strong>Decision</strong> is used for decision-making, allowing AI to help you judge and choose which Agent to run next.
- <strong>Call Agent</strong> can be used to package a basic Agent, customize its input and output, making it a more user-friendly Agent.

### Deploy

The Deploy function has already been demonstrated in the above steps.

## Project Ideas

- <strong>DIF Knowledge Base</strong>: Develop a simple AI-powered chatbot that can answer FAQs about decentralized identities using AIGNE Studio.
- <strong>Digital Identity Verification Badge</strong>: Design a digital badge using NFT Studio that users can earn after verifying their identity on a platform, showcasing their verified status.
- <strong>Event Attendance Certificates</strong>: Utilize NFT Studio to design and issue digital certificates for event attendance, which can be linked to the user's DID for authenticity..
- <strong>Event Ticketing System</strong>: Develop a decentralized event ticketing platform that leverages verifiable credentials to issue, verify, and manage event tickets. This system will ensure that each ticket is linked to a user's decentralized identity, making it nearly impossible to counterfeit or scalp tickets.
- <strong>Online Course Certification System</strong>: Create an online platform where educational institutions or trainers can issue verifiable certificates for course completion and exam passing. This system will use decentralized identities to authenticate the issuance and receipt of certificates.

## Read More

You can learn more about the usage to perfect your agent

<details>
<summary><strong>Customize the agent's Image Blender Templates</strong>
</summary>

We built some beautiful templates into AIGNE, and we'll share how "Online Course Certification" was created!

1. Go to the Template Management by clicking on Image Blender in AIGNE ![QQ_1729564357115.png](https://media.arcblock.io/lib/d1/d1aeec9615e8aaa51774495590f4d725.w1600.webp)
2. Go To NFT Blender and Create a Template

![QQ_1728013671033.png](https://media.arcblock.io/lib/65/65de013ef44cb4930c279724418df82b.w1600.webp)

1. Go to Template Details, we did the following operations to prepare the canvas
2.
  1. With the "Add Materials To Canvas" on the left, we added a series of backgrounds
  2. With the "Render Area Buttons" on the top, we added a 512 x 512 Render Area Border
  3. With the "Template Information" on the right, we changed its title and description

![QQ_1728013985952.png](https://media.arcblock.io/lib/31/31f663d20895088a247e1a515dbff5bf.w1600.webp)

1. Add the background to the Canvas and turn on the "Allow Random Material" switch on the right to allow these background materials to be combined freely.

![QQ_1728015920857.png](https://media.arcblock.io/lib/49/49d875762d70608efa3440d0246be805.w1600.webp)

1. We added some text, some of which required dynamic data, and we used the {{mustache}} dynamic input syntax to populate it, such as username

![QQ_1728016243751.png](https://media.arcblock.io/lib/0c/0c7e11fcea190ea99de739372d9fa34b.w1600.webp)

1. Finally, after debugging the template preview with the dynamic input, we get our template

![QQ_1728016452814.png](https://media.arcblock.io/lib/4f/4f9a616027cfa3b7bd9bf10d64f4c6f7.w1600.webp)

</details>

---

## Building on DID Spaces

URL: https://www.arcblock.io/en/docs/hackathon/dif-building-on-did-spaces/

## Introduction

In this article, you will learn how to use the Todo List application that has integrated DID Spaces, and store your data in DID Spaces.

## Prerequisites

- Skills required: developers with a certain foundation in developing React + Express + Typescript applications.
- Operating System: It is recommended to use MacOS, and Linux for development, while Windows needs   [Developing Blocklet in Docker](/en/docs/blocklet-developer/develop-blocklet-with-docker/)
- Environment: Node.js >= 20

## Getting Started

### Preparation

1. Install DID Wallet: please refer to  [Setup DID Wallet](/en/docs/blocklet-developer/setup-did-wallet/)   <video src="https://media.arcblock.io/lib/3e/3ece9961f911eb1b8082b6653971e263.mp4" controls></video>
2. Install Node.js: please refer to  [Setup Node.js](/en/docs/blocklet-developer/setup-nodejs/)
3. Install Blocklet CLI: Please refer to  [Install Blocklet CLI](/en/docs/blocklet-developer/install-blocklet-cli/)
4. Complete email verification and blocklet store setup
5.
  1. Get email verification certificate: [https://test.store.blocklet.dev/.well-known/service/kyc/email](https://test.store.blocklet.dev/.well-known/service/kyc/email)  <video src="https://media.arcblock.io/lib/e8/e8002add564fddb645d085c0d26834de.mp4" controls></video>
  2. Get TBA token for future use: [<strong>https://faucet.abtnetwork.io/</strong>](https://faucet.abtnetwork.io/)
  3. Get your developer passport on blocklet store: [https://test.store.blocklet.dev/join](https://test.store.blocklet.dev/join)
  4. Connect blocklet store and your development environment:  `blocklet connect `[`https://test.store.blocklet.dev/`](https://test.store.blocklet.dev/)					 <video src="https://media.arcblock.io/lib/7a/7a1235670bd5c91f18731c8e558b5590.mp4" controls></video>

### Create an application(video version)

<video src="https://media.arcblock.io/lib/f7/f75a96520bf25a91512102a796bcc7cb.mp4" controls></video>

### Create an application(text version)

1. Create a Todo List application

Now we can use the capabilities of Blocklet CLI to create a minimalist Todo List application integrated with DID Spaces in just a few minutes, which you can use as a basis for further development.

Enter `blocklet create` in the terminal, enter the project name, select the `[dapp: todo-list] react + express + typescript + DID Spaces` template, fill in the author and email, then press Enter:

```javascript
╰─➤  blocklet create
blocklet create v1.16.32-beta-20240924-105841-08174626
Need to install the following packages:
create-blocklet@0.9.5
Ok to proceed? (y) y

                 Powered By
     _             ____  _            _
    / \   _ __ ___| __ )| | ___   ___| | __
   / _ \ | '__/ __|  _ \| |/ _ \ / __| |/ /
  / ___ \| | | (__| |_) | | (_) | (__|   <
 /_/   \_\_|  \___|____/|_|\___/ \___|_|\_\

            Create Blocklet v0.9.5

✔ Project name: … todo-list //
? Choose one or more blocklet templates: ›
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  [dapp] react + express.js
◯  [dapp] react + express + typescript
◉  [dapp: todo-list] react + express + typescript + DID Spaces // 选择 DID Spaces 模板
◯  [dapp] solid + express.js
◯  [dapp] vue3 + express.js
◯  [dapp] svelte + express.js
◯  [static] react
◯  [static] solidjs
◯  [static] vue3
◯  [static] vue3 + typescript
```

Connect using DID Wallet to generate app DID

![image.png](https://media.arcblock.io/lib/ea/ea8aa6c27d806a5b56c8c61cafe520b9.w1600.webp)

![image.png](https://media.arcblock.io/lib/65/65b6469af6a82e0e80dce58d2e6a12e5.w1600.webp)

After the successful generation of the application DID, the terminal will output the following information.

```javascript
cd todo-list
npm install
blocklet dev

Find more usage in README.md
```

1. Run the application

Now, we can enter the following command to launch the todo-list application in development mode.

```javascript
cd todo-list
npm install // pnpm install or yarn install
blocklet dev
```

Login to the app and select your DID Spaces as the storage medium:

<video src="https://media.arcblock.io/lib/b8/b88ea01a1f9791d297242ea7db620aea.mp4" controls></video>
Create your Todo in the app. Once created successfully, the data will be stored in DID Spaces:

<video src="https://media.arcblock.io/lib/92/9288ba2d293ba4bc99f34fa59795cb8d.mp4" controls></video>

1. View data on DID Spaces

We can access the DID Spaces page by clicking on the avatar in the top right corner of the app -> clicking Profile -> clicking Settings -> clicking Storage.

On the DID Spaces page, click on the Todo List app, and then enter the specified folder to view the data stored in todo-list.json:

<video src="https://media.arcblock.io/lib/25/252f03d82f7766f255ad623138d88995.mp4" controls></video>

### Extended Development

When modifying your Todo on the front-end page, it will trigger the PUT API of the Todo List.

```javascript
  // src/pages/todo-list.tsx
  const putTodoList = (todoArray: Todo[]) => {
    return axios.put('/api/todo-list', {
      todoList: todoArray,
    });
  };
```

Upon receiving a PUT request, the backend API utilizes [@did-space/client](/en/docs/did-spaces/put-object-command/) capabilities to write data to DID Spaces.

```javascript
  // api/src/routes/todo-list/$put.ts
  const output = await spaceClient.send(
    new PutObjectCommand({
      key: 'todo-list.json',
      data: JSON.stringify(req.body.todoList),
    }),
  );
```

At this stage, you should be able to develop an application tailored to your specific business requirements based on this minimalist example.

For more information on developing with DID Spaces, please refer to our [development guide](/en/docs/did-spaces/did-spaces-how-to-guides/) and [API documentation](/en/docs/did-spaces/api-reference/).

### Publish Blocklet to Test Blocklet Store

You can complete the application's build and deployment publishing according to the following steps：

1. Bump version: `npm run bump-version`
2. Bundle: `npm run bundle`
3. Upload blocklet to Test Store: `blocklet upload`

Or you can directly use `npm run upload `	to skip bundle and blocklet upload (Step2-3)

1. Publish on store

<video src="https://media.arcblock.io/lib/29/29effe08c3978a87fa66d334cc2d726b.mp4" controls></video>

## Project Ideas

Here are some interesting and useful application ideas for your reference, but of course you can completely follow your ideas:

- <strong>Verifiable Email Signatures</strong>: Develop a web app where users can customize email signatures with a simple form and generate/persist/verify verifiable credentials in DID Spaces, then attach a public link to the email signature, the link will give a verifiable page of the signature
- <strong>Personal Identity Blocklet</strong>: Create a personal identity blocklet similar to [https://about.me](https://about.me), where users can build a personal landing page that aggregates links to their digital presence, powered by decentralized identity (DID).
- <strong>Decentralized User Profiles</strong>: Create a web app that allows users to design and generate personalized profile pages, which can be a alternative of [https://linktr.ee](https://linktr.ee)
- <strong>Private Content Sharing Platform</strong>: Develop a web app where users can create private, encrypted spaces to share content securely, utilizing DID Spaces as the base storage.

## References

Any issues encountered during this process, any suggestions generated, can be discussed in our community forum.

[ArcBlock Community](https://community.arcblock.io/discussions/boards/hackathon-support)

---

## DIF Hackathon Guide (2024)

URL: https://www.arcblock.io/en/docs/hackathon/dif-hackathon-2024/

Welcome to the ArcBlock DIF Hackathon! As proud [Decentralized Identity Foundation](https://identity.foundation) (DIF) members, we are thrilled to invite developers of all skill levels to explore and contribute to the future of decentralized identities. Whether you are a seasoned developer, new to the field, or without any coding skills, this hackathon provides a platform to innovate, create, and impact the decentralized web.

## Objectives and Goals

Our goal for this hackathon is to expand the possibilities and applications of decentralized identity by leveraging [ArcBlock's platform](https://www.arcblock.io). We aim to foster innovation that enhances user control and security over their digital identities through applications that are accessible, secure, and interoperable across various platforms and services.

## Challenges and Problem Statements

Participants are encouraged to tackle one or more of the following challenges:

- <strong>Low-code</strong> <strong>challenges</strong>: start building directly on our hosted service
-
  - <strong>Build on AIGNE Studio</strong>: Build AI-powered applications that support issueing appealing certificates (verifiable credentials) to decentralized identities
- <strong>Full-code</strong> <strong>challenges:</strong> starting from our project templates
-
  - <strong>Integrate with DID Wallet</strong>: Build applications that support user access with DID Wallet, our platform has built-in support for authentication with DID Wallet.
  - <strong>Innovate with DID Spaces</strong>: Build applications that create digital spaces and utilize decentralized identities to enhance user privacy and data ownership.
  - <strong>Leverage DID Connect</strong>: Develop applications that leverage the various use cases of DID Connect, or integrate DID Connect into existing authentication solutions such as passport.js.

## Technology and Tools

Participants will have access to ArcBlock’s comprehensive suite of tools:

- [<strong>AIGNE Studio</strong>](https://www.aigne.io): An AI Generative App platform for creating AI-powered apps that issuing verifiable credentials to decentralized identities.
- [<strong>DID Wallet</strong>](https://www.didwallet.io): The dedicated tool for managing digital identities (profiles and verifiable credentials), and digital assets (tokens, NFTs).
- [<strong>DID Spaces</strong>](https://www.didspaces.com/): A framework and service for creating and managing digital identity spaces, with which you can store any data owned by decentralized identities.
- [<strong>DID Connect</strong>](https://www.didconnect.io): A protocol for seamless connections between DID Wallet and decentralized applications.

## Participation Guidelines

Not sure which direction to go in when it comes to building applications? No worries! Here's a detailed comparison of 5 different building directions for you to consider. Take a look and choose the one that best fits your skills and the specific requirements of each direction.

| Topic  | Type  | Skill Requirements  | Environment Requirements  | Difficulty Level  | Video Tutorial  |
|---|---|---|---|---|---|
| [Building on AIGNE](/en/docs/hackathon/YgKlCBaFgdsf3zzySP4d4x5A/)    | No Code  | Basic Prompt Engineering  | PC, Internet, DID Wallet  | ⭐️  | TBD  |
| [Building with DID Wallet](/en/docs/hackathon/ATZhr-X_NEZGyx_KBrkaXTEy/)    | Full Code  | React.js, Express.js  | Web Developer, DID Wallet  | ⭐️⭐️  | TBD  |
| [Building on DID Spaces](/en/docs/hackathon/eb_0yPRdLp7DsGBjEi83mWdG/)    | Full Code  | React.js, Express.js  | Web Developer, DID Wallet  | ⭐️⭐️⭐️  | TBD  |
| [Building on DID Connect](/en/docs/hackathon/O5QlCMBqdFi9ZicMXWIUlbfP/)    | Full Code  | React.js, Express.js  | Web Developer, DID Wallet  | ⭐️⭐️⭐️  | TBD  |

Side notes:

- DID Wallet is used to manage your developer identity on the ArcBlock platform during the building process
- Difficulty levels are measured by how much effort you need to make some working apps

- [Building on AIGNE](/en/docs/hackathon/dif-building-on-aigne-studio/)

- [Building with DID Wallet](/en/docs/hackathon/did-building-on-did-wallet/)

- [Building on DID Spaces](/en/docs/hackathon/dif-building-on-did-spaces/)

- [Building on DID Connect](/en/docs/hackathon/did-building-on-did-connect/)

- [FAQ](/en/docs/hackathon/3U5V2c2ffFoWDuJPGQjiGl-P/)

## Prizes and Incentives

To reward innovation and participation, the following incentives (along with the DIF hackathon reward) will be offered:

- <strong>Builder Rewards</strong>: Anyone who joins the hackathon and gets their app published in our [Blocklet Store](https://store.blocklet.dev). will share a reward pool of 5000 ABT.
- <strong>Revenue Sharing</strong>: A share of the revenue from every future installation of your blocklet via the [ArcBlock Launcher](https://launcher.arcblock.io/) if your blocklet is accepted by our [Blocklet Store](https://store.blocklet.dev).
- <strong>NFT Airdrops</strong>: Early participants will receive special NFTs as a token of appreciation.
- <strong>Extended Support</strong>: Ongoing support and potential incubation for promising projects.

## Support and Mentorship

ArcBlock is committed to supporting all participants:

- <strong>Engineering Support</strong>: Our team can help you through each blocklet creation and publishing step. Direct support is available through the [ArcBlock Community](https://community.arcblock.io/discussions/boards/hackathon-support).
- <strong>Community Interaction</strong>: Engage with other builders and the ArcBlock team for feedback, ideas, and collaborations.

## Let's Build Together!

This hackathon is more than just a competition; it’s an opportunity to be part of a community dedicated to revolutionizing decentralized applications. We are excited to see your innovative solutions and how they contribute to the evolving landscape of decentralized identity.

Join us in shaping the future — your creativity and skills can lead to groundbreaking advancements in decentralized identity solutions. Let’s innovate, create, and succeed together!

---

## Identity and Data Spaces

URL: https://www.arcblock.io/en/docs/identity-data-spaces/

---

## Caller context

URL: https://www.arcblock.io/en/docs/identity-data-spaces/caller-context/

ARC resolves caller information from trusted credentials before it builds a session view. The resulting `CallerInfo` can carry a DID, authentication method, roles, and, when the server supplies a trusted instance context, an instance DID.

## What the runtime knows

`CallerInfo` (AFS core type) is the handoff shape after resolution:

| Field | Meaning |
|---|---|
| `did` | Caller DID, or `null` for anonymous. Treat `null` as anonymous, never as a sentinel string. |
| `roles` | Role strings after resolution (often a one-element array). |
| `pk` | Public key (hex) when available. |
| `authMethod` | How the caller authenticated (for example passkey, access-key, did-connect). |
| `instanceDid` | Instance context stamped by the server when membership or display needs it. |
| `displayName` | Optional display name for UI. |
| `authSource` | `"cookie"` or `"bearer"` — how the credential arrived. |

Mutating AFS RPC operations that care about CSRF require `authSource: "bearer"`. A cookie alone is not enough for those writes.

## Credential inputs

The shared caller core (`services/shared` → both Node and Cloudflare) accepts:

| Input | Resolution path |
|---|---|
| `Cookie: login_token=<JWT>` | Browser session JWT. |
| `Authorization: Bearer <JWT>` | Programmatic / mobile JWT (not an access key). |
| `Authorization: Bearer blocklet-…` | Blocklet-service access key. |

Anonymous requests (no JWT candidate and no Authorization header) resolve to `null`. Invalid or unresolvable credentials also return `null`; the core does not throw for ordinary unauthenticated traffic.

## Membership overlay

Instance membership is an overlay on trusted server context:

1. The server resolves the request's tenant / instance DID.
2. When that value is present, the general caller path sets `membership: true` and feeds it into connect-service `resolveIdentity`.
3. Connect-service can return a per-instance role (`owner` / `admin` / `member` / `guest`) on top of the user's global role.
4. The client cannot create that relationship by naming an instance in a UI message or by forging an instance header on paths that strip or replace client-supplied instance identifiers.

Some ingress paths remove or replace a client-supplied instance header before resolution. Treat that as an ingress-specific safeguard, not as a universal guarantee for every ARC entry point you invent later.

## Role ordering fails closed

Role comparison uses a fixed ordinal:

| Role | Level |
|---|---|
| `guest` | 0 |
| `member` | 1 |
| `admin` | 2 |
| `owner` | 3 |

Any unrecognised or absent role maps to level `0` (`guest`). Do not invent intermediate roles in application code and assume the runtime will honor them.

## Keep presentation separate from authorization

Use a session fact to decide whether a page should show an action. Do not treat that condition as the authorization check. The provider and runtime still decide whether the resolved caller may read, write, execute, or traverse a resource.

The same rule applies to identity input. A text field, a URL parameter, a page route, or a `$session` substitution cannot establish a caller identity. It may name a resource, but only server-side credential resolution can determine who is asking.

AUP-facing guidance for the same boundary: [Caller identity and safety](/en/docs/aup/caller-identity-safety/).

## Evidence

| Claim | Evidence |
|---|---|
| Shared credential → `CallerInfo` mapping | `services/shared/src/caller.ts` (`mapToCallerInfo`, `resolveCallerFromCredentials`) |
| Node daemon auth wire-up | `runtimes/node/src/daemon/auth/index.ts` (`setupAuthService`, `resolveCaller`) |
| Role fail-closed ordinal | `packages/aos/src/session/role-level.ts` |
| `CallerInfo` field contract | `packages/core/src/type.ts` |
| Read-only memberships AFS view | `@aigne/afs-members` (`providers/basic/members/`) — list/get only; not a membership-admin API |

## Current boundary

This page documents caller resolution and its fail-closed role behavior. It does not document account creation, DID recovery, membership administration UI, or a complete instance-identity lifecycle. Do not infer those flows from the presence of a DID or a role in a session.

---

## Core model

URL: https://www.arcblock.io/en/docs/identity-data-spaces/core-model/

Identity and storage have different jobs. A verified caller context describes who made a request and which role the runtime resolved. A DID Space is an AFS provider that exposes storage within a DID-scoped logical space. `Data Space` is the name this board uses when discussing the resulting data context from a developer's point of view.

Do not collapse those roles into one object:

| Concern | Object in ARC | Public surface today |
|---|---|---|
| Who is calling | `CallerInfo` after credential resolution | Runtime handoff into session and AFS context |
| Where durable data lives | DID Space (`@aigne/afs-did-space`) | AFS mount + local `arc space` inspection |
| What a session can see | Session overlays `/user`, `/tmp`, optional `/space` | Session-constrained AFS paths |
| How docs name the whole context | Data Space (term only) | No separate importable API |

The caller may be authenticated without receiving a particular mounted data view. A storage path may be present without allowing a network-origin read or write. A product term may be useful for explanation without being a stable API.

## Child pages

1. [Caller context](../caller-context/) — verified identity, credentials, roles, membership overlay.
2. [DID-scoped storage](../did-space/) — provider package, role prefixes, transport capability differences.
3. [What “Data Space” means here](../data-space-term/) — deliberately narrow documentation use of the term.

After the core model, read [Session data](../session-data/) for the views a session actually receives, then [Current contract boundaries](../current-boundaries/) before shipping assumptions.

---

## Current contract boundaries

URL: https://www.arcblock.io/en/docs/identity-data-spaces/current-boundaries/

The following boundaries are intentional. They keep this board from turning architecture intent or a historical product page into a present-tense product commitment.

## Safe statements versus non-promises

| Topic | Current safe statement | Do not claim yet |
|---|---|---|
| Data Space | Explanatory name for data context and session-visible views. | Separate public `DataSpace` API, resource type, or provisioning lifecycle. |
| DID Space | AFS provider for DID-scoped storage; may appear through session views and local CLI. | One backend, one remote deployment path, or equal ops for all transports. |
| Session scope | Tests cover current-caller isolation, `/tmp`, optional `/space`, and network base write gates. | Universal application ACL for every Blocklet and every path. |
| `/space` writes | Optional overlay; general writes may be readonly; collections write-guard is a fixed policy when wired. | Open write access to the whole DID Space root by default. |
| Caller and membership | Trusted credential resolution attaches caller identity and may overlay an instance role. | User account recovery, membership administration product, or complete instance DID lifecycle. |
| VC / trust | Not a public default gate documented here. | “VC trust is on by default” or full issuer-revocation operations. |
| Public sharing / CDN | Share and hosting mechanisms exist in provider code and plans; not packaged here as anonymous share-as-default. | DID Space is a public CDN or open anonymous data plane. |
| DID Connect | Runtime embeds connect-service for credential resolution and related host endpoints. | One-for-one migration of every former standalone UI or product surface. |
| Cloud sync CLI | `arc space sync` exists as a command and reaches a remote end when `--from`/`--to` is an `https://<host>` reference. | A re-verified remote E2E runbook on this board (not captured here). |
| Historical products | Names such as DID Spaces / DID Connect appear in lineage and runtime seams. | Every historical feature is already a stable ARC equivalent. |

## Architecture drafts are not contracts

Internal materials such as `docs/architecture/did-entities.md` and `docs/architecture/did-space.md` explain intent and evolution. They mark incomplete areas (for example instance DID lifecycle) explicitly. Public pages on this board only absorb conclusions that current source, tests, or a named CLI run still support.

## If you need something in the right column

1. Narrow the requirement to a testable claim.
2. Verify it against the target ARC release (source + tests + runtime).
3. Add a versioned operational page only after that evidence exists.
4. Until then, keep the gap explicit rather than papering it over with path-shaped language.

See [Evidence and version boundaries](../evidence-and-versions/) for the re-verification checklist used by this board.

---

## What “Data Space” means here

URL: https://www.arcblock.io/en/docs/identity-data-spaces/data-space-term/

In this board, `Data Space` is a reader-facing term for the data context an application can reason about: which caller is present, which AFS mounts or overlays are available, and which paths are visible through that session.

## What exists in code today

| Exists as implementation | Does not exist as a public product surface |
|---|---|
| DID Space providers (`@aigne/afs-did-space` local / Cloudflare) | A `DataSpace` class, package, or SDK |
| `CallerInfo` and session overlays | A `DataSpace` configuration file or lifecycle API |
| Logical AFS paths such as `/user`, `/tmp`, `/space` | A second backend parallel to DID Space |
| CLI `arc space` against local DID Space data | A separate “Data Space admin” product |

Keep the name at the explanatory layer until a versioned public contract exists.

## Mistakes this distinction prevents

- Designing against an imagined `DataSpace` API because a product conversation uses the term.
- Assuming every DID-scoped path belongs to a single caller-visible session view. The runtime may mount, filter, or reject it according to caller and provider policy.
- Treating ObjectStore layout, SQLite metadata files, or on-disk CID pools as the logical contract. Session and AFS paths are the contract; physical layout is an implementation detail.

## How to talk about it

| Prefer | Avoid |
|---|---|
| “the caller's data context” / “session-visible views” | “the Data Space backend” |
| “DID Space provider” for the storage implementation | “Data Space provider” as if it were a package name |
| “inspect local DID Space with `arc space`” | “connect to the Data Space API” |

Use [Session data](../session-data/) for the verified current views. Use [Current contract boundaries](../current-boundaries/) before extending this term in public material.

---

## DID Connect in ARC

URL: https://www.arcblock.io/en/docs/identity-data-spaces/did-connect/

The Node runtime imports the embedded `@arcblock/did-connect-service` and uses it at its authentication boundary. The resolver accepts trusted credentials, constructs caller information for AFS, and can add an instance membership role when the server supplies a trusted instance DID.

## Runtime seam

| Piece | Role in ARC |
|---|---|
| `createEmbeddedAuthService` | Boots connect-service against a local SQLite (or injected) auth database under the daemon home |
| HTTP handler | Serves `/.well-known/service/*` for connect endpoints the host exposes |
| `rpc.resolveIdentity` | Turns JWT / access-key inputs into a connect-service identity DTO |
| Shared `resolveCallerFromCredentials` | Maps that DTO to AFS `CallerInfo` for both Node and Cloudflare |
| `@aigne/afs-members` | Optional read-only AFS view of instance memberships for the fixed instance DID |

Membership context is not client-selected. Only a server-resolved instance DID may enter membership resolution. A request cannot create a stronger relationship with an instance merely by naming one.

## What to integrate against

Treat ARC's caller context as the handoff point for an AFS-aware Blocklet:

1. Rely on the runtime to produce `CallerInfo`.
2. Bind presentation to session facts if needed.
3. Let provider and session policy authorize each operation after the handoff.

If you need DID Connect protocol, wallet flows, or SDK usage outside the ARC runtime seam, use DID Connect's own documentation and packages. Do not treat this page as a full DID Connect product manual.

## What not to treat as the ARC product surface

| Material | How to treat it |
|---|---|
| Historical DID Connect admin / management UIs | Lineage or optional host UI — not the stable ARC extension contract for new apps |
| Standalone historical product marketing pages | Continuity references only; not proof of a complete migration into ARC |
| `arc did` developer / provider / blocklet identity tools | Separate CLI identity workflow for entity manifests; not end-user session login |

`arc did info` and `arc did check` require an entity manifest in the current directory (`blocklet.yaml`, `.aup/`, and related layouts). Running them in an empty directory fails with:

```text
ERROR: No entity manifest found in current directory (looked for blocklet.yaml, .aup/, index.html, index.{txt,md,ans}, package.json)
```

That failure is expected for session-auth work; those commands are for package/provider identity, not for inspecting a logged-in end user.

## Related

- [Caller context](../caller-context/) — field-level `CallerInfo` contract
- [Integrate identity](../integrate/) — order of work for Blocklet authors
- [Current contract boundaries](../current-boundaries/) — non-promises around trust and lifecycle

---

## DID-scoped storage

URL: https://www.arcblock.io/en/docs/identity-data-spaces/did-space/

`@aigne/afs-did-space` implements DID-scoped persistent storage as an AFS provider. One principal DID maps to one DID Space. A service or blocklet occupies a path prefix inside that space; it does not receive a second parallel storage product.

## Package surfaces

| Import / entry | Role |
|---|---|
| `@aigne/afs-did-space` | Package root |
| `@aigne/afs-did-space/local` | Node local provider (`DIDSpace`) — filesystem objects + SQLite metadata |
| `@aigne/afs-did-space/cloudflare` | Cloudflare provider — D1 index + R2 objects |
| `@aigne/afs-did-space` client / transports | Mount remote or static views as AFS modules |

Package description in source: *AIGNE AFS provider for DID-scoped persistent storage with CID-based content deduplication*.

## Role prefixes under an instance

For an instance fragment, the local provider requires role `system` or `user` and builds a role-specific prefix under the principal's blocklet space:

```text
{principalDid}/blocklets/{instance-did}/system/...   # installer / instance-owned
{principalDid}/blocklets/{instance-did}/user/...     # caller-owned for that principal
```

`getInstanceSpace({ instanceDid, role })` rejects any other role string. Role content trees sit directly at the role root (no extra `files/` wrapper). `config/` is an internal sibling for provider configuration and is not part of the blocklet `/instance` view.

When you inspect with CLI, those prefixes appear as logical AFS paths:

```text
/spaces/<user-did>/blocklets/<app-did>/system
/spaces/<user-did>/blocklets/<app-did>/user
```

`arc space path` prints those fragments. See [Inspect local spaces](../local-inspection/).

## Minimal local mount sketch

```ts
import { DIDSpace } from "@aigne/afs-did-space/local";

const space = new DIDSpace({
  rootPath: "~/.afs/spaces",
  userDid: "did:abt:z1...",
});

const afs = await space.getInstanceSpace({
  instanceDid: "did:abt:z1blocklet",
  role: "system",
});
await afs.write("/hello.txt", { content: "hello" });
```

This sketch shows the provider boundary. It is not a full deployment recipe. Prefer session views (`/user`, optional `/space`) inside a running blocklet rather than re-implementing mount selection in application UI code.

## Transport capabilities are not equal

`connectDIDSpace` accepts transport kinds `http`, `ws`, and `static-readonly`. The client strips operations the transport does not support so AFS routing sees `undefined` methods instead of surprising remote failures.

| Transport | Default access mode | Stripped or unsupported ops (current client) |
|---|---|---|
| `ws` | `readwrite` (unless overridden) | Full forward set when the transport implements it |
| `http` | `readwrite` (unless overridden) | `stat`, `search`, `exec`, `explain` unsupported |
| `static-readonly` | `readonly` | `search`, `exec` unsupported; `write` / `delete` stripped by access mode |

Do not treat “mounted in AFS” as a promise that every view can read, write, search, and execute. Write a Blocklet against the operations its chosen transport has actually exposed and tested.

Local and Cloudflare backends also share content-addressed objects (`.objects/{cid}`), tree indexes, and conformance suites. Backend choice does not by itself equalize transport capabilities.

## What this page does not specify

- One physical backend as the only supported deployment.
- Public CDN, anonymous share-as-default, or “open the whole space on the internet” behavior.
- A complete remote import/export operational runbook (cloud subcommands exist on `arc space`; they need environment-specific auth and are not re-run as part of this page).
- Instance DID lifecycle or VC trust gates.

For session-visible paths over this storage, continue with [Session data](../session-data/). For local CLI inspection, continue with [Inspect local spaces](../local-inspection/).

---

## Evidence and version boundaries

URL: https://www.arcblock.io/en/docs/identity-data-spaces/evidence-and-versions/

This board states two kinds of facts:

1. **Implementation facts** — true of the `ArcBlock/arc` tree and its tests at documentation time.
2. **Operational facts** — true of a named `arc` CLI release after commands were actually run in an isolated directory.

Do not upgrade an implementation fact into an operational recipe without a re-run.

## Baseline for this revision

| Axis | Value |
|---|---|
| Site board | `docs/identity-data-spaces` |
| CLI verified | `arc` **2.0.0-beta.28** (`arc --version`) for the implementation facts on this board; the operational recipe was re-captured on **2.0.0-beta.42**, whose `arc space` command surface differs |
| Operational capture | Isolated `--root-path` + fixture `--user-did` (see [Inspect local spaces](../local-inspection/), re-run on 2.0.0-beta.42) |
| Source tree | `ArcBlock/arc` (read-only reference at documentation time) |
| Primary source areas | `providers/basic/did-space/`, `providers/basic/members/`, `services/shared/src/caller.ts`, `runtimes/node/src/daemon/auth/`, `packages/aos/src/session/` |

## Evidence hierarchy

| Rank | Source | Can support |
|---|---|---|
| 1 | Current source + target-version tests + real local run | “Supported now” |
| 2 | Package README for the same package | Scope explanation; still re-run commands |
| 3 | Merged PR | That a change landed; re-check for later drift |
| 4 | Architecture draft / planning / historical product page | Intent and lineage only |

## Re-verify checklist

Run these steps when the CLI version, provider package, or session overlay behavior changes.

### A. CLI identity

```bash
arc --version
arc space --help
arc did --help
```

Record the version string on every operational page you refresh.

### B. Isolated space recipe

Repeat the recipe on [Inspect local spaces](../local-inspection/) with a fresh empty `--root-path`:

1. `list` on empty root
2. `sync` into the `system` and `user` fragment directories (read the destination back with `path` first — the scope directory is derived from the user DID)
3. `tree` and `path` for both scopes
4. `rm` and re-`tree`
5. Failure cases: missing app, invalid scope on `tree`, missing `path` argument

Replace pasted outputs with the new capture. Do not keep old timings or byte sizes if they changed.

### C. Source anchors (read-only)

Confirm these still match the prose:

| Claim | Look at |
|---|---|
| Caller mapping + membership flags | `services/shared/src/caller.ts` |
| Node auth setup | `runtimes/node/src/daemon/auth/index.ts` |
| Role fail-closed | `packages/aos/src/session/role-level.ts` |
| Session overlays | `packages/aos/src/session/session-user-afs.ts` |
| DID Space roles + local provider | `providers/basic/did-space/src/local.ts` |
| Transport op stripping | `providers/basic/did-space/src/client.ts` |
| Isolation tests | `runtimes/node/test/daemon/two-user-space-isolation.test.ts`, `scope-user-space-overlay.test.ts` |

### D. What not to re-assert without new E2E

- Complete instance DID provisioning lifecycle
- VC trust gate as a default public contract
- Remote `sync` (an `https://<host>` end) against a specific production server
- Historical DID Connect admin UI as the ARC-stable surface
- Anonymous public share as the default data plane

## Drift handling

| Symptom | Action |
|---|---|
| CLI output differs only in timing/size | Update the paste; keep the procedure |
| Subcommand flags change | Update local-inspection and link to arc-cli reference |
| Session overlay semantics change | Update session-views + isolation table; cite new tests |
| Package rename | Update did-space page imports and evidence table |
| Architecture draft conflicts with code | Prefer code; note the draft as archaeology only |

## Related

- [Current contract boundaries](../current-boundaries/)
- [Inspect local spaces](../local-inspection/)
- [arc space command reference](/en/docs/arc-cli/command-reference-space/)

---

## Integrate identity

URL: https://www.arcblock.io/en/docs/identity-data-spaces/integrate/

The integration point for identity is not a client widget. ARC resolves credentials into caller context at the runtime boundary, then uses that context when it constructs session data views and applies policy.

## Recommended order

1. Read [Caller context](../caller-context/) so you know what `CallerInfo` contains and what fails closed.
2. Read [Session data](../session-data/) and [session views](../session-views/) so you know which paths a caller can receive.
3. Store durable per-user data through the session's `/user` (and only use `/space` when the runtime enables it for your blocklet scope).
4. Keep authorization in provider and runtime policy. Use AUP or Web Device only for presentation and path binding.
5. When you need the protocol or SDK itself, follow [DID Connect in ARC](../did-connect/) for the runtime seam, then link out to DID Connect upstream materials for protocol details.

## What “integration” means in ARC

| Layer | Your job | Runtime job |
|---|---|---|
| Credentials | Do not invent alternate auth headers in UI messages | Resolve cookie / Bearer / access key into `CallerInfo` |
| Session view | Bind UI and logic to `/user`, `/tmp`, and declared mounts | Build `SessionUserAFS` for the resolved caller only |
| Membership | Do not trust client-selected instance roles | Overlay membership only when server supplies instance context |
| Storage | Mount or use DID Space through supported AFS paths | Enforce role prefixes, isolation, and write gates |

## Practical rules

- Prefer session paths over reconstructing `spaces/<did>/blocklets/...` in application code.
- Prefer server-resolved caller fields over form fields that “look like” a DID.
- Prefer local blocklet runs for UI acceptance; use isolated `arc space --root-path` for offline data inspection ([Inspect local spaces](../local-inspection/)).
- Do not package historical DID Connect admin UIs as the ARC-stable extension surface for new work.

## Not covered here

End-to-end passkey onboarding screens, OAuth provider configuration, remote multi-tenant provisioning, and membership administration APIs need their own versioned contracts and examples. This section stops at the verified handoff that current source implements.

---

## Inspect local spaces

URL: https://www.arcblock.io/en/docs/identity-data-spaces/local-inspection/

Use `arc space` to inspect **local** DID Space data: which app fragments exist, what logical tree they hold, and which AFS path a fragment maps to. This is offline DX on a data directory. It is not a substitute for a live session view (`/user`, `/tmp`, `/space`), and it is not a formal cloud deployment.

Verified against **ARC CLI `2.0.0-beta.42`**. Full man-style coverage of every subcommand also lives in [arc space](/en/docs/arc-cli/command-reference-space/). This page focuses on a reproducible local recipe and failure modes.

## Preconditions

| Item | Value used in the capture below |
|---|---|
| CLI | `arc` `2.0.0-beta.42` (`arc --version`) |
| Isolated root | `/tmp/arc-ids-docs-fixture` (any empty directory you own) |
| Fixture user DID | `z1fixtureIdentityDocs000000000000001` |
| Fixture app DID | `todo-docs-fixture` |
| Isolation flags | `--root-path` and `--user-did` on every inspection command |

Always pass an isolated `--root-path` when documenting or experimenting. Default config may point at your real `~/.afs/spaces` and list production app fragments.

You may see boot warnings such as `AFS_DID_SPACE_SCOPE_SECRET unset` when de-identification is off. They do not block local inspection; they mean on-disk directories may use plaintext identifiers.

## 1. Confirm empty root

```bash
arc space list \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001
```

Actual output:

```text
No app spaces found
```

`list` is the whole overview: DIDs, file counts and roots, for whichever `--scope` you ask for.

## 2. Seed a sample tree into the instance (system) fragment

`sync` takes two directories, so first ask `path` where the fragment lives:

```bash
arc space path todo-docs-fixture / \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance
```

```text
/spaces/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system
```

The first segment after `/spaces/` is the **scope directory**, derived from the user DID. With de-identification on it is an HMAC of the DID, not the DID itself — yours will differ from the capture above, which is why the recipe reads it back rather than hard-coding it. Swap `/spaces` for your `--root-path` and you have the on-disk destination:

```bash
mkdir -p /tmp/arc-ids-sample-fixture/notes
printf '%s\n' 'hello from identity docs evidence' > /tmp/arc-ids-sample-fixture/notes/readme.txt
printf '%s\n' 'secondary' > /tmp/arc-ids-sample-fixture/notes/extra.md

arc space sync \
  --from /tmp/arc-ids-sample-fixture \
  --to /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system
```

Actual output:

```text
/tmp/arc-ids-sample-fixture → /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system
Base path: /
Mode:      additive

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: the cursor engine mirrors (it deletes destination-only paths); this run is additive, so use --mirror to allow deletions or let the manifest engine handle it

Added:     2
Modified:  0
Deleted:   0
Unchanged: 0

Transferred: 2 files
Verified:    no
Duration:    294ms
```

`sync` is additive and never deletes existing files unless you pass `--mirror`. There is no `--scope` here: the role prefix (`system` / `user`) is the last segment of the path you sync into, so the destination itself says which fragment you meant.

## 3. List

```bash
arc space list \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance
```

```text
DID                  Files  Last Modified
───                  ─────  ─────────────
todo-docs-fixture        2  —
```

When you override `--root-path` / `--user-did`, human output may show a single section rather than the dual “Instance DID Space” / “User DID Space” headers you see against the default home layout. Always pass `--scope instance` or `--scope user` when the distinction matters.

## 4. Tree and path (instance → system)

```bash
arc space tree todo-docs-fixture \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance
```

```text
todo-docs-fixture:
[d] /notes  (128 B)
    /notes/extra.md  (10 B)
    /notes/readme.txt  (34 B)
```

```bash
arc space path todo-docs-fixture /notes \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance
```

```text
/spaces/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system/notes
```

`path` prints the **logical AFS path** for the role fragment. It is not a shell filesystem path and not a session path such as `/user/notes` — but as step 2 showed, replacing `/spaces` with your `--root-path` does give you the directory on disk.

## 5. User-scope fragment

Same move, one path segment different — `user` instead of `system`:

```bash
arc space sync \
  --from /tmp/arc-ids-sample-fixture \
  --to /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/user/docs
```

```text
/tmp/arc-ids-sample-fixture → /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/user/docs
Base path: /blocklets/todo-docs-fixture/user/docs
Mode:      additive

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: the cursor engine mirrors (it deletes destination-only paths); this run is additive, so use --mirror to allow deletions or let the manifest engine handle it

Added:     2
Modified:  0
Deleted:   0
Unchanged: 0

Transferred: 2 files
Verified:    no
Duration:    337ms
```

```bash
arc space tree todo-docs-fixture \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope user
```

```text
todo-docs-fixture:
[d] /docs  (96 B)
[d] /docs/notes  (128 B)
    /docs/notes/extra.md  (10 B)
    /docs/notes/readme.txt  (34 B)
```

```bash
arc space path todo-docs-fixture /docs \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope user
```

```text
/spaces/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/user/docs
```

Instance scope maps to the `system` role prefix; user scope maps to the `user` role prefix. That matches the provider's `getInstanceSpace({ role })` contract — and it is why a `sync` destination ending in `/system` or `/user/docs` lands where it does.

## 6. Delete inside a fragment

```bash
arc space rm todo-docs-fixture /notes/extra.md \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance
```

```text
Deleted todo-docs-fixture [instance] /notes/extra.md
```

```bash
arc space tree todo-docs-fixture \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance
```

```text
todo-docs-fixture:
[d] /notes  (96 B)
    /notes/readme.txt  (34 B)
```

Default `--scope` for `rm` is `user`. Pass `--scope instance` when deleting from the system fragment.

Use `rm` rather than deleting the file from the fragment directory by hand: a bare `rm -rf` leaves a phantom row in the space's index, which only `arc space repair --folder <dir>` clears.

## Failure modes (captured)

| Situation | Command | Observed result |
|---|---|---|
| Unknown app DID | `arc space tree does-not-exist-app --root-path … --user-did … --scope instance` | `ERROR: App space not found: does-not-exist-app` |
| Invalid scope on `tree` | `arc space tree todo-docs-fixture … --scope all` | `Invalid values: Argument: scope, Given: "all", Choices: "instance", "user"` |
| Missing app argument on `path` | `arc space path` | `Not enough non-option arguments: got 0, need at least 1` |
| Empty root | `arc space list` on a fresh directory | `No app spaces found` |

`tree` and `path` do **not** accept `--scope all`. Use `list` for the multi-scope overview, then inspect one role at a time.

## What local inspection is not

| Local `arc space` | Live session / formal deployment |
|---|---|
| Operates on a chosen root directory | Operates on runtime-mounted session views |
| Shows `system` / `user` fragments under `/spaces/…/blocklets/…` | Exposes `/user`, `/tmp`, optional `/space` to a caller |
| Does not authenticate end users for you | Requires verified `CallerInfo` for user overlays |
| Remote `sync` (an `https://<host>` end) needs server auth | Not re-run on this page; treat as separate environment-specific ops |

Do not deploy to DID Space only to inspect data for documentation or local UI work. Run the blocklet locally, and use an isolated `--root-path` for space CLI experiments.

## Related

- Provider role prefixes: [DID-scoped storage](../did-space/)
- Session composition: [User, temporary, and space views](../session-views/)
- How to re-run this page on a newer CLI: [Evidence and version boundaries](../evidence-and-versions/)
- Full subcommand list: [arc space](/en/docs/arc-cli/command-reference-space/)

---

## Identity and Data Spaces

URL: https://www.arcblock.io/en/docs/identity-data-spaces/overview/

Use this board when an application needs to know who is acting and which data view that caller may receive. Keep three related ideas separate.

## Terms

| Term | Current meaning in ARC | Do not say |
|---|---|---|
| DID | An identifier for subjects and for verified caller context; used to scope storage. | A client field, UI label, or path segment authenticates a caller. |
| DID Space | A concrete AFS provider and user-visible storage surface for DID-scoped data. | Mounting a DID Space automatically exposes the full AFS operation set. |
| Data Space | A documentation and architecture term for a caller's data context and views. | A separate public SDK, backend, API product, or lifecycle object. |
| `/user` · `/tmp` · `/space` | Session-constrained AFS views composed for one caller and session. | An invitation to poke ObjectStore, CAS, or SQLite internals. |

![DID feeds caller context and DID Space; both feed session views; Data Space only names that data context](/packages/content/docs/identity-data-spaces/overview/visuals/renditions/identity-terms.svg)

A path is not an authorization decision. The runtime resolves caller context, builds the session view, and applies provider policy before an application can use data. UI visibility and a path that happens to contain a DID are not permission grants.

## How the pieces connect

Trusted credentials become `CallerInfo`. The session then overlays caller-specific views on a shared instance world. `/user` and optional `/space` resolve through a DID Space provider; `/tmp` is session-local scratch.

| Step | What happens |
|---|---|
| 1 | Runtime accepts cookie JWT, Bearer JWT, or `Bearer blocklet-…` access key. |
| 2 | Shared caller core maps connect-service identity to `CallerInfo` (`did`, `roles`, `authMethod`, optional `instanceDid`). |
| 3 | Session construction mounts `/user`, `/tmp`, and optionally `/space` for that caller only. |
| 4 | DID Space provider stores persistent data under role prefixes `system` or `user`. |

![Flow from trusted credentials through CallerInfo and SessionUserAFS into session views backed by a DID Space provider](/packages/content/docs/identity-data-spaces/overview/visuals/renditions/session-data-flow.svg)

## Read by task

| If you need to | Start here |
|---|---|
| Understand what ARC knows about a caller | [Caller context](../caller-context/) |
| Store or mount data scoped to a DID | [DID-scoped storage](../did-space/) |
| Understand the documentation term Data Space | [What “Data Space” means here](../data-space-term/) |
| Understand `/user`, `/tmp`, and `/space` | [Session data](../session-data/) |
| Run local `arc space` inspection | [Inspect local spaces](../local-inspection/) |
| See how DID Connect enters the ARC runtime | [DID Connect in ARC](../did-connect/) |
| Check what this board deliberately does not promise | [Current contract boundaries](../current-boundaries/) |
| Re-verify against a named ARC release | [Evidence and version boundaries](../evidence-and-versions/) |

## Verified on

Operational commands on this board were re-run against **ARC CLI `2.0.0-beta.28`** in an isolated `--root-path` directory. Source and test references use the current `ArcBlock/arc` tree checked at documentation time. Architecture drafts about instance DID lifecycle remain archaeological, not public contracts.

## Related boards

- [AFS](/en/docs/afs/overview/) — provider contract and mount semantics.
- [Blocklets](/en/docs/blocklets/overview/) — package and instance workflow.
- [AUP](/en/docs/aup/aup-overview/) — declarative UI and session presentation.
- [Web Device](/en/docs/web-device/web-device-overview/) — AFS paths as static sites.
- [arc space](/en/docs/arc-cli/command-reference-space/) — full CLI man page for space subcommands.

---

## identity-data-spaces/overview/visuals

URL: https://www.arcblock.io/en/docs/identity-data-spaces/overview/visuals/

---

## Reference and boundaries

URL: https://www.arcblock.io/en/docs/identity-data-spaces/reference/

Use this section when a design decision depends on an exact boundary rather than a high-level explanation. The pages here separate three classes of statements:

| Class | How to use it |
|---|---|
| Current contract | Current source, tests, and (for CLI) a named release run show the behavior. Start here, then verify your target ARC version. |
| Architecture term | The term helps explain how parts fit together, but does not create an importable API or operational workflow. |
| Unverified or evolving area | Keep it outside production assumptions until a versioned contract and runnable evidence exist. |

## Child pages

1. [Current contract boundaries](../current-boundaries/) — safe statements versus non-promises.
2. [Evidence and version boundaries](../evidence-and-versions/) — how to re-verify this board against a named arc release.

## Quick index

| Topic | Current contract page | Notes |
|---|---|---|
| Caller resolution | [Caller context](../caller-context/) | Trusted credentials only |
| DID Space provider | [DID-scoped storage](../did-space/) | Transport ops unequal |
| Data Space name | [What “Data Space” means here](../data-space-term/) | Explanatory only |
| Session overlays | [Session views](../session-views/) | Isolation as tested |
| Local CLI | [Inspect local spaces](../local-inspection/) | `2.0.0-beta.28` capture |
| DID Connect seam | [DID Connect in ARC](../did-connect/) | Runtime handoff, not full product UI |

---

## Session data

URL: https://www.arcblock.io/en/docs/identity-data-spaces/session-data/

ARC can construct a session-specific AFS view over a shared instance world. The important question is not only where a file is stored. It is which provider or overlay the current session receives, and whether origin and policy permit the requested operation.

## Session-visible locations

| Location | Role in the session | Boundary |
|---|---|---|
| `/user` | Authenticated caller's user-data view (DID Space role `user` fragment). | Absent when the session has no user provider (anonymous). |
| `/tmp` | Temporary storage scoped to the current session. | Session state, not a shared application database. |
| `/space` | Optional view of the caller's whole DID Space root. | Only when the runtime enables it (for example `scope:user`); not universal. |
| `/instance` and other base paths | Shared per-instance world under the Small World / base AFS. | Network-origin base writes are gated; do not treat base as a free write surface. |

There is no in-session `/users/<did>` enumeration surface. Cross-caller isolation is structural: each session only receives its own overlays.

## Child pages

1. [User, temporary, and space views](../session-views/) — tested isolation, write gates, and `/space` policy notes.
2. [Inspect local spaces](../local-inspection/) — run `arc space` against an isolated root and read real outputs.

For how credentials become the caller that owns these views, see [Caller context](../caller-context/). For the durable provider behind `/user` and `/space`, see [DID-scoped storage](../did-space/).

---

## User, temporary, and space views

URL: https://www.arcblock.io/en/docs/identity-data-spaces/session-views/

`SessionUserAFS` overlays caller-specific and temporary providers onto a shared per-instance world. It is deliberately not a directory that contains every user's data.

Construction is single-sited in the runtime (`buildSessionView` / daemon join path). Do not invent a second construction path that mounts another caller's `/user`.

## View contract

| View | Current tested behavior |
|---|---|
| `/user` | Resolves to the current authenticated caller's user provider. Without that provider, `/user` is not found; writes are rejected. |
| `/tmp` | Resolves to a provider created for the current session. Present for every joined session. |
| `/space` | Optional. When the runtime enables it for `scope:user`, an authenticated caller can see their own whole DID Space root here. Anonymous callers do not receive a substitute `/space`. |

Root overlays are first-class: they are enumerable via `list("/")`, statable, and routable for read/write/delete/exec according to each overlay's policy.

## Isolation (what tests pin)

Daemon tests pin two-user isolation for the todo-style path:

- Caller A and caller B each write and read back their own `/user/app/x` values.
- Paths that try to reach another user through host layouts such as `/blocklets/<name>/users/<other-did>/…` or traversal variants under `/user` are rejected for that session.
- Isolation is structural because the session only mounts the singular `/user` for the resolved caller.

That is a session-view boundary. It is not a promise that every arbitrary path in every Blocklet has the same ACL.

## Write and base-data gates

Network-origin writes and deletes that fall through to the shared base are rejected. A write that targets a permitted overlay, such as the current caller's `/user` provider, is evaluated by that overlay's policy instead. Internal code and network requests are not interchangeable contexts.

For `/space` specifically:

- In the current user-scope daemon coverage, general writes under `/space` are rejected when the projection is readonly.
- A fixed write-guard policy can allow writes only under `blocklets/<app>/user/collections/**` and the canonical provenance sibling `blocklets/<app>/user/.provenance/collections/**` when the runtime wires that guard. Outside those roots, do not assume write access.
- Consumers that need the collections write channel should check the published capability marker for the collections + provenance policy rather than inferring from path shape alone.

## Do not

- Use `/user` aliases, a hidden component, or a client-side route as an access-control mechanism.
- Enumerate other users' data from inside a session and call it a supported API.
- Treat physical storage under `~/.afs/spaces` or an isolated `--root-path` as the same thing as session paths `/user` and `/space`. CLI inspection sees logical space fragments; the session view is a different composition.

## Evidence

| Claim | Evidence |
|---|---|
| Overlay design for `/user`, `/tmp`, `/space` | `packages/aos/src/session/session-user-afs.ts` |
| Two-user `/user` isolation | `runtimes/node/test/daemon/two-user-space-isolation.test.ts` |
| `scope:user` `/space` overlay (own root, cross-caller denial) | `runtimes/node/test/daemon/scope-user-space-overlay.test.ts` |
| Network base write gate | `packages/aos/test/session/session-user-afs-base-write-gate.test.ts` |
| `/space` collections write-guard policy | `packages/aos/src/session/space-write-gate.ts` |

Continue with [Inspect local spaces](../local-inspection/) for offline CLI inspection of the same logical fragments without treating the CLI as a session.

---

## Blocklet Launcher

URL: https://www.arcblock.io/en/docs/launcher/

---

## Data retention policy

URL: https://www.arcblock.io/en/docs/launcher/data-retention-policy/

After the invoice is overdue, the data will not be immediately deleted. After the due date, it is divided into two stages, `Past-due` and `Canceled`, where different treatments can be applied to applications and data in these two stages.

<em>The data retention policies for on-demand spaces and dedicated spaces are the same. Unless otherwise specified, the policies in the document apply to both on-demand spaces and dedicated spaces.</em>

Stage Explanation:

- Past-due
- Cancelled.

## Past-due

If the invoice is overdue and not paid, the app will be suspended; users can restore the app by renewing it.

<strong>During this period, the use of data will not have any impact.</strong>

## Cancelled

Cancellation of subscription related documents:
[Pricing policy](/en/docs/launcher/pricing-policy/)


Cancelled subscriptions cannot be restored. After cancellation, the application data will be retained for <strong>30 days</strong>, and data will be deleted after 30 days overdue.

Before the data is deleted, you can choose to backup the data to [DID Spaces](https://www.didspaces.com/):

- On-demand space can back up application data to DID Spaces, refer to the documentation:  [Backup the Blocklet to DID Spaces.](/en/docs/did-spaces/backup-to-did-space/)
- Dedicated space currently do not support backing up the entire Blocklet Server data to DID Spaces, but you can choose to backup the Blocklet data in the Blocklet Server to DID Spaces separately. If you have any other needs, please contact us through the forum [https://community.arcblock.io/](https://community.arcblock.io/)

---

## Launch an application on my own Blocklet Server

URL: https://www.arcblock.io/en/docs/launcher/launch-app-on-exist-server/

Blocklet Launcher supports launching applications on existing Blocklet Servers, whether they are launched on your own server or in dedicated spaces purchased on Blocklet Launcher.

Main steps

1. Select Blocklet
2. Select an existing space
3. Install Blocklet and follow-up operations

## 1. Select Blocklet

In [https://store.blocklet.dev/](https://store.blocklet.dev/), select the Blocklet to be installed and click the `Launch` button.

![选择 Blocklet-en.png](https://media.arcblock.io/lib/39/39b0b7e4c703fd1bffdc77803349330f.w1600.webp)

## 2. Select Existing Space

1. Click on the `Already have dedicated space` link at the bottom of the page.
2. Select target Blocklet Server.

![选择已有专用空间-en.png](https://media.arcblock.io/lib/98/98ddb52c274a0b82f35ce0292ddba74d.w1600.webp)

![选择已有专用空间-选择-en.png](https://media.arcblock.io/lib/b9/b9981a1a23e02981cddce97b912636c0.w1600.webp)

### 3. Install Blocklet and follow-up operations

The subsequent installation steps and installing an on-demand application are the same, please refer to the documentation: [https://www.arcblock.io/docs/launcher/en/launch-on-demand-application#3.-install-blocklet](/en/docs/launcher/launch-on-demand-application/#3.-install-blocklet)

---

## Launch the application in a dedicated space.

URL: https://www.arcblock.io/en/docs/launcher/launch-dedicated-application/

Dedicated Space is an independent server instance that adopts a pre-paid charging method.

Main steps

1. Select Blocklet
2. Purchase dedicated space
3. Waiting for the dedicated space to be ready.
4. Install Blocklet
5. Configuration & Start-up

## 1. Select Blocklet

In [https://store.blocklet.dev/](https://store.blocklet.dev/), select the Blocklet to be installed and click the `Launch` button.

![选择 Blocklet-en.png](https://media.arcblock.io/lib/39/39b0b7e4c703fd1bffdc77803349330f.w1600.webp)

## 2. Purchase dedicated space

1. Select dedicated space
2. Choose the required configuration type; currently, there are two configurations available: `Starter Space` and `Pro Space`, each suitable for different usage scenarios:
3.
  - Starter Space: Suitable for personal projects, providing basic functionality and performance support.
  - Pro Space: Higher configuration, better performance, designed specifically for commercial projects, able to meet higher demands and requirements.
4. Click the subscribe button to subscribe; after successful subscription, your wallet will receive a Blocklet Server Owner NFT, which will be used to verify your identity when installing Blocklet.

![选择专用空间-en.png](https://media.arcblock.io/lib/d2/d2d7c6fb268430d791558dc58929e25c.w1600.webp)

## 3. Waiting for the dedicated space to be prepared.

It takes about 3 minutes to prepare the dedicated space, with no need to do anything, just wait; it will automatically move to the next step after preparation.

![image.png](https://media.arcblock.io/lib/81/81fb5a0c5deb16eac890ad1cccda6516.w1600.webp)

## 4. Install Blocklet

After preparing the dedicated space, it will automatically redirect to the newly launched Blocklet installation page.

1. Show the wallet and agree to become the owner of the application:
2.
  1. Agree to become the application owner.
  2. Present the Blocklet Server NFT here to verify if you have permission to install applications on this Blocklet Server. <em>The NFT is sent asynchronously to the wallet. If the wallet prompts that there is no NFT, try refreshing the wallet.</em>
3. Then wait for the Blocklet installation to complete.

![image.png](https://media.arcblock.io/lib/fa/fa8a0765c8684c7cf9d85bcb33518eec.w1600.webp)

## 5. Configuration & Start-up

The process of `Configuration & Start-up` and installing an on-demand application are the same, you can refer to the documentation: [https://www.arcblock.io/docs/launcher/zh/launch-on-demand-application#4.-%E9%85%8D%E7%BD%AE-%26-%E5%90%AF%E5%8A%A8](/zh/docs/launcher/launch-on-demand-application/#4.-%E9%85%8D%E7%BD%AE-%26-%E5%90%AF%E5%8A%A8)

---

## Unable to install certain Blocklets in an On-demand space

URL: https://www.arcblock.io/en/docs/launcher/launch-from-untrusted-source/

## Reason

For security reasons, the Blocklet Launcher currently only allows blocklets to be installed from trusted sources to On-demand space.

Trusted installation sources currently:

- Blocklet Store: [https://store.blocklet.dev/](https://store.blocklet.dev/)
- Blocklet Store for Developer: [https://dev.store.blocklet.dev/](https://dev.store.blocklet.dev/)

## How to install Blocket from an untrusted source

Blocklets from untrusted sources can only be installed in dedicated spaces, currently there are two ways:

- Way One: [Purchase dedicated space](/zh/docs/launcher/launch-dedicated-application/)
- Way Two: [Installed in existing dedicated space](/zh/docs/launcher/launch-app-on-exist-server/#2.-%E9%80%89%E6%8B%A9%E5%B7%B2%E6%9C%89%E7%A9%BA%E9%97%B4)

---

## Launch on-demand application

URL: https://www.arcblock.io/en/docs/launcher/launch-on-demand-application/

The billing method of On-demand space is based on the <strong>number of components</strong> and <strong>usage duration</strong>. This more refined billing model allows users to subscribe more flexibly according to their actual needs. The new billing method adopts the subscription model brought by our <strong>Payment Kit</strong>, which can automatically pay and deduct fees, eliminating the worry of forgetting to pay and service interruption.

Steps:

1. Select Blocklet
2. Purchase on-demand space
3. Install Blocklet
4. Configuration & Startup

Related documents

- [Pricing policy](/en/docs/launcher/pricing-policy/)

## 1. Select Blocklet

Select the Blocklet you are ready to install in [https://store.blocklet.dev/](https://store.blocklet.dev/), and click the `Launch` button.

![选择 Blocklet-en.png](https://media.arcblock.io/lib/39/39b0b7e4c703fd1bffdc77803349330f.w1600.webp)

## 2. Purchase on-demand space

1. Select on-demand space.
2. Click the subscribe button to subscribe.

![选择按需空间-en.png](https://media.arcblock.io/lib/87/876654803253e5bfbd80f940798519fd.w1600.webp)

## 3. Install Blocklet

1. Present the DID Wallet, store the credentials of the owner in the wallet, and become the owner of the application.
2. Then wait for the successful installation.

## 4. Configuration & Startup

After installing the application, it will automatically redirect to the application configuration page, where you can choose to either <strong>launch the application directly</strong> or make some basic configurations for the application:

1. <em>Optional</em>: <strong>Access Control</strong>, configure access permissions.
2. <em>Optional</em>: <strong>Domain</strong>, add custom domain names, DID domain names, etc. DID Domain related documents:
3.
  1. [Get DID Domain](/en/docs/did-domain/get-did-domain/)
  2. [Use DID Domain](/en/docs/did-domain/use-did-domain/)
4. <em>Optional</em>: <strong>Configuration</strong>, other configurations, including application name, description, logo, etc.

![image.png](https://media.arcblock.io/lib/f0/f0dc440705530a1ea679863b39a0d760.w1600.webp)

Thus, a on-demand application has been launched.

---

## FAQs

URL: https://www.arcblock.io/en/docs/launcher/launcher-faqs/

### What is the difference between on-demand space and dedicated space?

- In an on-demand space, you only own the space the blocklet occupies.
- In the dedicated space, you own an entire Blocklet Server instance, in which you can run as many blocklets as you can.

### Is the number of blocklets limited in a dedicated space?

- From the Blocklet Server's perspective, there is no limitation on how many blocklets you can run in a dedicated space
- However, each blocklet you run in a dedicated space will take more CPU, Memory, Disk, and Network bandwidth, so there will always be a limit (you will know you have hit the limit when your blocklets are running slow).

### Is the number of blocklets limited in an on-demand space?

There are currently no restrictions, but restrictions may be imposed in future versions. Please note that each component are treated as a pricing unit according to our
[Pricing policy](/en/docs/launcher/63Wcq-bSfhn0-MSoRqStmRKN/)


### If I stop the entire blocklet, will I still be charged?

If the number of components is greater than 0, the stopped application will still be charged. The charges are now based on the number of components, and the charge amount will only be 0 if there are no components.

### Why some blocklet cannot be launched in on-demand spaces?

Some Blocklets require special resources, or consume more memory and CPU, so they are temporarily not supported to run in on-demand spaces.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/launcher/launcher-get-started/

## Overview

- [Launch on-demand application](/en/docs/launcher/launch-on-demand-application/)

- [Launch the application in a dedicated space.](/en/docs/launcher/launch-dedicated-application/)

- [Launch an application on my own Blocklet Server](/en/docs/launcher/launch-app-on-exist-server/)

---

## Reference Guides

URL: https://www.arcblock.io/en/docs/launcher/launcher-reference-guides/

Understanding pricing and data retention policies.

- [Pricing policy](/en/docs/launcher/pricing-policy/)

- [Data retention policy](/en/docs/launcher/data-retention-policy/)

- [Unable to install certain Blocklets in an On-demand space](/en/docs/launcher/launch-from-untrusted-source/)

- [Transfer subscription of application](/en/docs/launcher/transfer-subscription/)

---

## Welcome

URL: https://www.arcblock.io/en/docs/launcher/launcher-welcome/

## What is blocklet launcher?

Blocklet launcher is a hosted service by ArcBlock to boost your productivity when get your blocklets up and running.

---

## Pricing policy

URL: https://www.arcblock.io/en/docs/launcher/pricing-policy/

The latest version of Launcher has upgraded the payment method, with the aim of making it easier for users to purchase and maintain space. The new payment method is more convenient, with a more precise billing granularity, which can better help users to use on demand.

According to the different characteristics of "on-demand space" and "independent space", we have used different billing rules for these two types of spaces.

## On-demand space

### Features

- <strong>Improved accuracy:</strong> based on component and usage duration billing.
- <strong>More convenient:</strong> automatic deductions. If the account balance is sufficient, there is no need to worry about services being suspended due to forgetting to renew.
- <strong>More efficient:</strong> unnecessary components can be uninstalled to reduce expenses.

### Billing rules

- Price: The current price is <strong>0.05 ABT/Component/Day</strong>. Less than a day will be calculated as a day, for example: if you use it for 12 hours, then it is 12÷24 = 0.5 days. <strong>Note: The price of components per day is not fixed and may be adjusted in the future; the price of each component is currently the same and may also be adjusted in the future.</strong>

- Billing cycle: daily. A bill is generated every day based on the <strong>quantity and duration of components</strong> used the previous day, and the corresponding fee is automatically deducted. If the deduction fails due to insufficient balance or other reasons, the user will be reminded through email, wallet notifications, etc.

![计费规则文档-账单-en.png](https://media.arcblock.io/lib/5c/5c48cb770af038a49ae37ac610229ae1.w1600.webp)

### Unsubscribe

Users can now unsubscribe on the subscription management page.

Specific rules:

- The effective time of cancellation is after the current billing cycle ends.
- Before the current subscription period ends, users can resume their subscription at any time.
- Once the subscription status changes to "cancel," it cannot be restored.

### Outstanding payment processing.

Suppose the automatic deduction fails due to insufficient account balance. In that case, the subscription will enter a debt state, and the debt application will be immediately stopped, entering a grace period of 30 days. The application will be terminated if it exceeds 30 days.

Specific rules:

- Grace period: 30 days. During this period, you can recharge your account to restore your subscription, and users can also back up data to DID Space by logging into the application management page.
-
  - <strong>Note: There is no grace period for users who cancel voluntarily. The subscription will be cancelled immediately after the current billing cycle ends.</strong>
- Exceeding the grace period: If you do not renew after <strong>30 days</strong>, the subscription will not be able to be restored.

If the data is not backed up, it cannot be recovered. It is recommended to use DID Space to backup the data:
[Beginner's guide](https://www.arcblock.io/blog/docs/did-spaces/en/did-spaces-getting-started)


## Private Space.

### Characteristics

- Auto debit: If your account balance is sufficient, you don't have to worry about services being suspended due to forgetting to renew.
- Prepaid: pay first, use later.

The billing method for independent space is prepayment before use. Users need to first pay for the cost of independent space, and then use the space.

Like exclusive space, independent space also supports automatic deduction. As long as the account balance is sufficient, Launcher will automatically complete the deduction without the need for manual intervention.

### Unsubscribe

Users can proactively unsubscribe on the subscription management page.

Specific rules:

- The effective time of cancellation is after the current billing cycle ends.
- Before the current subscription period ends, users can resubscribe at any time.
- Once the subscription status changes to "canceled," it cannot be restored.

### Handling of unpaid fees

If the account balance is insufficient and leads to unpaid fees, the application will be suspended, entering a grace period of 30 days. If the period exceeds 30 days, the application will be terminated.

Specific rules:

- Grace period: 30 days, during which you can recharge your account to restore your subscription.
-
  - <strong>Note: There is no grace period for the user to cancel voluntarily. After voluntary cancellation, it will be immediately terminated after the current billing cycle ends.</strong>
- Exceeding the grace period: If you do not renew after <strong>30 days</strong>, the subscription will not be able to be restored.

If the data is not backed up, it will also be unable to recover; it is recommended to use DID Space to back up the data:
[Beginner's guide](https://www.arcblock.io/blog/docs/did-spaces/en/did-spaces-getting-started)

---

## Transfer subscription of application

URL: https://www.arcblock.io/en/docs/launcher/transfer-subscription/

## Applicable scenarios

Blocklet has been transferred to another user. At this time, the subscription page needs to be transferred to that user, otherwise Blocklet Launcher will continue to deduct fees from the original account.

Related documents:
[How to transfer a Blocklet](/en/docs/blocklet-developer/transfer-blocklet/)


## Conditions necessary for transferring subscriptions

The Blocklet has been transferred to another user in the Blocklet Server.

## The steps to transfer subscriptions

### 1. Generate transfer subscription link

If your Blocklet has already been transferred to another user, the Blocklet Launcher details page will remind the user to transfer the subscription and provide a button to generate a transfer link, which can be sent to the <strong>new owner</strong> of the Blocklet.

![image.png](https://media.arcblock.io/lib/c4/c4bd8cd2cb93455c490aca7d628e17e4.w1600.webp)

![image.png](https://media.arcblock.io/lib/d7/d73afbc6e25721c6c28b434127099a93.w1600.webp)

### 2. New owner takes over subscriptions.

- The recipient opens the transfer subscription link in the browser.
- Log in to the Blocklet Launcher account of the new owner
- Use DID wallet to verify the owner of the Blocklet.
- Complete subscription using DID Wallet
- Transfer completed.

> [!NOTE]
> ※Notice: If the current owner and the original owner of the Blocklet are using two different wallets under the same user, you will need to open the transfer link in a different browser or log out of the currently logged-in user from the Blocklet Launcher.

![image.png](https://media.arcblock.io/lib/da/da03d7fe2c90ada0ed21e1f7aa0736ba.w1600.webp)

![image.png](https://media.arcblock.io/lib/23/23e99a730de0bd432eaf264232f6c68c.w1600.webp)

## [Optional] Reconnect DID Spaces

If the Blocklet connected to DID Spaces before the transfer, you will need to reconnect DID Spaces, otherwise you <strong>WON'T</strong> be able to back up to DID Spaces.

1. Delete old DID Spaces connection

![image.png](https://media.arcblock.io/lib/b9/b9c7865bdade1c360ade4cf700bb6f14.w1600.webp)

2. Reconnect with Wallet

![image.png](https://media.arcblock.io/lib/e7/e7892d374474924bfb55c0fb12e58fd6.w1600.webp)

## Summary

After the transfer, the Blocklet Launcher will automatically deduct fees from the recipient's subscription and cancel the old subscription.

If the Blocklet connected to DID Spaces before the transfer, then you need to reconnect DID Spaces.

---

## Media Assets

URL: https://www.arcblock.io/en/docs/media-assets/

---

## ArcBlock logos

URL: https://www.arcblock.io/en/docs/media-assets/arcblock-logos/

Download the official kit from the [hub](../), or take one lockup below. The SVG and PNG links are the board copies.

Use the black wordmark on a light background. Use the white wordmark on a dark background. Do not recolor the cube gradient. Rules: [Usage](../usage/).

If a plate does not render, use the SVG and PNG links in the table under it.

## Horizontal lockup, cube gradient

This is the site header lockup: cube plus wordmark.

::gallery{folder="plates/horizontal-logo-gradient" layout="pair" lightbox="false"}

| File | Use on | SVG | PNG |
| --- | --- | --- | --- |
| `horizontal-logo-gradient-black` | Light background | [SVG](files/horizontal-logo-gradient-black.svg) | [PNG](files/horizontal-logo-gradient-black.png) |
| `horizontal-logo-gradient-white` | Dark background | [SVG](files/horizontal-logo-gradient-white.svg) | [PNG](files/horizontal-logo-gradient-white.png) |

## Horizontal lockup, solid cube

Same geometry, cube in black or white instead of the gradient.

::gallery{folder="plates/horizontal-logo" layout="pair" lightbox="false"}

| File | Use on | SVG | PNG |
| --- | --- | --- | --- |
| `horizontal-logo-black` | Light background | [SVG](files/horizontal-logo-black.svg) | [PNG](files/horizontal-logo-black.png) |
| `horizontal-logo-white` | Dark background | [SVG](files/horizontal-logo-white.svg) | [PNG](files/horizontal-logo-white.png) |

## Vertical lockup, cube gradient

::gallery{folder="plates/vertical-logo-gradient" layout="pair" lightbox="false"}

| File | Use on | SVG | PNG |
| --- | --- | --- | --- |
| `vertical-logo-gradient-black` | Light background | [SVG](files/vertical-logo-gradient-black.svg) | [PNG](files/vertical-logo-gradient-black.png) |
| `vertical-logo-gradient-white` | Dark background | [SVG](files/vertical-logo-gradient-white.svg) | [PNG](files/vertical-logo-gradient-white.png) |

## Vertical lockup, solid cube

::gallery{folder="plates/vertical-logo" layout="pair" lightbox="false"}

| File | Use on | SVG | PNG |
| --- | --- | --- | --- |
| `vertical-logo-black` | Light background | [SVG](files/vertical-logo-black.svg) | [PNG](files/vertical-logo-black.png) |
| `vertical-logo-white` | Dark background | [SVG](files/vertical-logo-white.svg) | [PNG](files/vertical-logo-white.png) |

## Cube only

`symbol-gradient` is the default mark. `symbol-black` and `symbol-white` are the solid versions.

::gallery{folder="plates/symbol-gradient" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `symbol-gradient` | [SVG](files/symbol-gradient.svg) | [PNG](files/symbol-gradient.png) |

::gallery{folder="plates/symbol" layout="pair" lightbox="false"}

| File | Use on | SVG | PNG |
| --- | --- | --- | --- |
| `symbol-black` | Light background | [SVG](files/symbol-black.svg) | [PNG](files/symbol-black.png) |
| `symbol-white` | Dark background | [SVG](files/symbol-white.svg) | [PNG](files/symbol-white.png) |

## Wordmark only

The wordmark is outlined paths in the SVG. That is not a claim about the live site font.

::gallery{folder="plates/wordmark" layout="pair" lightbox="false"}

| File | Use on | SVG | PNG |
| --- | --- | --- | --- |
| `wordmark-black` | Light background | [SVG](files/wordmark-black.svg) | [PNG](files/wordmark-black.png) |
| `wordmark-white` | Dark background | [SVG](files/wordmark-white.svg) | [PNG](files/wordmark-white.png) |

## ABT token mark

This is a brand mark from the official kit. It is not a product page about the token.

::gallery{folder="plates/abt-token" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `abt-token` | [SVG](files/abt-token.svg) | [PNG](files/abt-token.png) |

---

## media-assets/arcblock-logos/files

URL: https://www.arcblock.io/en/docs/media-assets/arcblock-logos/files/

---

## media-assets/arcblock-logos/plates

URL: https://www.arcblock.io/en/docs/media-assets/arcblock-logos/plates/

---

## DID logos

URL: https://www.arcblock.io/en/docs/media-assets/did-logos/

Download the official kit from the [hub](../), or take one mark below. Files named `*-light` go on a light background. Files named `*-dark` go on a dark background. `*-no-bg` is the mark without a rounded plate. `*-rect` is the mark on the official rounded rectangle.

If a plate does not render, use the SVG and PNG links in the table under it.

## DID

::gallery{folder="plates/did-logo" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `did-logo` | [SVG](files/did-logo.svg) | [PNG](files/did-logo.png) |
| `did-logo-no-bg` | [SVG](files/did-logo-no-bg.svg) | [PNG](files/did-logo-no-bg.png) |
| `did-logo-rect` | [SVG](files/did-logo-rect.svg) | [PNG](files/did-logo-rect.png) |
| `did-light` | [SVG](files/did-light.svg) | [PNG](files/did-light.png) |
| `did-dark` | [SVG](files/did-dark.svg) | [PNG](files/did-dark.png) |

::gallery{folder="plates/did-logo-no-bg" layout="pair" lightbox="false"}

## DID Names

::gallery{folder="plates/did-names-logo" layout="pair" lightbox="false"}

::gallery{folder="plates/did-names-lockup" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `did-names-logo` | [SVG](files/did-names-logo.svg) | [PNG](files/did-names-logo.png) |
| `did-names-logo-no-bg` | [SVG](files/did-names-logo-no-bg.svg) | [PNG](files/did-names-logo-no-bg.png) |
| `did-names-logo-rect` | [SVG](files/did-names-logo-rect.svg) | [PNG](files/did-names-logo-rect.png) |
| `did-names-light` | [SVG](files/did-names-light.svg) | [PNG](files/did-names-light.png) |
| `did-names-dark` | [SVG](files/did-names-dark.svg) | [PNG](files/did-names-dark.png) |

## DID Spaces

::gallery{folder="plates/did-spaces-logo" layout="pair" lightbox="false"}

::gallery{folder="plates/did-spaces-lockup" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `did-spaces-logo` | [SVG](files/did-spaces-logo.svg) | [PNG](files/did-spaces-logo.png) |
| `did-spaces-logo-no-bg` | [SVG](files/did-spaces-logo-no-bg.svg) | [PNG](files/did-spaces-logo-no-bg.png) |
| `did-spaces-logo-rect` | [SVG](files/did-spaces-logo-rect.svg) | [PNG](files/did-spaces-logo-rect.png) |
| `did-spaces-light` | [SVG](files/did-spaces-light.svg) | [PNG](files/did-spaces-light.png) |
| `did-spaces-dark` | [SVG](files/did-spaces-dark.svg) | [PNG](files/did-spaces-dark.png) |

## DID Connect

::gallery{folder="plates/did-connect-logo" layout="pair" lightbox="false"}

::gallery{folder="plates/did-connect-lockup" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `did-connect-logo` | [SVG](files/did-connect-logo.svg) | [PNG](files/did-connect-logo.png) |
| `did-connect-logo-no-bg` | [SVG](files/did-connect-logo-no-bg.svg) | [PNG](files/did-connect-logo-no-bg.png) |
| `did-connect-logo-rect` | [SVG](files/did-connect-logo-rect.svg) | [PNG](files/did-connect-logo-rect.png) |
| `did-connect-light` | [SVG](files/did-connect-light.svg) | [PNG](files/did-connect-light.png) |
| `did-connect-dark` | [SVG](files/did-connect-dark.svg) | [PNG](files/did-connect-dark.png) |

## DID Wallet

::gallery{folder="plates/did-wallet-logo" layout="pair" lightbox="false"}

::gallery{folder="plates/did-wallet-lockup" layout="pair" lightbox="false"}

| File | SVG | PNG |
| --- | --- | --- |
| `did-wallet-logo` | [SVG](files/did-wallet-logo.svg) | [PNG](files/did-wallet-logo.png) |
| `did-wallet-light` | [SVG](files/did-wallet-light.svg) | [PNG](files/did-wallet-light.png) |
| `did-wallet-dark` | [SVG](files/did-wallet-dark.svg) | [PNG](files/did-wallet-dark.png) |

---

## media-assets/did-logos/files

URL: https://www.arcblock.io/en/docs/media-assets/did-logos/files/

---

## media-assets/did-logos/plates

URL: https://www.arcblock.io/en/docs/media-assets/did-logos/plates/

---

## Media Assets

URL: https://www.arcblock.io/en/docs/media-assets/overview/

These are the official lockup files. Use them in press, slides, and product UI. Do not redraw the cube. Do not add a stroke or halo to the wordmark.

## Download

| Kit | Official ZIP | Files on this board |
| --- | --- | --- |
| ArcBlock logos | [ArcBlock-Logos.zip](https://www.arcblock.io/image-bin/uploads/57bb3e2eb314d4ce612854b153dcbbab.zip) | [ArcBlock logos](../arcblock-logos/) |
| DID logos | [DID-logos.zip](https://www.arcblock.io/image-bin/uploads/6e0a45195d5c738320ddd19a91615a47.zip) | [DID logos](../did-logos/) |

The ZIPs are the published official kits. SVG and PNG on this board are the same files with `__MACOSX` / `.DS_Store` removed and kebab-case names.

## Pick a lockup

| Need | Open |
| --- | --- |
| Cube, wordmark, horizontal or vertical lockup, ABT token mark | [ArcBlock logos](../arcblock-logos/) |
| DID, DID Names, DID Spaces, DID Connect, DID Wallet | [DID logos](../did-logos/) |
| Which file to put on a light or dark background, and which colors are in the SVG | [Usage](../usage/) |

## Not this board

The [Media Kit](/en/docs/media-kit/) product is an uploader. It is not a brand file dump.

The previous kit page stays at [/en/docs/arcblock-media-kit/](/en/docs/arcblock-media-kit/). It is deprecated. Keep that URL; use this board for new work.

This board does not include ArcSphere artwork. Those files are not in the official ZIPs published with this kit.

---

## Usage

URL: https://www.arcblock.io/en/docs/media-assets/usage/

Use the files on [ArcBlock logos](../arcblock-logos/) and [DID logos](../did-logos/). Do not redraw the cube. Do not add a stroke or halo to the wordmark.

## Background

| Background | ArcBlock wordmark | DID lockup file |
| --- | --- | --- |
| Light | `#121319`, file name ends in `-black` | file name ends in `-light` |
| Dark | `#ffffff`, file name ends in `-white` | file name ends in `-dark` |

The site header follows `html[data-mode]`. It inlines the official horizontal gradient lockup and swaps only the wordmark fill. The cube gradient stays.

## Do not

- Recolor the cube gradient.
- Stretch a lockup. Keep the official aspect ratio.
- Use a white wordmark on a light background, or a black wordmark on a dark background.
- Treat the outlined wordmark paths as a live-site font specimen. The kit ZIP has no type specimen. This site uses Sora and Inter.

## Cube gradient

Stops copied from `symbol-gradient.svg` and from every ArcBlock lockup that includes the cube:

| Offset | Hex |
| --- | --- |
| `0` | `#4EF1BA` |
| `0.501904` | `#16CED1` |
| `1` | `#3773F2` |

Wordmark on the official light lockup: `#121319`. Wordmark on the official dark lockup: `#ffffff`.

These are logo colors. They are not the Tiffany teal of the site chrome.

## DID marks

Fills copied from the official SVG for each family mark:

| Mark | Fill in the official SVG |
| --- | --- |
| DID | `#4598FA` on `#EBF4FF` |
| DID Names | `#5D8BB4` on `#F0F8FF` |
| DID Spaces | `#8C6AFC` on `#F7F1FF` |
| DID Connect | `#1DC1C7` on `#E3FDF6` |
| DID Wallet lockup | DID mark `#4598FA`. Wordmark `#25292F` on light, `#ffffff` on dark |
| DID Wallet logo (`did-wallet-logo.svg`) | Plate `#4F9DF6` → `#0A79F8`. Inner card `white` → `#ECEFFF`. Lower band `#77B2F6` → `#4F9DF6` → `#4598FA`. DID glyph `#9FCBFF`. DID wordmark `#4598FA` |

Do not substitute the old kit note `#1C7ED6` / `#079AFF`. Those values are not in the official SVG.

## ABT token mark

The ABT token mark is a brand file in the ArcBlock kit. Use that file when you need the mark. Do not write price, yield, market, or legal characterization next to it.

---

## media-assets/visuals

URL: https://www.arcblock.io/en/docs/media-assets/visuals/

---

## Media Kit

URL: https://www.arcblock.io/en/docs/media-kit/

---

## API Reference

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-eef257/

Welcome to the API reference for the Blocklet Uploader packages. This section provides comprehensive details on all exported components, functions, props, and configuration options for both the frontend and backend libraries. This is your go-to resource for in-depth technical information.

The uploader is split into two main packages:

- <strong>`@blocklet/uploader`</strong>: A flexible React component for your application's frontend.
- <strong>`@blocklet/uploader-server`</strong>: A set of Express middleware for handling file uploads on your backend.

While they are designed to work together seamlessly, it's important to note that `@blocklet/uploader` can be used with any backend that supports the Tus resumable upload protocol. `@blocklet/uploader-server` provides a powerful, pre-configured solution for handling upload logic within your Blocklet, but its use is optional.

![](https://media.arcblock.io/lib/1d/1d58f093ff7ce5b4.svg)

Select a package below to dive into its detailed API documentation.

::::card-group
::link-card{title="Frontend: @blocklet/uploader" description="Explore the props, components, hooks, and utility functions available in the frontend React package for creating a rich file upload experience." icon="box" href="/en/docs/media-kit/api-reference-uploader-eef257/"}
::link-card{title="Backend: @blocklet/uploader-server" description="A detailed reference for all server-side middleware functions used for handling file storage, remote sources via Companion, and serving static or dynamic resources." icon="server" href="/en/docs/media-kit/api-reference-uploader-server-eef257/"}
::::

If you need a higher-level understanding of how these packages are built and how they integrate with other systems, please see our [Concepts](/en/docs/media-kit/concepts-eef257/) section.

---

## <Uploader /> Component Props

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-component-props-eef257/

The `<Uploader />` component is the primary way to integrate a full-featured file upload interface into your React application. It is built on top of the popular [Uppy](https://uppy.io/) library and is highly customizable through a comprehensive set of props. This guide provides a detailed reference for all available props, enabling you to tailor the uploader's behavior, appearance, and functionality to your specific needs.

## Main Props

Here is a complete list of props you can pass to the `<Uploader />` component.

| Prop  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | A unique identifier for the Uppy instance. Defaults to `'Uploader'`.  |
| `popup`  | `boolean`  | If `true`, the uploader will render as a modal dialog instead of being inline. Defaults to `false`.  |
| `locale`  | `string`  | Sets the language for the UI. Supported values include 'en', 'zh'. Defaults to `'en'`.  |
| `onAfterResponse`  | `(response: any) => void`  | A callback function that fires after every HTTP response (from both Tus and Companion).  |
| `onUploadFinish`  | `(request: any) => void`  | A crucial callback that fires after a file has been successfully uploaded. The `request` object contains details like the `uploadURL`.  |
| `onOpen`  | `Function`  | A callback function that fires when the uploader UI (especially in popup mode) is opened.  |
| `onClose`  | `Function`  | A callback function that fires when the uploader UI is closed.  |
| `onChange`  | `Function`  | A callback that fires whenever a file is added or removed, providing the current list of all files.  |
| `plugins`  | `string[]` or `object[]`  | An array to configure which Uppy plugins are enabled. You can also pass custom plugins. See [Configuring Plugins](/en/docs/media-kit/guides-configuring-plugins-eef257/) for details.  |
| `installerProps`  | `object`  | Props passed to the `ComponentInstaller` for the Media Kit, such as `disabled` or a custom `fallback`.  |
| `uploadedProps`  | `object`  | Configuration for the custom 'Uploaded' plugin, including `params` and an `onSelectedFiles` callback.  |
| `resourcesProps`  | `object`  | Configuration for the custom 'Resources' plugin, including `params` and an `onSelectedFiles` callback.  |
| `tusProps`  | `TusOptions`  | An object of options passed directly to the `@uppy/tus` plugin. See [Tus documentation](https://uppy.io/docs/tus/#Options) for all options.  |
| `wrapperProps`  | `HTMLAttributes<HTMLDivElement>`  | Props applied to the main wrapper `div` element, including `sx`, `className`, and `style`.  |
| `coreProps`  | `UppyOptions`  | An object of options passed directly to the Uppy core instance. This is where you configure global settings like `restrictions`. See [Uppy Core documentation](https://uppy.io/docs/uppy/#Options) for all options.  |
| `dashboardProps`  | `DashboardOptions`  | An object of options passed directly to the `@uppy/dashboard` plugin. See [Uppy Dashboard documentation](https://uppy.io/docs/dashboard/#Options) for all options.  |
| `apiPathProps`  | `object`  | An object to configure the API endpoints for the uploader and Companion.  |
| `dropTargetProps`  | `DropTarget`  | Configuration for the `@uppy/drop-target` plugin, allowing drag-and-drop uploads onto a specified element.  |
| `initialFiles`  | `any[]`  | An array of file objects to pre-populate the uploader with when it initializes.  |
| `imageEditorProps`  | `ImageEditorOptions`  | An object of options passed directly to the `@uppy/image-editor` plugin. See [Uppy Image Editor documentation](https://uppy.io/docs/image-editor/#Options) for all options.  |

## Key Props in Detail

### `onUploadFinish`

This is one of the most important callbacks. It is triggered for each file after it has been successfully processed and stored by the backend. The callback receives a `result` object containing the final `uploadURL` and other metadata, which you can then use to update your application's state or save to your database.

**UploadHandler.jsx**

```javascript
import React, { useState } from 'react';
import Uploader from '@blocklet/uploader/react';

export default function UploadHandler() {
  const [fileUrl, setFileUrl] = useState('');

  const handleUploadFinish = (result) => {
    console.log('File uploaded:', result);
    // The result object contains the final URL of the uploaded file
    if (result.uploadURL) {
      setFileUrl(result.uploadURL);
      // Now you can save this URL to your state or database
    }
  };

  return (
    <div>
      <Uploader onUploadFinish={handleUploadFinish} />
      {fileUrl && <p>Last upload: <a href={fileUrl}>{fileUrl}</a></p>}
    </div>
  );
}
```

### `coreProps`

This prop gives you direct access to the Uppy core configuration. A primary use case is setting upload restrictions, such as file types, number of files, and file size.

**RestrictedUploader.jsx**

```javascript
import Uploader from '@blocklet/uploader/react';

export default function RestrictedUploader() {
  const restrictions = {
    maxFileSize: 1024 * 1024, // 1 MB
    maxNumberOfFiles: 3,
    allowedFileTypes: ['image/jpeg', 'image/png'],
  };

  return (
    <Uploader
      coreProps={{
        restrictions: restrictions,
      }}
    />
  );
}
```

### `plugins`

This prop allows you to customize the tabs available in the Uploader dashboard. You can enable or disable built-in plugins or even add your own custom tabs.

For a deep dive into creating your own plugin, see the [Creating a Custom Plugin](/en/docs/media-kit/guides-custom-plugin-eef257/) guide.

**CustomPluginUploader.jsx**

```javascript
import Uploader from '@blocklet/uploader/react';
import { PhotoIcon } from '@heroicons/react/24/solid';

export default function CustomPluginUploader() {
  const customPlugins = [
    {
      id: 'MyCustomPlugin',
      options: {
        id: 'MyCustomPlugin',
        title: 'My Photos',
        icon: <PhotoIcon />,
      },
      onShowPanel: (ref) => {
        // Logic to display your custom panel content
        console.log('Custom panel shown!', ref);
      },
    },
  ];

  return (
    <Uploader
      plugins={['Webcam', 'Url', ...customPlugins]}
    />
  );
}
```

### `apiPathProps`

By default, the uploader communicates with endpoints at `/api/uploads` (for Tus uploads) and `/api/companion` (for remote sources). You can override these paths if your backend is configured differently.

**CustomEndpoints.jsx**

```javascript
import Uploader from '@blocklet/uploader/react';

export default function CustomEndpoints() {
  const apiPaths = {
    uploader: '/custom/tus-endpoint',
    companion: '/custom/companion-endpoint',
  };

  return (
    <Uploader apiPathProps={apiPaths} />
  );
}
```

With a solid understanding of these props, you can configure the Uploader to fit a wide variety of use cases. For more advanced control, such as opening the uploader programmatically, proceed to the next section on the [UploaderProvider and Hooks](/en/docs/media-kit/api-reference-uploader-provider-hooks-eef257/).

---

## Frontend: @blocklet/uploader

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-eef257/

The `@blocklet/uploader` package provides a powerful and highly customizable React component for handling file uploads within the Blocklet ecosystem. It is built on top of [Uppy](https://uppy.io/), a sleek, modular open-source file uploader, ensuring a robust and user-friendly experience.

This package is designed to work seamlessly as a standalone component in any React application. However, its full potential is unlocked when used in conjunction with a [Media Kit blocklet](/en/docs/media-kit/concepts-media-kit-integration-eef257/), which provides centralized file management, advanced features like AI image generation, and pre-configured settings.

### Architecture Overview

The `Uploader` component acts as an orchestrator for an Uppy instance. It combines Uppy's core logic with a suite of standard plugins (like Webcam and URL import) and custom plugins tailored for the Blocklet environment (like AI Image and Resources). This modular architecture allows for great flexibility and feature richness.

![](https://media.arcblock.io/lib/a3/a35aa743144b65dd.svg)

### Core Concepts

The package exposes two primary ways to integrate the uploader:

::::steps
:::step{title="Direct Component:"}
The `<Uploader />` component can be rendered directly in your application. It can be configured to appear inline or as a modal dialog.
:::

:::step{title="Provider Pattern:"}
For more complex use cases, the `<UploaderProvider />` and `<UploaderTrigger />` components allow you to programmatically open the uploader from any part of your application, such as a button click.
:::
::::

### Basic Usage

Here is a minimal example of how to render the Uploader as a popup modal. A ref is used to gain access to its `open` and `close` methods.

**Basic Uploader Example**

```javascript
import { useRef } from 'react';
import Uploader from '@blocklet/uploader';
import Button from '@mui/material/Button';

export default function MyComponent() {
  const uploaderRef = useRef(null);

  const handleOpen = () => {
    uploaderRef.current?.open();
  };

  return (
    <div>
      <Button onClick={handleOpen}>Open Uploader</Button>
      <Uploader ref={uploaderRef} popup={true} />
    </div>
  );
}
```

This simple setup will render a button that, when clicked, opens the fully-featured Uploader modal.

### API Reference Deep Dive

To fully leverage the capabilities of `@blocklet/uploader`, explore the detailed API documentation for its components, hooks, and utilities.

::::card-group
::link-card{title="<Uploader /> Component Props" description="Explore the full range of props for the Uploader component, including core settings, dashboard options, and plugin configurations." icon="box" href="/en/docs/media-kit/api-reference-uploader-component-props-eef257/"}
::link-card{title="<UploaderProvider /> and Hooks" description="Learn how to use the UploaderProvider and hooks for programmatically controlling the uploader from anywhere in your app." icon="routes" href="/en/docs/media-kit/api-reference-uploader-provider-hooks-eef257/"}
::link-card{title="Available Plugins" description="Discover the custom-built plugins like AI Image generation, Uploaded files, and Resources that enhance the uploader's functionality." icon="box" href="/en/docs/media-kit/api-reference-uploader-plugins-eef257/"}
::link-card{title="Utility Functions" description="Reference for helper functions for tasks like file conversion, URL generation, and Uppy instance manipulation." icon="wrench" href="/en/docs/media-kit/api-reference-uploader-utility-functions-eef257/"}
::::

By understanding these building blocks, you can tailor the uploader to perfectly fit your application's needs. For a complete file upload solution, remember to also set up the corresponding backend service as described in the [@blocklet/uploader-server](/en/docs/media-kit/api-reference-uploader-server-eef257/) documentation.

---

## Available Plugins

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-plugins-eef257/

`@blocklet/uploader` extends the core Uppy library with several powerful, custom-built plugins. These plugins integrate seamlessly with the Blocklet ecosystem, particularly the Media Kit, to provide features like AI image generation, browsing previously uploaded files, and accessing shared resources. Most of these plugins are enabled automatically when you use the `<Uploader />` component and a properly configured backend is available.

This document provides a reference for the custom plugins included in the package.

## Acquirer Plugins (UI Tabs)

These plugins appear as tabs in the Uploader dashboard, providing different ways for users to select or create files.

### Uploaded

The `Uploaded` plugin provides a tab where users can browse, search, and select from files that have been previously uploaded to the Media Kit. It's an essential tool for reusing existing assets without needing to re-upload them.

<strong>Key Features:</strong>

- <strong>Infinite Scrolling:</strong> Lazily loads files from the server as the user scrolls, ensuring efficient performance even with large libraries.
- <strong>Rich Previews:</strong> Renders previews for images, videos, and PDFs directly in the grid view.
- <strong>Quick Upload:</strong> Includes a dedicated "add" button to quickly switch back to the "My Device" tab for new uploads.

<strong>Usage</strong>

This plugin is enabled by default when the Uploader detects an active Media Kit. You can customize its title or pass additional parameters to the backend API via `uploaderOptions`.

**uploaderOptions.js**

```javascript
<Uploader
  uploaderOptions={{
    plugins: {
      Uploaded: {
        title: 'My Media Library', // Change the tab title
        params: { customParam: 'value' } // Pass custom query params to the API
      }
    }
  }}
/>
```

### Resources

The `Resources` plugin allows users to select from a curated list of static assets. These assets can be provided by other blocklets or defined by your application's backend, making it easy to share common files like logos, icons, or document templates.

<strong>Key Features:</strong>

- <strong>Component Filtering:</strong> If multiple resource sources (components) are available, they are displayed as filter buttons, allowing users to switch between different asset collections.
- <strong>Grid View:</strong> Presents resources in a clean, easy-to-navigate grid.

<strong>Usage</strong>

This plugin becomes active when the backend is configured to serve resources. You can customize its title in the Uploader options.

**uploaderOptions.js**

```javascript
<Uploader
  uploaderOptions={{
    plugins: {
      Resources: {
        title: 'Shared Assets' // Change the tab title
      }
    }
  }}
/>
```

### AI Image

Integrate generative AI directly into your upload workflow. The `AI Image` plugin provides a dedicated interface for users to generate images from text prompts using various AI models configured on the backend.

<strong>Key Features:</strong>

- <strong>Prompt Interface:</strong> A user-friendly panel for writing prompts and selecting models.
- <strong>Model Filtering:</strong> Automatically filters the available AI models based on the `window.blocklet.preferences.supportModels` setting, ensuring users only see relevant options.
- <strong>Image Gallery:</strong> Displays generated images for selection and import into the Uploader.

<strong>Usage</strong>

This plugin is available when the Media Kit is configured with AI image generation capabilities.

**uploaderOptions.js**

```javascript
<Uploader
  uploaderOptions={{
    plugins: {
      AIImage: {
        title: 'Create with AI' // Change the tab title
      }
    }
  }}
/>
```

## Utility and Background Plugins

These plugins operate in the background to enhance functionality, security, and reliability. They do not have a visible UI tab in the dashboard.

### PrepareUpload (Internal Plugin)

This is a crucial background plugin that runs automatically for every file added to the Uploader. It performs essential pre-processing tasks before the upload begins to ensure files are safe, correctly formatted, and optimized.

| Feature  | Description  |
|---|---|
| <strong>XSS Prevention</strong>  | Sanitizes SVG files and filenames to remove potentially malicious scripts, protecting your application from cross-site scripting attacks.  |
| <strong>Zip Bomb Prevention</strong>  | Inspects compressed files (`.zip`, `.gz`) to ensure they don't contain decompression bombs that could exhaust server resources.  |
| <strong>Image Orientation</strong>  | Automatically corrects the orientation of images based on EXIF metadata, preventing sideways or upside-down photos.  |
| <strong>Remote File Handling</strong>  | Downloads files from remote sources (like Unsplash or a URL via Companion) into the browser so they can be processed and uploaded like local files.  |
| <strong>Hash Filename</strong>  | Generates a unique filename based on a hash of the file's content, which helps with caching and preventing naming conflicts.  |
| <strong>Image Validation</strong>  | Can be configured to enforce aspect ratios, automatically opening the Image Editor if a file doesn't match the required dimensions.  |

<strong>Usage</strong>

The `PrepareUpload` plugin is enabled by default. While it typically doesn't need to be configured, you can pass options to it, such as `cropperOptions`, to enforce a specific aspect ratio for all uploaded images.

**uploaderOptions.js**

```javascript
<Uploader
  uploaderOptions={{
    plugins: {
      PrepareUpload: {
        cropperOptions: {
          aspectRatio: 16 / 9
        }
      }
    }
  }}
/>
```

### SafariPastePlugin

This is a small utility plugin that addresses a specific browser compatibility issue. It ensures that pasting files into the Uploader dashboard works correctly in Safari, which handles paste events differently from other browsers. The plugin is enabled by default and requires no configuration.

### VirtualPlugin

`VirtualPlugin` is not a feature plugin but a base class for developers. It simplifies the process of creating your own custom acquirer (a new tab in the dashboard) without needing to write a full Uppy UI plugin from scratch.

:::action-card{title="Creating a Custom Plugin" description="For detailed instructions on how to build your own tab, please refer to our dedicated guide." icon="box"}
::action{label="View Guide" href="/en/docs/media-kit/guides-custom-plugin-eef257/" variant="primary"}
:::

---

## <UploaderProvider /> and Hooks

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-provider-hooks-eef257/

For more advanced use cases, you might need to trigger the Uploader from a different part of your application, or programmatically control its behavior. The `UploaderProvider` component and its associated hooks provide a flexible way to decouple the Uploader's UI from its trigger, using React's Context API.

This pattern is ideal when you want to open the Uploader modal from a button in a header, a link in a menu, or any element that isn't a direct child of the Uploader itself.

This approach involves three main parts:

::::card-group
::link-card{title="UploaderProvider" description="A wrapper component that instantiates the Uploader and provides its instance via context." icon="box"}
::link-card{title="UploaderTrigger" description="A simple component that creates a clickable area to open the Uploader modal." icon="navigation"}
::link-card{title="useUploaderContext" description="A hook to get direct access to the Uploader instance for custom logic." icon="link"}
::::

### How It Works

The `UploaderProvider` renders the `<Uploader />` component (often in a portal attached to the document body) and holds a reference (`ref`) to its instance. Any child component within the provider's tree can then access this `ref` using the `useUploaderContext` hook. The `UploaderTrigger` is a pre-built component that uses this hook to call the `open()` method on the Uploader instance.

![](https://media.arcblock.io/lib/fe/fea1ad7cd8fc24d8.svg)

## `UploaderProvider`

This component is the foundation of the pattern. It must wrap any components that need to interact with the Uploader, including any `UploaderTrigger` or custom components using the `useUploaderContext` hook.

It accepts all the same props as the `<Uploader />` component, allowing you to configure the Uploader's behavior, plugins, and appearance. For this pattern, you will almost always want to set `popup={true}`.

### Props

| Prop  | Type  | Description  |
|---|---|---|
| `children`  | `ReactNode`  | The child components that will have access to the Uploader context.  |
| `popup`  | `boolean`  | When `true`, the Uploader is rendered in a modal using a React Portal. When `false`, it's rendered inline. Defaults to `true`.  |
| `...restProps`  | `UploaderProps`  | All other props are passed directly to the underlying `<Uploader />` component. See the [Uploader Component Props](/en/docs/media-kit/api-reference-uploader-component-props-eef257/) for a full list.  |

### Usage

Wrap a section of your application, or your entire application, with `UploaderProvider`.

**MyUploader.jsx**

```javascript
import React from 'react';
import { UploaderProvider, UploaderTrigger } from '@blocklet/uploader/react';
import Button from '@mui/material/Button';

export default function MyUploader() {
  const handleUploadSuccess = (result) => {
    console.log('Files uploaded: ', result);
    // result contains { successful, failed } arrays of file objects
  };

  return (
    <UploaderProvider endpoint="/api/upload" popup={true}>
      <UploaderTrigger onChange={handleUploadSuccess}>
        <Button variant="contained">Upload File</Button>
      </UploaderTrigger>

      {/* Other components in your app can also be here */}
    </UploaderProvider>
  );
}
```

## `UploaderTrigger`

The `UploaderTrigger` component is a convenient wrapper that makes its children clickable, triggering the Uploader modal to open.

### Props

| Prop  | Type  | Description  |
|---|---|---|
| `children`  | `ReactNode`  | The React element(s) to use as the trigger, such as a `<Button>` or an `<a>` tag.  |
| `onChange`  | `Function`  | An optional callback function that is triggered only once after a successful upload. It receives the result object from Uppy.  |
| `...restProps`  | `object`  | Any additional props are passed to the underlying Material-UI `<Box>` component.  |

### Usage

Place any clickable component inside `UploaderTrigger`. The `onChange` prop provides a simple way to handle the result of the upload.

```javascript
<UploaderTrigger onChange={(result) => alert(`Uploaded ${result.successful.length} files!`)}>
  <Button>Click me to Upload</Button>
</UploaderTrigger>
```

## `useUploaderContext`

For the most control, the `useUploaderContext` hook gives you direct access to the Uploader's instance ref. This allows you to call any method on the Uploader or its underlying Uppy instance programmatically.

### Return Value

| Value  | Type  | Description  |
|---|---|---|
| `uploaderRef`  | `React.RefObject`  | A React ref object. The Uploader instance is at `uploaderRef.current`. To access the Uppy instance, use `uploaderRef.current.getUploader()`.  |

> <strong>Note:</strong> The hook will throw an error if it's used in a component that is not a descendant of `UploaderProvider`.
>

### Usage

Here's an example of a custom component that uses the hook to open the Uploader and also log the number of currently selected files.

**CustomControls.jsx**

```javascript
import React from 'react';
import { useUploaderContext } from '@blocklet/uploader/react';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';

export default function CustomControls() {
  const uploaderRef = useUploaderContext();

  const handleOpenUploader = () => {
    const uploader = uploaderRef?.current?.getUploader();
    uploader?.open();
  };

  const handleLogFiles = () => {
    const uploader = uploaderRef?.current?.getUploader();
    const files = uploader?.getFiles();
    console.log('Current files in Uppy:', files);
    alert(`There are ${files.length} files selected.`);
  };

  return (
    <Box sx={{ display: 'flex', gap: 2, mt: 2 }}>
      <Button variant="outlined" onClick={handleOpenUploader}>
        Open Uploader Manually
      </Button>
      <Button variant="outlined" color="secondary" onClick={handleLogFiles}>
        Log Current Files
      </Button>
    </Box>
  );
}
```

To use this `CustomControls` component, you would place it inside the `UploaderProvider` like so:

**App.jsx**

```javascript
// ... imports
import CustomControls from './CustomControls';

export default function App() {
  return (
    <UploaderProvider endpoint="/api/upload">
      {/* You can still have a primary trigger */}
      <UploaderTrigger>
        <Button>Upload</Button>
      </UploaderTrigger>

      {/* And also use your custom component for more control */}
      <CustomControls />
    </UploaderProvider>
  );
}
```

This pattern provides a high degree of flexibility, allowing you to integrate the uploader seamlessly into complex application layouts and workflows.

Next, you might want to explore some of the helper functions that can simplify common tasks.

:::action-card{title="Utility Functions" description="Learn about helper functions for tasks like file conversion and URL generation." icon="wrench"}
::action{label="View Utilities" href="/en/docs/media-kit/api-reference-uploader-utility-functions-eef257/" variant="primary"}
:::

---

## initCompanion(options)

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-server-companion-eef257/

The `initCompanion` function initializes and configures the Uppy Companion middleware, which is essential for enabling users to import files from remote sources like Unsplash, Google Drive, Instagram, or direct URLs. This function is a wrapper around the official [`@uppy/companion`](https://uppy.io/docs/companion/) library, tailored for seamless integration within a blocklet environment.

For a practical guide on setting this up, see [Integrating Remote Sources (Companion)](/en/docs/media-kit/guides-remote-sources-eef257/).

### How It Works

Companion acts as a server-side proxy. When a user selects a file from a remote source, the request is sent to your backend's Companion endpoint. Your server then fetches the file from the remote source and streams it back to the user's browser. Once in the browser, the file is treated like a local file and uploaded to your final destination (e.g., the endpoint handled by `initLocalStorageServer`).

![](https://media.arcblock.io/lib/43/437fce019cb27b87.svg)

### Usage

To use Companion, initialize it with your configuration options and then attach its `handle` to an Express router path. The frontend `Uploader` component must be configured with the same path for its `companionUrl` prop.

**Basic Companion Setup**

```javascript
import express from 'express';
import { initCompanion } from '@blocklet/uploader-server';

const router = express.Router();

// Basic configuration for Companion
const companion = initCompanion({
  // A temporary directory on your server for processing files
  path: '/tmp/uploads',
  express,
  // Provider options with necessary keys and secrets
  providerOptions: {
    unsplash: {
      key: process.env.UNSPLASH_KEY,
      secret: process.env.UNSPLASH_SECRET,
    },
  },
  // The public URL of your blocklet, required by some providers
  uploadUrls: [process.env.APP_URL],
});

// Mount the companion middleware on a specific path
// This path should match the `companionUrl` prop on the frontend
router.use('/companion', companion.handle);
```

### Parameters

The `initCompanion` function accepts a single options object with the following properties:

| Name  | Type  | Description  |
|---|---|---|
| `path`  | `string`  | <strong>Required.</strong> The absolute path to a temporary directory on the server where files will be stored during processing. This corresponds to the `filePath` option in Uppy Companion.  |
| `express`  | `Function`  | <strong>Required.</strong> The Express application instance. This is used to create the necessary sub-app and middleware stack for Companion.  |
| `providerOptions`  | `object`  | Optional. An object containing the configuration for each remote provider you want to enable. Each key is the provider name (e.g., `unsplash`), and the value is its configuration, like API keys and secrets.  |
| `...restProps`  | `any`  | Any other valid option from the official [Uppy Companion options](https://uppy.io/docs/companion/options/) can be passed here. For example, `uploadUrls` is a common and often required option.  |

### Return Value

The function returns a `companion` instance with the following key properties:

| Property  | Type  | Description  |
|---|---|---|
| `handle`  | `Function`  | An Express middleware that you must mount on a route (e.g., `/companion`). This handle contains all the logic for processing remote file requests.  |
| `setProviderOptions`  | `(options: object) => void`  | A method that allows you to dynamically update the `providerOptions` after initialization. This is useful if you need to load API keys from a database or change configurations without restarting the server.  |

#### Example: Dynamic Provider Options

You can change the provider options at runtime, which is useful for multi-tenant applications or when secrets are loaded asynchronously.

**Dynamic Provider Options**

```javascript
// Initialize companion without provider options initially
const companion = initCompanion({
  path: '/tmp/uploads',
  express,
});

// Later, perhaps after fetching secrets from a database
async function updateCompanionConfig() {
  const secrets = await getSecretsFromDb();
  companion.setProviderOptions({
    unsplash: {
      key: secrets.unsplashKey,
      secret: secrets.unsplashSecret,
    },
  });
}
```

### Additional Features

- <strong>Status Code Rewriting</strong>: For security and better error handling, if a remote provider returns an error with a status code of 500 or higher, this middleware automatically rewrites it to `400 Bad Request`. This prevents potential server error details from leaking to the client.

With Companion set up, your uploader is now capable of handling files from a wide variety of sources. You might also need to serve static files from your blocklet or other blocklets.

::::card-group
::link-card{title="Guide: Integrating Remote Sources" description="A step-by-step guide to configure both the frontend and backend for remote uploads." icon="link" href="/en/docs/media-kit/guides-remote-sources-eef257/"}
::link-card{title="API: initStaticResourceMiddleware" description="Learn how to serve static assets from other installed blocklets." icon="file" href="/en/docs/media-kit/api-reference-uploader-server-static-resource-eef257/"}
::::

---

## initDynamicResourceMiddleware(options)

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-server-dynamic-resource-eef257/

The `initDynamicResourceMiddleware` is a powerful Express middleware designed to serve files from one or more specified directories dynamically. Unlike `initStaticResourceMiddleware`, it actively watches for file system changes (additions, deletions, modifications) in real-time, making it ideal for serving content that can change during runtime, such as user-uploaded files, themes, or plugins.

It builds an in-memory map of resources for fast lookups and handles caching, file filtering, and conflict resolution gracefully.

## How It Works

The middleware follows a clear lifecycle: initialization, scanning, watching, and serving. When a request comes in, it performs a quick lookup in its internal map. If a file is added or removed from a watched directory, the map is updated automatically.

![](https://media.arcblock.io/lib/8c/8c7ea4ca6080ca8f.svg)

## Basic Usage

Here's how to configure the middleware to serve images from a dynamic `uploads` directory.

**Server Setup**

```javascript
import express from 'express';
import { initDynamicResourceMiddleware } from '@blocklet/uploader-server';
import path from 'path';

const app = express();

const dynamicResourceMiddleware = initDynamicResourceMiddleware({
  resourcePaths: [
    {
      path: path.join(__dirname, 'uploads/images'),
      whitelist: ['.jpg', '.jpeg', '.png', '.gif'],
    },
  ],
  onReady: (count) => {
    console.log(`${count} dynamic resources are ready to be served.`);
  },
  onFileChange: (filePath, event) => {
    console.log(`File ${filePath} was ${event}.`);
  },
});

// Mount the middleware
app.use('/uploads/images', dynamicResourceMiddleware);

// On server shutdown, clean up watchers
process.on('SIGINT', () => {
  if (dynamicResourceMiddleware.cleanup) {
    dynamicResourceMiddleware.cleanup();
  }
  process.exit();
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});
```

## Configuration Options

The `initDynamicResourceMiddleware` function accepts a single options object with the following properties:

| Option  | Type  | Description  |
|---|---|---|
| `componentDid`  | `string`  | Optional. If provided, the middleware will only activate if the current component's DID matches this value.  |
| `resourcePaths`  | `DynamicResourcePath[]`  | <strong>Required.</strong> An array of objects defining the directories to watch and serve. See details below.  |
| `watchOptions`  | `object`  | Optional. Configuration for the file system watcher.  |
| `cacheOptions`  | `object`  | Optional. Configuration for HTTP caching headers.  |
| `onFileChange`  | `(filePath: string, event: string) => void`  | Optional. A callback function that triggers when a file is changed, added, or deleted. The `event` can be `'change'`, `'rename'`, or `'delete'`.  |
| `onReady`  | `(resourceCount: number) => void`  | Optional. A callback that runs after the initial scan is complete and when the resource map changes, providing the total count of available resources.  |
| `setHeaders`  | `(res, filePath, stat) => void`  | Optional. A function to set custom headers on the response before serving a file.  |
| `conflictResolution`  | `'first-match'` \| `'last-match'` \| `'error'`  | Optional. Strategy to handle filename collisions when multiple directories contain a file with the same name. Defaults to `'first-match'`.  |

### `DynamicResourcePath` Object

Each object in the `resourcePaths` array defines a source for dynamic assets.

| Property  | Type  | Description  |
|---|---|---|
| `path`  | `string`  | <strong>Required.</strong> The absolute path to the directory. It supports glob patterns (e.g., `/path/to/plugins/*/assets`) to watch multiple matching directories.  |
| `whitelist`  | `string[]`  | Optional. An array of file extensions (e.g., `['.png', '.svg']`) to include. If specified, only files with these extensions will be served.  |
| `blacklist`  | `string[]`  | Optional. An array of file extensions to exclude.  |

### `watchOptions` Object

| Property  | Type  | Description  |
|---|---|---|
| `ignorePatterns`  | `string[]`  | An array of string patterns or regular expressions to ignore during watching.  |
| `persistent`  | `boolean`  | If `true`, the process will continue running as long as files are being watched. Defaults to `true`.  |
| `usePolling`  | `boolean`  | Whether to use polling for watching files. Can be necessary for certain network file systems.  |
| `depth`  | `number`  | The depth of subdirectories to watch. If `undefined`, it watches recursively.  |

### `cacheOptions` Object

| Property  | Type  | Description  |
|---|---|---|
| `maxAge`  | `string` \| `number`  | Sets the `Cache-Control` max-age header. Can be a number in milliseconds or a string like `'365d'`. Defaults to `'365d'`.  |
| `immutable`  | `boolean`  | If `true`, adds the `immutable` directive to the `Cache-Control` header. Defaults to `true`.  |
| `etag`  | `boolean`  | Whether to enable ETag generation.  |
| `lastModified`  | `boolean`  | Whether to enable the `Last-Modified` header.  |

## Advanced Usage

### Using Glob Patterns

To serve assets from multiple plugin directories, you can use a glob pattern. The middleware will find all matching directories and watch them for changes.

**Glob Pattern Example**

```javascript
const middleware = initDynamicResourceMiddleware({
  resourcePaths: [
    {
      // Watch the 'assets' folder inside every directory under 'plugins'
      path: path.join(__dirname, 'plugins', '*', 'assets'),
      whitelist: ['.css', '.js', '.png'],
    },
  ],
});
```

### Conflict Resolution

If two watched directories contain a file named `logo.png`, the `conflictResolution` strategy determines which one is served:

- `'first-match'` (default): The first one found during the initial scan is used. Subsequent finds are ignored.
- `'last-match'`: The last one found will overwrite any previous entry. This is useful if you have an override mechanism.
- `'error'`: Logs an error to the console indicating a conflict, and typically the first-match behavior is used.

## Return Value

The `initDynamicResourceMiddleware` function returns an Express middleware function. This returned function also has a `cleanup` method attached to it.

### `cleanup()`

This method should be called during a graceful server shutdown. It stops all file system watchers and clears the internal resource maps to prevent memory leaks and release file handles.

**Cleanup Example**

```javascript
const server = app.listen(3000);
const dynamicMiddleware = initDynamicResourceMiddleware(/* ...options */);

// ...

function gracefulShutdown() {
  console.log('Shutting down server...');
  if (dynamicMiddleware.cleanup) {
    dynamicMiddleware.cleanup();
  }
  server.close(() => {
    console.log('Server closed.');
    process.exit(0);
  });
}

process.on('SIGTERM', gracefulShutdown);
process.on('SIGINT', gracefulShutdown);
```

---

## Backend: @blocklet/uploader-server

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-server-eef257/

The `@blocklet/uploader-server` package provides a suite of Express.js middleware designed to handle various file handling tasks on the backend of your blocklet. It serves as the server-side counterpart to the `@blocklet/uploader` frontend component, enabling features like direct file uploads, integration with remote sources, and resource serving.

While designed to work seamlessly with its frontend partner, it can also be used as a standalone solution for customized file upload logic. The package exports several modular middleware initializers that you can easily integrate into your Express application.

### Core Middleware Interaction

The following diagram illustrates how the primary middleware components interact with the frontend and external services during an upload process.

![](https://media.arcblock.io/lib/a5/a523db76d356a336.svg)

## Installation

To get started, add the package to your blocklet's dependencies.

**Installation**

```bash
pnpm add @blocklet/uploader-server
```

## General Usage

Here is a typical example of how to integrate the upload and companion middleware into your Express application's router. You can initialize the required middleware and then mount their handlers onto specific routes.

**Express Router Example**

```javascript
import { initLocalStorageServer, initCompanion } from '@blocklet/uploader-server';
import express from 'express';

// Assume `env`, `user`, `auth`, `ensureComponentDid`, and `Upload` model are defined elsewhere
const router = express.Router();

// 1. Initialize the local storage server for direct uploads
const localStorageServer = initLocalStorageServer({
  path: env.uploadDir, // Directory to save uploads
  express,
  // Optional: Callback executed after a file is successfully uploaded
  onUploadFinish: async (req, res, uploadMetadata) => {
    const {
      id: filename,
      size,
      metadata: { filename: originalname, filetype: mimetype },
    } = uploadMetadata;

    // Construct the public URL for the uploaded file
    const obj = new URL(env.appUrl);
    obj.protocol = req.get('x-forwarded-proto') || req.protocol;
    obj.pathname = `/uploads/${filename}`;

    // Save file metadata to the database
    const doc = await Upload.insert({
      mimetype,
      originalname,
      filename,
      size,
      // ... other metadata from the request
    });

    // Return a JSON response to the frontend
    const resData = { url: obj.href, ...doc };
    return resData;
  },
});

// Mount the upload handler on a specific route
router.use('/uploads', user, auth, ensureComponentDid, localStorageServer.handle);

// 2. Initialize Companion for remote sources (e.g., URL, Unsplash)
const companion = initCompanion({
  path: env.uploadDir,
  express,
  providerOptions: env.providerOptions, // Your provider keys (e.g., Unsplash)
  uploadUrls: [env.appUrl], // The URL of your app
});

// Mount the companion handler on its route
router.use('/companion', user, auth, ensureComponentDid, companion.handle);
```

## Available Middleware

The package exports several middleware initializers for different functionalities. Click on a card to view its detailed API reference and configuration options.

::::card-group
::link-card{title="initLocalStorageServer" description="Handles direct file uploads from the user's computer, saving them to the server's local storage." icon="hard-drive" href="/en/docs/media-kit/api-reference-uploader-server-local-storage-eef257/"}
::link-card{title="initCompanion" description="Integrates with Uppy Companion to allow users to import files from remote sources like direct URLs and Unsplash." icon="link" href="/en/docs/media-kit/api-reference-uploader-server-companion-eef257/"}
::link-card{title="initStaticResourceMiddleware" description="Serves static assets (e.g., images, CSS) from other installed blocklets, enabling resource sharing." icon="folder" href="/en/docs/media-kit/api-reference-uploader-server-static-resource-eef257/"}
::link-card{title="initDynamicResourceMiddleware" description="Serves resources from a specified directory and can watch for file changes in real-time, useful for development." icon="folder" href="/en/docs/media-kit/api-reference-uploader-server-dynamic-resource-eef257/"}
::::

## Next Steps

The `@blocklet/uploader-server` package provides the essential server-side building blocks for a robust file handling system in your blocklet. By combining these middleware functions, you can create a feature-rich upload experience for your users.

To get started, we recommend exploring the [initLocalStorageServer](/en/docs/media-kit/api-reference-uploader-server-local-storage-eef257/) documentation to set up the core direct upload functionality.

---

## initLocalStorageServer(options)

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-server-local-storage-eef257/

The `initLocalStorageServer` function is the core middleware for handling direct file uploads from a user's device to your blocklet's local storage. It leverages the robust [Tus resumable upload protocol](https://tus.io/), ensuring that uploads are reliable and can be resumed after network interruptions.

This middleware is responsible for receiving file chunks, assembling them into a complete file on the server, and triggering callbacks for you to process the file metadata after the upload is complete.

### How It Works

The following diagram illustrates the typical data flow when a user uploads a file using the `Uploader` component connected to a backend with `initLocalStorageServer`.

![](https://media.arcblock.io/lib/3e/3ee7469138aab1f8.svg)

### Basic Usage

To get started, initialize the middleware in your Express application and mount it on a specific route. The most critical option is `onUploadFinish`, which is where you'll define what happens after a file is successfully saved.

**Basic Backend Setup**

```javascript
import express from 'express';
import { initLocalStorageServer } from '@blocklet/uploader-server';
import Upload from '../models/upload'; // Your database model

const router = express.Router();

// Initialize the uploader server middleware
const localStorageServer = initLocalStorageServer({
  // The directory where uploaded files will be stored
  path: process.env.UPLOAD_DIR,
  express,

  // This callback executes after a file is successfully uploaded
  onUploadFinish: async (req, res, uploadMetadata) => {
    const {
      id: filename, // The unique, randomized filename on disk
      size,
      metadata: { filename: originalname, filetype: mimetype },
    } = uploadMetadata;

    // Construct the public URL for the uploaded file
    const fileUrl = new URL(process.env.APP_URL);
    fileUrl.pathname = `/uploads/${filename}`;

    // Save file information to your database
    const doc = await Upload.insert({
      mimetype,
      originalname,
      filename,
      size,
      url: fileUrl.href,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      createdBy: req.user.did,
    });

    // Return the database document as a JSON response
    // This data will be passed to the frontend's onUploadFinish callback
    return doc;
  },
});

// Mount the middleware on the '/uploads' route
// Ensure any necessary authentication/authorization middleware runs before it
router.use('/uploads', yourAuthMiddleware, localStorageServer.handle);

export default router;
```

### Configuration Options

The `initLocalStorageServer` function accepts an options object with the following properties:

| Option  | Type  | Required  | Description  |
|---|---|---|---|
| `path`  | `string`  | Yes  | The absolute path to the directory where uploaded files will be stored.  |
| `express`  | `Function`  | Yes  | The Express application instance.  |
| `onUploadFinish`  | `Function`  | No  | An `async` callback function that runs after a file upload is complete. It receives `(req, res, uploadMetadata)`. The return value is sent as a JSON response to the frontend.  |
| `onUploadCreate`  | `Function`  | No  | An `async` callback function that runs when a new upload is initiated but before any data is transferred. Useful for validation or authorization checks. It receives `(req, res, uploadMetadata)`.  |
| `expiredUploadTime`  | `Number`  | No  | The time in milliseconds after which incomplete uploads are considered expired and will be cleaned up by a background job. <strong>Default:</strong> `1000 * 60 * 60 * 24 * 3` (3 days).  |
| `...restProps`  | `object`  | No  | Any other valid options for the underlying `@tus/server` package will be passed through.  |

### Callbacks in Detail

#### `onUploadFinish(req, res, uploadMetadata)`

This is the primary callback for processing completed uploads. It's the ideal place to save file metadata to your database, trigger webhooks, or perform other post-upload actions.

<strong>`uploadMetadata`</strong> <strong>Object</strong>

The `uploadMetadata` object passed to the callback contains detailed information about the uploaded file:

| Property  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The unique, randomly generated filename on the server's disk.  |
| `size`  | `number`  | The total size of the file in bytes.  |
| `offset`  | `number`  | The current number of bytes uploaded. Should equal `size` in this callback.  |
| `metadata`  | `object`  | An object containing metadata provided by the client.  |
| `metadata.filename`  | `string`  | The original filename from the user's computer.  |
| `metadata.filetype`  | `string`  | The MIME type of the file (e.g., `image/jpeg`).  |
| `runtime`  | `object`  | An object with runtime information about the file's location.  |
| `runtime.absolutePath`  | `string`  | The full path to the file on the server's filesystem.  |

<strong>Return Value</strong>

The value you return from `onUploadFinish` will be serialized into JSON and sent back to the frontend `Uploader` component. This allows you to pass back the database record ID, the public URL, or any other relevant data.

### Automatic Cleanup

The middleware automatically sets up a background cron job (`auto-cleanup-expired-uploads`) that runs hourly. This job safely removes any partial or expired uploads from the storage directory that have exceeded the `expiredUploadTime`, preventing your server from filling up with incomplete files.

### Advanced Features

#### EXIF Data Removal

For privacy and security, the middleware automatically attempts to strip EXIF (Exchangeable image file format) metadata from uploaded images (`.jpeg`, `.tiff`, etc.) after the upload is complete.

#### Manual File Deletion

The returned server instance includes a `delete` method you can use to programmatically remove an uploaded file and its associated metadata file.

**Manually Deleting a File**

```javascript
import { localStorageServer } from './setup'; // Assuming you exported the instance

async function deleteFile(filename) {
  try {
    await localStorageServer.delete(filename);
    console.log(`Successfully deleted ${filename}`);
  } catch (error) {
    console.error(`Failed to delete ${filename}:`, error);
  }
}
```

Now that you know how to handle direct uploads, you might want to enable users to import files from external services. Proceed to the next section to learn about `initCompanion`.

::link-card{title="Next: initCompanion(options)" description="Learn how to set up the Companion middleware to allow users to import files from remote sources like Unsplash and direct URLs." icon="link" href="/en/docs/media-kit/api-reference-uploader-server-companion-eef257/"}

---

## initStaticResourceMiddleware(options)

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-server-static-resource-eef257/

The `initStaticResourceMiddleware` is a powerful Express middleware designed to serve static assets from other installed blocklets. This allows your application to access shared resources like images, stylesheets, or fonts from dependent components without needing to know their exact location on the file system.

The middleware works by scanning the directories of installed blocklets that match a specified resource type, creating an in-memory map of available files. When a request comes in, it efficiently looks up the file in this map and serves it.

### How It Works

Here’s a high-level overview of the process:

![](https://media.arcblock.io/lib/f9/f96a6761dfa663cc.svg)

### Usage

To use the middleware, import it and add it to your Express application. You need to configure which resource types it should look for.

**server.js**

```javascript
import express from 'express';
import { initStaticResourceMiddleware } from '@blocklet/uploader-server';

const app = express();

// Initialize the middleware to serve resources of type 'imgpack'
// from any installed blocklet that provides it.
app.use(
  initStaticResourceMiddleware({
    express,
    resourceTypes: ['imgpack'], // Simple configuration using a string
  })
);

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});
```

In this example, if another installed blocklet has a `blocklet.yml` entry for a resource of type `imgpack`, any file within that resource's directory will be served. For example, a request to `/example.png` would serve the `example.png` file from that blocklet.

### Options

The `initStaticResourceMiddleware` function accepts a configuration object with the following properties:

| Option  | Type  | Description  |
|---|---|---|
| `express`  | `object`  | <strong>Required.</strong> The Express application instance.  |
| `resourceTypes`  | `(string \| ResourceType)[]`  | <strong>Required.</strong> An array defining the resource types to scan. See the `ResourceType` object details below.  |
| `options`  | `object`  | Optional. A configuration object passed to the underlying `serve-static` handler. Common properties include `maxAge` (e.g., '365d') and `immutable` (e.g., `true`) to control cache headers.  |
| `skipRunningCheck`  | `boolean`  | Optional. If `true`, the middleware will scan blocklets that are installed but not currently running. Defaults to `false`.  |

### The `ResourceType` Object

For more granular control, you can provide an array of objects to the `resourceTypes` option instead of simple strings. Each object can have the following properties:

| Property  | Type  | Description  |
|---|---|---|
| `type`  | `string`  | <strong>Required.</strong> The name of the resource type, which should match the type defined in a dependent blocklet's `blocklet.yml`.  |
| `did`  | `string`  | <strong>Required.</strong> The DID of the blocklet component that provides the resource. You can use `ImageBinDid` for the standard Media Kit.  |
| `folder`  | `string \| string[]`  | Optional. A specific sub-folder or an array of sub-folders within the resource directory to scan. Defaults to the root (`''`) of the resource directory.  |
| `whitelist`  | `string[]`  | Optional. An array of file extensions to include (e.g., `['.png', '.jpg']`). If provided, only files with these extensions will be served.  |
| `blacklist`  | `string[]`  | Optional. An array of file extensions to exclude (e.g., `['.md', '.txt']`).  |
| `setHeaders`  | `(res, path, stat) => void`  | Optional. A function to set custom response headers for a served file.  |
| `immutable`  | `boolean`  | Optional. Overrides the top-level `options.immutable` for this specific resource type to control the `Cache-Control` header.  |
| `maxAge`  | `string`  | Optional. Overrides the top-level `options.maxAge` for this specific resource type.  |

### Advanced Example

This example demonstrates a more complex configuration serving two different types of resources with specific rules.

**server.js**

```javascript
import express from 'express';
import { initStaticResourceMiddleware } from '@blocklet/uploader-server';
import { ImageBinDid } from '@blocklet/uploader-server/constants';

const app = express();

app.use(
  initStaticResourceMiddleware({
    express,
    skipRunningCheck: true,
    resourceTypes: [
      {
        type: 'imgpack',
        did: ImageBinDid,
        folder: 'public/images',
        whitelist: ['.png', '.jpg', '.gif'],
      },
      {
        type: 'theme-assets',
        did: 'z2q...someThemeBlockletDid', // DID of a specific theme blocklet
        folder: ['css', 'fonts'],
        blacklist: ['.map'],
      },
    ],
    options: {
      maxAge: '7d', // Default cache for 7 days
    },
  })
);

app.listen(3000);
```

This configuration does the following:

1. Scans for `imgpack` resources provided by the Media Kit (`ImageBinDid`), but only within the `public/images` sub-folder, and only serves `.png`, `.jpg`, and `.gif` files.
2. Scans for `theme-assets` resources from a blocklet with a specific DID, looking in both the `css` and `fonts` sub-folders, and ignores any source map (`.map`) files.
3. Sets a default `Cache-Control` max-age of 7 days for all matched files.

### Automatic Updates

This middleware is designed for a dynamic environment. It automatically listens for blocklet lifecycle events. If a component is added, removed, started, stopped, or updated, the middleware will automatically rescan and update its internal resource map, so you don't need to restart your application.

Next, learn how to serve files from a directory that can be updated in real-time without requiring an application restart.

:::action-card{title="initDynamicResourceMiddleware(options)" description="API reference for serving dynamic resources from specified directories with support for real-time file watching." icon="file"}
::action{label="Read More" href="/en/docs/media-kit/api-reference-uploader-server-dynamic-resource-eef257/" variant="primary"}
:::

---

## Utility Functions

URL: https://www.arcblock.io/en/docs/media-kit/api-reference-uploader-utility-functions-eef257/

The `@blocklet/uploader/utils` module exports a collection of helper functions designed to simplify common tasks associated with file handling, URL manipulation, Uppy instance customization, and network configuration. These utilities are used internally by the Uploader component but are also available for you to use in your application for more advanced integrations.

## File & Blob Manipulation

These functions help you work with different file formats and representations, such as Blobs, base64 strings, and File objects.

| Function  | Description  |
|---|---|
| `isBlob(file)`  | Checks if the given input is an instance of a `Blob`.  |
| `getObjectURL(fileBlob)`  | Creates a local object URL (e.g., `blob:http://...`) from a `Blob` or `File` object, which can be used for client-side previews.  |
| `blobToFile(blob, fileName)`  | Converts a `Blob` object into a `File` object, assigning it the specified file name.  |
| `base64ToFile(base64, fileName)`  | Converts a base64 encoded string into a `File` object. Useful for handling data URLs.  |
| `isSvgFile(file)`  | Asynchronously checks if a file is an SVG by examining its MIME type, extension, and content.  |
| `getExt(uppyFile)`  | Extracts the file extension from an Uppy file object, using both its name and MIME type for accuracy.  |

### Example: Converting Base64 to a File

```javascript
import { base64ToFile, getObjectURL } from '@blocklet/uploader/utils';

const base64Image = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...';
const imageFile = base64ToFile(base64Image, 'my-image.png');

// Now you can use this file object, for example, to create a preview
const previewUrl = getObjectURL(imageFile);
console.log(previewUrl);

// Or add it to an Uppy instance
// uppy.addFile({ name: imageFile.name, type: imageFile.type, data: imageFile });
```

## URL & Path Management

Functions for constructing and manipulating URLs, especially for interacting with the Media Kit's CDN and the uploader's backend endpoints.

| Function  | Description  |
|---|---|
| `createImageUrl(filename, width, height, overwritePrefixPath)`  | Constructs a URL for an image stored in the Media Kit. It can append query parameters for on-the-fly resizing (`w`, `h`).  |
| `getDownloadUrl(src)`  | Takes a Media Kit image URL and removes resizing parameters (`w`, `h`, `q`) to create a URL for downloading the original file.  |
| `getUploaderEndpoint(apiPathProps)`  | Generates the absolute URLs for the uploader (Tus) and Companion endpoints based on the props passed to the `Uploader` component.  |
| `setPrefixPath(apiPathProps)`  | Sets the internal prefix path used for API requests, allowing you to override the default behavior of using the Media Kit's mount point.  |

### Example: Generating a Resized Image URL

```javascript
import { createImageUrl } from '@blocklet/uploader/utils';

// Generates a URL for 'photo.jpg' with a width of 200px
const thumbnailUrl = createImageUrl('photo.jpg', 200);
// Result: https://your-cdn.com/uploads/photo.jpg?imageFilter=resize&w=200

// Generates a URL for the same image with both width and height
const sizedImageUrl = createImageUrl('photo.jpg', 400, 300);
// Result: https://your-cdn.com/uploads/photo.jpg?imageFilter=resize&w=400&h=300
```

## Uppy Instance Enhancement

### `initUppy(uppyInstance)`

This is a powerful function that enhances a standard Uppy core instance with custom methods, event handlers, and improved logic tailored for the Blocklet environment. It's automatically used by the `<Uploader />` component but can be used manually if you are creating your own Uppy instance.

<strong>Key Enhancements:</strong>

- <strong>Custom Success Events</strong>: Adds a robust event system for handling successful uploads.
-
  - `uppy.onUploadSuccess(file, callback)`: Listen for successful uploads, optionally for a specific file.
  - `uppy.onceUploadSuccess(file, callback)`: Same as above, but the listener is removed after one execution.
  - `uppy.emitUploadSuccess(file, response)`: Manually trigger the success event.
- <strong>Programmatic Upload</strong>: Adds an `async` helper method for easy programmatic uploads.
-
  - `uppy.uploadFile(blobFile)`: Takes a `Blob` or `File` object, adds it to Uppy, uploads it, and returns a Promise that resolves with the upload result.
- <strong>Custom Open/Close Events</strong>: Provides a clean way to listen for the Uploader Dashboard being opened or closed.
-
  - `uppy.onOpen(callback)` / `uppy.onClose(callback)`
- <strong>Improved Logic</strong>: Overrides default Uppy methods like `removeFiles` and `calculateTotalProgress` to better integrate with the backend and provide more accurate progress reporting.

### Example: Programmatic Upload with `initUppy`

```javascript
import Uppy from '@uppy/core';
import { initUppy } from '@blocklet/uploader/utils';

// 1. Create a standard Uppy instance
let uppy = new Uppy();

// 2. Enhance it with custom methods
uppy = initUppy(uppy);

async function uploadMyFile(fileBlob) {
  try {
    console.log('Starting upload...');
    const result = await uppy.uploadFile(fileBlob);
    console.log('Upload successful!', result.response.data.fileUrl);
  } catch (error) {
    console.error('Upload failed:', error);
  }
}

// Create a dummy file and upload it
const myFile = new File(['hello world'], 'hello.txt', { type: 'text/plain' });
uploadMyFile(myFile);
```

## Mocking & Testing

### `mockUploaderFileResponse(file)`

This utility is invaluable for testing or for adding pre-existing files to the Uploader's UI without actually uploading them. It takes a simple file object and generates a complete, Uppy-compatible response object that mimics a successful Tus upload.

This allows you to populate the dashboard with files that are already stored in your Media Kit.

### Example: Adding an Existing File to the UI

```javascript
import { mockUploaderFileResponse } from '@blocklet/uploader/utils';

// Assume 'uppy' is your initialized Uppy instance

// 1. Define your existing file data
const existingFile = {
  fileUrl: 'https://domain.com/uploads/existing-image.png',
  originalname: 'existing-image.png',
  mimetype: 'image/png',
  size: 12345,
  _id: 'file123',
};

// 2. Generate the mock response
const mockResponse = mockUploaderFileResponse(existingFile);

// 3. Add the file to Uppy's state and emit the success event
if (mockResponse) {
  uppy.addFile(mockResponse.file);
  uppy.emit('upload-success', mockResponse.file, mockResponse.responseResult);
}
```

---

## Concepts

URL: https://www.arcblock.io/en/docs/media-kit/concepts-eef257/

The `@blocklet/uploader` packages are designed to be both powerful and easy to integrate. To get the most out of them, it's helpful to understand the core concepts and key integrations that power their functionality. This section explores the foundational technologies and design principles behind the uploader.

At its core, `@blocklet/uploader` is built upon a solid foundation of proven open-source technology, enhanced with seamless integrations into the Blocklet ecosystem. The following concepts are key to understanding how it all works together.

![](https://media.arcblock.io/lib/f8/f86aa24d883fdd17.svg)

::::card-group
::link-card{title="Integration with Uppy" description="Learn how @blocklet/uploader leverages the powerful, modular Uppy library for its core upload functionality, including its plugin architecture and resumable uploads." icon="box" href="/en/docs/media-kit/concepts-uppy-integration-eef257/"}
::link-card{title="Integration with Media Kit" description="Discover the 'zero-config' experience. When a Media Kit blocklet is present, the uploader automatically configures itself and gains powerful new plugins." icon="cloud" href="/en/docs/media-kit/concepts-media-kit-integration-eef257/"}
::link-card{title="Internationalization (i18n)" description="Understand how to customize the uploader's interface for different languages and regions using the built-in localization support." icon="globe" href="/en/docs/media-kit/concepts-i18n-eef257/"}
::::

Understanding these concepts will help you customize and extend the uploader to fit your specific needs. To dive deeper, start by exploring the [Integration with Uppy](/en/docs/media-kit/concepts-uppy-integration-eef257/).

---

## Internationalization (i18n)

URL: https://www.arcblock.io/en/docs/media-kit/concepts-i18n-eef257/

The `@blocklet/uploader` component is designed with a global audience in mind, offering robust support for multiple languages and text customization. This allows you to create a seamless user experience that feels native to your users, regardless of their location.

This guide explains how to switch between built-in languages and how to provide your own custom translations.

## Switching Between Built-in Languages

The component ships with pre-configured language packs for English (`en`) and Chinese (`zh`). The simplest way to change the display language is by using the `locale` prop.

**Uploader with Chinese locale**

```jsx
import { Uploader } from '@blocklet/uploader/react';

function MyComponent() {
  return <Uploader locale="zh" />;
}
```

Setting `locale="zh"` will automatically translate the entire UI into Chinese. The default language is English (`en`).

## Customizing Text and Adding New Languages

For more advanced control, such as overriding specific text strings or adding support for a new language, you can provide a custom locale object to the Uploader. This is done through the `coreProps.locale` property, which gives you direct access to the underlying Uppy instance's configuration.

A locale object consists of a `strings` key, which contains all the text used in the UI.

### Overriding Existing Strings

You can easily change any text to better match your application's tone or terminology. For example, let's change the main drop hint.

First, import one of the base locale objects provided by the package, then merge your changes.

**Customizing the drop hint text**

```javascript
import { Uploader } from '@blocklet/uploader/react';
import { locales } from '@blocklet/uploader/i18n';
import merge from 'lodash/merge';

// Create a deep copy of the default English locale
const customEnglishLocale = merge({}, locales.en);

// Override the specific string you want to change
customEnglishLocale.strings.dropHint = 'Drop your awesome files here!';

function MyComponent() {
  return (
    <Uploader
      coreProps={{
        locale: customEnglishLocale,
      }}
    />
  );
}
```

### Adding a New Language

To add a language not included by default, you'll need to create a complete locale object. The recommended approach is to import a base locale from Uppy's extensive collection and then merge it with translations for the custom strings specific to `@blocklet/uploader`.

Here is an example of how you might create a basic French locale:

**Adding a French locale**

```javascript
import { Uploader } from '@blocklet/uploader/react';
import fr_FR from '@uppy/locales/lib/fr_FR'; // Base Uppy locale
import merge from 'lodash/merge';

// Create a custom locale object by merging Uppy's French pack
// with translations for our custom strings.
const customFrenchLocale = merge({}, fr_FR, {
  strings: {
    // Custom strings from @blocklet/uploader
    aiKitRequired: 'Veuillez installer et configurer le kit AI',
    aiImageGenerate: 'Générer',
    aiImageGenerating: 'Génération en cours...',
    browseFiles: 'parcourir les fichiers',
    browseFolders: 'parcourir les dossiers',
    dropHint: 'Déposez vos fichiers ici',
    // ... and so on for all other custom strings
  },
});

function MyComponent() {
  return (
    <Uploader
      coreProps={{
        locale: customFrenchLocale,
      }}
    />
  );
}
```

## Customizable Strings

While `@blocklet/uploader` inherits most of its strings from the Uppy ecosystem, it also adds several custom strings for its unique features. Below is a list of these specific keys that you can override.

| Key  | Default (English) Description  |
|---|---|
| `aiKitRequired`  | Text shown when the AI Image plugin is used without AI Kit being configured.  |
| `aiImageSelectedUse`  | Button text to confirm the use of a selected AI-generated image.  |
| `aiImageSelectedTip`  | A hint asking the user to select an image.  |
| `aiImagePrompt`  | Label for the AI image prompt input field.  |
| `aiImagePromptTip`  | Placeholder text for the prompt input.  |
| `aiImageSize`  | Label for the image size selector.  |
| `aiImageModel`  | Label for the image model selector.  |
| `aiImageNumber`  | Label for the number of images to generate.  |
| `aiImageGenerate`  | Button text to start image generation.  |
| `aiImageGenerating`  | Text displayed while images are being generated.  |
| `browseFolders`  | Text for the 'browse folders' link.  |
| `dropHint`  | The main text displayed in the drop area.  |
| `dropPasteBoth`  | Drop area text when both files and folders can be browsed.  |
| `dropPasteFiles`  | Drop area text when only files can be browsed.  |
| `dropPasteFolders`  | Drop area text when only folders can be browsed.  |
| `cancel`  | Text for the 'Back' or 'Cancel' button.  |
| `loadingStatus`  | Text shown when checking the Media Kit status.  |
| `aspectRatioMessage`  | Warning message for images that don't meet the required aspect ratio.  |
| `editorLoading`  | Message shown while the image editor is loading.  |
| `downloadRemoteFileFailure`  | Error message when a remote file (e.g., from a URL) fails to download.  |
| `noAllowedFileTypes`  | Message shown when `allowedFileTypes` is an empty array.  |
| `allowedFileTypes`  | Prefix for the list of allowed file types.  |
| `error`  | General initialization error message.  |

For a complete list of all strings available for translation, please refer to the official Uppy locale documentation.

By leveraging this flexible i18n system, you can ensure your application's file uploader is accessible and intuitive for all users. For more details on Uppy's configuration, see the [Integration with Uppy](/en/docs/media-kit/concepts-uppy-integration-eef257/) guide.

---

## Integration with Media Kit

URL: https://www.arcblock.io/en/docs/media-kit/concepts-media-kit-integration-eef257/

The `@blocklet/uploader` package is designed for seamless, zero-configuration integration with the <strong>Media Kit</strong> blocklet. Media Kit provides a centralized service for media storage, management, and processing. When the Uploader component detects that Media Kit is installed in the same environment, it automatically enhances its functionality without requiring any extra setup from the developer.

This automatic integration centralizes file storage, enforces consistent upload rules across all your blocklets, and dynamically enables advanced features like AI Image Generation. While this behavior is enabled by default for a streamlined experience, you can also opt-out if you need to handle uploads within your own blocklet's backend.

## How It Works: Automatic Detection and Configuration

The integration process is fully automated and follows a simple two-step process upon component initialization:

1. <strong>Detection</strong>: The `Uploader` component scans the environment for any installed blocklet with the unique DID of Media Kit (`z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9`).
2. <strong>Configuration</strong>: If Media Kit is found, the Uploader makes an API request to its `/api/uploader/status` endpoint. This endpoint returns a configuration object containing:
3.
  - <strong>Upload Restrictions</strong>: Global rules such as `maxFileSize` and `allowedFileTypes` that are centrally managed in the Media Kit.
  - <strong>Available Plugins</strong>: A map of which advanced plugins (e.g., `AIImage`, `Resources`, `Uploaded`) are enabled and should be displayed in the Uploader UI.
  - <strong>API Endpoints</strong>: The Uploader automatically configures itself to route all file uploads and related API calls to the Media Kit's services, ensuring all media is stored in one central location.

The following diagram illustrates this automatic configuration flow:

![](https://media.arcblock.io/lib/2a/2af9f6704803456f.svg)

## Core Benefits

Integrating with Media Kit offers several powerful advantages with no additional development effort.

::::card-group
::link-card{title="Centralized Media Management" description="All uploaded files are stored and managed within the Media Kit, creating a single source of truth for media assets across multiple blocklets. The `Resources` and `Uploaded` plugins allow users to easily browse and reuse existing assets." icon="book-open"}
::link-card{title="Dynamic Feature Plugins" description="Advanced features like the AI Image Generation plugin are enabled automatically if the capability is turned on in the Media Kit. This allows your application to gain new features without any code changes." icon="box"}
::link-card{title="Consistent Upload Rules" description="Upload restrictions are defined once in the Media Kit and automatically applied to every instance of the Uploader, ensuring consistency and simplifying policy management." icon="file"}
::link-card{title="Zero Backend Setup" description="Because Media Kit provides the necessary backend services for file processing and storage, you don't need to install or configure `@blocklet/uploader-server` in your own blocklet, reducing complexity." icon="server"}
::::

## Opting Out: Disabling the Integration

In scenarios where you need to manage uploads using your own backend logic and storage (with `@blocklet/uploader-server`), you can disable the automatic integration with Media Kit. This is done by passing specific props to the `apiPathProps` object on the `Uploader` component.

- `disableMediaKitStatus`: Set to `true` to prevent the Uploader from fetching configuration (restrictions and plugins) from the Media Kit.
- `disableMediaKitPrefix`: Set to `true` to prevent the Uploader from routing API requests to the Media Kit's endpoints. Instead, it will use the prefix of the current blocklet.

**Uploader with Media Kit Integration Disabled**

```jsx
import { Uploader } from '@blocklet/uploader/react';

export default function MyComponent() {
  return (
    <Uploader
      popup
      apiPathProps={{
        // Prevents fetching remote config from Media Kit
        disableMediaKitStatus: true,
        // Prevents routing API calls to Media Kit
        disableMediaKitPrefix: true,
      }}
      // You would now need to provide your own restrictions
      // and configure your own backend with @blocklet/uploader-server.
      coreProps={{
        restrictions: {
          maxFileSize: 1024 * 1024 * 5, // 5MB
          allowedFileTypes: ['image/jpeg', 'image/png'],
        },
      }}
    />
  );
}
```

By setting these properties, the `Uploader` component will operate in a standalone mode, relying entirely on its own props and the backend services configured within your application. You can learn more about this in the [Backend Setup](/en/docs/media-kit/getting-started-backend-setup-eef257/) guide.

---

## Integration with Uppy

URL: https://www.arcblock.io/en/docs/media-kit/concepts-uppy-integration-eef257/

The `@blocklet/uploader` package is built directly on top of [Uppy](https://uppy.io/), a sleek, modular, and open-source file uploader for the web. Instead of building a file uploader from scratch, we leverage Uppy's powerful core engine, extensive plugin ecosystem, and polished user interface. This allows us to provide a robust and feature-rich upload experience while focusing on seamless integration within the Blocklet ecosystem.

This approach means that `@blocklet/uploader` is essentially a pre-configured and enhanced wrapper around Uppy, tailored specifically for Blocklet development.

## Core Architecture

The `Uploader` component initializes and manages a core Uppy instance. It then integrates a set of standard Uppy plugins for common functionality (like the Dashboard UI, Webcam access, and Tus for resumable uploads) and layers on custom plugins designed to interact with other Blocklets, such as the Media Kit.

The following diagram illustrates this relationship:

![](https://media.arcblock.io/lib/1a/1a767e1bb0d80df0.svg)

## Accessing the Core Uppy Instance

For advanced use cases, you may need to interact with the underlying Uppy instance directly to access its rich API. The `Uploader` component provides a `ref` that exposes a `getUploader()` method, giving you full access to the Uppy object.

This allows you to programmatically control the uploader, listen for Uppy-specific events, or call any method available in the [Uppy API documentation](https://uppy.io/docs/uppy/).

**Accessing the Uploader Instance**

```jsx
import { useRef, useEffect } from 'react';
import { Uploader } from '@blocklet/uploader';

export default function MyComponent() {
  const uploaderRef = useRef(null);

  useEffect(() => {
    if (uploaderRef.current) {
      const uppy = uploaderRef.current.getUploader();

      // You can now use the full Uppy API
      uppy.on('complete', (result) => {
        console.log('Upload complete!', result.successful);
      });

      console.log('Uppy instance is ready:', uppy.getID());
    }
  }, []);

  return <Uploader ref={uploaderRef} popup />;
}
```

## Decoupled Frontend and Backend

It is important to understand that `@blocklet/uploader` is a frontend-only package. It is responsible for the user interface and client-side upload logic. It <strong>does not depend on</strong> <strong>`@blocklet/uploader-server`</strong>.

By default, it uses the [Tus protocol](https://tus.io/) for resumable uploads, meaning it can communicate with <em>any</em> backend server that implements the Tus specification. `@blocklet/uploader-server` is provided as a convenient, ready-to-use backend solution for Blocklet developers, but you are free to implement your own or use a different Tus-compatible service.

## For More Information

While our documentation covers the most common use cases and configurations for `@blocklet/uploader`, the official Uppy documentation is an invaluable resource for more advanced topics. If you want to dive deeper into Uppy's core concepts, explore its full range of plugins, or even create your own custom plugin, their website is the best place to start.

:::action-card{title="Uppy Official Documentation" description="Explore the comprehensive Uppy documentation for in-depth guides, API references, and advanced customization options." icon="book-open"}
::action{label="Visit Uppy.io" href="https://uppy.io/docs/quick-start/" variant="primary"}
:::

---

## Backend Setup (@blocklet/uploader-server)

URL: https://www.arcblock.io/en/docs/media-kit/getting-started-backend-setup-eef257/

This guide will walk you through setting up the `@blocklet/uploader-server` package in your Express.js-based blocklet. This package provides the necessary server-side middleware to handle file uploads initiated by the `@blocklet/uploader` frontend component.

While the frontend `@blocklet/uploader` can be used with any custom backend that supports the Tus resumable upload protocol, `@blocklet/uploader-server` offers a ready-to-use, integrated solution that handles local file storage, metadata processing, and cleanup of expired uploads.

## Upload Flow Overview

The following diagram illustrates the typical data flow when a user uploads a file using the frontend component and the backend server middleware.

![](https://media.arcblock.io/lib/31/3195f25ea39e3988.svg)

## Step 1: Installation

First, add the package to your blocklet's dependencies.

```bash
pnpm add @blocklet/uploader-server
```

## Step 2: Basic Configuration

The primary export from this package is `initLocalStorageServer`. This function creates an Express middleware that handles file uploads and stores them on the local filesystem.

Create a new route file in your blocklet (e.g., `routes/uploads.js`) and add the following basic configuration:

**Basic upload endpoint**

```javascript
import express from 'express';
import { initLocalStorageServer } from '@blocklet/uploader-server';

const router = express.Router();

// Initialize the uploader server middleware
const localStorageServer = initLocalStorageServer({
  path: process.env.UPLOAD_DIR, // A directory to store uploaded files
  express,
});

// Mount the uploader middleware to handle all requests to this route
router.use('/', localStorageServer.handle);

export default router;
```

In this minimal setup:

- We import `initLocalStorageServer`.
- We call it with a `path` option, which specifies the directory on the server where files will be stored. This should be an absolute path.
- We pass the `express` object itself to the middleware.
- Finally, we mount the returned handler on our router.

Now, you can mount this router in your main `app.js` file:

**app.js**

```javascript
// ... other imports
import uploadRouter from './routes/uploads';

// ... app setup
app.use('/api/uploads', uploadRouter);
```

With this in place, your backend is now ready to receive file uploads at the `/api/uploads` endpoint.

## Step 3: Handling Upload Completion

Simply saving a file isn't enough; you typically need to save its metadata to a database and return a publicly accessible URL to the frontend. This is done using the `onUploadFinish` callback.

The `onUploadFinish` function is executed after a file has been successfully and completely uploaded to the server.

Here is a more complete example demonstrating how to use it:

**Full backend example**

```javascript
import { initLocalStorageServer } from '@blocklet/uploader-server';
import express from 'express';
import url from 'url';
import path from 'path';

// Assume you have a database model for uploads
// import Upload from '../models/upload';

const router = express.Router();

const localStorageServer = initLocalStorageServer({
  path: process.env.UPLOAD_DIR,
  express,
  onUploadFinish: async (req, res, uploadMetadata) => {
    // 1. Destructure the metadata from the completed upload
    const {
      id: filename, // The unique, randomized filename on disk
      size,
      metadata: { filename: originalname, filetype: mimetype },
    } = uploadMetadata;

    // 2. Construct the public URL for the file
    const publicUrl = new URL(process.env.APP_URL);
    publicUrl.pathname = path.join('/api/uploads', filename);

    // 3. (Optional but recommended) Save the file metadata to your database
    /*
    const doc = await Upload.insert({
      mimetype,
      originalname,
      filename,
      size,
      url: publicUrl.href,
      createdAt: new Date().toISOString(),
      createdBy: req.user.did,
    });
    */

    // 4. Return a JSON object to the frontend. This object will be available
    // in the frontend's onUploadSuccess callback.
    const responseData = {
      url: publicUrl.href,
      // ...doc, // Include the database record if you created one
    };

    return responseData;
  },
});

// Mount the handler. Any middleware for authentication (like `user`, `auth`)
// should be placed before the handler.
router.use('/', localStorageServer.handle);

export default router;
```

### Key Points:

- <strong>`uploadMetadata`</strong>: This object contains all the information about the uploaded file, including its unique ID (which is also its filename on disk), size, and original metadata sent from the client (like `originalname` and `mimetype`).
- <strong>Database Integration</strong>: The callback is the perfect place to create a record in your database that links the uploaded file to a user or other resources in your application.
- <strong>Return Value</strong>: The object returned by `onUploadFinish` is serialized to JSON and sent as the response to the frontend. The frontend's `onUploadSuccess` callback will receive this object, which is how it learns the final URL of the uploaded file.

## Next Steps

With your backend configured, you are ready to explore more advanced features and customizations.

::::card-group
::link-card{title="Handling Uploads" description="Dive deeper into the `onUploadFinish` callback and learn how to process file metadata on both the client and server." icon="upload" href="/en/docs/media-kit/guides-handling-uploads-eef257/"}
::link-card{title="Integrating Remote Sources" description="Learn how to set up the Companion middleware to allow users to import files from URLs, Unsplash, and more." icon="link" href="/en/docs/media-kit/guides-remote-sources-eef257/"}
::link-card{title="initLocalStorageServer() API" description="Explore the full API reference for all available options to customize the local storage middleware." icon="book-open" href="/en/docs/media-kit/api-reference-uploader-server-local-storage-eef257/"}
::::

---

## Getting Started

URL: https://www.arcblock.io/en/docs/media-kit/getting-started-eef257/

This guide will walk you through the essential steps to integrate a powerful file uploader into your blocklet. We'll cover both the frontend UI component and the optional backend server setup to get you up and running quickly.

The solution is split into two primary packages:

- <strong>`@blocklet/uploader`</strong>: A React component that provides a rich user interface for uploading files.
- <strong>`@blocklet/uploader-server`</strong>: An Express middleware for your blocklet's backend to handle file storage and processing.

It's important to note that `@blocklet/uploader` can work independently, especially when integrated with a Media Kit blocklet which provides the necessary backend endpoints. You only need to use `@blocklet/uploader-server` if you want to implement your own custom upload logic on your server.

![](https://media.arcblock.io/lib/81/816045b56f3f33c4.svg)

To begin, choose the setup guide that matches your needs. We recommend starting with the frontend setup.

::::card-group
::link-card{title="Frontend Setup (@blocklet/uploader)" description="A step-by-step guide to installing and rendering the basic frontend uploader component in your React application." icon="layout" href="/en/docs/media-kit/getting-started-frontend-setup-eef257/"}
::link-card{title="Backend Setup (@blocklet/uploader-server)" description="Learn how to install and configure the necessary backend middleware in your Express-based blocklet to handle file uploads." icon="server" href="/en/docs/media-kit/getting-started-backend-setup-eef257/"}
::::

After completing these guides, you will have a fully functional file uploader. To explore more advanced features, such as customizing plugins or handling upload callbacks, proceed to the [Guides](/en/docs/media-kit/guides-eef257/) section.

---

## Frontend Setup (@blocklet/uploader)

URL: https://www.arcblock.io/en/docs/media-kit/getting-started-frontend-setup-eef257/

This guide will walk you through the process of installing and integrating the `@blocklet/uploader` React component into your Blocklet. This component provides a feature-rich user interface for file uploads, built upon the robust and extensible [Uppy](https://uppy.io/) file uploader.

By the end of this guide, you will have a working Uploader component in your application, ready to be connected to a backend service. For a seamless experience, we recommend using our companion backend package, which you can learn about in the [Backend Setup](/en/docs/media-kit/getting-started-backend-setup-eef257/) guide.

## 1. Installation

First, add the `@blocklet/uploader` package to your project's dependencies. Open your terminal in your project's root directory and run the following command:

**pnpm**

```bash
pnpm add @blocklet/uploader
```

## 2. Importing Styles

The Uploader component relies on several CSS files from the Uppy ecosystem for its appearance and functionality. You need to import these stylesheets into your application's entry point (e.g., `src/index.js` or `src/App.js`) to ensure the component renders correctly.

**App Entry Point (e.g., src/App.js)**

```javascript
// Import Uppy's core and plugin styles
import '@uppy/core/dist/style.min.css';
import '@uppy/dashboard/dist/style.min.css';
import '@uppy/webcam/dist/style.min.css';
import '@uppy/image-editor/dist/style.min.css';
import '@uppy/drag-drop/dist/style.min.css';
import '@uppy/drop-target/dist/style.min.css';
import '@uppy/status-bar/dist/style.min.css';

// ... the rest of your application's entry file
```

## 3. Basic Usage: Modal Uploader

The simplest way to use the uploader is to render it as a modal dialog. We'll use React's `lazy` loading to improve performance by only loading the component when it's needed.

Here is a complete example of a component that includes a button to open the uploader.

**UploaderButton.js**

```jsx
import { lazy, useRef, Suspense } from 'react';

// Lazily import the Uploader component
const UploaderComponent = lazy(() => import('@blocklet/uploader').then((res) => ({ default: res.Uploader })));

export default function UploaderButton() {
  const uploaderRef = useRef(null);

  const handleUploadFinish = (result) => {
    // The 'result' object contains details about the uploaded file
    console.log('Upload successful!', result);
    // You can now use the file URL from result.uploadURL or result.data
    alert(`File uploaded to: ${result.uploadURL}`);
  };

  const openUploader = () => {
    // The uploader instance has an `open` method
    uploaderRef.current?.getUploader()?.open();
  };

  return (
    <div>
      <button type="button" onClick={openUploader}>
        Open Uploader
      </button>

      {/* The Uploader component is rendered but hidden until opened */}
      {/* Use Suspense to handle the lazy loading of the component */}
      <Suspense fallback={<div>Loading...</div>}>
        <UploaderComponent
          ref={uploaderRef}
          popup // This prop makes the uploader a modal dialog
          onUploadFinish={handleUploadFinish}
        />
      </Suspense>
    </div>
  );
}
```

In this example:

- We create a `ref` (`uploaderRef`) to get access to the Uploader component's instance methods.
- The `popup` prop configures the uploader to work as a modal dialog, which is managed internally.
- A button's `onClick` handler calls the `open()` method on the uploader instance to make it visible.
- The `onUploadFinish` callback function is triggered after each file successfully uploads, receiving the file's metadata as an argument.

## 4. Advanced Usage: Using the Provider

For more complex applications, you might want to trigger the uploader from various components without passing refs down the component tree. The `@blocklet/uploader` package provides a context-based solution for this scenario with `UploaderProvider` and `UploaderTrigger`.

This approach separates the uploader's state from the components that trigger it.

**App.js**

```jsx
import { UploaderProvider, UploaderTrigger } from '@blocklet/uploader';

function MyPageComponent() {
  return (
    <div>
      <h2>My Page</h2>
      <p>Click the button below to upload a file.</p>
      {/* UploaderTrigger is a simple wrapper that opens the uploader on click */}
      <UploaderTrigger>
        <button type="button">Upload File</button>
      </UploaderTrigger>
    </div>
  );
}

export default function App() {
  const handleUploadFinish = (result) => {
    console.log('File uploaded from Provider:', result.uploadURL);
  };

  return (
    // Wrap your application or a part of it with UploaderProvider
    <UploaderProvider popup onUploadFinish={handleUploadFinish}>
      <h1>My Application</h1>
      <MyPageComponent />
      {/* You can have another trigger here */}
      <UploaderTrigger>
        <a>Or click this link</a>
      </UploaderTrigger>
    </UploaderProvider>
  );
}
```

### How It Works

::::steps
:::step{title="`UploaderProvider`"}
This component initializes and holds the Uploader instance. It should be placed high up in your component tree. All props for the `Uploader` component (like `popup` and `onUploadFinish`) are passed to the provider.
:::

:::step{title="`UploaderTrigger`"}
Any component wrapped by `UploaderTrigger` becomes a clickable element that will open the uploader modal. It can wrap buttons, links, or any other element.
:::
::::

This pattern is highly flexible and helps keep your component logic clean.

## Next Steps

You now have a fully functional frontend uploader component. However, to actually store the uploaded files, you need a backend service to receive them.

:::action-card{title="Backend Setup (@blocklet/uploader-server)" description="Learn how to install and configure the necessary backend middleware in your Express-based blocklet to handle file uploads." icon="server"}
::action{label="Continue" href="/en/docs/media-kit/getting-started-backend-setup-eef257/" variant="primary"}
:::

---

## Configuring Plugins

URL: https://www.arcblock.io/en/docs/media-kit/guides-configuring-plugins-eef257/

The `@blocklet/uploader` component is built on the flexible and powerful [Uppy](https://uppy.io/) file uploader. This architecture allows for extensive customization through a plugin-based system. The Uploader comes with several essential plugins pre-configured out-of-the-box, as well as special plugins designed to integrate with the Blocklet ecosystem.

This guide will walk you through how to enable, disable, and customize the behavior of these plugins to tailor the uploader to your specific needs.

## Controlling Active Plugins

The primary way to control which plugins are available to the user is through the `plugins` prop on the `Uploader` component. By default, if you don't provide this prop, the Uploader will attempt to enable all available built-in plugins.

To specify a custom set of plugins, pass an array of their IDs as strings. This will override the default set. Note that certain core plugins like `ImageEditor` and `PrepareUpload` are always active to ensure basic functionality.

Here are the IDs for the main acquirer plugins you can control:

| Plugin ID  | Description  |
|---|---|
| `Webcam`  | Allows users to take photos and record videos with their device's camera.  |
| `Url`  | Enables importing files from a direct URL.  |
| `Unsplash`  | Allows users to browse and import images from Unsplash (requires configuration).  |
| `AIImage`  | A custom plugin that enables AI image generation (requires Media Kit).  |
| `Uploaded`  | A custom plugin to browse and reuse files already uploaded to the Media Kit.  |
| `Resources`  | A custom plugin to select files from other resource-providing Blocklets.  |

### Example: Enabling Only Webcam and URL

If you only want users to upload from their webcam or a URL, you can configure the Uploader like this:

**Uploader with specific plugins**

```jsx
import Uploader from '@blocklet/uploader';

function MyComponent() {
  return (
    <Uploader
      popup
      plugins={['Webcam', 'Url']}
      // ... other props
    />
  );
}
```

This configuration will result in an uploader that only shows the Webcam and Import from URL options, in addition to the standard local file selection.

## Customizing Plugin Options

Beyond just enabling or disabling plugins, you can pass detailed configuration objects to customize their behavior. This is done through dedicated props on the `Uploader` component, named after the plugin they configure.

### Customizing the Image Editor

The most commonly customized plugin is the Image Editor. You can control everything from the output image quality to the available cropping tools using the `imageEditorProps` prop. These options are passed directly to the underlying `@uppy/image-editor` plugin.

For a complete list of available options, please refer to the [Uppy Image Editor documentation](https://uppy.io/docs/image-editor/#options).

**Customizing Image Editor**

```jsx
import Uploader from '@blocklet/uploader';

function MyImageEditor() {
  return (
    <Uploader
      popup
      imageEditorProps={{
        quality: 0.8, // Set JPEG quality to 80%
        cropperOptions: {
          viewMode: 1,
          aspectRatio: 16 / 9,
          background: false,
          autoCropArea: 1,
          responsive: true,
        },
      }}
      // ... other props
    />
  );
}
```

In this example, we've set the image compression quality to 80% and configured the cropper to enforce a 16:9 aspect ratio.

### Configuring Custom Plugins

Our custom plugins, `Uploaded` and `Resources`, also accept configuration through their respective props: `uploadedProps` and `resourcesProps`. A common use case is to provide a callback function for when a user selects files from these sources, allowing you to handle the selection directly instead of having the Uploader add them to its queue.

**Handling selection from Resources plugin**

```jsx
import Uploader from '@blocklet/uploader';

function MyResourceSelector() {
  const handleFilesSelected = (files) => {
    // The files array contains metadata about the selected resources,
    // including a `uppyFile` property for each.
    console.log('User selected these files from Resources:', files);
    // You can now process these files, e.g., display them in your UI.
  };

  return (
    <Uploader
      popup
      plugins={['Resources']}
      resourcesProps={{
        onSelectedFiles: handleFilesSelected,
      }}
      // ... other props
    />
  );
}
```

## Creating Your Own Plugin

The Uploader is designed to be extensible. If the built-in plugins don't meet your needs, you can create your own custom plugin tab to integrate unique functionality directly into the Uploader's dashboard.

:::action-card{title="Creating a Custom Plugin" description="Learn how to build and integrate your own custom plugin with a step-by-step guide." icon="box"}
::action{label="Read The Guide" href="/en/docs/media-kit/guides-custom-plugin-eef257/" variant="primary"}
:::

By mastering plugin configuration, you can transform the Uploader from a generic tool into a highly specialized component that fits perfectly within your application's workflow. Now that you know how to configure the interface, let's learn more about what happens after a file is selected.

Next, we'll explore how to work with files once they've been successfully uploaded. See the [Handling Uploads](/en/docs/media-kit/guides-handling-uploads-eef257/) guide for more details.

---

## Creating a Custom Plugin

URL: https://www.arcblock.io/en/docs/media-kit/guides-custom-plugin-eef257/

The `@blocklet/uploader` is designed for extensibility. While it comes with several powerful built-in plugins, you can easily add your own custom tabs to integrate unique workflows, connect to proprietary services, or provide specialized user interfaces. This guide will show you how to create a new plugin tab using the provided `VirtualPlugin` component.

This approach allows you to inject any React component into the Uploader's dashboard, opening up endless possibilities for customization.

## Understanding `VirtualPlugin`

At the heart of custom plugins is the `VirtualPlugin`. It's a special Uppy plugin that acts as a blank canvas. When you configure it, the Uploader creates a new tab button in the Dashboard and provides a container element for you to render your own React component. It simplifies the process of creating a new Uppy UI plugin from scratch.

## Configuration via the `plugins` Prop

To add your custom plugin, you'll configure the `plugins` prop on the `<Uploader />` component. This prop accepts an array of plugin configuration objects. Each object in the array defines a new tab.

Here is the structure for a custom plugin configuration:

**UploaderProps.ts**

```typescript
{
  id: string; // A unique identifier for your plugin
  options: {
    id: string; // Must match the top-level id
    title: string; // The text for the tab button
    icon?: string | React.ReactNode; // SVG string or React node for the icon
    autoHide?: boolean; // Automatically hide other panels when this one is shown
  };
  onShowPanel?: (ref: React.RefObject<any>) => void; // Callback to render your component
}
```

### Key Properties

| Property  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | A unique identifier for your plugin instance. This is crucial for Uppy to manage the plugin's state.  |
| `options`  | `object`  | Configuration passed directly to the `VirtualPlugin` constructor.  |
| `options.id`  | `string`  | Must be the same as the top-level `id`.  |
| `options.title`  | `string`  | The text that appears on the tab button in the Uploader UI.  |
| `options.icon`  | `string \| React.ReactNode`  | An SVG string or a React component for the tab icon. For an SVG string, it will be rendered using `dangerouslySetInnerHTML`.  |
| `onShowPanel`  | `(ref) => void`  | The core of the custom plugin. This callback function fires when the user clicks on your plugin's tab. It receives a React `RefObject` pointing to the panel's container `div`, into which you can render your custom UI.  |

## How it Works

The following diagram illustrates the workflow when a user interacts with a custom plugin tab:

![](https://media.arcblock.io/lib/bb/bb702b4a612b9ab5.svg)

## Complete Example

Let's create a simple plugin that allows generating an image from a prompt, similar to an AI image generator. This example demonstrates how to use the `onShowPanel` callback to render a custom React component into the plugin's panel.

First, define your custom panel component. This component will contain the UI for your plugin.

**MyCustomPanel.jsx**

```javascript
import React from 'react';
import ReactDOM from 'react-dom/client';

// Your custom UI component to be rendered in the panel
function MyCustomPanel({ uppy }) {
  const [prompt, setPrompt] = React.useState('');

  const handleGenerate = () => {
    // In a real app, you would fetch an image from an API
    // For this example, we'll use a placeholder and add it to Uppy
    const mockFile = {
      source: 'MyPlugin',
      name: `${prompt.slice(0, 10)}.png`,
      type: 'image/png',
      data: new Blob(['pretend-image-data'], { type: 'image/png' }), // Mock file data
    };
    uppy.addFile(mockFile);
    uppy.getPlugin('Dashboard').openModal(); // Switch back to the main dashboard view
  };

  return (
    <div style={{ padding: '20px' }}>
      <h4>AI Image Generator</h4>
      <input
        type="text"
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="Enter a prompt..."
        style={{ width: '100%', padding: '8px', marginBottom: '10px' }}
      />
      <button onClick={handleGenerate} style={{ padding: '8px 16px' }}>
        Generate Image
      </button>
    </div>
  );
}

export default MyCustomPanel;
```

Next, configure the `<Uploader />` component to include your new plugin. You'll define the plugin in the `plugins` array and use the `onShowPanel` callback to render your `MyCustomPanel` component.

**Uploader.jsx**

```javascript
import React from 'react';
import ReactDOM from 'react-dom/client';
import Uploader from '@blocklet/uploader';
import MyCustomPanel from './MyCustomPanel';

// An SVG string for the icon
const customIcon = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m12 3-1.9 1.9a2.5 2.5 0 0 0 0 3.54l1.9 1.9"/><path d="m12 21 1.9-1.9a2.5 2.5 0 0 0 0-3.54l-1.9-1.9"/><path d="M3 12h18"/><path d="m3 12 1.9 1.9a2.5 2.5 0 0 0 3.54 0l1.9-1.9"/><path d="m21 12-1.9-1.9a2.5 2.5 0 0 0-3.54 0l-1.9 1.9"/></svg>`;

function App() {
  const uploaderRef = React.useRef(null);

  const customPlugins = [
    {
      id: 'MyCustomPlugin',
      options: {
        id: 'MyCustomPlugin',
        title: 'AI Image',
        icon: customIcon,
      },
      onShowPanel: (panelRef) => {
        if (panelRef.current) {
          const uppy = uploaderRef.current?.uppy;
          const root = ReactDOM.createRoot(panelRef.current);
          root.render(<MyCustomPanel uppy={uppy} />);
        }
      },
    },
  ];

  return <Uploader ref={uploaderRef} plugins={customPlugins} />;
}

export default App;
```

In this example, when the 'AI Image' tab is clicked, the `onShowPanel` function is executed. It takes the `panelRef` and uses `ReactDOM.createRoot` to render the `<MyCustomPanel />` component inside it. We also pass the `uppy` instance to our custom component so it can interact with the Uploader, for example, by adding a generated file.

## Next Steps

You've now seen how to extend the `@blocklet/uploader` with custom functionality. For more advanced use cases, you can explore the official [Uppy documentation for writing plugins](https://uppy.io/docs/writing-plugins/).

To further customize your Uploader, review the full list of props in our API Reference.

::link-card{title="<Uploader /> Component Props" description="Explore all available props to fine-tune the Uploader's behavior and appearance." icon="box" href="/en/docs/media-kit/api-reference-uploader-component-props-eef257/"}

---

## Guides

URL: https://www.arcblock.io/en/docs/media-kit/guides-eef257/

Welcome to the Guides section. Here you'll find practical, task-oriented walkthroughs to help you implement common features and customizations for the uploader. These guides build on the concepts introduced in the [Getting Started](/en/docs/media-kit/getting-started-eef257/) section, providing step-by-step instructions for real-world scenarios.

These guides cover both the frontend `@blocklet/uploader` component and optional backend customizations with `@blocklet/uploader-server`. Remember, the frontend component can work independently, while the backend package is used for adding custom server-side upload handling and enabling remote sources.

::::card-group
::link-card{title="Configuring Plugins" description="Learn how to enable, disable, and pass custom options to Uppy plugins like the Image Editor, Webcam, and URL importer." icon="settings" href="/en/docs/media-kit/guides-configuring-plugins-eef257/"}
::link-card{title="Handling Uploads" description="Implement callbacks on both the frontend and backend to process files after a successful upload and access their metadata." icon="upload" href="/en/docs/media-kit/guides-handling-uploads-eef257/"}
::link-card{title="Integrating Remote Sources" description="Set up the Companion middleware on your backend to allow users to import files from remote sources like Unsplash and direct URLs." icon="link" href="/en/docs/media-kit/guides-remote-sources-eef257/"}
::link-card{title="Creating a Custom Plugin" description="Extend the Uploader's functionality by creating your own custom plugin tab using the provided VirtualPlugin component." icon="box" href="/en/docs/media-kit/guides-custom-plugin-eef257/"}
::::

After working through these guides, you'll have a solid understanding of how to tailor the uploader to your specific needs. For more in-depth information, you can dive into the [API Reference](/en/docs/media-kit/api-reference-eef257/).

---

## Handling Uploads

URL: https://www.arcblock.io/en/docs/media-kit/guides-handling-uploads-eef257/

After a file is successfully uploaded, you often need to perform actions on both the client and server. This guide explains how to use the `onUploadFinish` callback in both the `@blocklet/uploader` frontend component and the `@blocklet/uploader-server` middleware to process files and their metadata.

The frontend callback is ideal for updating the UI, while the backend callback is used for server-side tasks like saving file information to a database.

### The Upload Flow

The following diagram illustrates the complete process, from a user dropping a file to the final UI update, showing how the frontend and backend callbacks work together.

![](https://media.arcblock.io/lib/e8/e8697e2f1bd7dfed.svg)

## Frontend: `onUploadFinish` Prop

The `Uploader` component accepts an `onUploadFinish` prop, which is a function that executes after each file upload is complete. This callback receives the JSON response sent from your backend's `onUploadFinish` handler.

This is the perfect place to update your application's state, display the uploaded image, or store the returned file URL.

<strong>Prop Definition</strong>

| Prop  | Type  | Description  |
|---|---|---|
| `onUploadFinish`  | `(result: any) => void`  | A callback function that receives the final upload result object after the backend has processed the file.  |

<strong>Example Usage</strong>

In this example, we use the `onUploadFinish` callback to receive the file URL from the backend and store it in the component's state.

**Uploader Component**

```javascript
import { Uploader } from '@blocklet/uploader/react';
import { useState } from 'react';

export default function MyComponent() {
  const [fileUrl, setFileUrl] = useState('');

  const handleUploadFinish = (result) => {
    // The 'result' object is the JSON response from your backend
    console.log('Upload finished:', result);

    // 'result.data' contains the body returned by the server
    if (result.data && result.data.url) {
      setFileUrl(result.data.url);
    }
  };

  return (
    <div>
      <Uploader onUploadFinish={handleUploadFinish} />
      {fileUrl && (
        <div>
          <p>Upload successful!</p>
          <img src={fileUrl} alt="Uploaded content" width="200" />
        </div>
      )}
    </div>
  );
}
```

The `result` object passed to the frontend callback contains detailed information about the upload, including the response from the server.

<strong>Example</strong> <strong>`result`</strong> <strong>Object</strong>

```json
{
  "uploadURL": "http://localhost:3030/api/uploads/f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
  "data": {
    "url": "http://localhost:3030/api/uploads/f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
    "_id": "z2k...",
    "mimetype": "image/png",
    "originalname": "screenshot.png",
    "filename": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
    "size": 123456,
    "folderId": "component_did",
    "createdBy": "user_did",
    "updatedBy": "user_did",
    "createdAt": "2023-10-27T10:00:00.000Z",
    "updatedAt": "2023-10-27T10:00:00.000Z"
  },
  "method": "POST",
  "url": "http://localhost:3030/api/uploads/f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
  "status": 200,
  "headers": { ... },
  "file": { ... } // Uppy file object
}
```

## Backend: `onUploadFinish` Option

On the server, you provide an `onUploadFinish` function when initializing the `initLocalStorageServer`. This function is triggered after a file has been fully received and stored on the server's local disk, but before a final response is sent to the client.

This is where you should handle your core business logic, such as:

- Validating the uploaded file.
- Saving file metadata to a database.
- Associating the file with the current user.
- Returning a custom JSON object to the frontend.

<strong>Function Signature</strong>

```typescript
(req: Request, res: Response, uploadMetadata: object) => Promise<any>
```

- `req`: The Express request object, containing headers and user information.
- `res`: The Express response object.
- `uploadMetadata`: An object containing details about the uploaded file.

<strong>Example Usage</strong>

This example demonstrates how to save file metadata to a database (using a fictional `Upload` model) and return the created record to the frontend.

**Backend Server Setup**

```javascript
import { initLocalStorageServer } from '@blocklet/uploader-server';
import express from 'express';
import { joinUrl } from 'url-join';

// Assume 'Upload' is your database model
import Upload from '../models/upload';

const app = express();

const localStorageServer = initLocalStorageServer({
  path: process.env.UPLOAD_DIR,
  express,
  onUploadFinish: async (req, res, uploadMetadata) => {
    const {
      id: filename, // The unique, hashed filename on disk
      size,
      metadata: { filename: originalname, filetype: mimetype },
    } = uploadMetadata;

    // Construct the public URL for the file
    const fileUrl = joinUrl(process.env.APP_URL, '/api/uploads', filename);

    // Save file metadata to your database
    const doc = await Upload.insert({
      mimetype,
      originalname,
      filename, // Hashed filename
      size,
      folderId: req.componentDid, // DID of the component where the upload happened
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      createdBy: req.user.did, // Assumes user authentication middleware
      updatedBy: req.user.did,
    });

    // The returned object will be sent as the JSON response to the frontend
    const responseData = { url: fileUrl, ...doc };

    return responseData;
  },
});

// Mount the uploader middleware
app.use('/api/uploads', localStorageServer.handle);
```

<strong>`uploadMetadata`</strong> <strong>Object Details</strong>

The `uploadMetadata` object provides crucial information about the file:

```json
{
  "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
  "size": 123456,
  "offset": 123456,
  "is_final": true,
  "metadata": {
    "relativePath": null,
    "name": "screenshot.png",
    "filename": "screenshot.png",
    "type": "image/png",
    "filetype": "image/png",
    "uploaderId": "Uploader"
  },
  "runtime": {
    "relativePath": null,
    "absolutePath": "/path/to/uploads/f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
    "size": 123456,
    "hashFileName": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6.png",
    "originFileName": "screenshot.png",
    "type": "image/png",
    "fileType": "image/png"
  }
}
```

By implementing both callbacks, you create a robust upload pipeline that seamlessly connects user actions in the browser with your server-side business logic. To learn how to handle files from external sources like Unsplash, proceed to the next guide.

::link-card{title="Integrating Remote Sources (Companion)" description="Learn how to set up the Companion middleware to allow users to import files from direct URLs and other services." icon="link" href="/en/docs/media-kit/guides-remote-sources-eef257/"}

---

## Integrating Remote Sources (Companion)

URL: https://www.arcblock.io/en/docs/media-kit/guides-remote-sources-eef257/

To allow users to import files from external sources like direct URLs or services like Unsplash, you need to set up Uppy's Companion service on your backend. The `@blocklet/uploader-server` package provides a convenient `initCompanion` function that simplifies this process.

Companion acts as a server-side proxy. It fetches files from remote providers on behalf of the user and then streams them to the frontend uploader component, which then proceeds with the normal upload process. While basic file uploads can be handled without a custom backend, enabling remote sources requires setting up the `@blocklet/uploader-server` package.

### How It Works

The following diagram illustrates the data flow when a user imports a file from a remote source:

![](https://media.arcblock.io/lib/66/669ff7f8ca58260d.svg)

## Step 1: Configure the Backend Middleware

First, you need to initialize and mount the Companion middleware in your blocklet's backend Express server. This involves calling `initCompanion` and adding it to your router.

**Server-side Companion Setup**

```javascript
import express from 'express';
import { initCompanion } from '@blocklet/uploader-server';

const router = express.Router();

// Companion middleware for remote sources
const companion = initCompanion({
  path: env.uploadDir, // A temporary directory for file processing
  express,
  providerOptions: {
    // Configure providers here, e.g., Unsplash
    unsplash: {
      key: process.env.UNSPLASH_KEY,
      secret: process.env.UNSPLASH_SECRET,
    },
  },
  uploadUrls: [env.appUrl], // Your blocklet's public URL
});

// Mount the companion handler on a specific route
router.use('/companion', companion.handle);
```

### `initCompanion` Options

| Option  | Type  | Description  |
|---|---|---|
| `path`  | `string`  | <strong>Required.</strong> The directory on your server where Companion will temporarily store files during transfer.  |
| `express`  | `Function`  | <strong>Required.</strong> The Express app instance.  |
| `providerOptions`  | `Object`  | Optional. Configuration for remote providers. To enable Unsplash, for instance, you would provide your API key and secret. For a complete list of providers and their options, refer to the [official Uppy Companion documentation](https://uppy.io/docs/companion/providers/).  |
| `uploadUrls`  | `string[]`  | Optional but highly recommended for security. An array of URLs where your frontend uploader is running. This prevents others from using your Companion instance.  |

## Step 2: Configure the Frontend Component

After setting up the backend, you need to configure the frontend `<Uploader />` component to communicate with your Companion instance. You do this by specifying the route in the `apiPathProps` prop and enabling the desired plugins.

**Uploader Component with Companion**

```jsx
import { Uploader } from '@blocklet/uploader';

function MyUploaderComponent() {
  return (
    <Uploader
      popup
      apiPathProps={{
        // This path must match the backend route
        companion: '/api/companion',
        // The uploader path for the final upload
        uploader: '/api/uploads',
      }}
      plugins={[
        'Url', // Enables importing from a direct URL
        'Unsplash', // Enables importing from Unsplash
        'Webcam',
      ]}
    />
  );
}
```

With both the backend middleware and frontend component configured, the Uploader's dashboard will now display tabs for "Link" (URL) and "Unsplash", allowing users to import files directly from those sources.

Now that you can handle uploads from both local and remote sources, you might want to extend the uploader's functionality even further. Learn how to add your own custom tabs to the Uploader interface in the next guide.

:::action-card{title="Creating a Custom Plugin" description="Extend the Uploader's functionality by creating your own custom plugin tab using the provided VirtualPlugin component." icon="box"}
::action{label="Read More" href="/en/docs/media-kit/guides-custom-plugin-eef257/" variant="primary"}
:::

---

## Overview

URL: https://www.arcblock.io/en/docs/media-kit/overview-eef257/

The Blocklet Uploader is a comprehensive file upload solution designed for blocklets, built upon the robust and extensible [Uppy](https://uppy.io/) file uploader. It consists of two primary packages that work together to provide a seamless experience, from the user interface in the browser to file processing on the server.

::::card-group
::link-card{title="@blocklet/uploader (Frontend)" description="A React component that provides a rich, pluggable user interface for file selection and upload progress." icon="upload" href="/en/docs/media-kit/getting-started-frontend-setup-eef257/"}
::link-card{title="@blocklet/uploader-server (Backend)" description="Express middleware to handle file storage, processing, and integration with remote sources like Unsplash." icon="server" href="/en/docs/media-kit/getting-started-backend-setup-eef257/"}
::::

## How It Works

The standard workflow involves the user interacting with the `@blocklet/uploader` component in your application's frontend. This component then communicates with a backend endpoint, powered by `@blocklet/uploader-server`, which handles the actual file storage and processing.

It's important to note that `@blocklet/uploader` can function without a custom backend if a Media Kit blocklet is present, as it provides default upload handling. You only need to install and configure `@blocklet/uploader-server` when you require custom server-side logic, such as saving file metadata to a specific database after an upload completes.

![](https://media.arcblock.io/lib/78/785f61a6be5483f2.svg)

## Key Features

- <strong>Powered by Uppy</strong>: Leverages a mature, battle-tested core for reliable uploads.
- <strong>Flexible Architecture</strong>: Decoupled frontend and backend packages allow for independent use and customization.
- <strong>Rich Plugin System</strong>: Supports standard Uppy plugins like `ImageEditor`, `Webcam`, and `Url`, plus custom blocklet-specific plugins.
- <strong>Remote Source Integration</strong>: Easily enable users to import files from external sources like Unsplash using the Companion middleware.
- <strong>Customizable Hooks</strong>: Provides `onUploadFinish` callbacks on both the client and server, giving you full control over post-upload processing.
- <strong>Automatic Media Kit Integration</strong>: Seamlessly detects and configures itself when a Media Kit blocklet is available.

Ready to start? Let's get the uploader integrated into your blocklet.

:::action-card{title="Getting Started" description="Follow our step-by-step guides to set up both the frontend component and backend server in your application." icon="rocket"}
::action{label="Start the Guide" href="/en/docs/media-kit/getting-started-eef257/" variant="primary"}
:::

---

## NFT Studio

URL: https://www.arcblock.io/en/docs/nftstudio/

---

## Concept Guide

URL: https://www.arcblock.io/en/docs/nftstudio/concept-guide/

### What's NFT?

NFT, known as Non-Fungible Token, is one of the applications of blockchain technology. Unlike traditional cryptocurrencies (such as Bitcoin and Ether), NFTs are unique and non-fungible digital assets. Each NFT has its own unique identifier, making it unique and scarce.

### What's Collection?

In the digital asset and NFT space, a Collection is a group of related NFT works. It can be created by a single creator or a team and represents a particular theme, style, concept or series.
A Collection usually consists of multiple unique NFTs that may share the same creator, artistic style, backstory, or specific attributes. For example, an artist may create a Collection to showcase their digital artwork, with each NFT representing a different work by that artist.

### What's wallet?

A wallet is a digital tool or application for storing, managing and using cryptocurrencies and digital assets. It is similar to a traditional wallet, but in the digital realm, it acts as a virtual "wallet" for you to manage your digital assets.

---

## By using the NFT Blender + AI tool, 6000 NFTs with a theme of the Year of the Dragon for the Spring Festival can be quickly created.

URL: https://www.arcblock.io/en/docs/nftstudio/Cp6aXaCitdXO7Z-xZtwWyBg5/

Put some result pictures first

![Image](https://media.arcblock.io/lib/81/818061de3b471a8b8154df1ea8ecd697.webp)

NFT consists of the following parts

- A fixed background
- Idiom title
- Couplets on both sides
- Single character in the middle below
- Main body - dragon

Below are my design files in Figma
  ![Image](https://media.arcblock.io/lib/42/42dbdfbfdd86be6aeb63551cdc8424ad.webp)

The production process consists of the following steps

1. Determine the approach (consider what elements are needed, express what kind of emotion)
2. AI generated material
3. Material is processed in Figma (actually only a few functions in Figma are used, maybe Blender can take on this part of the work, fixed usage can directly provide users with the correct production ideas. Or just use Blender as a compositor. This is a place to think about).
4. Import materials into Blender for free combination of materials, directly creating 6000 NFTs

### Determine the direction

This step is actually quite mystical. Inspiration comes when it comes. If it doesn't come, you can't think of satisfactory ideas no matter what you do. Fortunately, GPT can now provide us with a very good starting point. Below are the design ideas provided by GPT 1068 1069.

Then I determined that the element of the dragon would be the main theme, using red and gold as the main colors. Coincidentally, I had a red envelope from my previous company stuck on the wall, and I thought it would be a good idea to use a similar envelope design as inspiration.

### AI-generated content

In fact, the only thing AI generated is the dragon, the rest just needs a simple design.

![Image](https://media.arcblock.io/lib/e1/e18a434bd4503bc4acd0de248a052976.webp) The title is just a calligraphy font, and then each character's size and position are individually modified to make it look a bit scattered, generating ten idioms related to dragons and positive atmosphere with GPT.

![Image](https://media.arcblock.io/lib/01/01d67c83c3e748ff61a52d281c9680a0.webp) The single characters are also designed very simply, following the design of red envelopes. They are also 10 single characters generated by GPT related to the Chinese New Year.

![Image](https://media.arcblock.io/lib/f8/f865daad513e300129481c4f16b94255.webp) The couplets are also very simple. Just put vertical text in a frame, also generated by GPT.

These are deliberately made as simple as possible, because I want to highlight the dragon as the main subject, and other elements should be kept simple.

I use Midjourney to generate dragons. Midjourney has the best effect and the simplest prompts, so there is no need to configure model parameters or research prompts like SD. There are actually many community-shared prompts, and the official community of Midjourney uses them as well. The best place for sharing prompts in the Chinese community surprised me, it is on Xiaohongshu (Little Red Book).

I generated many dragons using Midjourney, without going into details about how to use Midjourney since there are already many online tutorials available for MJ.
  ![image.png](https://media.arcblock.io/lib/16/16c396ae3c801e2947ab4a111dc185a4.w1600.webp)

![Image](https://media.arcblock.io/lib/a9/a9b0eda34b71ef9952d8efa1a131bc28.webp)

Right-click to copy the image of this dragon and paste it onto this website. [https://pixian.ai/](https://pixian.ai/)  It can directly remove the background.

![Image](https://media.arcblock.io/lib/25/25561c16a6fc7231e616d902cf9d5322.webp)

Click 'Copy' to directly go to Figma.

### Dealing with Materials in Figma

This step is actually quite simple, just need to handle each material like this

1. Each material is layered separately, such as each character being a layer, and the dragon being a layer. Students who have not been exposed to design may not be familiar with layers. Here is a diagram for reference.
2. The container size of each material should be consistent so that there is no need to process them again in NFT Blender, such as here each material size is in a square of 1024x1024.
3. Select all materials in Figma and export them to your computer.

### Combining in NFT Blender

Describe the process here in detail

1. Create NFT Blender templates. Fill in the template name and description on the right    ![Image](https://media.arcblock.io/lib/fc/fc48cbc296a4fe8a3cd4ba312288b204.w1600.webp)
2. Click this button to determine the NFT rendering range. Here you can change the NFT rendering range to 1024x1024 to match the material, and you can change the size of the material to match the rendering range.
3. Click the material binding button to add the materials that were just imported to the computer. Here, you need to add them in batches according to the previously sorted types. Only materials of the same type can be added at a time. 1141 1142 We just sorted out these 5 types 1144 1145 1146.
4. After adding friends, it becomes very simple. Drag the material (also known as content) into the rendering area, arrange the layer order on the right side, and you are pretty much done. Just publish it in NFT Maker.    ![image.png](https://media.arcblock.io/lib/12/12476f6f1b11c5a07faae0209f59b27f.w1600.webp)
5. Finally, remember to click on the blank area of the canvas to go back to the canvas properties.    ![image.png](https://media.arcblock.io/lib/fc/fce3729dff763dfaa8fba4c025516916.w1600.webp)    You can preview here and lock the template (to prevent accidental modifications).

---

## Ecological projects

URL: https://www.arcblock.io/en/docs/nftstudio/ecological-projects/

## Summarize

Any third-party project that meets the inclusion criteria will be included in our eco-projects.

The inclusion criteria are as follows:

1. Deployed with NFT Studio's associated Blocklet.
2. Have published a beautiful NFT Collection (no chains)
3. Have a complete landing page

## List of Eco-projects

[Mint Extraterrestrial Elf's Brilliance Page](https://www.luckwheel.xyz/maker/mint/z3CtScKmfUF6e6M62yGLiHJma1fWJFFnh4ASn)

---

## FAQs

URL: https://www.arcblock.io/en/docs/nftstudio/faqs/

## Overview

Here's a quick Q&A of NFT Studio's frequently asked questions.

## Q&A

### What is Blocklet Launcher?

Blocklet Launcher is a fully decentralized app launcher! With just a few clicks, you can quickly install decentralized applications in your digital world and immediately enable and run the applications smoothly.

### What is DID Spaces?

Experience the freedom and control of DID Spaces! Create and manage digital assets in a decentralized personal space that is secure, private, and reliable.

---

## How to Bind a Domain to a Blocklet (Google Domain)

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-bind-a-domain-to-a-blocklet-google-domain/

Why do I need to bind a domain name to Blocklet?

Although we provide a built-in DID Domain by default, it is highly recommended that NFT project owners bind their own domain names.

The reasons are as follows:

1. The NFT program will appear more formal
2. A shorter domain name will be more memorable to everyone

<strong>The detailed binding method can be found in the documentation:</strong>
[How to bind a domain to Blocklet and generate SSL/TLS certificate](/en/docs/blocklet-developer/bind-a-domain/)

---

## How to Build a Complete NFT Program

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-build-a-complete-nft-program/

## Overview

First, we need to define what a complete NFT project actually entails

- Preparation servers: used to set up related services
-
  - We provide the [<strong>Blocklet Launcher</strong>](https://launcher.arcblock.io/) for you to start your NFT project quickly and inexpensively.
  - We provide a [<strong>Blocklet Store</strong>](https://store.blocklet.dev/) for you to select the Blocklets you need to use.
- Site landing page: for displaying and promoting NFT
-
  - We provide [<strong>PagesKit</strong>](https://store.blocklet.dev/blocklets/z8iZiDFg3vkkrPwsiba1TLXy3H9XHzFERsP8o) for everyone to visually build site landing pages
- On-chain tools: used to deploy works of art onto the blockchain
-
  - We provide [<strong>NFT Maker</strong>](https://store.blocklet.dev/blocklets/z8ia2birZzhjbXqKnxPUUivmqErdsf3724tr6) for you to quickly create Collection
- Minting tools: used to mint NFT works on the chain
-
  - We provide[ <strong>NFT Store</strong>](https://store.blocklet.dev/blocklets/z8iZqkCjLP6TZpR12tT3jESWxB8SGzNsx8nZa) for you to quickly display NFTs, which is integrated in NFT Maker by default
- Artwork: A beautifully designed work of art
-
  - Works of art are usually picture resources, and each work has certain differences, which can be finished pictures or material pictures
  - We provide [<strong>NFT Blender</strong>](https://store.blocklet.dev/blocklets/z8ia1ieY5KhEC4LMRETzS5nUwD7PvAND8qkfX) for you to quickly and automatically combine material pictures to produce a large number of finished pictures, which is integrated in NFT Maker by default
  - We provide [<strong>DID Spaces</strong>](https://www.didspaces.com/) for you to store your artwork
- Promotion tool: used to promote NFT works
-
  - We provide [<strong>Tweet Token</strong>](https://store.blocklet.dev/blocklets/z8iZoLRKRXHzqdJ2vFZEi4H5UXT9ADsurxZRK) for everyone to use to retweet and collect likes to get airdrop NFTs
  - We provide a [<strong>Virtual Gift Card</strong>](https://store.blocklet.dev/blocklets/z8iZscGk6ohCejHEiX16C7apdFC7JrPYD1J4Z) for everyone to exchange for gift cards after obtaining NFT
  - We provide [<strong>DiscussKit</strong>](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu) for everyone to build NFT communities, publish blogs, and write documents
- Secondary market: for secondary circulation of NFTs
-
  - We provide an official [<strong>NFT Marketplace</strong>](https://marketplace.arcblock.io/) for everyone to buy their favorite NFT in the secondary market

Obviously, releasing a complete NFT project requires a lot of preparation, and in traditional NFT projects, they are all independent and SASS-based, and users need to go through multiple sites to complete an NFTs project, which is time-consuming and laborious

Now through our <strong>NFT Studio</strong>, you only need to move your fingers and combine Blocklets to build a complete NFT project

In the end we simplified the process to get the following steps:

1. Install PagesKit
2. Install NFT Maker
3. `Optional` Install other Blocklets as needed

Next, let me take everyone to follow the simplified process and try it together! ! !

## Build Process

### 1. Install PagesKit

Quickly install PagesKit by searching in the [<strong>Blocklet Store</strong>](https://store.blocklet.dev/)

![image.png](https://media.arcblock.io/misc/1688439210457-jSaL8UG1GdIMCv8eCE5TZrSY.w1600.webp)

Select the application space that needs to be purchased

![image.png](https://media.arcblock.io/misc/1688715864579-bAAYoJzm65zXycxJLorm8Twf.w1600.webp)

Select the corresponding payment method and scan the code to obtain NFT through [DID Wallet](https://www.didwallet.io/)

![image.png](https://media.arcblock.io/misc/1688715971108-ZqDptnmgdc6rVUKX8OsfdaaX.w1600.webp)

Use DID Wallet to scan the code to become the Owner of the application, and the application will enter the installation state

After the installation is complete, PagesKit can be easily configured

First, we configure the domain name and fill in the domain name we want to bind

![image.png](https://media.arcblock.io/misc/1689048603810-9Lyax6_owBywgRGfSclkIlbO.w1600.webp)

Go to the domain name provider (take Google Domain as an example) for DNS resolution, and CNAME your own domain name to the provided DID Domain,  [Reference link](https://www.nftstudio.rocks/comment/docs/how-to-build-a-complete-nft-program)

![image.png](https://media.arcblock.io/misc/1689048730815-JOZsu_6rnXRimS1W3Yvyuul2.w1600.webp)

Return to the page and click Next, the domain name will be added automatically and the HTTPS certificate will be issued

After performing other simple configurations, PagesKit can be started normally, and can also be opened through the bound domain name

Opening the bound domain name will open PagesKit normally, go to the upper right corner to connect to the wallet (provide Owner Passport), and then you can enter the background

![image.png](https://media.arcblock.io/misc/1688451032151-MqLZHULIfGbLsBFRGyEF4jLd.w1600.webp)

At the same time, you can also see the dashboard of the application space to manage the application space

![image.png](https://media.arcblock.io/misc/1689048838193-feArsXykzh6GWR9qm49C17O9.w1600.webp)

### 3. Install NFT Maker

Find Add Component on the Components Tab page of the dashboard

![image.png](https://media.arcblock.io/misc/1689048901770-tiaUv6kUHgWWqVNiX1CV6VK_.w1600.webp)

Search for NFT Maker and select it

![image.png](https://media.arcblock.io/misc/1689049011032-W-v3ZhTORo5mmGo8bbheG4VC.w1600.webp)

Next, you need to configure: path, environment variable, connection DID Spaces space

`Optional` If you need to test on the ArcBlock Beta chain, configure according to the red box below, otherwise the default is the ArcBlock Main chain
![image.png](https://media.arcblock.io/misc/1689049056656-4G5c6Ju1fV3ybRkyKuWqZHTn.w1600.webp)

NFT Maker requires to connect to DID Spaces to allow NFT to be stored persistently (even if the application is not working, NFT can be displayed normally), click Connect

![image.png](https://media.arcblock.io/misc/1689049126869-hYXkrx1ZitAGRJKVCOQdyhnt.w1600.webp)

`Optional` If you don’t have DID Spaces yet, you can click DID Wallet to purchase. After connecting the wallet and paying, an NFT will be sent to the wallet

![image.png](https://media.arcblock.io/misc/1689049319445-ZXuQomO5zDQK_gAI51t3wYiu.w1600.webp)

Trigger re-Connect, find the NFT of DID Spaces, operate DID Wallet to select the DID Spaces space you want to connect

![image.png](https://media.arcblock.io/misc/1689058763176-UWh1UcoyDb1yMl8EgXZNlv85.w1600.webp)

After successfully connecting to DID Spaces, it will be installed automatically, and finally you only need to wait for a moment to complete

![image.png](https://media.arcblock.io/misc/1689049477907-g-F6_ha-zA_MtKR4U-Jr2k_9.w1600.webp)

### 4. `Optional` Install other Blocklets as needed

Installation of additional Blocklets to support more features follows the same process as installing NFT Maker.

You can refer to the overview section to assemble as many blocklets as you need.

## Summary

Hopefully, with this document, you can quickly build a complete NFT project!

---

## How to Mount NFT Series Blocklets Locally

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-mount-nft-series-blocklets-locally/

## Overview

If you need to do secondary development with NFT Studio, it is inevitable that you will need to mount the NFT Series Blcoklet during local development.

## How to mount

Let's take the example of mounting NFT Maker

In the top-level application files directory, find the blocklet.yml file and add the components parameter

More configurations can view: [<strong>blocklet.yml</strong>](/en/docs/blocklet-developer/blockletyml/)

```javascript
// blcoklet.yml
components:
  - name: nft-maker
    mountPoint: /maker
    source:
      store:
        - https://store.blocklet.dev
      name: nft-maker
      version: latest

```

As shown in the figure below

![image.png](https://media.arcblock.io/misc/1688457024070-QSyIWkKYP_-MRdOGumy2JGTe.w1600.webp)

## Common Problems

### Why can't I start local apps after mounting

Because the image rendering function of NFT series apps relies on back-end rendering, you will need to use the canvas.node dependency package.

This kind of package has a characteristic: it's not directly compatible with different operating systems and chips, so if you can't find the dependency package, you need to recompile it.
If we mount it directly, during the pre-start phase, we will pull or compile the dependencies, and usually the compilation part is where things go wrong.

#### how to resolve

```javascript

// macOS Installation Compilation Dependencies
xcode-select --install

brew install pkg-config cairo pango libpng jpeg giflib librsvg

brew update --auto-update

// Optional: Restart your computer

// Restart the top-level Blocklet

// Other system build dependencies: https://github.com/Automattic/node-canvas/wiki
```

---

## How to publish NFT Templates to the Blocklet Store

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-publish-nft-templates-to-blocklet-store/

## Summary

If you need to publish NFT Templates to the Blocklet Store and share it with others for quick use, you can follow this guide.

## How to use

We use the NFT template of [Season Girl](https://www.nftstudio.rocks/maker/mint/z3CtAg8muLMSUxnbJcRoySEfdqyk4kiXHT7BQ) as an example.

1. First, we go to NFT Blender, click on the top right corner `Export Resource Pack`, or click on the left sidebar `Studio`.

![QQ_1731429179681.png](https://media.arcblock.io/lib/a9/a9001ca626c15d56a92732175ad7b16b.w1600.webp)

1. Then we select `New Blocklet`, creating a new Blocklet.

![2LBPYkru5UyWoBJT.png](https://media.arcblock.io/lib/11/1149907f0f863ee48f78a6ac92bdacac.w1600.webp)

1. Improve the brand information of Blocklet, which will be displayed on the Blocklet Store list page and details page.

![QQ_1731429571460.png](https://media.arcblock.io/lib/63/63e3330f4262d0f2957ff69e9277aab6.w1600.webp)

1. Improve the introduction of Blocklet, which will be displayed on the details page of Blocklet Store

![QQ_1731429809416.png](https://media.arcblock.io/lib/9f/9f2cf9f34818e98a79c08118b215d55f.w1600.webp)

1. Select the NFT template to be released, click on the  `Create Release`  in the upper right corner to generate a Blocklet (no need to make any selections in the following Blocklets steps)

![QQ_1731430060832.png](https://media.arcblock.io/lib/09/091278701164ea6d3ab5fbb78f93f150.w1600.webp)

1. Click on `Connect or Upload` at the end to complete the DID Connect authorization and upload to the store.

![QQ_1731430240798.png](https://media.arcblock.io/lib/7e/7e7fc41ade1c81ac3862d2c74d8b91f1.w1600.webp)

![QQ_1731430462752.png](https://media.arcblock.io/lib/1b/1b79a08b729e6ca75502c7be0dbb8774.w1600.webp)

1. We also need to click on `Visit` to go to the Blocklet Store and use DID Connect for `Publish`

![QQ_1731430593224.png](https://media.arcblock.io/lib/62/6216193ca98db284e989d364f8bc1fe3.w1600.webp)

1. Of course, we can also enable automatic publishing, so that each update no longer requires the use of DID Connect and Blocklet Store for authorized publishing.

![QQ_1731430410055.png](https://media.arcblock.io/lib/42/420eb00b68c77757bd98fdfc99cd72d9.w1600.webp)

## FAQ

#### How to get the official Blocklet Store app on the shelves authorization

Divided into several situations:

- If you need to be listed on the official ArcBlock beta store, you can visit [https://test.store.blocklet.dev](https://test.store.blocklet.dev) and stake tokens for authorization.
- If you need to list on the ArcBlock official Prod Store, you need to go to [https://community.arcblock.io](https://community.arcblock.io) to submit a post for review.
- If you need to list your Blocklets in your Blocklet Store, you can install Blocklet Store in the App Store and Connect in the steps above.

---

## How to Upload NFTs to DID Spaces Using the SDK

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-upload-nfts-to-did-spaces-using-the-sdk/

## Overview

If you need to develop NFT Studio and want to upload NFT customizations to DID Spaces, you can call NFT Blender via the SDK.

Here's how to use /api/sdk/upload-to-did-spaces

## How To Use

1. Mounting NFT Blender as a component, [related information ](https://www.nftstudio.rocks/comment/docs/how-to-mount-nft-series-blocklets-locally) Of course, mounting NFT Maker also works: NFT Maker mounts NFT Blender
2. For local development of top-level applications, you may need to fill in the Endpoint for DID Spaces, which can be added in the .env.development file ```javascript APP_SPACE_ENDPOINT=https://<your-did-spaces-endpoint> ```
3. In Top-Level Applications Mapping to the NFT Blender SDK ```javascript const component = require('@blocklet/sdk/lib/component');  // ----------------- NFT Blender SDK -----------------  const { data } = await component.call({   name: 'nft-blender',   path: '/api/sdk/upload-to-did-spaces',   data: {     fileName: '', // NFT Filename     filePath: '', // NFT Filepath     assetId: '', // NFT Address   }, });  // ----------------- NFT Blender SDK ----------------- ```
4. Complete the logic of the top-level application and trigger the code to upload the NFT to DID Spaces
5. You can check if the upload was successful by going to DID Spaces

## Parameter Description

| Parameter Name  | Required  | Default / Enum  | Tips  |
|---|---|---|---|
| fileName  | ✅  | undefined  | NFT display filename  |
| filePath  | ✅  | undefined  | NFT filepath  |
| assetId  | ✅  | undefined  | NFT address  |

---

## How to use AIGC to generate NFT image resources

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-use-aigc-to-generate-nft-image-resources/

## Overview of AIGC

With the continuous development and advancement of artificial intelligence technology, AIGC (Artificial Intelligence Generated Content) has become one of the most important trends in the field of digital art in recent years.

AIGC can generate various forms of digital artworks, including images, audio and video, through machine learning and deep learning technologies, etc. These artworks are not only highly creative and unique, but also can help people explore the relationship between AI and art, and promote the development and innovation of digital art.

Currently, more and more AI companies and artists have started to use AIGC technology to create digital artworks

For example, AIGC services such as Midjourney and Stable Diffusion have become mainstream creation tools, and more and more digital artworks have begun to circulate in the NFT marketplace.

With the continuous development and application of AIGC technology, we believe it will play an increasingly important role in the future of digital art.

This article will introduce how to use the mainstream AIGC services to generate NFT image resources.

- [Midjourney ](/en/docs/nftstudio/midjourney/)

- [Stable Diffusion（DrawThings）](/en/docs/nftstudio/stable-diffusiondrawthings/)

- [Stable Diffusion（InvokeAI）](/en/docs/nftstudio/stable-diffusioninvokeai/)

---

## How to use NFT Blender to manage materials

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-use-nft-blender-to-manage-materials/

## Overview

`NFT Blender` Provide material management ability, after uploading the material can be used in the template binding

It is recommended to export images of the same size from the same part of the material and then upload them to the material management.

## How To Manage Material

1. Open NFT Blender and switch to the Materials tab, click Add Material to open the dialog box ![image.png](https://media.arcblock.io/misc/1688459468439-K8FXqQxNX6Nm9cs3L3eRhQrY.w1600.webp)
2. Select or drag and drop the material to be uploaded (multiple selection supported) <strong>Make sure that the images you select are in the same part of the NFT and are exported at the same size!</strong> ![image.png](https://media.arcblock.io/misc/1688459518042-UPKLExJ9mdvmtMU5LtDOFoLF.w1600.webp)
3. Enter a group name and click Confirm Upload Materials ![image.png](https://media.arcblock.io/misc/1688459575709-5fDlJvW8g98tqGSU3WkMDMNv.w1600.webp)
4. The group operation bar allows you to manipulate the group, including: removing unused clips, adding clips, and collapsing and expanding the group ![image.png](https://media.arcblock.io/misc/1688459599531-5fq6-r60GVnN_IKgo_Pu8Rye.w1600.webp)

---

## How to use NFT Maker to create Collection

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-use-nft-maker-to-create-collection/

You can learn more by going to

[How To Use NFT Maker](https://www.nftstudio.rocks/en/nft-maker/how-to-use)

---

## How to use the SDK to recycle or redistribute NFTs

URL: https://www.arcblock.io/en/docs/nftstudio/how-to-use-the-sdk-to-recycle-or-redistribute-nfts/

## Overview

If you need to develop NFT Studio and want to recycle or transfer NFTs, you can do so by interfacing with the SDK.

Let's take an airdrop NFT application as an example of how to recycle or redistribute NFTs using /api/sdk/mint-asset-by-factory-trusted-issuer.

## How To Use

1. Mounting NFT Maker as a component,  [related information](https://www.nftstudio.rocks/comment/docs/how-to-mount-nft-series-blocklets-locally)
2. Developing locally The top-level application fills in the Endpoint of DID Spaces, which can be added to the .env.local file ```javascript APP_SPACE_ENDPOINT=https://<your-did-spaces-endpoint> ```
3. In Top-Level Applications Mapping to the NFT Maker SDK ```javascript const component = require('@blocklet/sdk/lib/component');  // ----------------- NFT Maker SDK -----------------  // Success returned a tx hash const { data: txHash } = await component.call({   // In-app calls, no need to worry about encryption and decryption issues   name: 'nft-maker', // This is where you need to look at the name definition in blocklet.yml.   path: '/api/sdk/mint-asset-by-factory-trusted-issuer', // This api cannot be called externally   data: {     factoryAddress, // Required, factory address     assetOwnerAddress, // Optional, asset owner address, default mint to the application's corresponding wallet address     locale, // Optional, Language of incorrect information     userPk, // Optional, will be parsed as a mint-asset wallet, app wallet is used by default, tweet token doesn't use this parameter.   }, });  // ----------------- NFT Maker SDK ----------------- ```
4. To refine the logic of the top-level application, create a Collection in NFT Maker to get the address using the method described above.

## Parameter Description

| Parameter Name  | Required  | Default / Enum  | Tips  |
|---|---|---|---|
| factoryAddress  | ✅  | undefined  | The address of the Collection  |
| assetOwnerAddress  | ❌  | appWallet.address  | The address of the asset owner, default is the application wallet address.  |
| userPk  | ❌  | undefined  | The collection trusted issuer address, defaults to the application wallet address  |
| locale  | ❌  | en / ['zh', 'en']  | Multi-language support  |

## Common Problems

#### Why create a Collection in NFT Maker?

When NFT Maker creates a Collection, it adds the top-level app's wallet address to trustedIssuers.

This allows the top-level app to link to NFT Maker via the SDK to reclaim or transfer NFTs from the Collection.

---

## Midjourney

URL: https://www.arcblock.io/en/docs/nftstudio/midjourney/

## Overview

Midjourney is a GAN (Generative Adversarial Networks) based AIGC service that generates high quality images and videos.

It is integrated into Discord by default, with no additional WebUI, and requires a fee.

Midjourney project address：[https://www.midjourney.com/home/](https://https://www.midjourney.com/home/)

<strong>Preview of the finished product</strong>

| ![ArcBlock_wear_a_T-shirt_ca796b37-ee21-40e7-8648-2709a35f87a7.png](https://media.arcblock.io/misc/1689314843957-DtbvWbZ6lpMlQjOAfW8owOCH.w1600.webp)  | ![ArcBlock_cute_dog_0b34ea53-1d47-4a0c-b793-297e862fd9d2.png](https://media.arcblock.io/misc/1689314843977-glKYZGypb64eUlHz12C8_Mx3.w1600.webp)  |
|---|---|

## How to use

1.  Optional First, confirm whether you have a Midjourney account. If not, you need to add a robot and activate a subscription according to the following methods, Open Midjourney official website, click Join the Beta in the lower right corner ![image.png](https://media.arcblock.io/misc/1688975279466-TXykbe3r1rTfxEWG_kNQLgHE.w1600.webp) At this point it will jump to Discord, and open the Midjourney community, we click Member List, find the robot, right-click to join our own server ![image.png](https://media.arcblock.io/misc/1688975598886--OdlFIVNaJuaScNv5G_bx1hx.w1600.webp) Select the server to join and complete the authorization ![image.png](https://media.arcblock.io/misc/1688975721701-BXLUcpYFrlRyRvaj-lGCCrl7.w1600.webp) Enter the server, select a channel, and enter /subscribe in the channel  ![image.png](https://media.arcblock.io/misc/1688975903729-HEX3tDvwklEgrzBLB5kjJYBk.w1600.webp) Jump to the official website to choose a package and make a paid subscription ![image.png](https://media.arcblock.io/misc/1688976092307-ww5SYOj-6Z-5MRenl57YXcSO.w1600.webp)

1. Back in Discord, enter /imagine in the chat box to wake up ![image.png](https://media.arcblock.io/misc/1688976988208--TTZtd-Dae2fRJjKtVPhf0VU.w1600.webp) Then enter Prompt: cute dog, and the corresponding picture will be generated after a while U1 ~ U4: Refers to the number of pictures to enlarge (Upscale), when we are satisfied with the picture, we can click V1 ~ V4: Refers to the first few pictures of Variation, when we feel that we need to continue to make subtle changes to the pictures, we can click Refresh button: refers to regenerate 4 pictures, when we are not satisfied with these pictures, we can click ![image.png](https://media.arcblock.io/misc/1688977742385-xf_W_voaSuJ6v1znHq6fBMBO.w1600.webp)
2. We click on U1 for a larger picture, for more action ![image.png](https://media.arcblock.io/misc/1688978416798-cyzO9uWAkTBb4rRH1Ck8SGS-.w1600.webp) Vary：Refers to the change picture, Vary(Strong) means strong change, Vary(Subtle) means weak change, you can check the difference ![image.png](https://media.arcblock.io/misc/1688978653313-o6wbamB-YFEKT5y82-4pSNKm.w1600.webp) In addition, Zoom Out and the arrow keys are the expansion operation Instead of simply zooming in on the picture, it will draw more details (green range) ![image.png](https://media.arcblock.io/misc/1688978907166-wxIvTcuzNUGqGS-Lh2UqOKbm.w1600.webp)
3. The final picture is suitable, we select U1 again, and right click to download the picture ![image.png](https://media.arcblock.io/misc/1688979057656-dJFg5NegkasZ1Sqh8v_R2tnX.w1600.webp)
4. We can also switch models and various modes through /settings ![image.png](https://media.arcblock.io/misc/1688979231114-Noruk1XymJy0Wm89AsfdVPSZ.w1600.webp)
5. We can also generate similar pictures by drawing pictures First upload the file to Discover ![image.png](https://media.arcblock.io/misc/1688979865268-kVSb4iJFRG6_lG6jtHoz572R.w1600.webp) Right click on the image, copy link ![image.png](https://media.arcblock.io/misc/1688979932907-nTDQbvKPhj8QCgd17V2PKTi9.w1600.webp) Enter /imagine, and copy the link in, enter a space and enter an additional prompt, let's change the picture to a T-shirt here ![image.png](https://media.arcblock.io/misc/1688980107044-RlyzZAaaei6AYnhnwRzo7284.w1600.webp) Finally, you can get a similar picture ![image.png](https://media.arcblock.io/misc/1688980315460--AhNdUGPLSXuzE_qx_HIb9zQ.w1600.webp)

## Summarize

Midjourney has become a popular product nowadays as it provides simpler interactions through Discord, making AIGC convenient!

There are many more parameters that are not provided in this article, so you can check them out at [Showcase](https://www.midjourney.com/showcase/recent/).

---

## Getting Started

URL: https://www.arcblock.io/en/docs/nftstudio/nftstudio-getting-started/

## Overview

- [How to Build a Complete NFT Program](/en/docs/nftstudio/how-to-build-a-complete-nft-program/)

---

## How To Guides

URL: https://www.arcblock.io/en/docs/nftstudio/nftstudio-how-to-guides/

## Overview

- [How to use NFT Maker to create Collection](/en/docs/nftstudio/how-to-use-nft-maker-to-create-collection/)

- [How to use NFT Blender to manage materials ](/en/docs/nftstudio/how-to-use-nft-blender-to-manage-materials/)

- [By using the NFT Blender + AI tool, 6000 NFTs with a theme of the Year of the Dragon for the Spring Festival can be quickly created.](/en/docs/nftstudio/Cp6aXaCitdXO7Z-xZtwWyBg5/)

---

## Welcome

URL: https://www.arcblock.io/en/docs/nftstudio/nftstudio-welcome/

## Overview

<strong>NFT Studio</strong> is a series of components about NFT, which currently consists of the following blocklets

- <strong>NFT Maker</strong> for uploading NFT Collections to the web
- <strong>NFT Blender</strong> for quickly generating NFT artifacts from materials
- <strong>NFT Store</strong> for selling the NFT Collection
- <strong>NFT Marketplace</strong> for a secondary marketplace for NFTs.

## View Demo Video

<video src="https://media.arcblock.io/lib/b9/b92511285cd27f254e3fc16156422718.mp4" controls></video>

---

## Official Projects

URL: https://www.arcblock.io/en/docs/nftstudio/official-projects/

You can learn more by going to

[NFT Studio's Demos](https://www.nftstudio.rocks/demos)

---

## Reference Guide

URL: https://www.arcblock.io/en/docs/nftstudio/reference-guide/

## Overview

- [How to publish NFT Templates to the Blocklet Store](/en/docs/nftstudio/how-to-publish-nft-templates-to-blocklet-store/)

- [How to Bind a Domain to a Blocklet (Google Domain)](/en/docs/nftstudio/how-to-bind-a-domain-to-a-blocklet-google-domain/)

- [How to Mount NFT Series Blocklets Locally](/en/docs/nftstudio/how-to-mount-nft-series-blocklets-locally/)

- [How to Upload NFTs to DID Spaces Using the SDK](/en/docs/nftstudio/how-to-upload-nfts-to-did-spaces-using-the-sdk/)

- [How to use the SDK to recycle or redistribute NFTs](/en/docs/nftstudio/how-to-use-the-sdk-to-recycle-or-redistribute-nfts/)

- [How to use AIGC to generate NFT image resources](/en/docs/nftstudio/how-to-use-aigc-to-generate-nft-image-resources/)

---

## NFT Studio + Payment Kit

URL: https://www.arcblock.io/en/docs/nftstudio/rpTQdaiIg_blfdMqiIX3qbS1/

<details>
<summary>How to add Stripe payment method to receive currencies other than Virtual Currencies</summary>

You need to go to Payment Kit to add new payment methods, restart all applications after adding, and then go to NFT Maker to configure multi-currency prices.

![image.png](https://media.arcblock.io/lib/8e/8e902a658419ad8c8f8df1bd2138c6c1.w1600.webp)

</details>

<details>
<summary>How to use the balance in the Payment Kit</summary>

Divided into 2 cases:

- Virtual currency payment: Find the Blocklet app account in the DID Wallet and proceed with the usage.
- Stripe Payment: The balance will not be stored in the Payment Kit, please go to Stripe Dashboard for confirmation

</details>

<details>
<summary>How to give users a refund or rebate</summary>

Go to the Payment Kit management page, and select the corresponding record for refund in Payments

![image.png](https://media.arcblock.io/lib/ad/adc65055881396c27ea3db47c5bdb73d.w1600.webp)

Operation according to the prompts on the page.

![image.png](https://media.arcblock.io/lib/03/0382fc977ed3d5812b02faa1ff1d2dd1.w1600.webp)

</details>

<details>
<summary>Why do you need to recharge the chain service fees</summary>

Unlike the previous acquire-asset minting method, the new minting method is completed through mint-asset, in order to prevent abuse of this feature, this feature requires payment of chain service fees.

In general, if the price of your NFT Collection is adjusted to be greater than 0.1 ABT, and no fiat (USD) payment is configured, you don't need to worry about this limit.

However, we still recommend that you recharge enough chain transaction fees based on the total minting amount of each batch to ensure the progress of the minting task

* Note: The recharge of the chain service fees is lossless and can be used at the disposal of the DID Wallet

![image.png](https://media.arcblock.io/lib/d5/d57f3746a572d5cc53df49a5eb48b888.w1600.webp)

</details>

<details>
<summary>How to close the new minting method</summary>

You can close the new way of minting at any time, just turn off the switch and save.

![image.png](https://media.arcblock.io/lib/95/95c4946e53a9855889120d20dbea8e42.w1600.webp)

Of course, you can also open and make adjustments at any time

</details>

<details>
<summary>Why is my USD being deducted more when I mint NFTs with Stripe?</summary>

When you make a payment in USD, Stripe may perform a pre-authorization transaction (usually 1 USD). The purpose of this transaction is to verify the validity of your credit card and to ensure that your payment method works. This pre-authorization is not an actual chargeback and will usually be automatically refunded to your account within a few days.

If this pre-authorization payment is not returned immediately, rest assured that it will usually be automatically released within a few days and will not be debited from your account. If you find that this payment has not been returned after a few days, please reach out to your card issuer or Stripe!

</details>

---

## Sample Projects

URL: https://www.arcblock.io/en/docs/nftstudio/sample-projects/

## Overview

- [Official Projects](/en/docs/nftstudio/official-projects/)

- [Ecological projects](/en/docs/nftstudio/ecological-projects/)

---

## Stable Diffusion（DrawThings）

URL: https://www.arcblock.io/en/docs/nftstudio/stable-diffusiondrawthings/

## Overview

Compared to Midjourney, Stable Diffusion offers the following advantages: Firstly, it's free to use, requiring no financial commitment. Secondly, Stable Diffusion supports model switching, allowing users to flexibly choose between different models based on their needs. Additionally, it boasts a more user-friendly interface, enhancing overall usability.

However, Stable Diffusion does come with a few limitations: Most of its features require local deployment, potentially adding complexity to the usage process.

Draw Things is an implementation built upon the Stable Diffusion framework, currently compatible only with MacOS operating systems. Its standout feature, when compared to other WebUI tools, is its plug-and-play nature, eliminating the need for intricate configurations.

You can find more details about the Draw Things project at the following address: [Draw Things: AI-assisted Image Generation](https://drawthings.ai/)

## ArtWork Preview

| ![_8k__best_quality__masterpiece_1_2___best_quality_1_0____ultra_highres_1_0___watercolor__a_beautiful_woman__shoulder__hair_ribbons__by_agnes_cecile__half_body_portrait__extremely_luminou_132340236.png](https://media.arcblock.io/misc/1688973561241-59Q8PHYE-nOSNOOQ8YEc1KGb.w1600.webp)  | ![](http://127.0.0.1:9090/outputs/000009.1b3e2817.931890518.png)![_8k_2_best_quality__masterpiece_1_2___best_quality_1_0____ultra_highres_1_0___watercolor__a_beautiful_woman__shoulder__hair_ribbons__by_agnes_cecile__half_body_portrait__extremely_luminou_132340236.png](https://media.arcblock.io/misc/1688973561442-x8jeH6CGvBCdDSshpyujtNC2.w1600.webp)  | ![](http://127.0.0.1:9090/outputs/000011.66528031.931890518.png)![_8k__best_quality__masterpiece_1_2___best_quality_1_0____ultra_highres_1_0___watercolor__a_beautiful_woman__shoulder__hair_ribbons__by_agnes_cecile__half_body_portrait__extremely_lumino_1024989392.png](https://media.arcblock.io/misc/1688973561279-iwXRaAwIZPCJi5JtM2yUse8-.w1600.webp)  |
|---|---|---|

## Step-by-step Guide

1. Begin by visiting the [official website](https://drawthings.ai/) and proceed with the installation of Draw Things. ![image.png](https://media.arcblock.io/misc/1688970371608-GV8DB8qNY-cKgWnDI6OvxZps.w1600.webp)
2. Upon opening DrawThings, a new user guide will appear, guiding you through the model installation process. You have the option to skip this step if desired.![image.png](https://media.arcblock.io/misc/1688970477896-w7gRJOE4GnOerVrFhXhWYs2Q.w1600.webp)
3. Click on the "Model List" to switch between models. For models indicated with ☁️, you can quickly download them by clicking on them.![image.png](https://media.arcblock.io/misc/1688970674221-f3qTYYg5F2ECLfPfX9Al3x5X.w1600.webp)
4. After switching the model, try entering "chibi, cat" in the prompt input box and adjust the parameters below. Then, click the "Generate" button to create the artwork. (It is recommended to use the DPM++ xxx Karas sampler for generating high-quality images around step 30.)![image.png](https://media.arcblock.io/misc/1688971560256-Y6lgK_QvbcxStW_UI_yStQl5.w1600.webp) Feel free to click the "Generate" button multiple times to create multiple artworks. Additionally, you can adjust the prompt to generate different types of content. ![image.png](https://media.arcblock.io/misc/1688971749750-pNOYYhgwtgV9KvlWIUUWBeQt.w1600.webp)
5. The default Stable Diffusion models may not fully meet everyone's requirements. In such cases, you have the option to adjust the model as needed. You can visit [https://civitai.com](https://civitai.com/) to explore artworks that have been generated by other users. ![image.png](https://www.nftstudio.rocks/comment/uploads/1688538403862-SNFkeWmxP9BKU0eSoY-e19fq.png)
6. When you click on a liked artwork, you will enter the detailed page for the model. Next to the "Download" button, you can click on the arrow icon.![image.png](https://www.nftstudio.rocks/comment/uploads/1688971842874-D0OQH87dGaS4v22IrONIQ59_.png) Select "Draw Things" from the list. ![image.png](https://www.nftstudio.rocks/comment/uploads/1688971910091-RCquPn9-FGWNO04am1xWu7jQ.png) This will automatically activate Draw Things for model download. Click "Continue," and the download process will commence automatically. ![image.png](https://www.nftstudio.rocks/comment/uploads/1688972149820-vFh3L5GWHK77bzKQ10hnakRf.png) Once the download is complete, click "Import" to finalize the import process. ![image.png](https://media.arcblock.io/misc/1688972397681-7pqDTghy7YFeQhQPAZznCMjn.w1600.webp)
7. Switch the model to the newly selected one. ![image.png](https://media.arcblock.io/misc/1688972438595-kY7k3XE4ULCOxZnzbDiLrjda.w1600.webp)
8. Navigate back to civitai and select a favorite artwork from the chosen model. This will bring up information about the selected artwork. Below, you will find prompts, configurations, and other parameters related to the artwork.![image.png](https://media.arcblock.io/misc/1688972529378-Zc1pK8s2jQKpceHc0fTOMiTs.w1600.webp)
9. Return to DrawThings, switch the model, and configure it as necessary.![image.png](https://media.arcblock.io/misc/1688973207671-Qw9cKV5f9f74Wnt68uRC83Hw.w1600.webp)
10. If you wish to stylize LORA, you can navigate to civitai and search for the corresponding LORA file. Import it using the same method as with models, and you'll ultimately obtain the finished product as described in the overview section.

## Summary

Stable Diffusion has the capability to adjust styles through model modifications, resulting in distinct artworks based on different prompts.

In Stable Diffusion, the process of Artistic Image Generation and Control (AIGC) is akin to conducting an experiment, requiring careful management of various variables to ensure the resulting artworks achieve aesthetic appeal.

DrawThings is currently a well-optimized out-of-the-box application of Stable Diffusion, offering users a seamless experience.

Apart from DrawThings, users can also utilize other WebUIs for Artistic Image Generation and Control (AIGC), with similar operational approaches, such as:

1. [https://github.com/AUTOMATIC1111/stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui) （MacOS / Win）
2. [https://diffusionbee.com/](https://diffusionbee.com/) （MacOS ）
3. [https://github.com/invoke-ai/InvokeAI](https://github.com/invoke-ai/InvokeAI)（MacOS / Win）

### References

<strong>Learn more about Stable Diffusion</strong>

[Civitai | Stable Diffusion 潜工具书【中文文档】](https://civitai.com/articles/851/stable-diffusion)

[NovelAI · 语雀](https://www.yuque.com/longyuye/lmgcwy)

[词图PromptTool - AI绘画](https://www.prompttool.com/NovelAI)

<strong>Prompt Generator</strong>

[NovelAI tag在线生成器](https://wolfchen.top/tag/)

---

## Stable Diffusion（InvokeAI）

URL: https://www.arcblock.io/en/docs/nftstudio/stable-diffusioninvokeai/

## Overview

Compared to Midjourney, Stable Diffusion's advantages are: free of charge, supports switching models, higher operability. Its disadvantages are: it mostly requires local deployment.

Suggestion: If you are new to AIGC, it's recommended to find ready-to-use services instead of wasting your passion on local deployment.

InvokeAI is an open-source implementation based on Stable Diffusion，Currently it does not have any online services and requires users to deploy locally on their own (MacOS/Win).

InvokeAI GitHub Repo：[https://github.com/invoke-ai/InvokeAI](https://github.com/invoke-ai/InvokeAI)

## Preview

| ![000007.426687c3.931890518.png](https://media.arcblock.io/misc/1688547181914-tkt38Z9W1ywJLiI7QoVSN-cc.w1600.webp)  | ![](http://127.0.0.1:9090/outputs/000009.1b3e2817.931890518.png)![000011.253c093e.931890518.png](https://media.arcblock.io/misc/1688548070294-vBNGWYy6gSfNF4N7dDjX5Eua.w1600.webp)  | ![](http://127.0.0.1:9090/outputs/000011.66528031.931890518.png)![000010.823a2a1a.931890518.png](https://media.arcblock.io/misc/1688548065543-rUvk6pB6qaZgDm0qzarKGKH3.w1600.webp)  |
|---|---|---|

## Usage

1. First,  [follow the official tutorial](https://)，choose the correct version for your computer and deploy InvokeAI locally ![image.png](https://media.arcblock.io/misc/1688464131345-CBPoA_I6LxLLUXg8t_ftZ-r4.w1600.webp)
2. Go to the InvokeAI installed folder，execute ` ./invoke.sh `，Select 2 to open the prompted URL and get a WebUI ![image.png](https://media.arcblock.io/misc/1688464376320-D-FgMx-qdQ1nT51xOJY485jM.w1600.webp)
3. Try inputting "a girl with long hair" in the Prompt text box in the top left. Then adjust the parameters below and click "Invoke" to generate an image![image.png](https://media.arcblock.io/misc/1688538065548--UgD_GToqY3Gul-pVjtoDIUE.w1600.webp) We can click "Invoke" multiple times to generate multiple images. We can also adjust the Prompt to generate other content. ![image.png](https://media.arcblock.io/misc/1688538251678-GqGMG-QH5awK2Vs_aIjcd9dh.w1600.webp)
4. The default Stable Diffusion model may not meet everyone's needs. In that case, you can adjust the model as needed  You can go to [https://civitai.com](https://civitai.com/) to see artwork generated by others.  ![image.png](https://media.arcblock.io/misc/1688538403862-SNFkeWmxP9BKU0eSoY-e19fq.w1600.webp)
5. We can click on a artwork we like to go to the model details, then click "Download" to download the model. ![image.png](https://media.arcblock.io/misc/1688543388885--QHPFcSKAflcdrduKNe8bl4D.w1600.webp)
6. Place the downloaded model in your local InvokeAI models folder (your-invokeai-path/models), and load the model through the WebUI.![image.png](https://media.arcblock.io/misc/1688539453346-55xhc7tJe71-dJfPQFXWmNaN.w1600.webp) ![image.png](https://media.arcblock.io/misc/1688539483512-0jwZUt-IniaE4oTCRl8jGdXl.w1600.webp) Input the model path, search for the model, select the model, and add it. ![image.png](https://media.arcblock.io/misc/1688544050547-VotMjZ3x5u47cq0UeSB2dJY5.w1600.webp)
7. Go back to civitai, select an artwork you like from the model, and the artwork information will pop up. Below there will be some parameters for the artwork such as Prompt, configurations, etc.![image.png](https://media.arcblock.io/misc/1688544083770-uz9RDNlJanequn_7p810dxtP.w1600.webp)
8. Go back to the WebUI, switch the model, and configure it as needed.![image.png](https://media.arcblock.io/misc/1688544514463-fgmITWVdg8uHrf3IbdM9JJXr.w1600.webp) ![image.png](https://media.arcblock.io/misc/1688544453654-srwFJNa4Mca4N-LCS4kikbGj.w1600.webp)
9. Iteratively refine parameters and invoke image generation multiple times to obtain high-quality samples for the overview section.

## Summary

Stable Diffusion allows styling through model adjustments. Works generated from different prompts also vary.
Using Stable Diffusion is like conducting experiments, requiring control over different variables to achieve aesthetic results.

In addition to InvokeAI, you can also use other WebUIs for AIGC. The operations are largely similar, such as:

1. [https://github.com/AUTOMATIC1111/stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui) （MacOS / Win）
2. [https://diffusionbee.com/](https://diffusionbee.com/) （MacOS ）
3. [https://drawthings.ai](https://drawthings.ai) （MacOS）

### More information

<strong>Learn Stable Diffusion</strong>

[Civitai | Stable Diffusion 潜工具书【中文文档】](https://civitai.com/articles/851/stable-diffusion)

[NovelAI · 语雀](https://www.yuque.com/longyuye/lmgcwy)

[词图PromptTool - AI绘画](https://www.prompttool.com/NovelAI)

<strong>Prompt</strong>

[NovelAI tag在线生成器](https://wolfchen.top/tag/)

---

## Payment Kit UI (React)

URL: https://www.arcblock.io/en/docs/payment-kit-react/

---

## Components

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-8b3f3d/

The `@blocklet/payment-react` library offers a comprehensive suite of pre-built React components designed to accelerate the development of payment, subscription, and donation features. These components are categorized to help you find the right tool for the job, whether you need a complete drop-in solution or fine-grained UI elements to build a custom experience.

All components are designed to work seamlessly within the `PaymentProvider` context, which handles state management and API communication.

## Component Architecture

The following diagram illustrates how the high-level components typically interact. User-facing components like `CheckoutTable` or `CheckoutDonate` act as entry points, which then utilize the core `CheckoutForm` to handle the final payment processing.

![Components](https://media.arcblock.io/lib/67/6773afbbc775e32b.w1600.webp)

## Component Categories

Explore our component categories to find the building blocks you need.

### Checkout Components

These are high-level components that provide complete, out-of-the-box payment experiences. Use them as the primary entry points for your payment flows.

::::card-group
::link-card{title="CheckoutForm" description="The primary component for handling payment links and checkout sessions." icon="credit-card" href="/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/"}
::link-card{title="CheckoutTable" description="Renders a complete pricing table and handles the checkout flow." icon="table-2" href="/en/docs/payment-kit-react/components-checkout-checkout-table-8b3f3d/"}
::link-card{title="CheckoutDonate" description="Implement donation functionality with this flexible component." icon="heart" href="/en/docs/payment-kit-react/components-checkout-checkout-donate-8b3f3d/"}
::::

### UI Components

A collection of granular components for building custom payment forms and displays. Combine these blocks to create a user interface that perfectly matches your application's design.

::::card-group
::link-card{title="PricingTable" description="Display subscription plans and pricing options in a structured table." icon="list" href="/en/docs/payment-kit-react/components-ui-pricing-table-8b3f3d/"}
::link-card{title="PaymentSummary" description="Show a detailed summary of an order, including line items and totals." icon="receipt" href="/en/docs/payment-kit-react/components-ui-payment-summary-8b3f3d/"}
::link-card{title="Form Elements" description="A collection of inputs for building custom payment and contact forms." icon="tool" href="/en/docs/payment-kit-react/components-ui-form-elements-8b3f3d/"}
::::

### Business Logic Components

Specialized components designed to handle complex business workflows, such as managing overdue invoices, resuming subscriptions, and configuring automatic credit top-ups.

::::card-group
::link-card{title="OverdueInvoicePayment" description="Handle the payment of overdue invoices for a customer or subscription." icon="warning" href="/en/docs/payment-kit-react/components-business-overdue-invoice-payment-8b3f3d/"}
::link-card{title="ResumeSubscription" description="Allow users to resume a canceled subscription with ease." icon="play" href="/en/docs/payment-kit-react/components-business-resume-subscription-8b3f3d/"}
::link-card{title="Auto-Topup Components" description="Manage and configure automatic credit top-up functionality." icon="bolt" href="/en/docs/payment-kit-react/components-business-auto-topup-8b3f3d/"}
::::

### History Components

Display historical payment and credit data to your users. These components make it easy to render lists of invoices, payments, and credit transactions.

::::card-group
::link-card{title="CustomerInvoiceList" description="Render a list of a customer's invoices with details and status." icon="clock" href="/en/docs/payment-kit-react/components-history-invoice-list-8b3f3d/"}
::link-card{title="CustomerPaymentList" description="Display a customer's payment history, including transaction details." icon="home" href="/en/docs/payment-kit-react/components-history-payment-list-8b3f3d/"}
::link-card{title="CreditGrantsList" description="Show a list of credit grants, including status and remaining amounts." icon="award" href="/en/docs/payment-kit-react/components-history-credit-grants-list-8b3f3d/"}
::::

---

## Business Logic Components

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-business-8b3f3d/

Business Logic Components are specialized React components designed to handle complex, stateful operations related to subscription and invoice management. These components encapsulate entire user flows, such as paying overdue invoices or resuming a canceled subscription, making it easy to integrate advanced functionalities into your application with minimal setup.

They are built on top of the core library features and often interact with the Payment Service API to perform actions and reflect state changes.

::::card-group
::link-card{title="OverdueInvoicePayment" description="A component to handle the payment of overdue invoices for a specific customer or subscription, presenting a dialog with payment options." icon="warning" href="/en/docs/payment-kit-react/components-business-overdue-invoice-payment-8b3f3d/"}
::link-card{title="ResumeSubscription" description="Allows a user to resume a canceled subscription. It handles the necessary API calls and re-staking logic if required." icon="play" href="/en/docs/payment-kit-react/components-business-resume-subscription-8b3f3d/"}
::link-card{title="Auto-Topup Components" description="A set of components for managing and configuring automatic credit top-ups, including a display card and a configuration modal." icon="zap" href="/en/docs/payment-kit-react/components-business-auto-topup-8b3f3d/"}
::::

### Next Steps

After integrating these business logic components, you might want to display historical data to your users. Proceed to the [History Components](/en/docs/payment-kit-react/components-history-8b3f3d/) section to learn how to list invoices, payments, and credit transactions.

---

## Auto-Topup Components

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-business-auto-topup-8b3f3d/

The auto-topup feature ensures uninterrupted service by automatically recharging a user's credit balance when it falls below a specified threshold. This is managed through two primary components: `AutoTopup`, which displays the current configuration, and `AutoTopupModal`, which provides the interface for setting it up.

## Auto-Topup Workflow

The diagram below illustrates the typical user flow for configuring the auto-topup feature. The user interacts with the `AutoTopup` display component, which launches the `AutoTopupModal` for making changes. The modal then communicates with the backend API to save the configuration.

![Auto-Topup Components](https://media.arcblock.io/lib/99/99ea4cb193e2ef77.w1600.webp)

## AutoTopup

The `AutoTopup` component is a display card that shows the current auto-recharge status for a specific currency and provides an entry point for configuration. It supports multiple rendering modes for flexibility.

### Props

| Prop  | Type  | Description  |
|---|---|---|
| `currencyId`  | `string`  | <strong>Required.</strong> The ID of the credit currency to manage.  |
| `onConfigChange`  | `(config: AutoRechargeConfig) => void`  | Optional. Callback function triggered when the configuration is successfully updated.  |
| `mode`  | `'default' \| 'simple' \| 'custom'`  | Optional. The rendering mode. Defaults to `'default'`. - `default`: A fully expanded card showing all details. - `simple`: A compact, collapsed view with a button to expand details. - `custom`: Renders a custom UI using the `children` render prop.  |
| `sx`  | `SxProps`  | Optional. Custom MUI styles to apply to the component.  |
| `children`  | `(openModal, config, paymentData, loading) => React.ReactNode`  | Optional. A render prop function used only when `mode` is `'custom'`. It receives the tools needed to build a custom interface.  |

### Usage

#### Simple Mode

This is the most common use case, providing a compact display that users can expand for more details.

**CreditManagement.tsx**

```tsx
import { PaymentProvider, AutoTopup } from '@blocklet/payment-react';

function CreditManagement({ session, currencyId }) {
  const handleConfigChange = (config) => {
    console.log('Auto-topup config updated:', config);
    // You might want to refresh the user's balance here
  };

  return (
    <PaymentProvider session={session}>
      <AutoTopup
        currencyId={currencyId}
        mode="simple"
        onConfigChange={handleConfigChange}
        sx={{ mt: 2 }}
      />
    </PaymentProvider>
  );
}
```

#### Custom Mode

For full control over the UI, use `custom` mode with a render prop. This allows you to integrate the auto-topup status and configuration trigger into your existing layout seamlessly.

**CustomAutoTopupDisplay.tsx**

```tsx
import { PaymentProvider, AutoTopup } from '@blocklet/payment-react';
import { Button, Card, CardContent, Typography } from '@mui/material';

function CustomAutoTopupDisplay({ session, currencyId }) {
  return (
    <PaymentProvider session={session}>
      <AutoTopup currencyId={currencyId} mode="custom">
        {(openModal, config, paymentData, loading) => {
          if (loading) return <div>Loading configuration...</div>;

          return (
            <Card variant="outlined">
              <CardContent>
                <Typography variant="h6">Smart Auto-Recharge</Typography>
                {config?.enabled ? (
                  <Typography color="success.main">
                    Status: Active
                  </Typography>
                ) : (
                  <Typography color="text.secondary">
                    Status: Inactive
                  </Typography>
                )}
                <Button onClick={openModal} variant="contained" sx={{ mt: 2 }}>
                  {config?.enabled ? 'Modify Settings' : 'Setup Now'}
                </Button>
              </CardContent>
            </Card>
          );
        }}
      </AutoTopup>
    </PaymentProvider>
  );
}
```

## AutoTopupModal

The `AutoTopupModal` is a dialog component that allows users to enable, disable, and configure all aspects of the auto-topup feature, including the trigger threshold, purchase amount, and payment method.

### Props

| Prop  | Type  | Description  |
|---|---|---|
| `open`  | `boolean`  | <strong>Required.</strong> Controls whether the modal is visible.  |
| `onClose`  | `() => void`  | <strong>Required.</strong> Callback function to close the modal.  |
| `currencyId`  | `string`  | <strong>Required.</strong> The ID of the credit currency being configured.  |
| `customerId`  | `string`  | Optional. The customer's DID. Defaults to the user from the `PaymentProvider` session.  |
| `onSuccess`  | `(config: AutoRechargeConfig) => void`  | Optional. Callback triggered after the configuration is successfully saved.  |
| `onError`  | `(error: any) => void`  | Optional. Callback triggered if an error occurs during submission.  |
| `defaultEnabled`  | `boolean`  | Optional. If `true`, the 'Enable Auto-Topup' switch will be on by default when the modal opens for a new configuration.  |

### Usage

Here is a complete example of how to manage the `AutoTopupModal`'s state and handle its callbacks.

**AutoRechargeSettings.tsx**

```tsx
import { PaymentProvider, AutoTopupModal } from '@blocklet/payment-react';
import { useState } from 'react';
import { Button } from '@mui/material';

function AutoRechargeSettings({ session, currencyId }) {
  const [isModalOpen, setModalOpen] = useState(false);

  const handleSuccess = (config) => {
    console.log('Configuration saved successfully:', config);
    setModalOpen(false);
    // Optionally, show a success toast or refresh data
  };

  const handleError = (error) => {
    console.error('Failed to save configuration:', error);
    // Optionally, show an error message to the user
  };

  return (
    <PaymentProvider session={session}>
      <Button variant="contained" onClick={() => setModalOpen(true)}>
        Configure Auto-Recharge
      </Button>

      <AutoTopupModal
        open={isModalOpen}
        onClose={() => setModalOpen(false)}
        currencyId={currencyId}
        onSuccess={handleSuccess}
        onError={handleError}
        defaultEnabled={true}
      />
    </PaymentProvider>
  );
}
```

This setup provides a robust way to manage auto-recharge functionality, giving users control while ensuring a smooth experience for maintaining their service credits.

---

## OverdueInvoicePayment

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-business-overdue-invoice-payment-8b3f3d/

The `OverdueInvoicePayment` component is a specialized tool designed to handle the payment of overdue invoices for a specific customer or subscription. It simplifies the process by automatically fetching overdue invoices and presenting users with a clear interface to settle their outstanding payments.

This component can operate in two modes: a default mode that displays a pre-built dialog for quick integration, and a custom mode that provides the flexibility to build a unique user interface using a render prop. It must be wrapped within a `PaymentProvider` to function correctly.

## Props

The `OverdueInvoicePayment` component accepts the following props to customize its behavior:

- **subscriptionId** `string` — The ID of the subscription to check for overdue invoices. Either subscriptionId or customerId must be provided.
- **customerId** `string` — The ID or DID of the customer. Use this to handle all overdue invoices for a specific customer.
- **mode** `'default' | 'custom'` (default: `default`) — The rendering mode. 'default' shows a pre-built dialog. 'custom' uses the children render prop for a custom UI.
- **onPaid** `function` — An optional callback function that is triggered after payment for a specific currency is successfully completed. It receives (id, currencyId, type), where id is the subscriptionId or customerId, and type is 'subscription' or 'customer'.
  - **parameters** `object`
    - **id** `string` — The subscriptionId or customerId.
    - **currencyId** `string` — The ID of the currency used for payment.
    - **type** `'subscription' | 'customer'` — Indicates if the payment was for a subscription or a customer.
- **dialogProps** `object` — Optional props to pass to the underlying Material-UI Dialog component in default mode. For example, { open: true, title: 'Custom Title', onClose: handleClose }.
- **detailLinkOptions** `object` — Optional settings for the "View Details" link. Can be used to disable the link, change its text, or provide a custom onClick handler.
  - **enabled** `boolean` — Whether the link is enabled.
  - **onClick** `(e: React.MouseEvent) => void` — Custom click handler.
  - **title** `string` — Custom link text.
- **successToast** `boolean` (default: `true`) — If true, a success toast notification is shown upon successful payment.
- **alertMessage** `string` — An optional message to append to the default title text when in customer mode.
- **children** `function` — A render prop function used only when mode is 'custom'. It receives a handlePay function and a data object.
  - **parameters** `object`
    - **handlePay** `(item: SummaryItem) => void` — Function to initiate the payment process for a specific currency group.
    - **data** `object` — An object containing the fetched payment information.
- **authToken** `string` — An optional authentication token for API requests, useful for server-to-server or cross-origin scenarios.

### children Render Prop Data

When using `mode="custom"`, the `data` object passed to the `children` function contains the following fields:

- **subscription** `Subscription` — The subscription details, if subscriptionId was provided.
- **summary** `{ [key: string]: SummaryItem }` *(required)* — An object where each key is a currency ID. The value contains the total amount, currency details, and payment method for that currency.
- **invoices** `Invoice[]` *(required)* — An array of all overdue invoice objects.
- **subscriptionCount** `number` — The number of subscriptions with overdue invoices (for customer mode).
- **detailUrl** `string` *(required)* — The URL to view detailed invoice information.

## Usage Examples

All examples assume you have `PaymentProvider` set up in your application as detailed in the [PaymentProvider documentation](/en/docs/payment-kit-react/providers-payment-provider-8b3f3d/).

### 1. Default Mode for a Subscription

This is the simplest way to handle overdue payments for a specific subscription. The component will automatically render a dialog if any overdue invoices are found.

**SubscriptionOverdue.jsx**

```javascript
import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session'; // Your custom session hook

function SubscriptionPage({ subscriptionId }) {
  const { session, connect } = useSessionContext();

  const handlePaymentSuccess = (id, currencyId, type) => {
    console.log(`Payment successful for ${type} ${id} with currency ${currencyId}`);
    // You can refetch subscription data here to update its status
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      {/* This component will be null if there are no overdue invoices */}
      <OverdueInvoicePayment subscriptionId={subscriptionId} onPaid={handlePaymentSuccess} />
      {/* Other subscription details can be rendered here */}
    </PaymentProvider>
  );
}
```

### 2. Default Mode for a Customer

Use this to create a centralized place for a customer to pay all their overdue invoices across multiple subscriptions.

**CustomerDashboard.jsx**

```javascript
import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session'; // Your custom session hook

function CustomerDashboard() {
  const { session, connect } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connect}>
      <h2>Payment Center</h2>
      <p>Please settle any outstanding payments to ensure uninterrupted service.</p>
      <OverdueInvoicePayment
        customerId={session.user.did}
        onPaid={() => {
          console.log('All customer overdue invoices paid for a currency!');
          // Refresh customer account status
        }}
      />
      {/* The rest of the customer dashboard */}
    </PaymentProvider>
  );
}
```

### 3. Custom UI Mode

For full control over the user experience, use `mode="custom"`. This allows you to integrate the payment functionality directly into your existing UI instead of using a dialog.

**CustomOverdueUI.jsx**

```javascript
import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session'; // Your custom session hook
import { Card, CardContent, Typography, Button, Stack } from '@mui/material';

function CustomOverdueUI({ subscriptionId }) {
  const { session, connect } = useSessionContext();

  // A simple Amount component for formatting
  const Amount = ({ amount, decimal, symbol }) => {
    const formattedAmount = (parseInt(amount, 10) / 10 ** (decimal || 0)).toFixed(2);
    return (
      <strong>
        {formattedAmount} {symbol}
      </strong>
    );
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      <OverdueInvoicePayment
        subscriptionId={subscriptionId}
        mode="custom"
        onPaid={() => console.log('Custom UI payment successful!')}>
        {(handlePay, { summary, invoices }) => {
          const summaryList = Object.values(summary);
          if (invoices.length === 0) {
            return <Typography>No overdue payments. All clear!</Typography>;
          }

          return (
            <Card variant="outlined">
              <CardContent>
                <Typography variant="h6" color="error" gutterBottom>
                  You have {invoices.length} overdue invoice(s).
                </Typography>
                <Stack spacing={2} mt={2}>
                  {summaryList.map(item => (
                    <Stack key={item.currency.id} direction="row" justifyContent="space-between" alignItems="center">
                      <Typography>
                        Total Due:{' '}
                        <Amount
                          amount={item.amount}
                          decimal={item.currency.decimal}
                          symbol={item.currency.symbol}
                        />
                      </Typography>
                      <Button variant="contained" color="primary" onClick={() => handlePay(item)}>
                        Pay with {item.currency.symbol}
                      </Button>
                    </Stack>
                  ))}
                </Stack>
              </CardContent>
            </Card>
          );
        }}
      </OverdueInvoicePayment>
    </PaymentProvider>
  );
}
```

![OverdueInvoicePayment](https://media.arcblock.io/lib/6b/6bf93c6c3b07bf61.w1600.webp)

---

## ResumeSubscription

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-business-resume-subscription-8b3f3d/

The `ResumeSubscription` component provides a straightforward UI for users to resume a canceled subscription. It renders a dialog that guides the user through the confirmation process and automatically handles complex scenarios like re-staking if the subscription requires it.

This component must be used within a `PaymentProvider` to access the necessary context for handling wallet interactions.

## Workflow

The following diagram illustrates the process flow when a user resumes a subscription, including the conditional logic for re-staking.

![ResumeSubscription](https://media.arcblock.io/lib/b1/b11b0cdb89a8aee2.w1600.webp)

## Props

| Prop  | Type  | Required  | Description  |
|---|---|---|---|
| `subscriptionId`  | `string`  | Yes  | The unique identifier of the subscription to be resumed.  |
| `onResumed`  | `(subscription: Subscription) => void`  | No  | A callback function that is triggered after the subscription is successfully resumed. It receives the updated subscription object as an argument.  |
| `dialogProps`  | `object`  | No  | Props to customize the underlying Material-UI Dialog. You can control its state (`open`, `onClose`) and appearance (`title`).  |
| `successToast`  | `boolean`  | No  | If `true`, a success notification toast is displayed upon successful resumption. Defaults to `true`.  |
| `authToken`  | `string`  | No  | An optional authentication token for API requests. This is useful for cross-origin or server-to-server integration scenarios.  |

## Usage Examples

### Basic Usage

This is the simplest way to use the component. It will render an open dialog by default.

**Basic ResumeSubscription Example**

```tsx
import { ResumeSubscription } from '@blocklet/payment-react';

function ResumePage({ subscriptionId }) {
  // This component must be rendered within a PaymentProvider
  return <ResumeSubscription subscriptionId={subscriptionId} />;
}
```

### Handling the Result

Use the `onResumed` callback to receive the updated subscription data and refresh your application's state.

**Handling the onResumed Callback**

```tsx
import { ResumeSubscription } from '@blocklet/payment-react';
import { useState } from 'react';

function SubscriptionDetails({ initialSubscription }) {
  const [subscription, setSubscription] = useState(initialSubscription);

  const handleSubscriptionResumed = (updatedSubscription) => {
    console.log('Subscription has been successfully resumed:', updatedSubscription);
    setSubscription(updatedSubscription);
    // You can also show a confirmation message or redirect the user.
  };

  return (
    <div>
      {/* Display subscription details based on the `subscription` state */}
      <ResumeSubscription
        subscriptionId={subscription.id}
        onResumed={handleSubscriptionResumed}
      />
    </div>
  );
}
```

### Controlling the Dialog

For a more practical integration, control the dialog's visibility from a parent component. This allows you to open it in response to a user action, like clicking a button.

**Triggering ResumeSubscription with a Button**

```tsx
import { ResumeSubscription } from '@blocklet/payment-react';
import { useState } from 'react';
import { Button } from '@mui/material';

function SubscriptionActions({ subscriptionId }) {
  const [isModalOpen, setIsModalOpen] = useState(false);

  const handleResumed = () => {
    setIsModalOpen(false);
    // Refetch subscription data to update UI
    alert('Subscription resumed!');
  };

  return (
    <>
      <Button variant="contained" onClick={() => setIsModalOpen(true)}>
        Resume Subscription
      </Button>

      {isModalOpen && (
        <ResumeSubscription
          subscriptionId={subscriptionId}
          onResumed={handleResumed}
          dialogProps={{
            open: isModalOpen,
            title: 'Confirm Subscription Renewal',
            onClose: () => setIsModalOpen(false),
          }}
        />
      )}
    </>
  );
}
```

## Full Integration Example

Here is a complete example showing how to integrate `ResumeSubscription` within the required `PaymentProvider`.

**Complete Integration Example**

```tsx
import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
import { useSessionContext } from 'path/to/your/session/context'; // Your app's session context
import { useState } from 'react';
import { Button, Card, CardContent, Typography } from '@mui/material';

function SubscriptionManagementPage({ subscription }) {
  const { session, connect } = useSessionContext();
  const [isResumeOpen, setIsResumeOpen] = useState(false);

  const handleResumed = (updatedSubscription) => {
    console.log('Subscription updated:', updatedSubscription);
    setIsResumeOpen(false);
    // Ideally, you would trigger a data refetch here to update the entire page.
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      <Card>
        <CardContent>
          <Typography variant="h5">Manage Your Subscription</Typography>
          <Typography color="text.secondary">Status: {subscription.status}</Typography>

          {subscription.status === 'canceled' && (
            <Button
              variant="contained"
              color="primary"
              sx={{ mt: 2 }}
              onClick={() => setIsResumeOpen(true)}>
              Resume Subscription
            </Button>
          )}
        </CardContent>
      </Card>

      {isResumeOpen && (
        <ResumeSubscription
          subscriptionId={subscription.id}
          onResumed={handleResumed}
          dialogProps={{
            open: isResumeOpen,
            onClose: () => setIsResumeOpen(false),
          }}
        />
      )}
    </PaymentProvider>
  );
}
```

---

## Checkout Components

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-checkout-8b3f3d/

This section covers the high-level components that serve as entry points for various checkout flows. These components are designed to provide a complete, out-of-the-box experience for common payment scenarios like standard payments from a link, selecting a plan from a pricing table, or making a donation. They encapsulate the necessary logic to initiate and process payments, often leveraging the core `CheckoutForm` component internally.

### Component Relationship

The typical flow involves a user interacting with an entry-point component like `CheckoutTable` or `CheckoutDonate`. These components handle the initial user interaction (e.g., selecting a subscription plan) and then create a `CheckoutSession`. Once the session is ready, they delegate the final payment processing to the `CheckoutForm`, which renders the actual payment interface.

The following diagram illustrates this component relationship:

DIAGRAM_PLACEHOLDER

This modular design allows for both flexibility and ease of use. You can quickly implement a complete payment workflow with a single component or compose them for more complex scenarios.

For more detailed information on each component, including props and usage examples, please refer to their respective documentation pages.

::::card-group
::link-card{title="CheckoutForm" description="The primary component for handling payment links and checkout sessions. It supports various display modes, including inline, standalone, and popup." icon="credit-card" href="/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/"}
::link-card{title="CheckoutTable" description="Renders a complete pricing table and manages the checkout flow when a user selects a plan, automatically creating a session and displaying the payment form." icon="table-2" href="/en/docs/payment-kit-react/components-checkout-checkout-table-8b3f3d/"}
::link-card{title="CheckoutDonate" description="Implements donation functionality with flexible options for display modes, supporter history, and customization, guiding the user through the donation process." icon="heart" href="/en/docs/payment-kit-react/components-checkout-checkout-donate-8b3f3d/"}
::::

---

## CheckoutDonate

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-checkout-checkout-donate-8b3f3d/

This document provides a detailed guide to implementing the `CheckoutDonate` component, a flexible solution for adding donation functionality to your application. By following these steps, you will learn how to configure the component, set up the required providers, and utilize its various display modes to create a seamless donation experience.

The `CheckoutDonate` component is designed to be highly customizable, supporting everything from a simple donation button to a fully bespoke user interface. It must be wrapped within both a `PaymentProvider` and a `DonateProvider` to manage state and connect to the payment backend.

## Provider Setup

Correctly setting up the `PaymentProvider` and `DonateProvider` is a prerequisite for using `CheckoutDonate`. The `PaymentProvider` handles the connection to the payment service, while the `DonateProvider` manages the configuration and state for donation instances within a specific part of your application.

The following diagram illustrates how these providers wrap the `CheckoutDonate` component and interact with the payment backend and your application's session context.

![CheckoutDonate](https://media.arcblock.io/lib/b2/b293a397a0f3e75d.w1600.webp)

The example below demonstrates the required provider structure. The `DonateProvider` is configured with a unique `mountLocation` to distinguish this donation context from others in your application.

**ProviderSetup.jsx**

```javascript
import {
  PaymentProvider,
  DonateProvider,
  CheckoutDonate,
} from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context'; // This is your app's session context hook

function DonationSection() {
  const { session, connectApi } = useSessionContext();

  if (!session) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <DonateProvider
        mountLocation="blog-post-donations"
        description="Handles all donations for blog posts"
        defaultSettings={{
          btnText: 'Support Me',
          historyType: 'avatar',
        }}>
        <CheckoutDonate
          settings={{
            target: 'post-123',
            title: 'Support the Author',
            description: 'If you found this article helpful, consider a small donation.',
            reference: 'https://example.com/posts/123',
            beneficiaries: [
              {
                address: 'z2qa...gCLd', // Author's DID address
                share: '100',
              },
            ],
          }}
        />
      </DonateProvider>
    </PaymentProvider>
  );
}
```

For a more in-depth explanation of its props and functionality, please refer to the [DonateProvider documentation](/en/docs/payment-kit-react/providers-donate-provider-8b3f3d/).

## Component Props

The `CheckoutDonate` component accepts several props to control its behavior and appearance.

- **settings** `CheckoutDonateSettings` *(required)* — Configuration object for this specific donation instance. See the CheckoutDonateSettings section below for details.
- **onPaid** `(session: TCheckoutSessionExpanded) => void` — Callback function executed after a successful donation. It receives the checkout session details as an argument.
- **onError** `(error: Error) => void` — Callback function executed if an error occurs during the payment process.
- **mode** `'default' | 'inline' | 'custom'` (default: `default`) — Specifies the rendering mode. 'default' shows a button and supporter list. 'inline' shows a button that opens a popover. 'custom' uses a render prop for a completely custom UI.
- **inlineOptions** `object` — Configuration options specific to the 'inline' mode.
  - **button** `ButtonType` — Custom properties for the inline button, such as text and icon.
- **livemode** `boolean` — Overrides the livemode setting from PaymentProvider. Set to true for live transactions or false for test transactions.
- **timeout** `number` (default: `5000`) — The delay in milliseconds before the donation dialog closes automatically after a successful payment.
- **theme** `'default' | 'inherit' | PaymentThemeOptions` (default: `default`) — Controls the component's styling. See the Theming guide for more information.
- **children** `function` — A render prop function used only when mode is set to 'custom'. See the Custom UI Mode example for the function signature.

### CheckoutDonateSettings

This object is passed to the `settings` prop and defines the core details of the donation target.

- **target** `string` *(required)* — A unique identifier for the donation target, such as a post ID or project name. This is used to group donations.
- **title** `string` *(required)* — The title displayed at the top of the donation dialog.
- **description** `string` *(required)* — A brief description of the donation's purpose, shown in the dialog.
- **reference** `string` *(required)* — A URL related to the donation target, used for record-keeping and context.
- **beneficiaries** `PaymentBeneficiary[]` *(required)* — An array of objects defining the fund recipients. Each object must include an address (recipient's DID) and a share (percentage).
- **amount** `object` — Configures the donation amounts. If not provided, it falls back to settings from DonateProvider or a system default.
  - **presets** `string[]` — An array of suggested donation amounts (e.g., ['1', '5', '10']).
  - **preset** `string` — The default selected amount from the presets.
  - **minimum** `string` — The minimum allowed donation amount.
  - **maximum** `string` — The maximum allowed donation amount.
  - **custom** `boolean` — Determines if users can enter a custom donation amount.
- **appearance** `object` — Customizes the component's visual elements.
  - **button** `object` — Customizes the donation button's `text`, `icon`, `size`, `color`, and `variant`.
  - **history** `object` — Configures the appearance of the supporter history list. Set `variant` to 'avatar' or 'table'.

## Usage Examples

### Default Mode

The default mode is the most straightforward implementation. It renders a donation button and a list of recent supporters. Clicking the button opens a dialog where the user can complete the donation.

**DefaultMode.jsx**

```javascript
import {
  PaymentProvider,
  DonateProvider,
  CheckoutDonate,
} from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context';

function App() {
  const { session, connectApi } = useSessionContext();

  if (!session) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <DonateProvider
        mountLocation="blog-post-donations"
        description="Donations for the main blog"
        defaultSettings={{
          btnText: 'Buy me a coffee',
          historyType: 'avatar',
        }}>
        <CheckoutDonate
          settings={{
            target: 'post-123',
            title: 'Support the Author',
            description: 'If you found this article helpful, consider a small donation.',
            reference: 'https://example.com/posts/123',
            beneficiaries: [
              {
                address: 'z2qa...gCLd', // Author's DID address
                share: '100',
              },
            ],
          }}
          onPaid={() => {
            alert('Thank you for your donation!');
          }}
        />
      </DonateProvider>
    </PaymentProvider>
  );
}
```

### Custom UI Mode

For complete control over the layout and presentation, use `mode="custom"`. This mode utilizes a render prop passed as the component's `children`. The function provides access to the donation state and methods, allowing you to build a unique user experience.

**CustomMode.jsx**

```javascript
import {
  PaymentProvider,
  DonateProvider,
  CheckoutDonate,
} from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context';
import { CircularProgress, Button, Avatar, Box, Typography } from '@mui/material';

function CustomDonationDisplay() {
  const { session, connectApi } = useSessionContext();

  if (!session) {
    return <div>Loading session...</div>;
  }

  const donateSettings = {
    target: 'project-alpha',
    title: 'Support Project Alpha',
    description: 'Help us build the next generation of tools.',
    reference: 'https://example.com/projects/alpha',
    beneficiaries: [
      {
        address: 'z2qa...gCLd',
        share: '100',
      },
    ],
  };

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <DonateProvider
        mountLocation="project-alpha-donations"
        description="Donations for Project Alpha">
        <CheckoutDonate mode="custom" settings={donateSettings}>
          {(openDonate, totalAmount, supporters, loading, settings) => (
            <Box sx={{ border: '1px solid #e0e0e0', padding: '24px', borderRadius: '8px', textAlign: 'center' }}>
              <Typography variant="h5">Our Supporters</Typography>
              <Typography variant="body1" color="text.secondary" sx={{ mb: 2 }}>
                Total Donated: <strong>{totalAmount}</strong>
              </Typography>
              <Button variant="contained" size="large" onClick={openDonate}>
                {settings?.appearance?.button?.text || 'Donate Now'}
              </Button>
              {loading && <CircularProgress sx={{ display: 'block', margin: '16px auto' }} />}
              {!loading && (supporters.supporters || []).length > 0 && (
                <Box sx={{ mt: 3 }}>
                  {(supporters.supporters || []).slice(0, 5).map((supporter) => (
                    <Box key={supporter.id} sx={{ display: 'flex', alignItems: 'center', mb: 1 }}>
                      <Avatar src={supporter.customer?.avatar} sx={{ width: 24, height: 24, mr: 1 }} />
                      <Typography variant="body2">{supporter.customer?.name}</Typography>
                    </Box>
                  ))}
                </Box>
              )}
            </Box>
          )}
        </CheckoutDonate>
      </DonateProvider>
    </PaymentProvider>
  );
}
```

#### Custom Render Prop Arguments

The `children` function provides the following arguments:

- `openDonate()`: A function to programmatically open the donation dialog.
- `donateTotalAmount`: A formatted string representing the total amount donated (e.g., `"125.00 T"`).
- `supporters`: A `DonateHistory` object containing the `supporters` array, total amount, currency, and method details.
- `loading`: A boolean that is `true` while supporter data is being fetched.
- `donateSettings`: The final, resolved donation settings, merged from `DonateProvider` and the component's `settings` prop.

---

## CheckoutForm

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/

The `CheckoutForm` component is the primary entry point for handling payment links and checkout sessions. It serves as a high-level wrapper that automatically fetches the necessary data based on a provided ID and renders the appropriate payment or donation interface. This component provides the most straightforward method for integrating a complete checkout flow into your application.

For the `CheckoutForm` to function correctly, it must be nested within a `PaymentProvider`. This provider supplies the necessary context, such as session information and API configuration. For detailed setup instructions, please refer to the [PaymentProvider documentation](/en/docs/payment-kit-react/providers-payment-provider-8b3f3d/).

## How It Works

The component manages the entire checkout process through a clear, sequential flow:

::::steps
:::step{title="Initialization"}
The component is mounted with an `id` prop, which must be either a `paymentLink` ID (prefixed with `plink_`) or a `checkoutSession` ID (prefixed with `cs_`).
:::

:::step{title="Data Fetching"}
It sends a request to the payment backend to retrieve the complete checkout context, which includes available payment methods, line items, and customer details.
:::

:::step{title="UI Rendering"}
Based on the `formType` prop, it internally renders either the standard `Payment` component for purchases or the specialized `DonationForm` for contributions.
:::

:::step{title="State Management"}
It handles the full lifecycle of the transaction, managing loading states, completion status, and any potential errors.
:::
::::

## Props

The `CheckoutForm` component is configured using the following properties.

- **id** `string` *(required)* — The unique identifier for the payment link (plink_...) or checkout session (cs_...).
- **mode** `'standalone' | 'inline' | 'popup' | 'inline-minimal' | 'popup-minimal'` (default: `inline`) — Defines the rendering mode. 'standalone' creates a full-page view, while 'inline' embeds the form within an existing container. The -minimal variants hide the order summary.
- **formType** `'payment' | 'donation'` (default: `payment`) — Specifies the type of form to render. Use 'donation' to activate the specialized donation user interface.
- **onPaid** `(res: CheckoutContext) => void` — A callback function that is executed upon successful payment completion. It receives the final checkout context as an argument.
- **onError** `(err: Error) => void` (default: `console.error`) — A callback function that is executed if an error occurs during the checkout process.
- **onChange** `(data: CheckoutFormData) => void` — A callback function that fires whenever a value in the payment form changes.
- **goBack** `() => void` — If provided, a back button is rendered. This function is called when the button is clicked.
- **extraParams** `Record<string, any>` (default: `{}`) — An object containing extra parameters to be appended to the URL when initiating a checkout session from a payment link.
- **theme** `'default' | 'inherit' | PaymentThemeOptions` (default: `default`) — Controls the component's theme. 'inherit' uses the parent theme, while 'default' applies the library's standard theme. A custom theme object can also be provided.
- **action** `string` (default: `''`) — A string identifier used for customizing UI elements, such as button text, or for tracking specific analytics events.

## Usage Examples

### Basic Inline Payment Form

This is the most common use case, where the payment form is embedded directly into a page of your application. The component handles all data fetching and state management internally.

**MyStorePage.jsx**

```javascript
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context'; // This is an example hook from your application

export default function MyStorePage() {
  const { session, connectApi } = useSessionContext();

  const handlePaymentSuccess = (result) => {
    console.log('Payment successful!', result);
    alert('Thank you for your purchase!');
  };

  const handlePaymentError = (error) => {
    console.error('Payment failed:', error);
    alert('Sorry, your payment could not be processed.');
  };

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ maxWidth: '960px', margin: '0 auto' }}>
        <h1>Checkout</h1>
        <CheckoutForm
          id="plink_xxxxxxxxxxxxxx" // Replace with your Payment Link ID
          mode="inline"
          onPaid={handlePaymentSuccess}
          onError={handlePaymentError}
        />
      </div>
    </PaymentProvider>
  );
}
```

### Standalone Full-Page Checkout

Use `mode="standalone"` to render a dedicated, full-page checkout experience. This mode is ideal for redirecting the user to a separate URL to complete their payment without distractions.

**CheckoutPage.jsx**

```javascript
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';

export default function CheckoutPage() {
  const { session, connectApi } = useSessionContext();

  // In a real application, you would get this ID from the URL parameters
  const paymentLinkId = 'plink_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <CheckoutForm
        id={paymentLinkId}
        mode="standalone"
        onPaid={() => {
          // Redirect to a success page
          window.location.href = '/payment-success';
        }}
      />
    </PaymentProvider>
  );
}
```

### Donation Form

By setting `formType="donation"`, the component renders a specialized UI tailored for donation campaigns. This form includes features such as amount presets and can display information about the benefits of donating.

**DonationPage.jsx**

```javascript
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';

export default function DonationPage() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ padding: '2rem', textAlign: 'center' }}>
        <h2>Support Our Cause</h2>
        <CheckoutForm
          id="plink_yyyyyyyyyyyyyy" // Replace with your Donation Link ID
          formType="donation"
          onPaid={() => alert('Thank you for your generous donation!')}
        />
      </div>
    </PaymentProvider>
  );
}
```

---

## CheckoutTable

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-checkout-checkout-table-8b3f3d/

The `CheckoutTable` component provides a complete, out-of-the-box solution for subscription checkouts. It fetches and renders a pricing table, allows users to select a plan, and then seamlessly transitions them to a payment form to complete the purchase. This high-level component is the fastest way to integrate a plan-based payment flow into your application.

It internally uses the [`PricingTable`](/en/docs/payment-kit-react/components-ui-pricing-table-8b3f3d/) component to display the plans and the [`CheckoutForm`](/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/) component to process the payment.

## How it Works

The checkout flow managed by `CheckoutTable` is straightforward. The following diagram illustrates the sequence of events from displaying plans to finalizing the transaction:

![CheckoutTable](https://media.arcblock.io/lib/81/810966fafe40d22e.w1600.webp)

::::steps
:::step{title="Fetch Data"}
The component fetches the pricing table configuration from the server using the provided `id`.
:::

:::step{title="Display Plans"}
It renders the subscription plans in a responsive table, allowing users to switch between billing intervals (e.g., monthly/yearly) and currencies.
:::

:::step{title="Create Session"}
When a user selects a plan, the component communicates with the backend to create a secure checkout session.
:::

:::step{title="Process Payment"}
It then displays the `CheckoutForm`, pre-filled with the session details, allowing the user to enter their payment information and finalize the transaction.
:::
::::

## Props

The `CheckoutTable` component accepts the following props to customize its behavior and handle events.

- **id** `string` *(required)* — The ID of the pricing table to display. This value must be prefixed with prctbl_.
- **mode** `'standalone' | 'embedded'` (default: `embedded`) — The display mode. In 'standalone' mode, the user is redirected to a separate hosted page upon selecting a plan. In 'embedded' mode, the entire checkout flow occurs inline within the component.
- **onPaid** `(sessionId: string) => void` — A callback function that is triggered when a payment is successfully completed. It receives the sessionId of the transaction.
- **onError** `(error: Error) => void` — A callback function for handling any errors that occur during the checkout process.
- **onChange** `(data: any) => void` — A callback function that is triggered for any state change within the underlying CheckoutForm component.
- **extraParams** `Record<string, any>` — An object containing extra parameters to be sent to the server when creating the checkout session. This is useful for passing custom data, such as a user ID or tracking information.
- **goBack** `() => void` — A function to handle the back action from the payment form, which returns the user to the pricing table view. The component manages the UI transition; this callback is for synchronizing external application state.
- **theme** `object | 'inherit'` — A custom Material-UI theme object to style the component, or 'inherit' to use the ambient theme. For more details, see the Theming guide.

## Usage

To use the `CheckoutTable` component, you must wrap it in a `PaymentProvider`. Pass the pricing table `id` and an `onPaid` callback to handle successful transactions.

**MyCheckoutPage.jsx**

```javascript
import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
import { useSessionContext } from './path-to-your-session-context'; // Centralize this context as per guidelines

export default function MyCheckoutPage() {
  const { session, connectApi } = useSessionContext();

  const handlePaymentSuccess = (sessionId) => {
    console.log(`Payment successful for session: ${sessionId}`);
    alert('Thank you for your subscription!');
  };

  if (!session) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ height: '700px', width: '100%' }}>
        <CheckoutTable
          id="prctbl_z2v5NvY3tYjH2zK8yL9xP6" // Replace with your actual pricing table ID
          onPaid={handlePaymentSuccess}
        />
      </div>
    </PaymentProvider>
  );
}
```

## Modes of Operation

### Embedded Mode (Default)

By default, `CheckoutTable` operates in `'embedded'` mode. The component manages the entire flow inline, transitioning from the pricing table view to the payment form within its own container. This is ideal for single-page applications where you want the checkout to feel like an integrated part of the page.

### Standalone Mode

By setting `mode='standalone'`, the component's behavior changes. When a user selects a plan, they are redirected to a dedicated, hosted checkout page. This mode is useful for simpler integrations that don't require an embedded payment form.

**StandaloneMode.jsx**

```javascript
import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
import { useSessionContext } from './path-to-your-session-context';

export default function StandaloneCheckout() {
  const { session, connectApi } = useSessionContext();

  if (!session) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <CheckoutTable
        id="prctbl_z2v5NvY3tYjH2zK8yL9xP6"
        mode="standalone"
      />
    </PaymentProvider>
  );
}
```

## Advanced Usage

### Handling Back Navigation

The `goBack` prop allows you to define custom logic for when the user navigates back from the payment form to the pricing table. The component handles the view transition automatically, but this callback is useful for synchronizing your application's state.

**GoBackExample.jsx**

```javascript
import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
import { useSessionContext } from './path-to-your-session-context';
import { useState } from 'react';

export default function CheckoutWithBackNavigation() {
  const { session, connectApi } = useSessionContext();
  const [view, setView] = useState('pricing');

  const handleGoBack = () => {
    console.log('User returned to the pricing table.');
    setView('pricing');
  };

  if (!session) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ height: '700px', width: '100%' }}>
        <CheckoutTable
          id="prctbl_z2v5NvY3tYjH2zK8yL9xP6"
          onPaid={() => alert('Payment successful!')}
          goBack={handleGoBack}
          onChange={() => setView('payment')}
        />
      </div>
    </PaymentProvider>
  );
}
```

### Passing Extra Parameters

Use the `extraParams` prop to send additional data when creating the checkout session. This data can be associated with the resulting payment and is useful for tracking and reconciliation on your backend.

**ExtraParamsExample.jsx**

```javascript
import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
import { useSessionContext } from './path-to-your-session-context';

export default function CheckoutWithExtraParams() {
  const { session, connectApi } = useSessionContext();

  if (!session) {
    return <div>Loading session...</div>;
  }

  const user = { id: 'user_12345' }; // Example user object

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ height: '700px', width: '100%' }}>
        <CheckoutTable
          id="prctbl_z2v5NvY3tYjH2zK8yL9xP6"
          onPaid={() => alert('Payment successful!')}
          extraParams={{ userId: user.id, source: 'marketing_campaign' }}
        />
      </div>
    </PaymentProvider>
  );
}
```

## Customization

While `CheckoutTable` is a high-level component designed for ease of use, you can achieve more granular control by using its constituent parts. For a fully custom UI, you can use the [`PricingTable`](/en/docs/payment-kit-react/components-ui-pricing-table-8b3f3d/) component to display plans and then manually trigger a checkout session that renders in a [`CheckoutForm`](/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/).

---

## History Components

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-history-8b3f3d/

The `@blocklet/payment-react` library provides a suite of history components designed to give your users a clear and detailed view of their past activities. These components are essential for building customer portals, account dashboards, and administrative interfaces where users need to track their billing, payments, and credit usage.

These components fetch and display data directly from the payment service, offering a seamless way to present historical information without needing to build complex data-fetching and rendering logic from scratch.

::::card-group
::link-card{title="CustomerInvoiceList" description="Render a list or table of a customer's invoices, including details on status, amount, and creation date." icon="receipt" href="/en/docs/payment-kit-react/components-history-invoice-list-8b3f3d/"}
::link-card{title="CustomerPaymentList" description="Display a customer's complete payment history, including transaction details, payment method, and status." icon="credit-card" href="/en/docs/payment-kit-react/components-history-payment-list-8b3f3d/"}
::link-card{title="CreditGrantsList" description="Show a list of all credit grants for a customer, detailing the status, remaining amount, and effective dates." icon="award" href="/en/docs/payment-kit-react/components-history-credit-grants-list-8b3f3d/"}
::link-card{title="CreditTransactionsList" description="List all individual credit transactions, providing a detailed log of credit usage and adjustments over time." icon="clock" href="/en/docs/payment-kit-react/components-history-credit-transactions-list-8b3f3d/"}
::::

## Common Use Case

A typical use case is to create a "Billing History" section in a user's account page. You can use a tabbed interface to switch between different history views, such as Invoices, Payments, and Credits.

Below is a conceptual example of how you might structure such a page.

**MyBillingPage.tsx**

```jsx
import React from 'react';
import { CustomerInvoiceList, CustomerPaymentList } from '@blocklet/payment-react';

// Assume you have the customer's ID from your session or context
const customerId = 'cus_xxxxxxxxxxxxxx';

export default function MyBillingPage() {
  // In a real application, you would use state to manage the active tab
  const [activeTab, setActiveTab] = React.useState('invoices');

  return (
    <div>
      <h1>Billing History</h1>
      <nav>
        <button onClick={() => setActiveTab('invoices')}>Invoices</button>
        <button onClick={() => setActiveTab('payments')}>Payments</button>
      </nav>

      <div style={{ marginTop: '20px' }}>
        {activeTab === 'invoices' && (
          <CustomerInvoiceList
            customer_id={customerId}
            type="table"
          />
        )}
        {activeTab === 'payments' && (
          <CustomerPaymentList
            customer_id={customerId}
          />
        )}
      </div>
    </div>
  );
}
```

This example demonstrates how you can easily embed the history components to provide comprehensive, self-service billing information to your users. Each component handles its own data fetching, pagination, and display logic.

Explore the detailed documentation for each component to understand its specific props and customization options.

---

## CreditGrantsList

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-history-credit-grants-list-8b3f3d/

The `CreditGrantsList` component renders a paginated table displaying a customer's credit grants. It provides a clear overview of each grant's status, remaining balance, scope, and validity period.

This component is essential for both customer-facing portals where users can track their available credits and admin dashboards for managing customer grants. It must be used within a `PaymentProvider` to access the necessary session and API context.

## Props

| Prop  | Type  | Description  | Default  |
|---|---|---|---|
| `customer_id`  | `string`  | Optional. The ID of the customer. If omitted, it defaults to the DID of the currently authenticated user from the session context.  | `session.user.did`  |
| `subscription_id`  | `string`  | Optional. Filters the list to show only grants associated with a specific subscription.  | `''`  |
| `status`  | `string`  | Optional. A comma-separated string of statuses to filter by. Valid statuses include `granted`, `pending`, `expired`, `depleted`, and `voided`.  | `'granted,pending,depleted,expired'`  |
| `pageSize`  | `number`  | Optional. The number of items to display per page.  | `10`  |
| `onTableDataChange`  | `(data, prevData) => void`  | Optional. A callback function that is invoked whenever the table data is fetched or updated.  | `() => {}`  |
| `mode`  | `'dashboard' \| 'portal'`  | Optional. Determines the navigation behavior when a row is clicked. Use `'portal'` for customer-facing views and `'dashboard'` for admin panels, which generates different link paths.  | `'portal'`  |

## Usage

### Basic Usage (For Logged-in Customer)

By default, the `CreditGrantsList` component fetches and displays the credit grants for the currently authenticated user. This is the most common use case for a customer's account page.

**My Credit Grants**

```jsx
import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '/path/to/your/session/context'; // Adjust this import path

function MyCreditGrantsPage() {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h2>My Credit Grants</h2>
      <CreditGrantsList />
    </PaymentProvider>
  );
}
```

### Admin or Dashboard Usage

In an administrative dashboard, you can display the credit grants for any customer by providing the `customer_id` prop. You can also customize the filters and page size.

**Customer Credit Grants**

```jsx
import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '/path/to/your/session/context'; // Adjust this import path

function CustomerDetailsPage({ customerId }) {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h3>Active Credit Grants for Customer</h3>
      <CreditGrantsList
        customer_id={customerId}
        status="granted,pending"
        pageSize={5}
        mode="dashboard"
      />
    </PaymentProvider>
  );
}
```

This example shows how to list only the 'granted' and 'pending' grants for a specific customer, displaying 5 items per page. The `mode="dashboard"` ensures that clicking a grant will navigate to an admin-specific URL.

---

## CreditTransactionsList

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-history-credit-transactions-list-8b3f3d/

The `CreditTransactionsList` component renders a detailed and paginated table of all credit transactions, providing a clear log of credit usage and adjustments. It is ideal for use in customer portals or administrative dashboards to track how credits are granted and consumed.

This component automatically handles data fetching, pagination, and formatting, offering a straightforward way to display transaction history.

## Props

| Prop  | Type  | Description  | Default  |
|---|---|---|---|
| `customer_id`  | `string`  | The ID of the customer whose transactions are to be displayed. If not provided, it defaults to the DID of the currently logged-in user from the `PaymentProvider` context.  | `session.user.did`  |
| `subscription_id`  | `string`  | Filters the transactions to a specific subscription.  | `undefined`  |
| `credit_grant_id`  | `string`  | Filters the transactions to a specific credit grant.  | `undefined`  |
| `pageSize`  | `number`  | The number of transactions to display per page.  | `10`  |
| `onTableDataChange`  | `(data, prevData) => void`  | A callback function that is triggered when the table data is fetched or updated.  | `() => {}`  |
| `showAdminColumns`  | `boolean`  | If `true` and the user is an admin, additional columns like 'Meter Event' are shown.  | `false`  |
| `showTimeFilter`  | `boolean`  | If `true`, a date range picker is displayed to allow filtering transactions by date.  | `false`  |
| `source`  | `string`  | An optional source string to filter transactions.  | `''`  |
| `mode`  | `'dashboard' \| 'portal'`  | Determines the link structure for related items like credit grants. Use `'dashboard'` for admin views and `'portal'` for customer-facing views.  | `'portal'`  |

## Basic Usage for a Customer Portal

This example shows how to display the credit transaction history for the currently logged-in user. The component automatically uses the user's DID from the `PaymentProvider` context when `customer_id` is omitted.

**MyCreditHistoryPage.tsx**

```jsx
import React from 'react';
import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context'; // Your session context hook

function MyCreditHistoryPage() {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h2>My Credit Transactions</h2>
      <CreditTransactionsList />
    </PaymentProvider>
  );
}

export default MyCreditHistoryPage;
```

## Admin View with Filtering

For an admin dashboard, you can pass a specific `customer_id` and enable admin columns and time filters to provide a more powerful and detailed view of a user's transaction history.

**CustomerDetailsPage.tsx**

```jsx
import React from 'react';
import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context'; // Your session context hook

function CustomerDetailsPage({ customerId }) {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h3>Transaction History for {customerId}</h3>
      <CreditTransactionsList
        customer_id={customerId}
        showAdminColumns={true}
        showTimeFilter={true}
        pageSize={20}
        mode="dashboard"
      />
    </PaymentProvider>
  );
}

export default CustomerDetailsPage;
```

## Displaying Transactions for a Specific Credit Grant

To show a detailed log of how a particular credit grant was consumed, pass the `credit_grant_id`. This is useful for pages that show the details of a single credit grant.

**CreditGrantDetailsPage.tsx**

```jsx
import React from 'react';
import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context'; // Your session context hook

function CreditGrantDetailsPage({ grantId }) {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h4>Usage Details for Grant {grantId}</h4>
      <CreditTransactionsList credit_grant_id={grantId} />
    </PaymentProvider>
  );
}

export default CreditGrantDetailsPage;
```

---

## CustomerInvoiceList

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-history-invoice-list-8b3f3d/

The `CustomerInvoiceList` component is designed to render a customer's invoice history. It fetches and displays invoice data from the payment service, offering two distinct layouts: a simple, date-grouped list with infinite scroll, and a detailed, paginated table. This component must be used within a `PaymentProvider` to function correctly.

## Props

| Prop  | Type  | Description  | Default  |
|---|---|---|---|
| `customer_id`  | `string`  | The ID of the customer whose invoices are to be displayed.  | `''`  |
| `subscription_id`  | `string`  | Filter invoices by a specific subscription ID.  | `''`  |
| `currency_id`  | `string`  | Filter invoices by a specific currency ID.  | `''`  |
| `include_staking`  | `boolean`  | If `true`, includes staking-related invoices in the list.  | `false`  |
| `include_return_staking`  | `boolean`  | If `true`, includes return staking invoices.  | `false`  |
| `include_recovered_from`  | `boolean`  | If `true`, includes invoices that were recovered from a previous balance.  | `false`  |
| `status`  | `string`  | A comma-separated string of invoice statuses to display (e.g., `'open,paid,uncollectible'`).  | `'open,paid,uncollectible'`  |
| `pageSize`  | `number`  | The number of invoices to fetch per page.  | `10`  |
| `target`  | `string`  | The target attribute for invoice links (e.g., `'_self'`, `'_blank'`).  | `'_self'`  |
| `action`  | `string`  | Defines a call-to-action for certain invoices. Set to `'pay'` to show a pay button for open invoices.  | `''`  |
| `type`  | `'list' \| 'table'`  | The display mode for the invoice list.  | `'list'`  |
| `onTableDataChange`  | `Function`  | A callback function that is triggered when the invoice data changes.  | `() => {}`  |
| `relatedSubscription`  | `boolean`  | In `table` mode, if `true`, shows a column with a link to the related subscription.  | `false`  |

## Basic Usage (List View)

The default view (`type="list"`) renders a simple list of invoices, grouped by date, with an infinite scroll mechanism to load more items.

**CustomerInvoiceListPage.tsx**

```tsx
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryPage() {
  // Assuming customerId is available, e.g., from session or props
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList customer_id={customerId} />
    </PaymentProvider>
  );
}
```

## Table View

For a more detailed and structured presentation, you can set `type="table"`. This mode displays invoices in a paginated table with sortable columns.

**CustomerInvoiceTablePage.tsx**

```tsx
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryTable() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        relatedSubscription={true} // Show a column for the related subscription
        pageSize={5}
      />
    </PaymentProvider>
  );
}
```

In this example, the `relatedSubscription` prop is enabled to add a column that links directly to the subscription associated with each invoice, which is useful for subscription-based services.

## Filtering Invoices

You can use various props to filter the invoices displayed. For example, to show only paid invoices related to staking:

**FilteredInvoiceListPage.tsx**

```tsx
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function FilteredInvoiceList() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        status="paid" // Only show paid invoices
        include_staking={true} // Also include staking transactions
      />
    </PaymentProvider>
  );
}
```

## Enabling Payments for Open Invoices

By setting the `action` prop to `'pay'`, you can add a "Pay" button to any invoices with `open` or `uncollectible` status. Clicking this button will initiate the payment flow using the `connect` instance from `PaymentProvider`.

**PayableInvoiceListPage.tsx**

```tsx
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function PayableInvoiceList() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        status="open,uncollectible" // Show only invoices that need payment
        action="pay" // Add a "Pay" button
      />
    </PaymentProvider>
  );
}
```

---

## CustomerPaymentList

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-history-payment-list-8b3f3d/

The `CustomerPaymentList` component renders a detailed history of a customer's payments. It automatically handles fetching, pagination via infinite scroll, and grouping of payments by date, providing a clear and organized view of a user's transaction history.

This component is ideal for user dashboards or account pages where customers need to review their past transactions.

## Props

| Prop  | Type  | Required  | Description  |
|---|---|---|---|
| `customer_id`  | `string`  | Yes  | The unique identifier for the customer (e.g., the user's DID) whose payment history you want to display.  |

## Usage Example

To use the `CustomerPaymentList`, you must wrap it in a `PaymentProvider` and provide the required `customer_id`.

**Customer Payment History**

```tsx
import { PaymentProvider, CustomerPaymentList } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/useSessionContext'; // Adjust path to your session context hook

export default function CustomerDashboard() {
  const { session, connectApi } = useSessionContext();

  // Ensure the user is logged in to get their DID
  if (!session?.user?.did) {
    return <div>Please log in to view your payment history.</div>;
  }

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <h2>My Payment History</h2>
      <CustomerPaymentList customer_id={session.user.did} />
    </PaymentProvider>
  );
}
```

## Features

- <strong>Automatic Data Fetching</strong>: The component fetches payment intents from the API endpoint `/api/payment-intents`.
- <strong>Infinite Scroll</strong>: It automatically loads more payments as the user requests them, ensuring efficient data handling for long payment histories.
- <strong>Date Grouping</strong>: Payments are visually grouped by date, making the list easy to scan.
- <strong>Detailed Information</strong>: For each payment, it displays the creation time, amount, status, description, and a link to the blockchain transaction if available.
- <strong>Loading and Empty States</strong>: It includes a loading indicator during data fetching and displays a user-friendly message if the customer has no payment history.

---

## UI Components

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-8b3f3d/

The `@blocklet/payment-react` library provides a set of granular UI Components designed to give you maximum flexibility when building your payment and checkout interfaces. Unlike the high-level [Checkout Components](/en/docs/payment-kit-react/components-checkout-8b3f3d/), which encapsulate entire flows, these components are the building blocks for creating a custom user experience.

These components are ideal when you need to integrate payment functionality into an existing application layout or when the standard checkout flows do not meet your specific design requirements.

::::card-group
::link-card{title="PricingTable" description="Display subscription plans and pricing options in a structured table, allowing users to select a plan and proceed to checkout." icon="list" href="/en/docs/payment-kit-react/components-ui-pricing-table-8b3f3d/"}
::link-card{title="PaymentSummary" description="Show a detailed summary of an order, including line items, totals, and trial information within the checkout flow." icon="receipt" href="/en/docs/payment-kit-react/components-ui-payment-summary-8b3f3d/"}
::link-card{title="Form Elements" description="A collection of specialized input components for building custom payment and contact information forms, such as address, phone, and country selection." icon="edit" href="/en/docs/payment-kit-react/components-ui-form-elements-8b3f3d/"}
::::

## Composing Your Payment UI

UI Components are meant to be composed together to construct a complete payment page. Most of these components require access to the payment context for data like payment methods and settings, so they must be rendered within a `PaymentProvider`.

Below is a conceptual example of how you might combine `PricingTable` and `PaymentSummary` to create a custom checkout page.

**A Custom Checkout Page**

```jsx
import { PaymentProvider } from '@blocklet/payment-react';
import { PricingTable, PaymentSummary } from '@blocklet/payment-react/components';
// The useSessionContext hook is defined in the PaymentProvider documentation
import { useSessionContext } from '/path/to/session/context';

function CustomCheckoutPage() {
  const { session, connectApi } = useSessionContext();

  // In a real application, you would fetch this data from your backend
  const pricingData = { /* ... pricing table data object ... */ };
  const selectedItems = [ /* ... line items based on user selection ... */ ];
  const currency = { /* ... currency object ... */ };

  const handleSelect = (priceId, currencyId) => {
    console.log('User selected plan:', priceId, 'with currency:', currencyId);
    // Add the selected plan to the 'selectedItems' state and update the UI
  };

  return (
    <PaymentProvider
      apiHost={connectApi}
      sessionId={session.user?.did}
      locale="en"
    >
      <div className="checkout-container" style={{ display: 'flex', gap: '2rem' }}>
        <div className="pricing-section" style={{ flex: 2 }}>
          <h2>Choose Your Plan</h2>
          <PricingTable table={pricingData} onSelect={handleSelect} />
        </div>
        <div className="summary-section" style={{ flex: 1 }}>
          <h2>Order Summary</h2>
          <PaymentSummary items={selectedItems} currency={currency} />
        </div>
      </div>
    </PaymentProvider>
  );
}
```

In this example, `PricingTable` and `PaymentSummary` are used together on a custom page. The `PaymentProvider` wraps the entire structure, making payment settings and methods available to all child components.

## Next Steps

Now that you understand the role of UI Components, dive into the specifics of each one to start building your custom payment flow. We recommend starting with the `PricingTable`.

[Learn about the PricingTable component →](/en/docs/payment-kit-react/components-ui-pricing-table-8b3f3d/)

---

## Form Elements

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-form-elements-8b3f3d/

The `@blocklet/payment-react` library provides a collection of granular input components designed to simplify the creation of custom payment and contact information forms. These elements are built with validation and user experience in mind, integrating smoothly with `react-hook-form` to provide a robust and flexible solution for data collection.

Each component is designed to be a self-contained unit, allowing you to compose them into complex forms tailored to your specific requirements. Below is an overview of the available form elements.

::::card-group
::link-card{title="AddressForm" description="A pre-built form for collecting billing address details with country-specific validation." icon="map-pin" href="/en/docs/payment-kit-react/components-ui-form-elements-address-form-8b3f3d/"}
::link-card{title="PhoneInput" description="An international phone number input with an integrated country code selector and validation." icon="phone" href="/en/docs/payment-kit-react/components-ui-form-elements-phone-input-8b3f3d/"}
::link-card{title="CountrySelect" description="A searchable dropdown for selecting a country, complete with flags and a mobile-friendly UI." icon="globe" href="/en/docs/payment-kit-react/components-ui-form-elements-country-select-8b3f3d/"}
::link-card{title="CurrencySelector" description="A component that allows users to choose their preferred payment currency from available options." icon="wallet" href="/en/docs/payment-kit-react/components-ui-form-elements-currency-selector-8b3f3d/"}
::::

## Common Usage Pattern

These form elements are intended to be used within a `FormProvider` from `react-hook-form`. You can compose them to build comprehensive forms that capture all the necessary information for a transaction. While each component has its own set of properties, they share a common integration pattern.

Here is a basic example of how you might combine several form elements to create a user information form:

**MyCustomForm.tsx**

```jsx
import { FormProvider, useForm } from 'react-hook-form';
import { AddressForm, PhoneInput, CurrencySelector } from '@blocklet/payment-react';
import { Button, Stack } from '@mui/material';

// Assume `availableCurrencies` is fetched from your backend
const availableCurrencies = [
  {
    id: 'usd_xxx',
    name: 'USD',
    symbol: 'USD',
    logo: 'url/to/usd_logo.png',
    method: { id: 'stripe', name: 'Stripe' },
  },
  // ... other currencies
];

function MyCustomForm() {
  const methods = useForm({
    defaultValues: {
      currency: 'usd_xxx',
      phone_number: '',
      billing_address: {
        line1: '',
        city: '',
        state: '',
        postal_code: '',
        country: 'US', // Use ISO2 code
      },
    },
  });

  const onSubmit = (data) => {
    console.log('Form data submitted:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <CurrencySelector
            value={methods.watch('currency')}
            currencies={availableCurrencies}
            onChange={(currencyId) => methods.setValue('currency', currencyId)}
          />
          <PhoneInput name="phone_number" label="Phone Number" required />
          <AddressForm mode="required" stripe={false} />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

In this example, `CurrencySelector`, `PhoneInput`, and `AddressForm` are combined within a single form. `CurrencySelector` is used as a controlled component tied to the form's state, while `PhoneInput` and `AddressForm` are uncontrolled components that automatically register their fields and validation rules with the `react-hook-form` context.

## Next Steps

To learn more about the specific properties and implementation details of each component, please explore their individual documentation pages.

Start with the [AddressForm](/en/docs/payment-kit-react/components-ui-form-elements-address-form-8b3f3d/) to see how to collect billing information.

---

## AddressForm

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-form-elements-address-form-8b3f3d/

The `AddressForm` component provides a pre-built UI for collecting billing address information. It integrates seamlessly with `react-hook-form` and includes built-in, country-specific validation for fields like postal codes.

This component is designed to be flexible, supporting both full address collection and a simplified version for Stripe postal code verification.

## Props

| Prop  | Type  | Description  | Default  |
|---|---|---|---|
| `mode`  | `string`  | Determines the fields to display. Set to `'required'` to show the complete address form (line 1, city, state, postal code, country).  | `undefined`  |
| `stripe`  | `boolean`  | If `true`, displays a simplified form with only the postal code and country, typically used for card validation with Stripe.  | `false`  |
| `sx`  | `SxProps`  | MUI's `sx` prop for custom styling of the root `Stack` component.  | `{}`  |
| `fieldValidation`  | `Record<string, any>`  | An object for providing custom validation rules, such as regex patterns, for specific fields. See the validation section for details.  | `{}`  |
| `errorPosition`  | `'right'` \| `'bottom'`  | Specifies where to display validation error messages relative to the input field.  | `'right'`  |

## Usage

`AddressForm` must be used within a `FormProvider` from `react-hook-form` because it relies on its context to register fields and manage state.

### Standard Billing Address

To collect a full billing address, set the `mode` prop to `'required'`. This will render all standard address fields, each with a 'required' validation rule.

**AddressForm with Full Address**

```tsx
import { FormProvider, useForm } from 'react-hook-form';
import { Button, Stack } from '@mui/material';
import AddressForm from './AddressForm'; // Adjust the import path

export default function FullAddressExample() {
  const methods = useForm({
    defaultValues: {
      billing_address: {
        line1: '',
        city: '',
        state: '',
        postal_code: '',
        country: 'US', // Default country
      },
    },
  });

  const onSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm mode="required" />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

This setup renders input fields for the address line, city, state, and postal code. The country is selected via the integrated [CountrySelect](/en/docs/payment-kit-react/components-ui-form-elements-country-select-8b3f3d/) component.

### Stripe Postal Code Verification

When using payment methods like Stripe, you often only need the postal code and country for card verification. Set the `stripe` prop to `true` to render a simplified form containing only these two fields.

**AddressForm for Stripe**

```tsx
import { FormProvider, useForm } from 'react-hook-form';
import { Button, Stack } from '@mui/material';
import AddressForm from './AddressForm'; // Adjust the import path

export default function StripeAddressExample() {
  const methods = useForm({
    defaultValues: {
      billing_address: {
        postal_code: '',
        country: 'US', // Default country
      },
    },
  });

  const onSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm stripe={true} />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

## Validation

The component includes automatic validation for required fields. The most notable feature is the dynamic postal code validation, which adjusts its rules based on the selected country.

- <strong>Required Fields</strong>: All visible fields are automatically marked as required.
- <strong>Postal Code</strong>: The validation logic uses the `validator/lib/isPostalCode` library. It checks the postal code format against the selected country's standard format (e.g., 5 digits for the US, alphanumeric for Canada). If a country's format is not explicitly supported, a general validation is applied.
- <strong>Custom Validation</strong>: You can pass additional validation rules via the `fieldValidation` prop. For example, to enforce a specific pattern on the `state` field:

```tsx
const customValidation = {
  'billing_address.state': {
    pattern: '^[A-Z]{2}$',
    pattern_message: {
      en: 'State must be a 2-letter code.',
    },
  },
};

<AddressForm mode="required" fieldValidation={customValidation} />;
```

---

## CountrySelect

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-form-elements-country-select-8b3f3d/

The `CountrySelect` component provides a user-friendly dropdown for selecting a country. It features a searchable list, displays country flags, and offers a responsive design that adapts to both desktop and mobile viewports. It is designed to be used within a form managed by `react-hook-form`.

## Props

| Prop  | Type  | Description  | Required  | Default  |
|---|---|---|---|---|
| `value`  | `CountryIso2`  | The ISO2 code of the selected country (e.g., 'us').  | Yes  |  |
| `onChange`  | `(value: CountryIso2) => void`  | A callback function that is invoked when a country is selected.  | Yes  |  |
| `name`  | `string`  | The name attribute for the input, used for integration with `react-hook-form`.  | Yes  |  |
| `sx`  | `SxProps`  | Custom styles to be applied to the root element.  | No  | `{}`  |
| `showDialCode`  | `boolean`  | If `true`, the country's dial code will be displayed alongside its name in the list.  | No  | `false`  |

## Basic Usage

To use the `CountrySelect` component, you must wrap it in a `FormProvider` from `react-hook-form`. The component's state should be managed through the form context.

**Basic CountrySelect Example**

```tsx
import { FormProvider, useForm } from 'react-hook-form';
import { Box, Button, Typography } from '@mui/material';
import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // Adjust path as needed
import type { CountryIso2 } from 'react-international-phone';

export default function BasicCountrySelect() {
  const methods = useForm<{ country: CountryIso2 }>({
    defaultValues: {
      country: 'us',
    },
  });

  const { handleSubmit, watch, setValue } = methods;
  const countryValue = watch('country'); // Watch for changes to update the controlled component

  const onSubmit = (data: { country: CountryIso2 }) => {
    alert(`Form submitted with country: ${data.country}`);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onSubmit)}>
        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
          <Typography variant="h6">Select Your Country</Typography>
          <CountrySelect
            name="country"
            value={countryValue}
            onChange={(newCountry) => {
              setValue('country', newCountry, { shouldValidate: true });
            }}
          />
          <Button type="submit" variant="contained">
            Submit
          </Button>
          <Typography>
            Current form value: {countryValue}
          </Typography>
        </Box>
      </form>
    </FormProvider>
  );
}
```

## Features

### Search and Filter

The component includes a search bar at the top of the dropdown list, allowing users to quickly find a country by its name, ISO2 code, or dial code. For example, searching for "+1" will show the United States and Canada.

### Responsive UI

On desktop devices, `CountrySelect` renders as a standard dropdown menu. On mobile, it transforms into a full-width dialog that slides up from the bottom of the screen, providing an optimized user experience on smaller devices.

### Keyboard Accessibility

`CountrySelect` supports full keyboard navigation. Users can use the `ArrowUp` and `ArrowDown` keys to navigate the list, `Enter` to select a country, and `Escape` to close the dropdown. `Tab` and `Shift+Tab` also cycle through the list items.

### Form Integration

Designed to work seamlessly with `react-hook-form`. It automatically updates the form state when a selection is made, requiring it to be wrapped within a `FormProvider`.

## Advanced Usage

### Displaying Dial Codes

You can display the telephone dial code for each country in the list by setting the `showDialCode` prop to `true`.

**CountrySelect with Dial Code**

```tsx
import { FormProvider, useForm } from 'react-hook-form';
import { Box, Button } from '@mui/material';
import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // Adjust path as needed
import type { CountryIso2 } from 'react-international-phone';

export default function CountrySelectWithDialCode() {
  const methods = useForm<{ country: CountryIso2 }>({
    defaultValues: {
      country: 'gb',
    },
  });

  const { handleSubmit, watch, setValue } = methods;
  const countryValue = watch('country');

  const onSubmit = (data: { country: CountryIso2 }) => {
    alert(`Form submitted with country: ${data.country}`);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onSubmit)}>
        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
          <CountrySelect
            name="country"
            value={countryValue}
            onChange={(newCountry) => setValue('country', newCountry)}
            showDialCode={true}
          />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Box>
      </form>
    </FormProvider>
  );
}
```

## Next Steps

This component is a building block for more complex form elements. See how it's integrated into the [PhoneInput](/en/docs/payment-kit-react/components-ui-form-elements-phone-input-8b3f3d/) component to create a complete international phone number field.

---

## CurrencySelector

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-form-elements-currency-selector-8b3f3d/

The `CurrencySelector` component provides a user-friendly interface for selecting a payment currency from a list of available options. It displays each currency with its logo, symbol, and associated payment method, making it easy for users to make a choice. This component is typically used within a larger payment or checkout form.

## Props

| Prop  | Type  | Description  | Required  |
|---|---|---|---|
| `value`  | `string`  | The ID of the currently selected currency. This should be managed by the parent component's state.  | Yes  |
| `currencies`  | `TPaymentCurrency[]`  | An array of available currency objects to display as selectable options.  | Yes  |
| `onChange`  | `(currencyId: string, methodId?: string) => void`  | Callback function that is executed when a user selects a currency. It receives the new currency ID and the optional associated payment method ID.  | Yes  |

### TPaymentCurrency Type

The `currencies` prop expects an array of objects with the following structure:

**TPaymentCurrency**

```typescript
export type TPaymentCurrency = {
  id: string;       // Unique identifier for the currency option
  logo: string;     // URL for the currency/method logo
  name: string;     // Display name for the currency
  symbol: string;   // Currency symbol (e.g., '$', '€')
  method: {         // Associated payment method
    id: string;
    name: string;
  };
};
```

## Usage Example

Here is a basic example of how to implement the `CurrencySelector` component. You need to manage the selected currency's state in the parent component and provide a list of available currencies.

Note that `@blocklet/payment-react` components are designed to work within a `PaymentProvider`, which supplies the necessary theme and context. Ensure your component is wrapped accordingly.

**MyCurrencySelectorComponent.tsx**

```jsx
import React, { useState } from 'react';
import { PaymentProvider } from '@blocklet/payment-react';
import { CurrencySelector } from '@blocklet/payment-react/components';
import type { TPaymentCurrency } from '@blocklet/payment-types';
import { useSessionContext } from '@/hooks/session-context'; // Adjust this import path to your project structure

// Mock data for demonstration purposes
const mockCurrencies: TPaymentCurrency[] = [
  {
    id: 'usd_xxxxxx',
    logo: 'https://path-to-your/usd-logo.png',
    name: 'US Dollar',
    symbol: 'USD',
    method: {
      id: 'stripe_yyyyy',
      name: 'Stripe',
    },
  },
  {
    id: 'eth_zzzzzz',
    logo: 'https://path-to-your/eth-logo.png',
    name: 'Ethereum',
    symbol: 'ETH',
    method: {
      id: 'crypto_aaaaa',
      name: 'Crypto Payment',
    },
  },
];

function MyCurrencySelectorComponent() {
  const [selectedCurrency, setSelectedCurrency] = useState<string>(mockCurrencies[0].id);

  const handleCurrencyChange = (currencyId: string, methodId?: string) => {
    console.log(`Selected currency: ${currencyId}, Method: ${methodId}`);
    setSelectedCurrency(currencyId);
  };

  return (
    <div>
      <h3>Select a Currency</h3>
      <CurrencySelector
        value={selectedCurrency}
        currencies={mockCurrencies}
        onChange={handleCurrencyChange}
      />
    </div>
  );
}

// Your App's entry point
export default function App() {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <MyCurrencySelectorComponent />
    </PaymentProvider>
  );
}
```

In this example:

1. We define a `mockCurrencies` array that follows the `TPaymentCurrency` structure.
2. The `MyCurrencySelectorComponent` uses the `useState` hook to keep track of the `selectedCurrency`.
3. The `handleCurrencyChange` function updates the state when a new currency is selected and logs the new values.
4. The `CurrencySelector` is a controlled component, with its `value` and `onChange` props managed by the parent's state.
5. The entire component is wrapped in `PaymentProvider` to ensure proper rendering and access to the Material-UI theme used for styling.

---

## PhoneInput

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-form-elements-phone-input-8b3f3d/

The `PhoneInput` component provides a user-friendly, international phone number input field. It integrates seamlessly with `react-hook-form` and includes a searchable country selector with flags and dial codes, automatic number formatting, and powerful validation powered by `google-libphonenumber`.

This component is designed to work in tandem with other form elements, such as the [`CountrySelect`](/en/docs/payment-kit-react/components-ui-form-elements-country-select-8b3f3d/) or [`AddressForm`](/en/docs/payment-kit-react/components-ui-form-elements-address-form-8b3f3d/), by synchronizing its selected country with a shared form field.

## How It Works

The component leverages the `react-international-phone` library for its core functionality and wraps it to provide deep integration with `react-hook-form` and Material-UI. When a user selects a country or types a number, the component updates the corresponding fields in the form state. It also automatically updates its country selection when another component modifies the linked country field in the form.

![PhoneInput](https://media.arcblock.io/lib/72/72e00024f48c0f9d.w1600.webp)

## Props

The `PhoneInput` component accepts all standard Material-UI `TextField` props, in addition to the following specific props:

| Prop  | Type  | Required  | Default  | Description  |
|---|---|---|---|---|
| `name`  | `string`  | Yes  | -  | The name of the field to register with `react-hook-form` for the phone number.  |
| `countryFieldName`  | `string`  | No  | `'billing_address.country'`  | The name of the form field that stores the selected country's ISO2 code. This allows the phone input's country to be synchronized with other parts of your form, such as an address component.  |

## Usage

To use the `PhoneInput` component, you must wrap it in a `FormProvider` from `react-hook-form`. The following example demonstrates a basic implementation with validation.

First, you need the asynchronous validation function provided by the library.

**phone-validator.js**

```javascript
// src/libs/phone-validator.js
import { getPhoneUtil } from '@blocklet/payment-react/libs/phone-validator';

export const validatePhoneNumber = async (phoneNumber) => {
  if (!phoneNumber) return true;
  try {
    const util = await getPhoneUtil();
    const parsed = util.parseAndKeepRawInput(phoneNumber);
    return util.isValidNumber(parsed);
  } catch (err) {
    console.error('Phone validation error:', err);
    // Fallback to a simple regex if lib fails to load
    const pattern = /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im;
    return pattern.test(phoneNumber) || 'Invalid phone number';
  }
};
```

Now, you can use this validator in your form component.

**MyPaymentForm.tsx**

```jsx
import { FormProvider, useForm } from 'react-hook-form';
import { Button, Box } from '@mui/material';
import { PhoneInput } from '@blocklet/payment-react';
import { validatePhoneNumber } from '../libs/phone-validator'; // Adjust path as needed

export default function MyPaymentForm() {
  const methods = useForm({
    mode: 'onBlur',
    defaultValues: {
      phone: '',
      'billing_address.country': 'us', // Default country
    },
  });

  const onSubmit = (data) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Box display="flex" flexDirection="column" gap={2}>
          <PhoneInput
            label="Phone Number"
            name="phone"
            // Link to the country field in the form state
            countryFieldName="billing_address.country"
            // Add validation rules
            rules={{
              validate: async (value) => {
                const isValid = await validatePhoneNumber(value);
                return isValid || 'Please enter a valid phone number.';
              },
            }}
            fullWidth
          />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Box>
      </form>
    </FormProvider>
  );
}
```

### Explanation

::::steps
:::step{title="`FormProvider`"}
The entire form, including the `PhoneInput`, is wrapped in a `FormProvider` to provide the necessary form context.
:::

:::step{title="`name=\"phone\"`"}
This registers the input field under the name `phone` in the form data.
:::

:::step{title="`countryFieldName=\"billing_address.country\"`"}
This tells `PhoneInput` to both read from and write to the `billing_address.country` field in the form's state. This is how it stays synchronized. The default value for this field is set to `'us'` in `useForm`.
:::

:::step{title="`rules`"}
We pass an asynchronous `validate` function to the `rules` prop. `react-hook-form` will await this function to resolve during validation. The `validatePhoneNumber` utility is called to perform the check.
:::
::::

## Integration with AddressForm

The true power of `PhoneInput` is revealed when used alongside an `AddressForm`. Since both components can be linked to the same country field (`billing_address.country` by default), changing the country in the `AddressForm` will automatically update the flag and dial code in the `PhoneInput`.

For a complete example of this integration, please see the documentation for [`AddressForm`](/en/docs/payment-kit-react/components-ui-form-elements-address-form-8b3f3d/).

---

## PaymentSummary

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-payment-summary-8b3f3d/

The `PaymentSummary` component is a crucial UI element for any checkout process. It provides a detailed breakdown of the order, including all line items, trial period information, staking requirements, and the final total amount. It's designed to be responsive and adapts its layout for mobile devices.

This component works in tandem with `ProductItem` and `ProductDonation` to render each item in the cart, and it handles user interactions like applying cross-sells or changing quantities.

## Props

The `PaymentSummary` component accepts the following props to customize its behavior and display:

| Prop  | Type  | Required  | Description  |
|---|---|---|---|
| `items`  | `TLineItemExpanded[]`  | Yes  | An array of line items to be displayed in the summary.  |
| `currency`  | `TPaymentCurrency`  | Yes  | The currency object for formatting amounts.  |
| `trialInDays`  | `number`  | Yes  | The number of trial days for recurring subscriptions.  |
| `billingThreshold`  | `number`  | Yes  | The billing threshold amount. Used in staking calculation if applicable.  |
| `trialEnd`  | `number`  | No  | A Unix timestamp for when the trial ends. Overrides `trialInDays`.  |
| `showStaking`  | `boolean`  | No  | If `true`, displays staking details. Defaults to `false`.  |
| `onUpsell`  | `(from: string, to: string) => void`  | No  | Callback function when a user accepts an upsell offer.  |
| `onDownsell`  | `(from: string) => void`  | No  | Callback function when a user reverts an upsell offer.  |
| `onQuantityChange`  | `(itemId: string, quantity: number) => void`  | No  | Callback function when the quantity of an item is changed.  |
| `onChangeAmount`  | `(itemId: string, amount: string) => void`  | No  | Callback for changing the amount of a custom-amount item, like a donation.  |
| `onApplyCrossSell`  | `(crossSellId: string) => void`  | No  | Callback function when a user adds a cross-sell item.  |
| `onCancelCrossSell`  | `() => void`  | No  | Callback function when a user removes a cross-sell item.  |
| `checkoutSessionId`  | `string`  | No  | The ID of the checkout session, used to fetch potential cross-sell items.  |
| `crossSellBehavior`  | `string`  | No  | Defines the behavior of the cross-sell item (e.g., `'required'`).  |
| `donationSettings`  | `DonationSettings`  | No  | Configuration for donation items.  |
| `action`  | `string`  | No  | A custom title for the summary section, replacing "Order Summary".  |
| `completed`  | `boolean`  | No  | If `true`, disables interactive elements like quantity adjustment. Defaults to `false`.  |

## Usage

The `PaymentSummary` component should be placed within a `PaymentProvider` and is typically used as part of a larger checkout form. You need to provide it with the line items and currency information.

Here is a basic example of how to integrate the `PaymentSummary` component.

**PaymentSummary Example**

```tsx
import React from 'react';
import { PaymentProvider, PaymentSummary } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context'; // Your session context hook

// Mock data for demonstration purposes
const mockCurrency = {
  id: 'usd_4573516104843264',
  symbol: '$',
  name: 'USD',
  decimal: 2,
  isDefault: true,
};

const mockItems = [
  {
    id: 'li_1',
    price_id: 'price_1',
    quantity: 1,
    adjustable_quantity: { enabled: true, minimum: 1, maximum: 10 },
    price: {
      id: 'price_1',
      type: 'recurring',
      recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
      unit_amount: '2000',
      product: {
        name: 'Pro Plan',
        images: [],
      },
    },
  },
];

export default function MyCheckoutPage() {
  const { session, connectApi } = useSessionContext();

  const handleQuantityChange = (itemId, newQuantity) => {
    console.log(`Item ${itemId} quantity changed to ${newQuantity}`);
    // Here you would typically update your state and refetch checkout info
  };

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <PaymentSummary
        items={mockItems}
        currency={mockCurrency}
        trialInDays={14}
        billingThreshold={0}
        showStaking={true}
        onQuantityChange={handleQuantityChange}
      />
    </PaymentProvider>
  );
}
```

### Displaying Staking and Totals

If `showStaking` is set to `true`, the component will calculate and display the required staking amount for recurring items. It separates the amount due for immediate payment from the amount required for staking, providing a clear financial summary to the user. The final total combines these amounts.

### Handling Trial Periods

The component clearly communicates trial periods to the user. By passing `trialInDays` or `trialEnd`, a message like "Then $20.00 / month" will be displayed below the total, informing the user about the recurring charges after the trial concludes.

### Interactive Features

- <strong>Quantity Adjustment</strong>: If an item has `adjustable_quantity.enabled` set to `true`, the `PaymentSummary` (via its child `ProductItem`) will render controls to increase or decrease the quantity. The `onQuantityChange` callback is triggered upon modification.
- <strong>Upsell/Downsell</strong>: For products with an upsell configuration, a switch is rendered to allow users to upgrade their plan. The `onUpsell` and `onDownsell` callbacks handle these actions.
- <strong>Cross-Sell</strong>: If a `checkoutSessionId` is provided, the component can fetch and display suggested cross-sell items. Buttons to add or remove these items trigger the `onApplyCrossSell` and `onCancelCrossSell` callbacks.

### Mobile Responsiveness

On mobile devices, the list of products is collapsible by default to save space, especially for orders with many items. Users can tap to expand or collapse the list, providing a cleaner and more user-friendly experience on smaller screens.

---

## PricingTable

URL: https://www.arcblock.io/en/docs/payment-kit-react/components-ui-pricing-table-8b3f3d/

The `PricingTable` component is a flexible UI element designed to display subscription plans and pricing options in a structured, responsive table. It allows users to toggle between billing cycles (e.g., monthly, yearly), select their preferred currency, and choose a plan to proceed with.

This component is ideal for building custom checkout flows where you need granular control over the presentation of pricing plans. For a more integrated solution that handles the entire checkout process, consider using the higher-level [`CheckoutTable`](/en/docs/payment-kit-react/components-checkout-checkout-table-8b3f3d/) component.

## Props

| Prop  | Type  | Default  | Description  |
|---|---|---|---|
| `table`  | `TPricingTableExpanded`  | -  | <strong>Required</strong>. An object containing the pricing table data, including a list of items (plans), currency information, and other details.  |
| `onSelect`  | `(priceId: string, currencyId: string) => void`  | -  | <strong>Required</strong>. A callback function that is triggered when a user clicks the action button for a plan. It receives the selected `priceId` and `currencyId`.  |
| `alignItems`  | `'center' \| 'left'`  | `'center'`  | Controls the horizontal alignment of the table's header content (billing cycle and currency selectors).  |
| `mode`  | `'checkout' \| 'select'`  | `'checkout'`  | Determines the behavior and text of the action button. `'checkout'` mode is for initiating a payment, while `'select'` mode is for selecting a plan within a larger form.  |
| `interval`  | `string`  | `''`  | Sets the initially selected billing interval. The format is typically `interval-interval_count` (e.g., `month-1`, `year-1`).  |
| `hideCurrency`  | `boolean`  | `false`  | If `true`, the currency selector dropdown will be hidden, even if multiple currencies are available.  |

## Usage Example

To use the `PricingTable`, you must wrap it in a `PaymentProvider`. The component requires a `table` object with your product data and an `onSelect` handler to manage user selections.

**Integration Example**

```tsx
import { PaymentProvider } from '@blocklet/payment-react';
import { PricingTable } from '@blocklet/payment-react/components/ui';
import type { TPricingTableExpanded } from '@blocklet/payment-types';

// In a real application, you would fetch this data from your payment service.
const pricingTableData: TPricingTableExpanded = {
  id: 'pt_123',
  livemode: false,
  currency: { id: 'usd', symbol: '$' },
  items: [
    {
      price_id: 'price_basic_monthly',
      product: {
        name: 'Basic Plan',
        description: 'For individuals and small teams.',
        unit_label: 'user',
        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '1000', // in cents
        recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
      },
      is_highlight: false,
    },
    {
      price_id: 'price_pro_monthly',
      product: {
        name: 'Pro Plan',
        description: 'For growing businesses.',
        unit_label: 'user',
        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '2500',
        recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '2500' }],
      },
      is_highlight: true,
      highlight_text: 'Popular',
    },
    {
      price_id: 'price_basic_yearly',
      product: {
        name: 'Basic Plan',
        description: 'For individuals and small teams.',
        unit_label: 'user',
        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '10000',
        recurring: { interval: 'year', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '10000' }],
      },
      is_highlight: false,
    },
    {
      price_id: 'price_pro_yearly',
      product: {
        name: 'Pro Plan',
        description: 'For growing businesses.',
        unit_label: 'user',
        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '25000',
        recurring: { interval: 'year', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '25000' }],
      },
      is_highlight: true,
      highlight_text: 'Popular',
    },
  ],
};

function MyPricingPage() {
  const { session, connect } = useSessionContext();

  const handlePlanSelect = async (priceId: string, currencyId: string) => {
    console.log(`Plan selected: ${priceId}, Currency: ${currencyId}`);
    // Here, you would typically navigate to a checkout page or open a payment modal.
    // For example: `router.push(\"/checkout?price_id=${priceId}&currency_id=${currencyId}\")`
    alert(`Selected Price ID: ${priceId}`);
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      <div style={{ maxWidth: 800, margin: 'auto' }}>
        <PricingTable table={pricingTableData} onSelect={handlePlanSelect} />
      </div>
    </PaymentProvider>
  );
}

export default MyPricingPage;
```

## Usage Scenarios

### Mode: checkout vs. select

The `mode` prop changes the call-to-action button to fit different use cases.

- <strong>`mode='checkout'`</strong> <strong>(Default):</strong> The button text will be context-aware, showing labels like "Subscribe" or "Start Trial". This mode is intended for when the user's click should immediately initiate the payment or checkout process.
- <strong>`mode='select'`</strong><strong>:</strong> The button text will show "Select" or "Selected". This is useful when the pricing table is part of a larger form or multi-step process. The `onSelect` callback can be used to update the application's state with the chosen plan, and the UI will visually indicate which plan is currently selected.

### Handling onSelect

The `onSelect` callback is the core mechanism for handling user interaction. It's an async function that receives the `priceId` and `currencyId` of the chosen plan. Your application logic should reside here. Common actions include:

- Storing the selected plan in your application's state.
- Redirecting the user to a dedicated checkout page, passing the `priceId` as a URL parameter.
- Using the `priceId` to create a checkout session with the payment service backend and then opening a payment form.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/payment-kit-react/getting-started-8b3f3d/

This guide will walk you through the essential steps to install `@blocklet/payment-react` and integrate a basic, functional payment form into your application. In just a few minutes, you'll have a working checkout experience.

## Step 1: Installation

First, add the library to your project using npm or your preferred package manager.

**Installation Command**

```bash
npm install @blocklet/payment-react
```

## Step 2: Set Up the PaymentProvider

Most components in this library require access to a shared payment context. The `PaymentProvider` component provides this context and must be placed at the root of your application or component tree where payments will be handled.

It requires a `session` object and a `connect` API function from your application's authentication context to work correctly.

**App.tsx**

```tsx
import { PaymentProvider } from '@blocklet/payment-react';
// This is a placeholder for your app's authentication context hook.
// It should return the current user session and an API connector.
import { useSessionContext } from './contexts/session';

function App({ children }) {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      {/* Your payment components will go here */}
      {children}
    </PaymentProvider>
  );
}
```

> For detailed information on setting up your session context and for advanced `PaymentProvider` configurations, please see the [PaymentProvider documentation](/en/docs/payment-kit-react/providers-payment-provider-8b3f3d/).
>

## Step 3: Add a CheckoutForm

The `CheckoutForm` is the primary component for rendering a payment flow. It can handle both one-time payments and subscriptions initiated from a Payment Link.

To use it, simply place it inside the `PaymentProvider` and pass the required `id` of a Payment Link (`plink_...`) or a Checkout Session (`cs_...`).

## Complete Example

Here is a complete, minimal example that combines the steps above. You can use this code as a starting point for your integration.

**PaymentPage.tsx**

```tsx
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
// This is a placeholder for your app's authentication context hook.
import { useSessionContext } from './contexts/session';

function PaymentPage() {
  const { session, connectApi } = useSessionContext();

  // A Payment Link ID is generated from your Payment Kit dashboard.
  const paymentLinkId = 'plink_xxx';

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm
        id={paymentLinkId}
        mode="inline" // Embeds the form directly into your page
        showCheckoutSummary={true}
        onChange={(state) => console.log('Checkout State Changed:', state)}
        onPaid={(result) => console.log('Payment Successful:', result)}
      />
    </PaymentProvider>
  );
}

export default PaymentPage;
```

With this setup, the `CheckoutForm` will render a complete payment UI, handle user input, and process the transaction seamlessly.

## Next Steps

Congratulations! You've successfully integrated your first payment form. Now you're ready to explore more advanced features and components.

- [<strong>CheckoutForm</strong>](/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/): Dive deeper into the `CheckoutForm` props and customization options.
- [<strong>Providers</strong>](/en/docs/payment-kit-react/providers-8b3f3d/): Learn more about the context providers that power the library.
- [<strong>Components</strong>](/en/docs/payment-kit-react/components-8b3f3d/): Discover the full range of UI and business logic components available.

---

## Guides

URL: https://www.arcblock.io/en/docs/payment-kit-react/guides-8b3f3d/

Welcome to the guides section. Here, you'll find in-depth articles on advanced topics that go beyond individual component usage. These guides are designed to help you customize the library's appearance and leverage its powerful utility functions to build more sophisticated payment solutions.

Explore the guides below to master theming and utilities.

::::card-group
::link-card{title="Theming" description="Learn how to customize the look and feel of payment components to match your application's design system. This guide covers using the built-in theme provider, overriding styles with Material-UI theme options, and applying custom CSS." icon="palette" href="/en/docs/payment-kit-react/guides-theming-8b3f3d/"}
::link-card{title="Utilities" description="Discover a collection of powerful utility functions for handling API requests, caching data, formatting dates and amounts, and managing internationalization. This guide will help you write cleaner and more efficient code." icon="wrench" href="/en/docs/payment-kit-react/guides-utilities-8b3f3d/"}
::::

After exploring these guides, you might be interested in learning about the custom React hooks provided by the library.

➡️ <strong>Next:</strong> [<strong>Hooks</strong>](/en/docs/payment-kit-react/hooks-8b3f3d/)

---

## Theming

URL: https://www.arcblock.io/en/docs/payment-kit-react/guides-theming-8b3f3d/

Learn how to customize the appearance of payment components using the built-in theme provider and Material-UI theme options. The `@blocklet/payment-react` library is built on top of Material-UI, giving you extensive control over the look and feel of your payment flows.

## Overview of PaymentThemeProvider

The library includes a dedicated `PaymentThemeProvider` that wraps all payment components. This provider establishes a default theme that inherits from the ArcBlock UX theme (`@arcblock/ux/lib/Theme`), ensuring visual consistency within the ArcBlock ecosystem. It also adds its own customizations, such as a special `chip` color palette and style overrides for various MUI components.

Here is a simplified look at how `PaymentThemeProvider` is structured:

**src/theme/index.tsx**

```tsx
import { createTheme, ThemeProvider } from '@mui/material/styles';
import { create as createBlockletTheme, deepmerge } from '@arcblock/ux/lib/Theme';

export function PaymentThemeProvider({ children, theme: customTheme = {} }) {
  const parentTheme = useTheme();

  const mergeTheme = useMemo(() => {
    // Start with the base blocklet theme
    const blockletTheme = parentTheme.themeName === 'ArcBlock' ? parentTheme : createBlockletTheme();

    // Merge our custom payment theme options
    let paymentThemeOptions = deepmerge(blockletTheme, {
      // Custom palette extensions, e.g., for chips
      palette: {
        chip: { /* ... */ },
      },
      // Custom component style overrides
      components: {
        MuiButton: { /* ... */ },
        MuiOutlinedInput: { /* ... */ },
        // ... other components
      },
    });

    // Merge any user-provided custom theme
    paymentThemeOptions = deepmerge(paymentThemeOptions, customTheme);

    return createTheme(paymentThemeOptions);
  }, [parentTheme, customTheme]);

  return (
    <ThemeProvider theme={mergeTheme}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}
```

## Customizing Component Styles

Since version 1.14.22, you can easily customize the theme for individual payment components by passing a `theme` prop. This prop accepts a Material-UI `ThemeOptions` object, giving you two primary ways to apply custom styles.

### 1. Using styleOverrides

For deep, structural changes, you can override the styles for specific Material-UI components within the payment component's scope. This is the standard MUI way of theming.

**Customizing the Primary Button**

```tsx
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from '@/hooks/session-context'; // Assuming session context is defined here

function CustomStyledCheckout() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm
        id="plink_xxx"
        onChange={console.info}
        theme={{
          components: {
            MuiButton: {
              styleOverrides: {
                containedPrimary: {
                  backgroundColor: '#1DC1C7',
                  color: '#fff',
                  '&:hover': {
                    backgroundColor: 'rgb(20, 135, 139)',
                  },
                },
              },
            },
          },
        }}
      />
    </PaymentProvider>
  );
}
```

In this example, we target the primary contained button (`MuiButton.styleOverrides.containedPrimary`) and change its background and text color.

### 2. Using the sx Prop

For quick, targeted CSS changes, you can pass an `sx` object within the `theme` prop. This allows you to use CSS selectors to target specific elements within the component.

**Customizing with the sx Prop**

```tsx
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from '@/hooks/session-context';

function SxStyledCheckout() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm
        id="plink_xxx"
        showCheckoutSummary={false}
        onChange={console.info}
        theme={{
          sx: {
            // Target the submit button by its specific class name
            '.cko-submit-button': {
              backgroundColor: '#1DC1C7',
              color: '#fff',
              '&:hover': {
                backgroundColor: 'rgb(20, 135, 139)',
              },
            },
          },
        }}
      />
    </PaymentProvider>
  );
}
```

This method is useful when you need to override a style that isn't easily accessible through the standard component style overrides.

## Understanding the Default Theme

The default theme is built upon a system of CSS variables (Design Tokens) for colors, spacing, and typography, allowing for consistent styling across light and dark modes.

### Color Palette

The theme extends the standard Material-UI palette with a custom `chip` object to style status indicators. You can override these colors in your custom theme.

**src/theme/types.ts**

```ts
declare module '@mui/material/styles' {
  interface Palette {
    chip: {
      success: { text: string; background: string; border: string; };
      default: { text: string; background: string; border: string; };
      secondary: { text: string; background: string; border: string; };
      error: { text: string; background: string; border: string; };
      warning: { text: string; background: string; border: string; };
      info: { text: string; background: string; border: string; };
    };
  }
  // ... PaletteOptions definition
}
```

### Design Tokens (CSS Variables)

For advanced, global customization, you can override the CSS variables that define the theme. These variables are defined for both light (`:root`) and dark (`[data-theme='dark']`) modes.

Here are some of the key variables you can target:

**src/theme/index.css**

```css
:root {
  /* Light Theme */
  --backgrounds-bg-base: #ffffff;
  --backgrounds-bg-interactive: #3b82f6;
  --foregrounds-fg-base: #030712;
  --foregrounds-fg-interactive: #3b82f6;
  --stroke-border-base: #eff1f5;
  --radius-m: 0.5rem; /* 8px */
}

[data-theme='dark'] {
  /* Dark Theme */
  --backgrounds-bg-base: #1b1b1f;
  --backgrounds-bg-interactive: #60a5fa;
  --foregrounds-fg-base: #edeef0;
  --foregrounds-fg-interactive: #60a5fa;
  --stroke-border-base: #2e3035;
  --radius-m: 0.5rem;
}
```

Overriding these variables in your global stylesheet will apply changes across all `@blocklet/payment-react` components.

### Typography

The default typography settings can be found in `src/theme/typography.ts`. You can override any of these settings in your custom theme to match your application's typography.

**src/theme/typography.ts**

```ts
export const typography = {
  h1: {
    fontSize: '1.5rem',
    lineHeight: 1.2,
    fontWeight: 800,
  },
  body1: {
    fontSize: '0.875rem',
    lineHeight: 1.75,
  },
  // ... other typography settings
};
```

By understanding these layers of customization, you can seamlessly integrate the payment components into your application with a consistent and polished design.

Next, explore the various utility functions that can help you with tasks like data caching and date formatting.

:::action-card{title="Next: Utilities" description="A reference for utility functions provided by the library, including cached requests, and date formatting." icon="wrench"}
::action{label="Read More" href="/en/docs/payment-kit-react/guides-utilities-8b3f3d/" variant="primary"}
:::

---

## Utilities

URL: https://www.arcblock.io/en/docs/payment-kit-react/guides-utilities-8b3f3d/

The `@blocklet/payment-react` library exports a suite of utility functions and classes designed to simplify common tasks such as making API requests, managing cache, handling dates, formatting prices, and setting up internationalization. These tools are built to work seamlessly with the library's components and providers.

## API Client

The library provides a pre-configured Axios instance for making API requests to your payment backend. It automatically handles base URLs and other necessary configurations.

**API Client Usage**

```tsx
import { api } from '@blocklet/payment-react';

// Basic GET request
const getPayments = async () => {
  const response = await api.get('/api/payments');
  return response.data;
};

// POST request with a payload
const createCheckout = async (amount) => {
  const data = await api.post('/api/checkout', { amount });
  return data;
};

// GET request with query parameters
const getPaidInvoices = async () => {
  const results = await api.get('/api/invoices', {
    params: { status: 'paid' }
  });
  return results.data;
};

// PUT request with additional configuration
const updateSubscription = async (data) => {
  const config = {
    headers: { 'Custom-Header': 'value' }
  };
  const response = await api.put('/api/subscription', data, config);
  return response.data;
};
```

## CachedRequest

To optimize performance and reduce redundant network requests, you can use the `CachedRequest` class. It provides a simple way to cache data with configurable strategies and time-to-live (TTL).

### Configuration Options

When creating a `CachedRequest` instance, you can provide the following options:

| Option  | Type  | Description  | Default  |
|---|---|---|---|
| `strategy`  | `'session' \| 'local' \| 'memory'`  | The storage mechanism for the cache.  | `'session'`  |
| `ttl`  | `number`  | The cache's time-to-live in milliseconds. A value of `0` means no expiration.  | `0`  |

### Usage Example

Here’s how to create and use a cached request to fetch product prices.

**CachedRequest Example**

```tsx
import { CachedRequest, api } from '@blocklet/payment-react';

// 1. Create a cached request instance
const priceRequest = new CachedRequest(
  'product-prices',
  () => api.get('/api/prices'),
  {
    strategy: 'session',  // Cache data in sessionStorage
    ttl: 5 * 60 * 1000   // Cache for 5 minutes
  }
);

// 2. Use the cached request in your component
async function fetchPrices() {
  // This will use the cache if it's available and not expired
  const prices = await priceRequest.fetch();

  // To bypass the cache and force a fresh data fetch
  const freshPrices = await priceRequest.fetch(true);

  return prices;
}

// 3. Clear the cache when data changes
async function updatePrices() {
  await api.post('/api/prices', newPriceData);
  priceRequest.clearCache(); // Or await priceRequest.fetch(true);
}
```

## Date Handling

The library re-exports a pre-configured `dayjs` instance with useful plugins like `relativeTime`, `utc`, and `timezone` already included. You can use this for any date and time manipulation needs.

**Date Handling with dayjs**

```tsx
import { dayjs } from '@blocklet/payment-react';

// Format the current date
const formattedDate = dayjs().format('YYYY-MM-DD HH:mm');

// Parse a timestamp
const dateFromTimestamp = dayjs(1672531200000);
const unixTimestamp = dateFromTimestamp.unix();

// Calculate relative time
const fiveMinutesAgo = dayjs().subtract(5, 'minute');
const relativeTime = dayjs().from(fiveMinutesAgo); // "5 minutes ago"
```

## Internationalization (i18n)

`@blocklet/payment-react` includes built-in support for i18n. You can create your own translator or merge your translations with the library's defaults.

### Creating a Translator

Use the `createTranslator` function to set up your own translation instance.

**Custom Translator Setup**

```tsx
import { createTranslator } from '@blocklet/payment-react';

const myTranslations = {
  en: {
    checkout: { title: 'Complete Payment' }
  },
  zh: {
    checkout: { title: '完成支付' }
  }
};

const translator = createTranslator({ fallbackLocale: 'en' }, myTranslations);

translator('checkout.title', 'zh'); // '完成支付'
```

### Merging with Library Translations

To leverage the library's built-in translations for components while adding your own, you can merge them together.

**Merging Translations**

```tsx
import { translations as paymentTranslations } from '@blocklet/payment-react';
import merge from 'lodash/merge';

// Your application's translations
import en from './locales/en';
import zh from './locales/zh';

export const translations = merge(
  {
    en,
    zh,
  },
  paymentTranslations
);
```

## Formatting Utilities

Several helper functions are available to format data for display.

| Function  | Description  |
|---|---|
| `formatPrice`  | Formats a price object into a human-readable string, considering recurring intervals.  |
| `formatRecurring`  | Formats a recurring object into strings like "monthly" or "every 3 months".  |
| `formatBNStr`  | Formats a BigNumber string from a base unit into a token value with specified precision.  |
| `formatNumber`  | Formats a number or string with thousand separators and precision.  |
| `formatError`  | Parses various error formats (GraphQL, Joi, Axios) into a readable string.  |

**Formatting Example**

```tsx
import { formatNumber, formatRecurring } from '@blocklet/payment-react';

// Format a number
const formatted = formatNumber('1234567.89123', 2); // "1,234,567.89"

// Format a recurring interval
const monthly = formatRecurring({ interval: 'month', interval_count: 1 }); // "per month"
const quarterly = formatRecurring({ interval: 'month', interval_count: 3 }); // "Quarterly"
```

## Validation Utilities

The library also includes helpers for form validation.

### validatePostalCode

Checks if a given postal code is valid for a specific country.

**Postal Code Validation**

```tsx
import { validatePostalCode } from '@blocklet/payment-react';

// Returns true
const isValidUS = validatePostalCode('90210', 'US');

// Returns false
const isInvalidUS = validatePostalCode('ABC-123', 'US');

// Returns true for a UK postal code
const isValidGB = validatePostalCode('SW1A 0AA', 'GB');
```

---

## Hooks

URL: https://www.arcblock.io/en/docs/payment-kit-react/hooks-8b3f3d/

The `@blocklet/payment-react` library provides a set of custom React hooks to encapsulate and simplify common logic, such as handling real-time events or adapting to different screen sizes. These hooks allow you to easily integrate advanced functionalities into your components with minimal boilerplate code.

Explore the available hooks to enhance your application's interactivity and responsiveness.

::::card-group
::link-card{title="useSubscription" description="Subscribe to real-time events from the payment service, such as 'invoice.paid', to create dynamic and responsive user experiences." icon="link" href="/en/docs/payment-kit-react/hooks-use-subscription-8b3f3d/"}
::link-card{title="useMobile" description="A utility hook for detecting if the application is being viewed on a mobile device, helping you build responsive and mobile-friendly UIs." icon="smartphone" href="/en/docs/payment-kit-react/hooks-use-mobile-8b3f3d/"}
::::

---

## useMobile

URL: https://www.arcblock.io/en/docs/payment-kit-react/hooks-use-mobile-8b3f3d/

The `useMobile` hook is a convenient utility for detecting if the application is being viewed on a mobile-sized device. It helps in creating responsive layouts and components directly within your React logic by leveraging Material-UI's breakpoint system.

## How It Works

Internally, `useMobile` uses Material-UI's `useTheme` and `useMediaQuery` hooks. It checks the current screen width against the theme's defined breakpoints to determine if the viewport qualifies as "mobile".

## Basic Usage

Here's a simple example of how to use the `useMobile` hook to conditionally render content.

**ResponsiveComponent.tsx**

```tsx
import { useMobile } from '@blocklet/payment-react';
import { Typography, Box } from '@mui/material';

function ResponsiveComponent() {
  const { isMobile, mobileSize } = useMobile();

  return (
    <Box p={2}>
      <Typography variant="h5">
        Responsive Content
      </Typography>
      {
        isMobile ? (
          <Typography>
            This is the mobile view. The screen is {mobileSize} or smaller.
          </Typography>
        ) : (
          <Typography>
            This is the desktop view. The screen is wider than {mobileSize}.
          </Typography>
        )
      }
    </Box>
  );
}

export default ResponsiveComponent;
```

## Parameters

The `useMobile` hook accepts an optional parameter to customize the breakpoint.

| Name  | Type  | Description  |
|---|---|---|
| `mobilePoint`  | `'md' \| 'sm' \| 'lg' \| 'xl' \| 'xs'`  | The breakpoint to consider as the mobile threshold. The `isMobile` flag will be true if the screen width is at or below this point. Defaults to `'md'`.  |

### Customizing the Breakpoint

You can easily change the breakpoint by passing a different value.

**CustomBreakpoint.tsx**

```tsx
import { useMobile } from '@blocklet/payment-react';
import { Typography } from '@mui/material';

function CustomBreakpointComponent() {
  // Consider 'sm' (small) screens and below as mobile
  const { isMobile } = useMobile('sm');

  return (
    <div>
      {isMobile ? (
        <Typography>Display for small screens</Typography>
      ) : (
        <Typography>Display for medium and larger screens</Typography>
      )}
    </div>
  );
}

export default CustomBreakpointComponent;
```

## Return Value

The hook returns an object with the following properties:

| Key  | Type  | Description  |
|---|---|---|
| `isMobile`  | `boolean`  | `true` if the current viewport width is less than or equal to the specified `mobilePoint` breakpoint, otherwise `false`.  |
| `mobileSize`  | `string`  | A string representing the pixel width of the `mobilePoint` breakpoint (e.g., `"900px"`).  |

---

## useSubscription

URL: https://www.arcblock.io/en/docs/payment-kit-react/hooks-use-subscription-8b3f3d/

The `useSubscription` hook provides a simple way to subscribe to real-time events from the payment service using WebSockets. It handles the connection, subscription, and cleanup logic, allowing you to focus on how your application reacts to events like `invoice.paid`.

This is essential for creating dynamic user experiences where the UI needs to update instantly in response to backend events without requiring the user to refresh the page.

## How It Works

The hook abstracts the complexity of managing a WebSocket connection. When a component uses `useSubscription`, it establishes a persistent connection to a relay service. It then subscribes to a specific `channel` you provide. The hook automatically namespaces the channel for you, constructing a final channel name in the format `relay:<app-id>:<your-channel>`.

When the backend service publishes an event to that channel, the hook's subscription object emits the event, which your component can listen for.

The following diagram illustrates this data flow:

![useSubscription](https://media.arcblock.io/lib/70/703a50ed701baa2a.w1600.webp)

## Parameters

The hook takes a single string argument.

| Parameter  | Type  | Description  | Required  |
|---|---|---|---|
| `channel`  | `string`  | A unique identifier for the event stream you want to listen to. <strong>Important</strong>: This string must not contain separators like `/`, `.`, or `:`.  | Yes  |

## Return Value

The hook returns a `subscription` object from the underlying `@arcblock/ws` client library. This object may initially be `null` while the connection is being established.

Once the connection is successful, the returned object provides methods to manage event listeners:

- `subscription.on(eventName, handler)`: Attaches an event listener.
- `subscription.off(eventName, handler)`: Removes an event listener.

## Example Usage

Here's an example of a component that tracks the status of an invoice in real-time. When the backend broadcasts an `invoice.paid` event on the invoice's channel, the component's UI updates automatically.

**Real-time Invoice Status Tracker**

```tsx
import { useSubscription } from '@blocklet/payment-react';
import React, { useState, useEffect } from 'react';

/**
 * A component that displays an invoice's status and updates it in real-time
 * when a 'invoice.paid' event is received.
 */
function InvoiceStatusTracker({ invoiceId }) {
  const [status, setStatus] = useState('pending');
  // Subscribe to a channel dedicated to this invoice
  const subscription = useSubscription(invoiceId);

  useEffect(() => {
    // The subscription object becomes available after the WebSocket connection is established.
    if (subscription) {
      const handlePaymentSuccess = (eventData) => {
        console.log(`Received 'invoice.paid' event for channel ${invoiceId}:`, eventData);
        // Update the component's state based on the event
        setStatus('paid');
      };

      // Attach the listener for the 'invoice.paid' event
      subscription.on('invoice.paid', handlePaymentSuccess);

      // It's crucial to clean up the event listener when the component unmounts
      // or when the subscription object changes to prevent memory leaks.
      return () => {
        subscription.off('invoice.paid', handlePaymentSuccess);
      };
    }
    // This effect should re-run if the subscription object itself changes.
  }, [subscription, invoiceId]);

  return (
    <div>
      <h2>Invoice Status</h2>
      <p>ID: {invoiceId}</p>
      <p>Status: <strong>{status.toUpperCase()}</strong></p>
      {status === 'pending' && <p>Waiting for payment confirmation...</p>}
      {status === 'paid' && <p>Payment confirmed! Your invoice is settled.</p>}
    </div>
  );
}

export default InvoiceStatusTracker;
```

---

## Overview

URL: https://www.arcblock.io/en/docs/payment-kit-react/overview-8b3f3d/

This document provides a high-level overview of the `@blocklet/payment-react` library. By the end of this guide, you will understand its core features, architecture, and the types of payment functionalities you can build with it. This library is designed to simplify the integration of payment flows, subscriptions, and donation systems into React applications by interfacing with the Blocklet Payment Kit.

## Key Features

The library offers a comprehensive set of tools to accelerate the development of payment-related features.

::::card-group
::link-card{title="Pre-built UI Components" description="A suite of ready-to-use components, including checkout forms, pricing tables, and donation widgets, to handle common payment workflows." icon="layout"}
::link-card{title="Customizable Themes" description="Leverages Material-UI for theming, allowing for extensive customization to match your application's design system." icon="palette"}
::link-card{title="Comprehensive Payment Operations" description="Supports a wide range of payment operations such as subscriptions, invoice management, refunds, and metered billing." icon="credit-card"}
::link-card{title="Internationalization (i18n)" description="Includes built-in support for multiple languages, enabling you to create a localized experience for a global user base." icon="globe"}
::::

## How It Works

`@blocklet/payment-react` operates on a provider-component model. The `PaymentProvider` component is central to the library's functionality. It establishes a React context that manages API communication, state, and session information. All other payment-related components must be nested within a `PaymentProvider` to function correctly. This architecture centralizes critical logic, ensuring that components are decoupled and focused on their specific UI tasks.

The diagram below illustrates the high-level data flow. User interactions with payment components trigger API calls handled by the `PaymentProvider`, which communicates with the Payment Kit backend and updates the UI with the response.

![Overview](https://media.arcblock.io/lib/5b/5b95c0485447400b.w1600.webp)

## Available Components

The library is organized into several categories of components and utilities to address different aspects of building a payment system.

| Category  | Description  | Key Components  |
|---|---|---|
| <strong>Providers</strong>  | Context providers that wrap your application to enable payment features.  | `PaymentProvider`, `DonateProvider`  |
| <strong>Checkout Components</strong>  | High-level components for complete payment and donation flows.  | `CheckoutForm`, `CheckoutTable`, `CheckoutDonate`  |
| <strong>UI Components</strong>  | Granular components for building custom payment user interfaces.  | `PricingTable`, `PaymentSummary`, `AddressForm`  |
| <strong>History Components</strong>  | Components for displaying historical data like invoices and payments.  | `CustomerInvoiceList`, `CustomerPaymentList`  |
| <strong>Business Logic</strong>  | Specialized components for managing subscriptions and overdue payments.  | `ResumeSubscription`, `OverdueInvoicePayment`  |
| <strong>Hooks & Utilities</strong>  | Custom hooks and utility functions for interacting with the payment service.  | `useSubscription`, `api`, `dayjs`  |

## Next Steps

To begin implementing payment features, proceed to the [Getting Started](/en/docs/payment-kit-react/getting-started-8b3f3d/) guide, which provides step-by-step instructions for installation and building a basic payment form.

---

## Providers

URL: https://www.arcblock.io/en/docs/payment-kit-react/providers-8b3f3d/

To enable payment functionalities in your application, you must first wrap your components with the appropriate context providers. These providers use React's Context API to supply essential data and functions throughout your component tree, eliminating the need to pass props down manually.

Nearly all components in `@blocklet/payment-react` depend on a provider to function correctly. Wrapping your application or a specific page in a provider makes payment settings, user session information, and API clients available to all nested payment components.

The following diagram illustrates how these providers wrap your application components:

![Providers](https://media.arcblock.io/lib/50/508a31361b9ec613.w1600.webp)

The library includes two primary providers, each designed for a specific use case.

::::card-group
::link-card{title="PaymentProvider" description="The core provider required for all standard payment operations. It manages payment methods, currency settings, API access, and user session data." icon="package" href="/en/docs/payment-kit-react/providers-payment-provider-8b3f3d/"}
::link-card{title="DonateProvider" description="A specialized provider for donation features. It handles the unique settings and state management for donation components like `CheckoutDonate`." icon="heart" href="/en/docs/payment-kit-react/providers-donate-provider-8b3f3d/"}
::::

For detailed setup instructions and available properties, please refer to the documentation for each specific provider.

---

## DonateProvider

URL: https://www.arcblock.io/en/docs/payment-kit-react/providers-donate-provider-8b3f3d/

The `DonateProvider` is a crucial context provider that manages the state and settings for all donation-related components within your application. It handles fetching configuration from the backend, caching it for performance, and providing it to components like `CheckoutDonate`.

To use any donation features, you must wrap your components with `DonateProvider`. This provider must also be nested within a [`PaymentProvider`](/en/docs/payment-kit-react/providers-payment-provider-8b3f3d/) to ensure access to the necessary payment context and session information.

## How It Works

The `DonateProvider` performs several key functions:

::::steps
:::step{title="Fetches Settings"}
On mount, it calls an API endpoint to retrieve the donation settings associated with the unique `mountLocation` prop. These settings determine the behavior of child donation components.
:::

:::step{title="Caches Data"}
To improve performance and reduce network requests, the fetched settings are stored in `localStorage`. The cache is automatically used on subsequent loads and can be manually cleared if needed.
:::

:::step{title="Provides Context"}
It uses React's Context API to pass down the settings and control functions (`refresh`, `updateSettings`) to any descendant component that needs them.
:::

:::step{title="Enables Donations"}
For administrative users ('owner' or 'admin'), if the donation instance is inactive but the `enableDonate` prop is set, the provider will render a UI to activate it.
:::
::::

## Props

The `DonateProvider` accepts the following props to configure its behavior:

| Prop  | Type  | Required  | Description  |
|---|---|---|---|
| `mountLocation`  | `string`  | Yes  | A unique string identifier for this specific donation instance. This is used as the key for fetching, caching, and updating settings.  |
| `description`  | `string`  | Yes  | A human-readable description to help identify this donation instance in the system backend or logs.  |
| `children`  | `ReactNode`  | Yes  | The child components that will render inside the provider, typically including `CheckoutDonate`.  |
| `defaultSettings`  | `DonateConfigSettings`  | No  | An object with default settings to apply if no settings are found on the backend. See the type definition below for available options.  |
| `active`  | `boolean`  | No  | Sets the initial active state for the donation instance when it's first created. Defaults to `true`.  |
| `enableDonate`  | `boolean`  | No  | If `true`, allows admin users to enable this donation instance from the UI if it's currently inactive. Defaults to `false`.  |

### DonateConfigSettings Type

This is the shape of the `defaultSettings` object:

**DonateConfigSettings type**

```typescript
export interface DonateConfigSettings {
  amount?: {
    presets?: string[]; // e.g., ['1', '5', '10']
    preset?: string; // Default selected preset amount
    custom: boolean; // Allow users to enter a custom amount
    minimum?: string; // Minimum custom amount
    maximum?: string; // Maximum custom amount
  };
  btnText?: string; // Text for the main donation button, e.g., "Donate"
  historyType?: 'table' | 'avatar'; // How to display the list of supporters
}
```

## Usage Example

Here is a complete example of setting up a donation section on a page. It shows how to wrap `CheckoutDonate` with both `DonateProvider` and `PaymentProvider`.

**App.tsx**

```tsx
import {
  PaymentProvider,
  DonateProvider,
  CheckoutDonate,
} from '@blocklet/payment-react';
import { useSessionContext } from './hooks/use-session'; // Your custom session hook

function DonationSection() {
  const { session, connectApi } = useSessionContext();

  // Render nothing or a login prompt if the user is not authenticated
  if (!session?.user) {
    return <div>Please log in to make a donation.</div>;
  }

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <DonateProvider
        mountLocation="support-our-blog-post-123"
        description="Donation for the article 'Getting Started with React'"
        defaultSettings={{
          btnText: 'Support the Author',
          amount: {
            presets: ['1', '5', '10'],
            custom: true,
            minimum: '1',
          },
        }}>
        <CheckoutDonate
          settings={{
            target: 'post-123', // A unique identifier for the donation target
            title: 'Support the Author',
            description: 'If you found this article helpful, feel free to buy me a coffee.',
            reference: 'https://your-site.com/posts/123',
            beneficiaries: [
              {
                address: 'z8iZ75n8fWJ2aL1c9a9f4c3b2e1a0d9f8e7d6c5b4a392817',
                share: '100',
              },
            ],
          }}
        />
      </DonateProvider>
    </PaymentProvider>
  );
}
```

## Hooks and Utilities

The library also exports several helper functions for advanced control over the donation context and cache.

### useDonateContext

A React hook to access the donation context directly from any child component of `DonateProvider`.

```tsx
import { useDonateContext } from '@blocklet/payment-react';

function CustomDonationInfo() {
  const { settings, refresh } = useDonateContext();

  return (
    <div>
      <p>Donations are currently {settings.active ? 'enabled' : 'disabled'}.</p>
      <button onClick={() => refresh(true)}>Refresh Settings</button>
    </div>
  );
}
```

### clearDonateCache

This function manually removes the cached settings for a specific `mountLocation` from `localStorage`. This is useful when you know the settings have changed on the server and you want to force a fresh fetch on the next component render.

```javascript
import { clearDonateCache } from '@blocklet/payment-react';

// Call this function when you need to invalidate the cache
clearDonateCache('support-our-blog-post-123');
```

### clearDonateSettings

This function sends a `DELETE` request to the backend API to permanently remove the settings for a given `mountLocation`. It also clears the local cache for that location.

```javascript
import { clearDonateSettings } from '@blocklet/payment-react';

async function deleteDonationInstance() {
  try {
    await clearDonateSettings('support-our-blog-post-123');
    console.log('Donation settings have been deleted.');
  } catch (error) {
    console.error('Failed to delete settings:', error);
  }
}
```

With `DonateProvider` configured, you can now implement various donation features. The next step is to explore the main component for displaying the donation UI.

➡️ Next, learn how to use the [`CheckoutDonate`](/en/docs/payment-kit-react/components-checkout-checkout-donate-8b3f3d/) component to render the donation widget.

---

## PaymentProvider

URL: https://www.arcblock.io/en/docs/payment-kit-react/providers-payment-provider-8b3f3d/

The `PaymentProvider` is the cornerstone of the `@blocklet/payment-react` library. It functions as a context provider that must wrap your application or the relevant payment-related components. It handles fetching essential settings, managing application state, and providing helper functions and an API client to all its children.

Nearly every component and hook in this library requires being nested within a `PaymentProvider` to function correctly.

## How It Works

The provider initializes and fetches configuration data from the Payment Kit backend when it mounts. This data, along with the user's session and other utilities, is then made available to any descendant component via the `usePaymentContext` hook. This pattern ensures that your payment components always have access to the necessary context without prop drilling.

The following diagram illustrates this flow:

![PaymentProvider](https://media.arcblock.io/lib/f0/f04b67f27e79ed40.w1600.webp)

## Setup and Usage

To use `PaymentProvider`, you need to supply it with `session` and `connect` objects from your application's authentication context. Throughout this documentation, we'll use a custom hook `useSessionContext` to represent your app's authentication logic. Here is a typical implementation of such a hook:

**SessionContext.tsx**

```typescript
import React, { createContext, useContext } from 'react';
import { SessionProvider, useSessionContext as useDidSessionContext } from '@arcblock/did-connect-react';

// You can create your own context or use an existing one
const AppContext = createContext({});

export function AppProvider({ children }) {
  return (
    <SessionProvider>
      <AppContext.Provider value={{}}>
        {children}
      </AppContext.Provider>
    </SessionProvider>
  );
}

// This custom hook provides the session and connectApi to PaymentProvider
export function useSessionContext() {
  const { session, connect } = useDidSessionContext();
  return { session, connectApi: connect };
}
```

Once you have your session management in place, wrap your main application component with `PaymentProvider`.

**App.tsx**

```tsx
import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext'; // Your session context hook
import MyPaymentPage from './MyPaymentPage';

function App() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <MyPaymentPage />
    </PaymentProvider>
  );
}

export default App;
```

## Props

The `PaymentProvider` component accepts the following props:

| Prop  | Type  | Required  | Description  |
|---|---|---|---|
| `session`  | `Session`  | Yes  | The user session object from your authentication context (e.g., `@arcblock/did-connect-react`).  |
| `connect`  | `Connect`  | Yes  | The `connect` API function from your authentication context, used for DID Connect operations.  |
| `children`  | `React.ReactNode`  | Yes  | The child components that will have access to the payment context.  |
| `baseUrl`  | `string`  | No  | The base URL of the Payment Kit blocklet. Required only when integrating payment components from a different origin (cross-origin).  |
| `authToken`  | `string`  | No  | A specific authentication token for API requests. If provided, it will be used instead of the session-based authentication.  |

## Context Values

Components within `PaymentProvider` can access the following values using the `usePaymentContext` hook.

**MyComponent.tsx**

```typescript
import { usePaymentContext } from '@blocklet/payment-react';

function MyComponent() {
  const { settings, livemode, setLivemode } = usePaymentContext();

  return (
    <div>
      <p>Base Currency: {settings.baseCurrency?.name}</p>
      <p>Mode: {livemode ? 'Live' : 'Test'}</p>
      <button onClick={() => setLivemode(!livemode)}>Toggle Mode</button>
    </div>
  );
}
```

Here is a complete list of available context values:

| Key  | Type  | Description  |
|---|---|---|
| `session`  | `object`  | The authenticated user session, including user details.  |
| `connect`  | `function`  | The `connect` function for initiating DID Wallet interactions.  |
| `livemode`  | `boolean`  | Indicates if the context is in live (`true`) or test (`false`) mode.  |
| `setLivemode`  | `(livemode: boolean) => void`  | A function to toggle between live and test modes. This will trigger a refetch of settings.  |
| `settings`  | `Settings`  | An object containing `paymentMethods` and `baseCurrency` configuration fetched from the backend.  |
| `refresh`  | `(forceRefresh?: boolean) => void`  | A function to manually trigger a refetch of the settings data.  |
| `getCurrency`  | `(id: string) => TPaymentCurrency`  | A helper function to retrieve a specific currency's details by its ID.  |
| `getMethod`  | `(id: string) => TPaymentMethodExpanded`  | A helper function to retrieve a specific payment method's details by its ID.  |
| `api`  | `AxiosInstance`  | A pre-configured Axios instance for making authenticated API calls to the Payment Kit backend.  |
| `prefix`  | `string`  | The URL prefix of the blocklet.  |
| `payable`  | `boolean`  | A state that can be used to control the availability of payment actions.  |
| `setPayable`  | `(status: boolean) => void`  | A function to update the `payable` status.  |

## Advanced Scenarios

### Cross-Origin Integration

If your application and the Payment Kit blocklet are hosted on different domains, you must use the `baseUrl` prop. This allows `PaymentProvider` to correctly locate and communicate with the Payment Kit API.

**CrossOriginApp.tsx**

```tsx
import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext';

function CrossOriginApp() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider
      session={session}
      connect={connectApi}
      baseUrl="https://payment-kit.another-domain.com"
    >
      {/* Your payment components */}
    </PaymentProvider>
  );
}
```

### Custom Authentication Token

In scenarios where you need to use a specific API token instead of the default session-based authentication (e.g., for server-to-server communication or specific access grants), you can pass the `authToken` prop.

**TokenAuthApp.tsx**

```tsx
import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext';

function TokenAuthApp() {
  const { session, connectApi } = useSessionContext();
  const myCustomAuthToken = 'sk_xxxxxx'; // Your secret token

  return (
    <PaymentProvider
      session={session}
      connect={connectApi}
      authToken={myCustomAuthToken}
    >
      {/* Components will use the provided authToken for API calls */}
    </PaymentProvider>
  );
}
```

With `PaymentProvider` set up, you are now ready to start integrating payment components into your application. A good next step is to explore how to create a payment flow using the [CheckoutForm](/en/docs/payment-kit-react/components-checkout-checkout-form-8b3f3d/) component.

---

## Payment Kit SDK (Node.js)

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/

---

## API Reference

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-381920/

The API reference provides detailed documentation for every resource and method available in the PaymentKit Node.js SDK. Each resource has a dedicated page with comprehensive information on its methods, parameters, return values, and usage examples.

Browse the resources below to find the specific API you need to work with.

## Core Resources

::::card-group
::link-card{title="Checkout Sessions" description="Create and manage Checkout Sessions to handle payment flows for one-time purchases and subscriptions." icon="shopping-cart" href="/en/docs/payment-kit-sdk/api-reference-checkout-sessions-381920/"}
::link-card{title="Customers" description="Create and manage Customer objects to store payment information and track subscriptions." icon="users" href="/en/docs/payment-kit-sdk/api-reference-customers-381920/"}
::link-card{title="Payment Intents" description="Manage the lifecycle of a payment, from creation to confirmation and completion." icon="credit-card" href="/en/docs/payment-kit-sdk/api-reference-payment-intents-381920/"}
::link-card{title="Payment Links" description="Create shareable links for products or prices that redirect to a checkout page." icon="link" href="/en/docs/payment-kit-sdk/api-reference-payment-links-381920/"}
::link-card{title="Payment Methods" description="List and manage available payment methods for your customers." icon="wallet" href="/en/docs/payment-kit-sdk/api-reference-payment-methods-381920/"}
::link-card{title="Refunds" description="Programmatically create and manage refunds for completed payments." icon="receipt" href="/en/docs/payment-kit-sdk/api-reference-refunds-381920/"}
::::

## Product & Pricing

::::card-group
::link-card{title="Products" description="Define the goods or services you offer. Products are the foundation of your billing system." icon="package" href="/en/docs/payment-kit-sdk/api-reference-products-381920/"}
::link-card{title="Prices" description="Manage the pricing models for your products, including one-time and recurring options." icon="tag" href="/en/docs/payment-kit-sdk/api-reference-prices-381920/"}
::link-card{title="Payment Currencies" description="List supported currencies and manage configurations for credit currency recharges." icon="dollar-sign" href="/en/docs/payment-kit-sdk/api-reference-payment-currencies-381920/"}
::::

## Subscriptions & Usage

::::card-group
::link-card{title="Subscriptions" description="Create and manage subscriptions for recurring billing." icon="refresh" href="/en/docs/payment-kit-sdk/api-reference-subscriptions-381920/"}
::link-card{title="Subscription Items" description="Manage individual items within a subscription and report usage records for metered billing." icon="list" href="/en/docs/payment-kit-sdk/api-reference-subscription-items-381920/"}
::::

## Credit-Based Billing

::::card-group
::link-card{title="Meters" description="Create and manage meters to track customer usage for credit-based billing." icon="activity" href="/en/docs/payment-kit-sdk/api-reference-meters-381920/"}
::link-card{title="Meter Events" description="Report usage events to a meter, which will be used to deduct from a customer's credit balance." icon="activity" href="/en/docs/payment-kit-sdk/api-reference-meter-events-381920/"}
::link-card{title="Credit Grants" description="Issue credits to customers, either as a paid purchase or a promotional bonus." icon="award" href="/en/docs/payment-kit-sdk/api-reference-credit-grants-381920/"}
::link-card{title="Credit Transactions" description="View a customer's credit history, including grants, deductions, and expirations." icon="clock" href="/en/docs/payment-kit-sdk/api-reference-credit-transactions-381920/"}
::::

## System & Webhooks

::::card-group
::link-card{title="Webhook Endpoints" description="Configure endpoints to receive asynchronous events from PaymentKit, such as payment success or subscription updates." icon="link" href="/en/docs/payment-kit-sdk/api-reference-webhook-endpoints-381920/"}
::link-card{title="Settings" description="Manage various settings within your PaymentKit account." icon="settings" href="/en/docs/payment-kit-sdk/api-reference-settings-381920/"}
::::

---

## Checkout Sessions

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-checkout-sessions-381920/

A Checkout Session represents your customer's session as they are making a payment. It is the primary mechanism for collecting payment details to create a one-time payment or a subscription. After you create a Session, you redirect the customer to a secure, hosted payment page. Once the payment is complete, the customer is redirected back to your application.

Related guides: [One-Time Payments](/en/docs/payment-kit-sdk/core-concepts-one-time-payments-381920/), [Subscriptions](/en/docs/payment-kit-sdk/core-concepts-subscriptions-381920/).

## The Checkout Session Object

A Checkout Session object contains all the details about the payment flow, including line items, payment status, and customer information.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the object.  |
| `url`  | string  | The URL to which you should redirect your customer to complete the payment.  |
| `status`  | string  | The status of the Checkout Session. Can be `open`, `complete`, or `expired`.  |
| `payment_status`  | string  | The payment status of the session. Can be `paid`, `unpaid`, or `no_payment_required`.  |
| `mode`  | string  | The mode of the Checkout Session, which determines the type of payment being collected. Can be `payment`, `setup`, or `subscription`.  |
| `amount_subtotal`  | string  | Total of all line item prices.  |
| `amount_total`  | string  | The total amount after discounts and taxes are applied.  |
| `currency_id`  | string  | The ID of the currency used for the payment.  |
| `customer_id`  | string  | The ID of the Customer for this session.  |
| `line_items`  | array  | A list of items the customer is purchasing.  |
| `metadata`  | object  | A set of key-value pairs that you can attach to an object.  |
| `success_url`  | string  | The URL to redirect to on successful payment.  |
| `cancel_url`  | string  | The URL to redirect to if the customer cancels the session.  |
| `expires_at`  | number  | The Unix timestamp at which the Checkout Session will expire.  |

## Create a Checkout Session

Creates a Session for a customer to enter their payment details.

**Create a Checkout Session**

```javascript
const session = await payment.checkoutSessions.create({
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price_id: 'price_12345',
      quantity: 1,
    },
  ],
  mode: 'payment', // or 'subscription'
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `line_items`  | array  | <strong>Required.</strong> A list of line item objects. See the <strong>Line Item Properties</strong> table below for details.  |
| `success_url`  | string  | <strong>Required.</strong> The URL to which the customer will be directed after a successful payment.  |
| `cancel_url`  | string  | <strong>Required.</strong> The URL to which the customer will be directed if they cancel the payment.  |
| `allow_promotion_codes`  | boolean  | Enables the use of promotion codes. Defaults to `false`.  |
| `billing_address_collection`  | string  | Specifies whether to collect the customer's billing address. Can be `auto` or `required`. Defaults to `auto`.  |
| `client_reference_id`  | string  | A unique string to reference the Checkout Session. This can be used to reconcile the session with your internal systems.  |
| `customer_id`  | string  | The ID of an existing Customer to associate with this session.  |
| `customer_creation`  | string  | Determines how to handle customer creation. Can be `if_required` or `always`. Defaults to `always`.  |
| `expires_at`  | number  | A Unix timestamp after which the session will expire. Defaults to 24 hours from creation.  |
| `metadata`  | object  | A set of key-value pairs to store additional information about the object.  |
| `payment_intent_data`  | object  | Data that will be used to create the underlying PaymentIntent. See the <strong>Payment Intent Data Properties</strong> table below.  |
| `subscription_data`  | object  | Data that will be used to create a subscription if the session is in `subscription` mode. See the <strong>Subscription Data Properties</strong> table below.  |
| `include_free_trial`  | boolean  | If `true` and the session is in `subscription` mode, it will include any trial period defined on the price.  |

<strong>Line Item Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `price_id`  | string  | The ID of the Price object.  |
| `quantity`  | number  | The quantity of the line item being purchased. Defaults to 1.  |
| `adjustable_quantity`  | object  | Allows the customer to adjust the quantity of this line item on the checkout page. Contains `enabled` (boolean), `minimum` (number), and `maximum` (number) properties.  |

<strong>Subscription Data Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `description`  | string  | An optional description for the subscription.  |
| `trial_period_days`  | number  | The number of trial days for the subscription.  |
| `metadata`  | object  | A set of key-value pairs to store on the subscription.  |

<strong>Returns</strong>

The created Checkout Session object.

**Response**

```json
{
  "id": "cs_123456789",
  "object": "checkout.session",
  "url": "https://checkout.example.com/pay/cs_123456789",
  "status": "open",
  "payment_status": "unpaid",
  "mode": "payment",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "expires_at": 1678886400,
  // ... other properties
}
```

## Retrieve a Checkout Session

Retrieves the details of an existing Checkout Session.

**Retrieve a Checkout Session**

```javascript
const session = await payment.checkoutSessions.retrieve('cs_123456789');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The unique identifier of the Checkout Session to retrieve.  |

<strong>Returns</strong>

The retrieved Checkout Session object.

**Response**

```json
{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "complete",
  "payment_status": "paid",
  // ... other properties
}
```

## Update a Checkout Session

Updates a Checkout Session object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

**Update a Checkout Session**

```javascript
const session = await payment.checkoutSessions.update('cs_123456789', {
  metadata: {
    order_id: '6735'
  }
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the session to update.  |
| `metadata`  | object  | A set of key-value pairs to store on the object. This is the only field that can be updated.  |

<strong>Returns</strong>

The updated Checkout Session object.

## List all Checkout Sessions

Returns a list of your Checkout Sessions. The sessions are returned sorted by creation date, with the most recent sessions appearing first.

**List Checkout Sessions**

```javascript
const sessions = await payment.checkoutSessions.list({
  limit: 5,
  status: 'open'
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `status`  | string  | Filter sessions by status. Can be `open`, `complete`, or `expired`.  |
| `payment_status`  | string  | Filter sessions by payment status. Can be `paid`, `unpaid`, or `no_payment_required`.  |
| `customer_id`  | string  | Only return sessions for the given customer ID.  |
| `customer_did`  | string  | Only return sessions for the given customer DID.  |
| `payment_intent_id`  | string  | Only return the session for the given PaymentIntent.  |
| `payment_link_id`  | string  | Only return sessions created from the given Payment Link.  |
| `subscription_id`  | string  | Only return the session for the given subscription.  |
| `metadata.{key}`  | string  | Filter by custom metadata fields. For example, `metadata.order_id: '6735'`.  |
| `page`  | number  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | number  | The number of items per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated object containing a `list` of Checkout Session objects.

**Response**

```json
{
  "count": 15,
  "list": [
    {
      "id": "cs_123456789",
      "object": "checkout.session",
      "status": "open",
      // ... other properties
    },
    {
      "id": "cs_987654321",
      "object": "checkout.session",
      "status": "open",
      // ... other properties
    }
  ]
}
```

## Expire a Checkout Session

Manually expires a Checkout Session. This action is irreversible.

**Expire a Checkout Session**

```javascript
const session = await payment.checkoutSessions.expire('cs_123456789');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the Checkout Session to expire.  |

<strong>Returns</strong>

The expired Checkout Session object with a status of `expired`.

**Response**

```json
{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "expired",
  // ... other properties
}
```

---

## Coupons

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-coupons-381920/

Coupons are a powerful tool for offering discounts on your products and services. A coupon object contains information about a specific discount, such as a percentage off or a fixed amount off. To make a coupon redeemable, you must associate it with one or more [Promotion Codes](/en/docs/payment-kit-sdk/api-reference-promotion-codes-381920/). This API allows you to create, manage, and track the usage of coupons.

## Create a Coupon

Creates a new coupon. You can optionally create one or more promotion codes to associate with this coupon in the same request.

### Parameters

- **name** `string` *(required)* — The coupon’s name, meant to be displayable to the customer. For example, SUMMER25.
- **percent_off** `number` — A positive integer between 1 and 100 that represents the percentage of the subscription invoice subtotal that will be discounted. Either percent_off or amount_off is required.
- **amount_off** `string` — A positive decimal that represents the amount of discount that will be applied to an invoice. Either percent_off or amount_off is required. Requires currency_id to be set.
- **currency_id** `string` — The ID of the currency that the amount_off is in. Required if amount_off is set.
- **duration** `string` *(required)* — Specifies how long the discount will be in effect. Can be once, repeating, or forever.
- **duration_in_months** `number` — If duration is repeating, the number of months the coupon applies. Required if duration is repeating.
- **max_redemptions** `number` — A positive integer specifying the maximum number of times the coupon can be redeemed. Leaving this blank will allow the coupon to be redeemed an unlimited number of times.
- **redeem_by** `number` — Unix timestamp specifying the last time at which the coupon can be redeemed. After this time, the coupon can no longer be applied to new customers.
- **applies_to** `object` — A hash containing product IDs that this coupon applies to.
  - **products** `string[]` — An array of product IDs that this coupon will apply to.
- **currency_options** `object` — When amount_off is specified, this hash can be used to configure per-currency coupon amounts. If a customer's currency matches a key in the hash, the value of that key will be used as the discount amount.
- **metadata** `object` — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- **promotion_codes** `array` — An array of promotion code objects to create and attach to this coupon. See details below.

<strong>promotion_codes Object Properties</strong>

- **code** `string` — The customer-facing code. If left blank, a random code will be generated.
- **description** `string` — An optional description for the promotion code.
- **max_redemptions** `number` — The maximum number of times this specific promotion code can be redeemed.
- **expires_at** `number` — Unix timestamp specifying when the promotion code expires.

### Returns

Returns an object containing the newly created `coupon` and an array of `promotion_codes`.

- **** `object`
  - **coupon** `object` — The created coupon object.
  - **promotion_codes** `array` — An array of created promotion code objects.

### Example

**Create a Coupon**

```javascript
import payment from '@blocklet/payment-js';

async function createCoupon() {
  try {
    const result = await payment.coupons.create({
      name: '20% Off First Month',
      percent_off: 20,
      duration: 'once',
      max_redemptions: 100,
      promotion_codes: [
        {
          code: 'NEWUSER20',
          description: 'Discount for new users',
          max_redemptions: 50,
          expires_at: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60, // 30 days from now
        },
      ],
    });
    console.log('Coupon created:', result.coupon);
    console.log('Promotion codes:', result.promotion_codes);
  } catch (error) {
    console.error('Error creating coupon:', error);
  }
}

createCoupon();
```

### Example Response

```json
{
  "coupon": {
    "id": "coupon_12345",
    "name": "20% Off First Month",
    "percent_off": 20,
    "amount_off": null,
    "currency_id": null,
    "duration": "once",
    "duration_in_months": null,
    "max_redemptions": 100,
    "times_redeemed": 0,
    "valid": true,
    "livemode": false,
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z"
  },
  "promotion_codes": [
    {
      "id": "promo_67890",
      "coupon_id": "coupon_12345",
      "code": "NEWUSER20",
      "description": "Discount for new users",
      "active": true,
      "max_redemptions": 50,
      "times_redeemed": 0,
      "expires_at": 1699984800,
      "livemode": false
    }
  ]
}
```

## Retrieve a Coupon

Retrieves the coupon with the given ID. The response includes associated promotion codes and any products the coupon applies to.

### Parameters

- **id** `string` *(required)* — The ID of the coupon to retrieve.

### Returns

Returns a coupon object if a valid ID was provided. Returns an error otherwise.

- **** `object` — The retrieved coupon object, expanded with related promotion codes and applied products.

### Example

**Retrieve a Coupon**

```javascript
import payment from '@blocklet/payment-js';

async function retrieveCoupon(couponId) {
  try {
    const coupon = await payment.coupons.retrieve(couponId);
    console.log('Retrieved coupon:', coupon);
  } catch (error) {
    console.error('Error retrieving coupon:', error);
  }
}

retrieveCoupon('coupon_12345');
```

### Example Response

```json
{
  "id": "coupon_12345",
  "name": "20% Off First Month",
  "percent_off": 20,
  "duration": "once",
  "valid": true,
  "promotion_codes": [
    {
      "id": "promo_67890",
      "code": "NEWUSER20",
      "active": true
    }
  ],
  "applied_products": []
}
```

## Update a Coupon

Updates the specified coupon by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

### Parameters

- **id** `string` *(required)* — The ID of the coupon to update.
- **name** `string` — The coupon’s name.
- **description** `string` — An optional description for the coupon.
- **max_redemptions** `number` — The maximum number of times the coupon can be redeemed.
- **redeem_by** `number` — Unix timestamp specifying the last time at which the coupon can be redeemed.
- **valid** `boolean` — Whether the coupon is currently valid.
- **currency_options** `object` — Update per-currency coupon amounts.
- **metadata** `object` — Set of key-value pairs to update on the object.

### Returns

Returns the updated coupon object.

- **** `object` — The updated coupon object.

### Example

**Update a Coupon**

```javascript
import payment from '@blocklet/payment-js';

async function updateCoupon(couponId) {
  try {
    const updatedCoupon = await payment.coupons.update(couponId, {
      name: 'Summer Sale 2024',
      metadata: { campaign: 'summer-2024' },
    });
    console.log('Coupon updated:', updatedCoupon);
  } catch (error) {
    console.error('Error updating coupon:', error);
  }
}

updateCoupon('coupon_12345');
```

### Example Response

```json
{
  "id": "coupon_12345",
  "name": "Summer Sale 2024",
  "percent_off": 20,
  "duration": "once",
  "valid": true,
  "metadata": {
    "campaign": "summer-2024"
  }
}
```

## List all Coupons

Returns a list of your coupons.

### Parameters

- **valid** `boolean` — Filter coupons by their validity.
- **name** `string` — Filter coupons by name.
- **page** `number` (default: `1`) — The page number to retrieve.
- **pageSize** `number` (default: `20`) — The number of items to retrieve per page.

### Returns

An object with a `list` property containing an array of coupons, a `count` property with the total number of coupons, and a `paging` object.

- **** `object`
  - **list** `array` — An array of coupon objects.
  - **count** `number` — Total number of coupons matching the query.
  - **paging** `object` — Pagination information.
    - **page** `number` — Current page number.
    - **pageSize** `number` — Number of items per page.

### Example

**List Coupons**

```javascript
import payment from '@blocklet/payment-js';

async function listCoupons() {
  try {
    const coupons = await payment.coupons.list({ valid: true, pageSize: 5 });
    console.log('Found coupons:', coupons.list);
  } catch (error) {
    console.error('Error listing coupons:', error);
  }
}

listCoupons();
```

### Example Response

```json
{
  "count": 25,
  "list": [
    {
      "id": "coupon_12345",
      "name": "Summer Sale 2024",
      "percent_off": 20,
      "valid": true
    },
    {
      "id": "coupon_67890",
      "name": "10 USD Off",
      "amount_off": "1000",
      "valid": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
```

## Delete a Coupon

You can delete coupons via the API. Deleting a coupon will prevent it from being applied to any future subscriptions. It will not, however, remove it from any subscriptions it has already been applied to.

### Parameters

- **id** `string` *(required)* — The ID of the coupon to delete.

### Returns

Returns the deleted coupon object. If the coupon has been used, it cannot be deleted and will throw an error.

- **** `object` — The deleted coupon object.

### Example

**Delete a Coupon**

```javascript
import payment from '@blocklet/payment-js';

async function deleteCoupon(couponId) {
  try {
    const deletedCoupon = await payment.coupons.del(couponId);
    console.log('Coupon deleted:', deletedCoupon.id);
  } catch (error) {
    console.error('Error deleting coupon:', error);
  }
}

deleteCoupon('coupon_abcde');
```

### Example Response

```json
{
  "id": "coupon_abcde",
  "name": "Temporary Discount",
  "percent_off": 15,
  "valid": false
}
```

## Check if Coupon is Used

Checks whether a coupon has been redeemed at least once.

### Parameters

- **id** `string` *(required)* — The ID of the coupon to check.

### Returns

An object containing a boolean `used` property.

- **used** `boolean` — True if the coupon has been redeemed, false otherwise.

### Example

**Check Coupon Usage**

```javascript
import payment from '@blocklet/payment-js';

async function checkCouponUsage(couponId) {
  try {
    const result = await payment.coupons.used(couponId);
    console.log(`Is coupon ${couponId} used?`, result.used);
  } catch (error) {
    console.error('Error checking coupon usage:', error);
  }
}

checkCouponUsage('coupon_12345');
```

### Example Response

```json
{
  "used": true
}
```

## Get Coupon Redemptions

Retrieves detailed analytics about a coupon's redemptions, including which customers or subscriptions have used it.

### Parameters

- **id** `string` *(required)* — The ID of the coupon.
- **type** `string` — The type of redemption data to retrieve. Can be customer or subscription.
- **page** `number` (default: `1`) — The page number to retrieve.
- **pageSize** `number` (default: `20`) — The number of items to retrieve per page.

### Returns

Returns a data object with redemption details.

- **** `object`
  - **count** `number` — Total number of redemptions.
  - **subscriptions** `array` — List of subscriptions that redeemed the coupon (if type is 'subscription').
  - **customers** `array` — List of customers that redeemed the coupon (if type is 'customer').
  - **paging** `object` — Pagination information.

### Example

**Get Coupon Redemptions**

```javascript
import payment from '@blocklet/payment-js';

async function getRedemptions(couponId) {
  try {
    const redemptions = await payment.coupons.redemptions(couponId, {
      type: 'customer',
      pageSize: 10,
    });
    console.log('Total redemptions:', redemptions.count);
    console.log('Customers who redeemed:', redemptions.customers);
  } catch (error) {
    console.error('Error getting redemptions:', error);
  }
}

getRedemptions('coupon_12345');
```

### Example Response

```json
{
  "count": 1,
  "subscriptions": [],
  "customers": [
    {
      "id": "cus_abc123",
      "did": "did:abt:z123...",
      "email": "customer@example.com",
      "name": "Test Customer",
      "coupon_usage_stats": {
        "coupon_12345": 1
      }
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

---

## Credit Grants

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-credit-grants-381920/

Credit Grant objects are used to issue credits to your customers, which can then be applied to future invoices, particularly in usage-based or credit-based billing models. Each grant tracks the total amount, the remaining balance, its status, and any specific applicability rules.

For a broader understanding of how to implement a complete credit-based system, refer to our guide on [Credit-Based Billing](/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/).

## The Credit Grant Object

A `CreditGrant` object contains all the details about a specific issuance of credits to a customer.

**The Credit Grant Object**

```json
{
  "id": "crdg_1B2c3D4e5F6g7H8i9J0k1L2m",
  "object": "credit_grant",
  "amount": "5000",
  "currency_id": "curr_usd",
  "customer_id": "cus_a1b2c3d4e5f6g7h8",
  "name": "Promotional Onboarding Credit",
  "category": "promotional",
  "priority": 50,
  "status": "granted",
  "effective_at": 1672531200,
  "expires_at": 1704067199,
  "granted_at": 1672531200,
  "remaining_amount": "3500",
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "metadata": {
    "campaign_id": "promo_q1_2024"
  },
  "livemode": true,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-15T10:30:00.000Z",
  "customer": {
    "id": "cus_a1b2c3d4e5f6g7h8",
    "did": "did:abt:z1...",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "paymentCurrency": {
    "id": "curr_usd",
    "name": "United States Dollar",
    "symbol": "$",
    "decimal": 2
  }
}
```

## Create a Credit Grant

Issues a new credit grant to a customer. If the specified customer does not exist, a new customer will be created automatically based on the provided `customer_id` (DID).

**Create a Credit Grant**

```javascript
import payment from '@blocklet/payment-js';

async function createCreditGrant() {
  try {
    const creditGrant = await payment.creditGrants.create({
      amount: '100.00',
      currency_id: 'curr_usd', // Replace with a valid currency ID
      customer_id: 'cus_a1b2c3d4e5f6g7h8', // or a user DID
      name: 'Initial sign-up bonus',
      category: 'promotional',
      priority: 50,
      expires_at: Math.floor(new Date('2024-12-31').getTime() / 1000),
      metadata: {
        source: 'marketing_campaign_fall_2024'
      }
    });
    console.log('Credit grant created:', creditGrant);
  } catch (error) {
    console.error('Error creating credit grant:', error.message);
  }
}

createCreditGrant();
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `amount`  | string  | <strong>Required.</strong> The amount of credit to grant, as a string representation of a number.  |
| `currency_id`  | string  | <strong>Required.</strong> The ID of the currency for this grant.  |
| `customer_id`  | string  | <strong>Required.</strong> The ID or DID of the customer to receive the credit.  |
| `name`  | string  | An optional name for the credit grant for internal reference.  |
| `category`  | 'paid' \| 'promotional'  | <strong>Required.</strong> The category of the grant. `paid` grants are typically purchased by the customer, while `promotional` grants are given away.  |
| `priority`  | number  | Optional. A number between 0 and 100 used to determine the order of application. Lower numbers are applied first. Defaults to `50`.  |
| `effective_at`  | number  | Optional. A Unix timestamp indicating when the grant becomes active. If not provided, it becomes effective immediately.  |
| `expires_at`  | number  | Optional. A Unix timestamp indicating when the grant expires.  |
| `applicability_config`  | object  | Optional. Defines rules for where this credit can be applied. See details below. If not set, it defaults to all metered prices.  |
| `metadata`  | object  | Optional. A set of key-value pairs that you can attach to the object. Useful for storing additional information.  |

<strong>`applicability_config`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `scope`  | object  | Defines the scope of prices the credit grant applies to.  |

<strong>`scope`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `prices`  | string[]  | An array of Price IDs. If specified, the credit grant will only apply to these prices.  |
| `price_type`  | string  | Can be set to `'metered'`. If specified, the credit grant will apply to all prices of this type.  |

<strong>Returns</strong>

A `TCreditGrantExpanded` object if the call is successful.

## Retrieve a Credit Grant

Retrieves the details of an existing credit grant by its unique identifier.

**Retrieve a Credit Grant**

```javascript
import payment from '@blocklet/payment-js';

async function getCreditGrant(grantId) {
  try {
    const creditGrant = await payment.creditGrants.retrieve(grantId);
    console.log('Retrieved credit grant:', creditGrant);
  } catch (error) {
    console.error(`Error retrieving credit grant ${grantId}:`, error.message);
  }
}

getCreditGrant('crdg_1B2c3D4e5F6g7H8i9J0k1L2m'); // Replace with a valid credit grant ID
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The unique identifier of the credit grant to retrieve.  |

<strong>Returns</strong>

A `TCreditGrantExpanded` object with an additional `items` property containing an array of expanded Price objects if `applicability_config.scope.prices` is set.

## Update a Credit Grant

Updates the specified credit grant by setting or unsetting the `metadata` property. Other properties cannot be updated.

**Update a Credit Grant**

```javascript
import payment from '@blocklet/payment-js';

async function updateCreditGrantMetadata(grantId) {
  try {
    const result = await payment.creditGrants.update(grantId, {
      metadata: {
        source: 'marketing_campaign_fall_2024',
        updated_by: 'admin_user_xyz'
      }
    });
    console.log('Update successful:', result.success);
  } catch (error) {
    console.error(`Error updating credit grant ${grantId}:`, error.message);
  }
}

updateCreditGrantMetadata('crdg_1B2c3D4e5F6g7H8i9J0k1L2m'); // Replace with a valid credit grant ID
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the credit grant to update.  |
| `metadata`  | object  | A set of key-value pairs to store on the object. To remove a key, set its value to `null`.  |

<strong>Returns</strong>

An object containing a `success` boolean.

**Response**

```json
{
  "success": true
}
```

## List Credit Grants

Returns a paginated list of credit grants. You can filter the list based on various parameters.

**List Credit Grants**

```javascript
import payment from '@blocklet/payment-js';

async function listCustomerCreditGrants() {
  try {
    const grants = await payment.creditGrants.list({
      customer_id: 'cus_a1b2c3d4e5f6g7h8', // Replace with a valid customer ID
      status: 'granted,pending',
      pageSize: 10
    });
    console.log(`Found ${grants.count} grants.`);
    grants.list.forEach(grant => {
      console.log(`- ${grant.id} (${grant.status})`);
    });
  } catch (error) {
    console.error('Error listing credit grants:', error.message);
  }
}

listCustomerCreditGrants();
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `customer_id`  | string  | Optional. Filter grants by a specific customer ID or DID.  |
| `currency_id`  | string  | Optional. Filter grants by currency ID.  |
| `status`  | string  | Optional. A comma-separated string of statuses to filter by (e.g., `'granted,pending,depleted'`).  |
| `livemode`  | boolean  | Optional. Filter by live mode.  |
| `q`  | string  | Optional. A general search query string.  |
| `page`  | number  | Optional. The page number for pagination. Defaults to `1`.  |
| `pageSize`  | number  | Optional. The number of items per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated object containing a `list` of `TCreditGrantExpanded` objects and a `count` of the total number of records.

## Get Credit Summary

Retrieves a summary of a customer's effective credit balances, grouped by currency. This is useful for displaying a customer's total available credit.

**Get Credit Summary**

```javascript
import payment from '@blocklet/payment-js';

async function getCustomerCreditSummary(customerId) {
  try {
    const summary = await payment.creditGrants.summary({ customer_id: customerId });
    console.log('Customer Credit Summary:', summary);
  } catch (error) {
    console.error(`Error fetching credit summary for ${customerId}:`, error.message);
  }
}

getCustomerCreditSummary('cus_a1b2c3d4e5f6g7h8'); // Replace with a valid customer ID
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `customer_id`  | string  | <strong>Required.</strong> The ID or DID of the customer whose credit summary you want to retrieve.  |
| `subscription_id`  | string  | Optional. If provided, the summary will only include credits applicable to the prices in this specific subscription.  |

<strong>Returns</strong>

Returns a `CreditSummary` object. This is a map where each key is a currency ID. The value is an object containing the total and remaining credit amounts for that currency, along with a count of active grants.

**Response**

```json
{
  "curr_usd": {
    "paymentCurrency": {
      "id": "curr_usd",
      "name": "United States Dollar",
      "symbol": "$",
      "decimal": 2
    },
    "totalAmount": "15000",
    "remainingAmount": "8500",
    "grantCount": 2
  },
  "curr_eur": {
    "paymentCurrency": {
      "id": "curr_eur",
      "name": "Euro",
      "symbol": "€",
      "decimal": 2
    },
    "totalAmount": "2000",
    "remainingAmount": "2000",
    "grantCount": 1
  }
}
```

Next, you can explore how credit consumption is recorded by viewing the [Credit Transactions](/en/docs/payment-kit-sdk/api-reference-credit-transactions-381920/) API.

---

## Credit Transactions

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-credit-transactions-381920/

Credit Transaction objects record every change to a customer's credit balance. This includes grants, consumptions, adjustments, and expirations. You can use this API to retrieve a detailed history of a customer's credit activities.

Each transaction provides a snapshot of the credit balance at the time of the event, making it a reliable ledger for auditing and tracking credit usage. For a higher-level overview of credit management, see the [Credit-Based Billing](/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/) guide.

## The Credit Transaction Object

A `CreditTransaction` object contains detailed information about a single credit event.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the credit transaction object.  |
| `customer_id`  | string  | ID of the customer associated with this transaction.  |
| `credit_grant_id`  | string  | ID of the credit grant from which this transaction originated.  |
| `meter_id`  | string  | (Optional) ID of the meter if the transaction is a consumption event.  |
| `subscription_id`  | string  | (Optional) ID of the subscription associated with this transaction.  |
| `meter_event_id`  | string  | (Optional) ID of the meter event that triggered a consumption.  |
| `type`  | string  | The type of transaction. Can be `grant`, `consumption`, `adjustment`, or `expiration`.  |
| `amount`  | string  | The amount of credit transacted, represented as a string. A positive value indicates credits added (e.g., a grant), and a negative value indicates credits removed (e.g., consumption).  |
| `running_balance`  | string  | The customer's credit balance after this transaction occurred.  |
| `description`  | string  | (Optional) An internal description of the transaction.  |
| `livemode`  | boolean  | `true` if the transaction was created in live mode, `false` for test mode.  |
| `created_at`  | string  | Timestamp of when the object was created.  |
| `updated_at`  | string  | Timestamp of the last update to the object.  |
| `metadata`  | object  | (Optional) A set of key-value pairs that you can attach to an object.  |

## Retrieve a Credit Transaction

Retrieves the details of a specific credit transaction by its unique ID.

**Retrieve a Transaction**

```javascript
const transaction = await payment.creditTransactions.retrieve(
  'ct_xxxxxxxxxxxxxx'
);

console.log(transaction);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The unique identifier of the credit transaction to retrieve.  |

<strong>Returns</strong>

Returns a `TCreditTransactionExpanded` object if a valid ID is provided. Otherwise, this call returns an error.

**Response Example**

```json
{
  "id": "ct_123456789",
  "customer_id": "cus_abcdefgh",
  "credit_grant_id": "cg_ijklmnop",
  "meter_id": "mtr_qrstuvwx",
  "subscription_id": "sub_yz123456",
  "meter_event_id": "me_7890abcd",
  "type": "consumption",
  "amount": "-100.00",
  "running_balance": "900.00",
  "description": "API Call Usage",
  "livemode": true,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {},
  "customer": {
    "id": "cus_abcdefgh",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "meter": {
    "id": "mtr_qrstuvwx",
    "name": "API Calls"
  },
  "subscription": {
    "id": "sub_yz123456",
    "description": "Premium Plan"
  },
  "creditGrant": {
    "id": "cg_ijklmnop",
    "name": "Initial Grant"
  }
}
```

## List Credit Transactions

Returns a paginated list of credit transactions. You can filter the list based on various parameters.

**List Transactions**

```javascript
const transactions = await payment.creditTransactions.list({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  limit: 10,
});

console.log(transactions);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `page`  | number  | Optional. The page number for pagination, starting at 1. Defaults to `1`.  |
| `pageSize`  | number  | Optional. The number of items to return per page. Defaults to `20`.  |
| `customer_id`  | string  | Optional. Filter transactions for a specific customer.  |
| `subscription_id`  | string  | Optional. Filter transactions for a specific subscription.  |
| `credit_grant_id`  | string  | Optional. Filter transactions originating from a specific credit grant.  |
| `meter_id`  | string  | Optional. Filter transactions related to a specific meter.  |
| `source`  | string  | Optional. Filter by the source of the transaction.  |
| `start`  | number  | Optional. A Unix timestamp to filter for transactions created on or after this time.  |
| `end`  | number  | Optional. A Unix timestamp to filter for transactions created on or before this time.  |
| `livemode`  | boolean  | Optional. Specify whether to fetch live or test mode transactions.  |
| `q`  | string  | Optional. A general search query string.  |

<strong>Returns</strong>

Returns a paginated list of `TCreditTransactionExpanded` objects.

**Response Example**

```json
{
  "count": 15,
  "list": [
    {
      "id": "ct_123456789",
      "customer_id": "cus_abcdefgh",
      "credit_grant_id": "cg_ijklmnop",
      "type": "consumption",
      "amount": "-100.00",
      "running_balance": "900.00",
      "livemode": true,
      "created_at": "2023-10-27T10:00:00.000Z",
      // ... other fields and expanded objects
    }
    // ... more transactions
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

## Get Usage Summary

Retrieves a summary of credit consumption over a specified period for a customer, subscription, or meter.

**Get Usage Summary**

```javascript
const summary = await payment.creditTransactions.summary({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  start: Math.floor(new Date('2023-01-01').getTime() / 1000),
  end: Math.floor(new Date('2023-12-31').getTime() / 1000),
});

console.log(summary);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `customer_id`  | string  | Optional. The ID of the customer to summarize usage for.  |
| `subscription_id`  | string  | Optional. The ID of the subscription to summarize usage for.  |
| `currency_id`  | string  | Optional. Filter summary by a specific credit currency.  |
| `meter_id`  | string  | Optional. Filter summary by a specific meter.  |
| `start`  | number  | Optional. A Unix timestamp for the beginning of the reporting period.  |
| `end`  | number  | Optional. A Unix timestamp for the end of the reporting period.  |

<strong>Returns</strong>

Returns a `UsageSummary` object detailing the total consumption and transaction count within the specified filters.

**Response Example**

```json
{
  "total_quantity": "1500",
  "total_credit_amount": "-1500.00",
  "transaction_count": 42,
  "filters": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "start_time": "2023-01-01T00:00:00.000Z",
    "end_time": "2023-12-31T00:00:00.000Z"
  }
}
```

---

## Customers

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-customers-381920/

Customer objects allow you to create and manage the customers your business serves. They store essential information such as contact details, addresses, and billing history, which are fundamental for creating subscriptions and processing payments.

## The Customer Object

A Customer object represents a unique customer in your system.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the customer object, starting with `cus_`.  |
| `did`  | string  | The customer's Decentralized Identifier (DID).  |
| `livemode`  | boolean  | `true` if the object exists in live mode, or `false` if it exists in test mode.  |
| `name`  | string  | The customer's full name.  |
| `email`  | string  | The customer's primary email address.  |
| `phone`  | string  | The customer's primary phone number.  |
| `address`  | object  | The customer's billing address. See the Address object properties below.  |
| `balance`  | string  | The current credit balance of the customer.  |
| `delinquent`  | boolean  | Whether the customer has an overdue payment.  |
| `metadata`  | object  | A set of key-value pairs that you can attach to an object.  |
| `created_at`  | string  | The timestamp of when the customer was created.  |
| `updated_at`  | string  | The timestamp of the last update to the customer object.  |

<strong>Address Object Properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `country`  | string  | Two-letter country code (ISO 3166-1 alpha-2).  |
| `state`  | string  | State, province, prefecture, or region.  |
| `city`  | string  | City, district, suburb, town, or village.  |
| `line1`  | string  | Address line 1 (e.g., street, PO Box, or company name).  |
| `line2`  | string  | Address line 2 (e.g., apartment, suite, unit, or building).  |
| `postal_code`  | string  | ZIP or postal code.  |

## Retrieve a Customer

Retrieves the details of an existing customer by providing their unique ID or DID.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | The identifier of the customer to be retrieved (`cus_...` or a DID).  |

### Returns

Returns a `TCustomerExpanded` object if a customer with the given ID exists.

### Example

**Retrieve a Customer**

```javascript
async function retrieveCustomer(customerId) {
  try {
    const customer = await payment.customers.retrieve(customerId);
    console.log('Retrieved customer:', customer);
    return customer;
  } catch (error) {
    console.error('Error retrieving customer:', error.message);
  }
}

// Example usage with a customer ID
retrieveCustomer('cus_xxxxxxxxxxxxxxxx');
```

### Example Response

**Example Customer Object**

```json
{
  "id": "cus_xxxxxxxxxxxxxxxx",
  "did": "zNK...",
  "livemode": true,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "address": {
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "postal_code": "94105"
  },
  "balance": "100.00",
  "delinquent": false,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Update a Customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | The identifier of the customer to be updated.  |
| `data`  | object  | An object containing the fields to update. See details below.  |

<strong>Data Object Properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `name`  | string  | The customer's full name.  |
| `email`  | string  | The customer's email address.  |
| `phone`  | string  | The customer's phone number.  |
| `address`  | object  | The customer's billing address. Follows the Address object structure.  |
| `metadata`  | object  | A set of key-value pairs to store with the customer.  |

### Returns

Returns the updated `TCustomer` object.

### Example

**Update a Customer**

```javascript
async function updateCustomerDetails(customerId) {
  try {
    const updatedCustomer = await payment.customers.update(customerId, {
      email: 'john.new.doe@example.com',
      metadata: {
        internal_id: 'user-456'
      }
    });
    console.log('Customer updated successfully:', updatedCustomer);
    return updatedCustomer;
  } catch (error) {
    console.error('Error updating customer:', error.message);
  }
}

updateCustomerDetails('cus_xxxxxxxxxxxxxxxx');
```

## List all Customers

Returns a paginated list of your customers.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `params`  | object  | An object containing pagination and filtering parameters.  |

<strong>Params Object Properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `did`  | string  | Optional. Filter the list to customers with a specific DID.  |
| `page`  | number  | Optional. The page number to retrieve. Defaults to `1`.  |
| `pageSize`  | number  | Optional. The number of customers to retrieve per page. Defaults to `20`.  |

### Returns

Returns a paginated object containing a `list` of `TCustomerExpanded` objects and pagination details.

### Example

**List Customers**

```javascript
async function listCustomers() {
  try {
    const response = await payment.customers.list({ pageSize: 5 });
    console.log(`Total customers: ${response.count}`);
    console.log('First page of customers:', response.list);
    return response;
  } catch (error) {
    console.error('Error listing customers:', error.message);
  }
}

listCustomers();
```

### Example Response

**Paginated Customer List**

```json
{
  "count": 50,
  "list": [
    {
      "id": "cus_xxxxxxxxxxxxxxxx",
      "did": "zNK...",
      "name": "John Doe",
      "email": "john.doe@example.com",
      // ... other customer fields
    }
    // ... more customer objects
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
```

## Search Customers

Returns a paginated list of customers that match a search query. The search is performed on fields like name, email, and DID.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `params`  | object  | An object containing search and pagination parameters.  |

<strong>Params Object Properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `query`  | string  | The search string.  |
| `page`  | number  | Optional. The page number to retrieve. Defaults to `1`.  |
| `pageSize`  | number  | Optional. The number of customers to retrieve per page. Defaults to `20`.  |

### Returns

Returns a paginated object containing a `list` of `TCustomerExpanded` objects that match the search query.

### Example

**Search for Customers**

```javascript
async function searchForCustomer(query) {
  try {
    const results = await payment.customers.search({ query: query });
    console.log(`Found ${results.count} customer(s) matching '${query}':`, results.list);
    return results;
  } catch (error) {
    console.error('Error searching for customers:', error.message);
  }
}

searchForCustomer('john.doe');
```

## Retrieve Overdue Invoices

Retrieves a list of `uncollectible` invoices for a specific customer, along with a summary of the total amounts due, grouped by currency.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | The identifier of the customer.  |

### Returns

An object containing the customer, a list of their overdue invoices, and a summary of the amounts due.

### Example

**Get Overdue Invoices**

```javascript
async function getOverdueInvoices(customerId) {
  try {
    const overdueData = await payment.customers.overdueInvoices(customerId);
    console.log('Overdue invoices data:', overdueData);
    return overdueData;
  } catch (error) {
    console.error('Error retrieving overdue invoices:', error.message);
  }
}

getOverdueInvoices('cus_xxxxxxxxxxxxxxxx');
```

### Example Response

**Overdue Invoices Response**

```json
{
  "customer": {
    "id": "cus_xxxxxxxxxxxxxxxx",
    // ... customer details
  },
  "invoices": [
    {
      "id": "in_yyyyyyyyyyyyyyyy",
      "status": "uncollectible",
      "amount_remaining": "2500",
      "currency_id": "curr_zzzzzzzzzzzzzzzz",
      // ... other invoice details
    }
  ],
  "summary": {
    "curr_zzzzzzzzzzzzzzzz": {
      "amount": "2500",
      "currency": {
        // ... payment currency details
      },
      "method": {
        // ... payment method details
      }
    }
  }
}
```

---

## Invoices

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-invoices-381920/

The Invoices API allows you to create, manage, and finalize invoices. It provides comprehensive functionality for handling various billing scenarios, including one-time payments, recurring subscriptions, and credit-based billing. You can retrieve detailed invoice information, apply discounts, manage staking operations, and search through historical records.

For more information on related features, see [Subscriptions](/en/docs/payment-kit-sdk/api-reference-subscriptions-381920/) and [Credit-Based Billing](/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/).

## Retrieve an Invoice

Retrieves the details of an existing invoice. This method returns a comprehensive invoice object, including line items, applied discounts, related credit grants, and payment information.

## Parameters

- **id** `string` *(required)* — The unique identifier of the invoice to retrieve.

## Returns

- **Invoice** `object` — An Invoice object with expanded details. See TInvoiceExpanded and the additional properties below for the full structure.
  - **discountDetails** `array` — Details of discounts applied to the invoice.
    - **coupon** `object` — The coupon associated with the discount.
    - **promotionCode** `object` — The promotion code used to apply the discount.
  - **relatedInvoice** `object` — Information about a related invoice, if applicable (e.g., for credit notes).
  - **relatedCreditGrants** `array` — A list of credit grants created as a result of this invoice being paid.
  - **paymentLink** `object` — The payment link used to create the checkout session for this invoice.
  - **checkoutSession** `object` — The checkout session associated with this invoice.

**Retrieve an Invoice**

```javascript
import payment from '@blocklet/payment-js';

async function getInvoice(invoiceId) {
  try {
    const invoice = await payment.invoices.retrieve(invoiceId);
    console.log('Retrieved Invoice:', invoice.id);
    console.log('Discount Details:', invoice.discountDetails);
    console.log('Related Credit Grants:', invoice.relatedCreditGrants);
  } catch (error) {
    console.error('Error retrieving invoice:', error.message);
  }
}

// Example usage:
getInvoice('inv_xxxxxxxxxxxxxx');
```

## List Invoices

Returns a paginated list of your invoices. You can filter the list based on various criteria such as status, customer, or subscription.

## Parameters

- **status** `string` — A comma-separated string of invoice statuses to filter by (e.g., paid,open).
- **customer_id** `string` — Filter invoices by a specific customer ID.
- **customer_did** `string` — Filter invoices by the customer's DID.
- **subscription_id** `string` — Filter invoices by a specific subscription ID.
- **currency_id** `string` — Filter invoices by a specific currency ID.
- **ignore_zero** `boolean` (default: `false`) — If true, invoices with a subtotal of zero will be excluded.
- **include_staking** `boolean` (default: `false`) — If true, staking-related invoices will be included in the results.
- **include_return_staking** `boolean` (default: `false`) — If true, invoices related to returned stakes will be included.
- **include_overdraft_protection** `boolean` (default: `true`) — If true, invoices for stake overdraft protection will be included.
- **include_recovered_from** `boolean` (default: `false`) — If true, invoices from previous subscriptions in a recovery chain will be included.
- **metadata.{key}** `string` — Filter by custom metadata fields. Replace {key} with your metadata key.
- **page** `number` (default: `1`) — The page number for pagination.
- **pageSize** `number` (default: `20`) — The number of items to return per page.

## Returns

- **PaginatedInvoices** `object` — An object containing a list of invoices and pagination information.
  - **list** `array` — An array of `Invoice` objects.
  - **count** `number` — The total number of invoices matching the filter criteria.
  - **paging** `object` — Pagination details.
    - **page** `number` — The current page number.
    - **pageSize** `number` — The number of items per page.

**List Invoices**

```javascript
import payment from '@blocklet/payment-js';

async function listPaidInvoices() {
  try {
    const invoices = await payment.invoices.list({
      status: 'paid',
      customer_id: 'cus_xxxxxxxxxxxxxx',
      ignore_zero: true,
      pageSize: 10,
    });
    console.log(`Found ${invoices.count} paid invoices.`);
    invoices.list.forEach(invoice => {
      console.log(`- Invoice ID: ${invoice.id}, Amount: ${invoice.total}`);
    });
  } catch (error) {
    console.error('Error listing invoices:', error.message);
  }
}

listPaidInvoices();
```

## Search Invoices

Performs a search for invoices matching a query string across various fields like invoice number, customer details, and line item descriptions.

## Parameters

- **q** `string` *(required)* — The search query string.
- **page** `number` (default: `1`) — The page number for pagination.
- **pageSize** `number` (default: `20`) — The number of items to return per page.

## Returns

- **PaginatedInvoices** `object` — An object containing a list of invoices and pagination information.
  - **list** `array` — An array of `Invoice` objects.
  - **count** `number` — The total number of invoices matching the search criteria.
  - **paging** `object` — Pagination details.
    - **page** `number` — The current page number.
    - **pageSize** `number` — The number of items per page.

**Search Invoices**

```javascript
import payment from '@blocklet/payment-js';

async function searchForInvoice(query) {
  try {
    const results = await payment.invoices.search({ q: query, pageSize: 5 });
    console.log(`Found ${results.count} results for query: '${query}'`);
    results.list.forEach(invoice => {
      console.log(`- Invoice ID: ${invoice.id}, Customer: ${invoice.customer.did}`);
    });
  } catch (error) {
    console.error('Error searching invoices:', error.message);
  }
}

// Example usage:
searchForInvoice('Premium Plan');
```

## Update an Invoice

Updates the specified invoice by setting the `metadata` key-value pairs. Other invoice properties are generally not updatable.

## Parameters

- **id** `string` *(required)* — The unique identifier of the invoice to update.
- **metadata** `object` — A set of key-value pairs to store with the invoice object. Keys can be up to 40 characters long and values can be up to 500 characters long.

## Returns

- **Invoice** `object` — The updated Invoice object.

**Update Invoice Metadata**

```javascript
import payment from '@blocklet/payment-js';

async function updateInvoiceMetadata(invoiceId) {
  try {
    const updatedInvoice = await payment.invoices.update(invoiceId, {
      metadata: { order_id: 'order_12345' },
    });
    console.log('Invoice metadata updated:', updatedInvoice.metadata);
  } catch (error) {
    console.error('Error updating invoice:', error.message);
  }
}

// Example usage:
updateInvoiceMetadata('inv_xxxxxxxxxxxxxx');
```

## Void an Invoice

Voids an invoice. This action is only possible on an invoice that is `open` or `uncollectible`. Once voided, an invoice cannot be paid.

## Parameters

- **id** `string` *(required)* — The unique identifier of the invoice to void.

## Returns

- **Invoice** `object` — The voided Invoice object, with its status set to void.

**Void an Invoice**

```javascript
import payment from '@blocklet/payment-js';

async function voidInvoice(invoiceId) {
  try {
    const voidedInvoice = await payment.invoices.void(invoiceId);
    console.log(`Invoice ${voidedInvoice.id} has been voided. Status: ${voidedInvoice.status}`);
  } catch (error) {
    console.error('Error voiding invoice:', error.message);
  }
}

// Example usage:
voidInvoice('inv_xxxxxxxxxxxxxx');
```

## Get Return Stake Information

Retrieves the amount of stake that can be returned for a `stake` or `stake_overdraft_protection` invoice.

## Parameters

- **id** `string` *(required)* — The identifier of the staking invoice.

## Returns

- **StakeInfo** `object` — An object containing details about the remaining stake.

**Get Returnable Stake**

```javascript
import payment from '@blocklet/payment-js';

async function getStakeInfo(invoiceId) {
  try {
    const stakeInfo = await payment.invoices.getReturnStake(invoiceId);
    console.log('Returnable Stake Information:', stakeInfo);
  } catch (error) {
    console.error('Error getting stake info:', error.message);
  }
}

// Example usage:
getStakeInfo('inv_stake_xxxxxx');
```

## Return Stake

Initiates the process of returning a stake associated with a paid `stake` or `stake_overdraft_protection` invoice.

## Parameters

- **id** `string` *(required)* — The identifier of the staking invoice.

## Returns

- **ReturnResult** `object` — An object indicating the result of the operation.
  - **success** `boolean` — Indicates if the return stake process was successfully initiated.
  - **subscriptionId** `string` — The ID of the associated subscription.
  - **error** `string` — An error message if the operation failed.

**Return a Stake**

```javascript
import payment from '@blocklet/payment-js';

async function returnStake(invoiceId) {
  try {
    const result = await payment.invoices.returnStake(invoiceId);
    if (result.success) {
      console.log(`Stake return initiated for subscription: ${result.subscriptionId}`);
    } else {
      console.error('Failed to return stake:', result.error);
    }
  } catch (error) {
    console.error('Error returning stake:', error.message);
  }
}

// Example usage:
returnStake('inv_stake_xxxxxx');
```

---

## Meter Events

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-meter-events-381920/

Meter Events are records of usage that you report to a specific `Meter`. Each event represents a quantifiable action performed by a customer, which can then be used to deduct credits from their balance in a usage-based or credit billing model. Before reporting events, you must first create a [Meter](/en/docs/payment-kit-sdk/api-reference-meters-381920/).

This API allows you to create, retrieve, list, and analyze meter events.

## The Meter Event Object

A Meter Event object represents a single reported usage event. The expanded form includes related objects like the customer and subscription.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the meter event.  |
| `event_name`  | `string`  | The name of the event, which corresponds to the `event_name` of an associated Meter.  |
| `payload`  | `object`  | Contains the core details of the event, such as the customer ID and usage value.  |
| `identifier`  | `string`  | A unique identifier for the event provided by you to ensure idempotency. Subsequent `create` calls with the same identifier will not create a new event.  |
| `status`  | `string`  | The processing status of the event. Can be `pending`, `processed`, `failed`, `requires_action`, or `requires_capture`.  |
| `livemode`  | `boolean`  | `true` if the event was created in live mode, `false` for test mode.  |
| `credit_consumed`  | `string`  | The amount of credit consumed by this event after processing.  |
| `credit_pending`  | `string`  | The amount of credit that is pending consumption for this event.  |
| `timestamp`  | `number`  | The Unix timestamp when the event occurred.  |
| `created_at`  | `string`  | The timestamp when the event was created in the system.  |
| `metadata`  | `object`  | A set of key-value pairs that you can attach to the event.  |
| `customer`  | `object`  | (Expanded) The full Customer object associated with this event.  |
| `subscription`  | `object`  | (Expanded) The full Subscription object if the event is linked to one.  |
| `meter`  | `object`  | (Expanded) The full Meter object associated with this event.  |

## Create a Meter Event

Reports a usage event to the system. This action is idempotent; if an event with the same `identifier` already exists, the system will not create a new one.

**Create a Meter Event**

```javascript
const event = await payment.meterEvents.create({
  event_name: 'api_calls',
  identifier: 'unique-event-id-12345',
  payload: {
    customer_id: 'cus_xxxxxxxxxxxxxx',
    value: '100',
    subscription_id: 'sub_xxxxxxxxxxxxxx' // Optional
  },
  timestamp: Math.floor(Date.now() / 1000),
  metadata: {
    region: 'us-west'
  }
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `event_name`  | `string`  | <strong>Required.</strong> The name of the event. This must match the `event_name` of an active `Meter`.  |
| `identifier`  | `string`  | <strong>Required.</strong> A unique string to identify this event, used for idempotency. Maximum 255 characters.  |
| `payload`  | `object`  | <strong>Required.</strong> An object containing the event's core data. See details below.  |
| `timestamp`  | `number`  | <em>Optional.</em> A Unix timestamp representing when the event occurred. If not provided, it defaults to the time of the API call.  |
| `metadata`  | `Record<string, any>`  | <em>Optional.</em> A set of key-value pairs to store additional information about the event.  |

<strong>Payload Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `customer_id`  | `string`  | <strong>Required.</strong> The ID of the customer who triggered the event.  |
| `value`  | `string`  | <strong>Required.</strong> The amount of usage to report. This should be a positive number represented as a string.  |
| `subscription_id`  | `string`  | <em>Optional.</em> The ID of the subscription to associate this usage with. The subscription must consume credits.  |

### Returns

Returns the created Meter Event object. Upon creation, the event is queued for asynchronous processing. The returned object includes a `processing` field that indicates its queued status.

**Response**

```json
{
  "id": "mevt_xxxxxxxxxxxxxx",
  "event_name": "api_calls",
  "payload": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "value": "100",
    "subscription_id": "sub_xxxxxxxxxxxxxx"
  },
  "identifier": "unique-event-id-12345",
  "status": "pending",
  "livemode": false,
  "credit_consumed": "0",
  "credit_pending": "100",
  "timestamp": 1678886400,
  "created_at": "2023-03-15T12:00:00.000Z",
  "metadata": {
    "region": "us-west"
  },
  "processing": {
    "queued": true,
    "message": "Credit consumption will be processed asynchronously"
  }
}
```

## Retrieve a Meter Event

Retrieves the details of a specific meter event by its unique ID.

**Retrieve a Meter Event**

```javascript
const eventId = 'mevt_xxxxxxxxxxxxxx';
const event = await payment.meterEvents.retrieve(eventId);
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier of the meter event to retrieve.  |

### Returns

Returns the Meter Event object, including expanded `customer`, `subscription`, and `meter` details if available.

**Response**

```json
{
  "id": "mevt_xxxxxxxxxxxxxx",
  "event_name": "api_calls",
  "payload": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "value": "100"
  },
  "identifier": "unique-event-id-12345",
  "status": "processed",
  "livemode": false,
  "credit_consumed": "100",
  "credit_pending": "0",
  "timestamp": 1678886400,
  "created_at": "2023-03-15T12:00:00.000Z",
  "metadata": {},
  "customer": { /* Customer object */ },
  "subscription": { /* Subscription object */ },
  "meter": { /* Meter object */ }
}
```

## List Meter Events

Returns a paginated list of meter events. You can filter the list using various parameters.

**List Meter Events**

```javascript
const events = await payment.meterEvents.list({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  start: 1672531200, // January 1, 2023
  limit: 10
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `customer_id`  | `string`  | <em>Optional.</em> Filter events by a specific customer ID.  |
| `meter_id`  | `string`  | <em>Optional.</em> Filter events associated with a specific meter ID.  |
| `event_name`  | `string`  | <em>Optional.</em> Filter events by their name.  |
| `start`  | `number`  | <em>Optional.</em> A Unix timestamp to filter events created on or after this time.  |
| `end`  | `number`  | <em>Optional.</em> A Unix timestamp to filter events created on or before this time.  |
| `livemode`  | `boolean`  | <em>Optional.</em> Filter events by their `livemode` status.  |
| `q`  | `string`  | <em>Optional.</em> A general search query string.  |
| `page`  | `number`  | <em>Optional.</em> The page number for pagination, starting from 1.  |
| `pageSize`  | `number`  | <em>Optional.</em> The number of events to return per page. Defaults to 20.  |

### Returns

Returns a paginated object containing a list of Meter Event objects.

**Response**

```json
{
  "count": 15,
  "list": [
    {
      "id": "mevt_xxxxxxxxxxxxxx",
      "event_name": "api_calls",
      // ... other event properties
    }
    // ... more events
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

## Get Meter Event Stats

Retrieves aggregated statistics for a given meter over a specified time period.

**Get Meter Event Stats**

```javascript
const stats = await payment.meterEvents.stats({
  meter_id: 'mtr_xxxxxxxxxxxxxx',
  start: 1672531200, // January 1, 2023
  end: 1675209600,   // February 1, 2023
  granularity: 'day'
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `meter_id`  | `string`  | <strong>Required.</strong> The ID of the meter to retrieve statistics for.  |
| `start`  | `number`  | <strong>Required.</strong> A Unix timestamp for the beginning of the time range.  |
| `end`  | `number`  | <strong>Required.</strong> A Unix timestamp for the end of the time range.  |
| `customer_id`  | `string`  | <em>Optional.</em> Filter statistics for a specific customer.  |
| `granularity`  | `string`  | <em>Optional.</em> The temporal granularity of the statistics. Can be `'minute'`, `'hour'`, or `'day'`. Defaults to `'day'`.  |

### Returns

Returns a list of statistical data points, aggregated by the specified granularity.

**Response**

```json
{
  "count": 31,
  "list": [
    {
      "date": "2023-01-01",
      "timestamp": "2023-01-01T00:00:00.000Z",
      "event_count": 500,
      "total_value": "5000"
    },
    {
      "date": "2023-01-02",
      "timestamp": "2023-01-02T00:00:00.000Z",
      "event_count": 750,
      "total_value": "7500"
    }
    // ... more data points
  ]
}
```

## Get Pending Amount

Calculates the total value of meter events that are pending processing and require action (e.g., have not yet consumed credit). This is useful for understanding outstanding usage.

**Get Pending Amount**

```javascript
const pending = await payment.meterEvents.pendingAmount({
  customer_id: 'cus_xxxxxxxxxxxxxx'
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `subscription_id`  | `string`  | <em>Optional.</em> Filter by a specific subscription ID.  |
| `customer_id`  | `string`  | <em>Optional.</em> Filter by a specific customer ID.  |
| `currency_id`  | `string`  | <em>Optional.</em> Filter by a specific currency ID.  |

### Returns

Returns an object summarizing the total pending amounts, grouped by currency.

**Response**

```json
{
  "currency_id": "ccy_xxxxxxxxxxxxxx",
  "total_pending_amount": "12500",
  "currency": {
    "id": "ccy_xxxxxxxxxxxxxx",
    "name": "Credit",
    "decimal": 2
  }
}
```

---

## Meters

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-meters-381920/

Meters are used to define and track usage for credit-based billing. They represent a specific feature or resource that you bill for, such as API calls, data storage, or compute time. Each meter aggregates usage events sent to it.

Once a meter is created, you can report usage against it using [Meter Events](/en/docs/payment-kit-sdk/api-reference-meter-events-381920/). This is a core component of implementing a [Credit-Based Billing](/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/) model.

## The Meter Object

A Meter object contains all the information about a specific usage tracker.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the meter.  |
| `name`  | string  | The display name of the meter.  |
| `event_name`  | string  | A unique name for the event this meter tracks. This is used when reporting usage.  |
| `aggregation_method`  | string  | The method used to aggregate usage. Currently, only `sum` is supported.  |
| `unit`  | string  | The unit of measurement for the usage (e.g., 'requests', 'gb', 'credits').  |
| `status`  | string  | The current status of the meter. Can be `active` or `inactive`. Inactive meters do not accept new events.  |
| `livemode`  | boolean  | `true` if the meter was created in live mode, `false` for test mode.  |
| `currency_id`  | string  | The ID of the payment currency associated with this meter.  |
| `description`  | string  | An optional description of the meter.  |
| `metadata`  | object  | A set of key-value pairs that you can attach to an object. Useful for storing additional information.  |
| `paymentCurrency`  | object  | The expanded payment currency object associated with the meter.  |

<strong>The</strong> <strong>`paymentCurrency`</strong> <strong>Object Properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the currency.  |
| `name`  | string  | The name of the currency (e.g., 'API Credits').  |
| `symbol`  | string  | The symbol for the currency (e.g., 'AC').  |
| `decimal`  | number  | The number of decimal places for the currency.  |
| `type`  | string  | The type of currency.  |

## Create a Meter

Creates a new meter to track usage of a specific feature.

<strong>Parameters</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `name`  | string  | <strong>Required.</strong> The display name of the meter. Maximum 64 characters.  |
| `event_name`  | string  | <strong>Required.</strong> A unique name for the event this meter tracks. This is used when reporting usage. Maximum 64 characters.  |
| `unit`  | string  | <strong>Required.</strong> The unit of measurement for the usage (e.g., 'requests', 'gb', 'credits'). Maximum 32 characters.  |
| `aggregation_method`  | string  | Optional. The method to aggregate usage. Defaults to `sum`. Currently, this is the only supported value.  |
| `currency_id`  | string  | Optional. The ID of the payment currency to associate with this meter. If not provided, a new credit currency will be created automatically.  |
| `description`  | string  | Optional. A description of what this meter tracks. Maximum 255 characters.  |
| `metadata`  | object  | Optional. A set of key-value pairs to store additional information about the meter.  |

<strong>Returns</strong>

Returns the newly created `Meter` object.

**Create a Meter**

```javascript
import payment from '@blocklet/payment-js';

async function createMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.v1',
      unit: 'requests',
      description: 'Tracks the number of API calls made.',
    });
    console.log('Meter created:', meter);
  } catch (error) {
    console.error('Error creating meter:', error.message);
  }
}

createMeter();
```

<strong>Example Response</strong>

```json
{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks the number of API calls made.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}
```

## Retrieve a Meter

Retrieves the details of an existing meter. You can retrieve a meter by its unique ID or its `event_name`.

<strong>Parameters</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID or `event_name` of the meter to retrieve.  |

<strong>Returns</strong>

Returns the `Meter` object if found.

**Retrieve a Meter**

```javascript
import payment from '@blocklet/payment-js';

async function retrieveMeter(meterId) {
  try {
    const meter = await payment.meters.retrieve(meterId);
    console.log('Retrieved meter:', meter);
  } catch (error) {
    console.error('Error retrieving meter:', error.message);
  }
}

retrieveMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');
```

<strong>Example Response</strong>

```json
{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks the number of API calls made.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}
```

## Update a Meter

Updates an existing meter by setting the values of the parameters passed.

<strong>Parameters</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the meter to update.  |
| `name`  | string  | Optional. A new display name for the meter.  |
| `description`  | string  | Optional. An updated description for the meter.  |
| `status`  | string  | Optional. The new status. Can be `active` or `inactive`.  |
| `unit`  | string  | Optional. A new unit of measurement for the usage.  |
| `metadata`  | object  | Optional. A set of key-value pairs to update on the meter.  |

<strong>Returns</strong>

Returns the updated `Meter` object.

**Update a Meter**

```javascript
import payment from '@blocklet/payment-js';

async function updateMeter(meterId) {
  try {
    const meter = await payment.meters.update(meterId, {
      name: 'API Calls (V2)',
      description: 'Tracks V2 API calls.',
    });
    console.log('Meter updated:', meter);
  } catch (error) {
    console.error('Error updating meter:', error.message);
  }
}

updateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');
```

<strong>Example Response</strong>

```json
{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls (V2)",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks V2 API calls.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:01:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}
```

## List all Meters

Returns a paginated list of your meters. You can filter the list based on various criteria.

<strong>Parameters</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `page`  | number  | Optional. The page number for pagination, starting at 1. Defaults to 1.  |
| `pageSize`  | number  | Optional. The number of items to return per page. Defaults to 20.  |
| `event_name`  | string  | Optional. Filter meters by a specific event name.  |
| `livemode`  | boolean  | Optional. Filter meters by their live mode status.  |
| `q`  | string  | Optional. A search query string that filters results based on matching `name` or `description`.  |

<strong>Returns</strong>

Returns a paginated object containing a list of `Meter` objects.

| Attribute  | Type  | Description  |
|---|---|---|
| `count`  | number  | The total number of meters matching the query.  |
| `list`  | array  | An array of `Meter` objects for the current page.  |
| `paging`  | object  | An object containing pagination information (`page`, `pageSize`).  |

**List all Meters**

```javascript
import payment from '@blocklet/payment-js';

async function listMeters() {
  try {
    const result = await payment.meters.list({
      pageSize: 5,
      livemode: false,
    });
    console.log(`Found ${result.count} meters.`);
    console.log('Meters on this page:', result.list);
  } catch (error) {
    console.error('Error listing meters:', error.message);
  }
}

listMeters();
```

<strong>Example Response</strong>

```json
{
  "count": 20,
  "list": [
    {
      "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
      "name": "API Calls",
      "event_name": "api.calls.v1",
      "status": "active",
      "livemode": false
    },
    {
      "id": "mtr_2K8mN3kR7G0p4wYcZ0u9sHdF",
      "name": "Data Storage",
      "event_name": "data.storage.gb",
      "status": "active",
      "livemode": false
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
```

## Activate a Meter

Activates an inactive meter. Once activated, the meter will start accepting usage events.

<strong>Parameters</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the meter to activate.  |

<strong>Returns</strong>

Returns the activated `Meter` object.

**Activate a Meter**

```javascript
import payment from '@blocklet/payment-js';

async function activateMeter(meterId) {
  try {
    const meter = await payment.meters.activate(meterId);
    console.log(`Meter ${meter.id} is now ${meter.status}.`);
  } catch (error) {
    console.error('Error activating meter:', error.message);
  }
}

activateMeter('mtr_some_inactive_meter_id');
```

## Deactivate a Meter

Deactivates a meter. The meter will stop accepting new usage events until it is reactivated.

<strong>Parameters</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the meter to deactivate.  |

<strong>Returns</strong>

Returns the deactivated `Meter` object.

**Deactivate a Meter**

```javascript
import payment from '@blocklet/payment-js';

async function deactivateMeter(meterId) {
  try {
    const meter = await payment.meters.deactivate(meterId);
    console.log(`Meter ${meter.id} is now ${meter.status}.`);
  } catch (error) {
    console.error('Error deactivating meter:', error.message);
  }
}

deactivateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');
```

After creating and configuring your meters, the next step is to report usage. See the [Meter Events](/en/docs/payment-kit-sdk/api-reference-meter-events-381920/) documentation to learn how.

---

## Payment Currencies

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-payment-currencies-381920/

The Payment Currencies API allows you to manage the currencies accepted for payments. This includes standard blockchain-based tokens (like ERC-20 or ArcBlock native tokens) as well as custom credit currencies used for implementing credit-based billing systems.

Each payment currency is linked to a specific [Payment Method](/en/docs/payment-kit-sdk/api-reference-payment-methods-381920/), which defines the underlying network or system (e.g., Ethereum, ArcBlock).

## The Payment Currency Object

A `PaymentCurrency` object contains all the details about a currency available for transactions.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the payment currency object.  |
| `name`  | `string`  | The full name of the currency (e.g., "Ethereum Tether").  |
| `description`  | `string`  | A brief description of the currency.  |
| `logo`  | `string`  | URL of an image representing the currency.  |
| `symbol`  | `string`  | A short, recognizable symbol for the currency (e.g., "USDT").  |
| `decimal`  | `number`  | The number of decimal places the currency has.  |
| `contract`  | `string`  | The contract address for token-based currencies.  |
| `type`  | `string`  | The type of currency. Can be `standard` for regular tokens or `credit` for custom credit systems.  |
| `active`  | `boolean`  | Whether this currency is currently available for use.  |
| `livemode`  | `boolean`  | `true` if the currency is in live mode, `false` for test mode.  |
| `is_base_currency`  | `boolean`  | Indicates if this is a native chain token.  |
| `payment_method_id`  | `string`  | The ID of the associated `PaymentMethod`.  |
| `recharge_config`  | `object`  | For credit currencies, this object contains the configuration for topping up credit balances. See the `getRechargeConfig` method for details.  |
| `metadata`  | `object`  | A set of key-value pairs that you can attach to an object.  |

## Create a Payment Currency

Creates a new payment currency. This is typically used to add support for a new ERC-20 token or a similar asset on a supported blockchain.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `name`  | `string`  | <strong>Required.</strong> The name of the currency. Maximum 32 characters.  |
| `description`  | `string`  | <strong>Required.</strong> A description for the currency. Maximum 255 characters.  |
| `payment_method_id`  | `string`  | <strong>Required.</strong> The ID of the payment method this currency belongs to (e.g., an Ethereum payment method).  |
| `contract`  | `string`  | <strong>Required.</strong> The contract address of the token. The system will verify this contract on the corresponding network.  |
| `logo`  | `string`  | <em>Optional.</em> A URL for the currency's logo. If not provided, the logo of the payment method will be used.  |

### Returns

Returns the newly created `PaymentCurrency` object.

**Create a new payment currency**

```javascript
import payment from '@blocklet/payment-js';

async function createCurrency() {
  try {
    const newCurrency = await payment.paymentCurrencies.create({
      name: 'My Custom Token',
      description: 'An ERC-20 token for our platform',
      payment_method_id: 'pm_xxxxxxxxxxxxxx', // ID of an EVM-based payment method
      contract: '0x..._token_contract_address',
      logo: 'https://example.com/token_logo.png',
    });
    console.log('Payment Currency created:', newCurrency);
  } catch (error) {
    console.error('Error creating payment currency:', error.message);
  }
}

createCurrency();
```

**Response Example**

```json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "livemode": false,
  "active": true,
  "locked": false,
  "is_base_currency": false,
  "payment_method_id": "pm_xxxxxxxxxxxxxx",
  "name": "My Custom Token",
  "description": "An ERC-20 token for our platform",
  "contract": "0x..._token_contract_address",
  "logo": "https://example.com/token_logo.png",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Retrieve a Payment Currency

Retrieves the details of an existing payment currency by its unique ID or symbol.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier (`curr_...`) or the symbol (e.g., `USDT`) of the payment currency to retrieve.  |

### Returns

Returns the corresponding `PaymentCurrency` object if found, otherwise returns a 404 error.

**Retrieve a payment currency**

```javascript
import payment from '@blocklet/payment-js';

async function getCurrency(currencyId) {
  try {
    const currency = await payment.paymentCurrencies.retrieve(currencyId);
    console.log('Retrieved Currency:', currency);
  } catch (error) {
    console.error('Error retrieving currency:', error.message);
  }
}

// Retrieve by ID
getCurrency('curr_xxxxxxxxxxxxxx');

// Or, retrieve by symbol
// getCurrency('USDT');
```

**Response Example**

```json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "livemode": false,
  "active": true,
  "name": "My Custom Token",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Update a Payment Currency

Updates the specified payment currency by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the payment currency to update.  |
| `updateData`  | `object`  | <strong>Required.</strong> An object containing the fields to update.  |
| `updateData.name`  | `string`  | <em>Optional.</em> A new name for the currency.  |
| `updateData.description`  | `string`  | <em>Optional.</em> A new description for the currency.  |
| `updateData.logo`  | `string`  | <em>Optional.</em> A new logo URL for the currency.  |
| `updateData.metadata`  | `object`  | <em>Optional.</em> A set of key-value pairs to store with the object.  |
| `updateData.symbol`  | `string`  | <em>Optional.</em> For `credit` type currencies only, updates the symbol.  |

### Returns

Returns the updated `PaymentCurrency` object.

**Update a payment currency**

```javascript
import payment from '@blocklet/payment-js';

async function updateCurrency(currencyId) {
  try {
    const updatedCurrency = await payment.paymentCurrencies.update(currencyId, {
      description: 'An updated description for my token.'
    });
    console.log('Currency updated:', updatedCurrency);
  } catch (error) {
    console.error('Error updating currency:', error.message);
  }
}

updateCurrency('curr_xxxxxxxxxxxxxx');
```

**Response Example**

```json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "name": "My Custom Token",
  "description": "An updated description for my token.",
  "symbol": "MCT",
  "decimal": 18,
  "updated_at": "2023-10-27T11:30:00.000Z"
}
```

## List Payment Currencies

Returns a list of your payment currencies. The currencies are returned sorted by creation date, with the most recently created currencies appearing first.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `filters`  | `object`  | <em>Optional.</em> An object containing filter criteria.  |
| `filters.active`  | `boolean`  | <em>Optional.</em> Filters the list to only include active or inactive currencies.  |
| `filters.livemode`  | `boolean`  | <em>Optional.</em> Filters the list based on the environment (live or test).  |
| `filters.credit`  | `boolean`  | <em>Optional.</em> If `true`, the list will include currencies of type `credit` in addition to `standard` currencies.  |

### Returns

Returns an array of `PaymentCurrency` objects.

**List all active currencies**

```javascript
import payment from '@blocklet/payment-js';

async function listCurrencies() {
  try {
    const currencies = await payment.paymentCurrencies.list({ active: true });
    console.log(`Found ${currencies.length} active currencies.`);
    currencies.forEach(c => console.log(`- ${c.name} (${c.symbol})`));
  } catch (error) {
    console.error('Error listing currencies:', error.message);
  }
}

listCurrencies();
```

**Response Example**

```json
[
  {
    "id": "curr_xxxxxxxxxxxxxx",
    "name": "My Custom Token",
    "symbol": "MCT",
    "active": true
  },
  {
    "id": "curr_yyyyyyyyyyyyyy",
    "name": "Another Token",
    "symbol": "ATK",
    "active": true
  }
]
```

## Get Recharge Configuration

Retrieves the recharge configuration for a `credit` type currency. This configuration defines how users can purchase or top up their balance for that credit.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the credit currency (`curr_...`).  |

### Returns

Returns a configuration object with details about how to recharge the specified credit currency.

| Name  | Type  | Description  |
|---|---|---|
| `currency_id`  | `string`  | The ID of the credit currency.  |
| `currency_info`  | `object`  | Basic information about the credit currency (`id`, `name`, `symbol`, `decimal`, `type`).  |
| `recharge_config`  | `object`  | An object detailing the recharge mechanism.  |
| `recharge_config.base_price_id`  | `string`  | The ID of the `Price` object that serves as the base for purchasing credits.  |
| `recharge_config.payment_url`  | `string`  | A direct URL to a checkout page for purchasing credits.  |
| `recharge_config.basePrice`  | `object`  | The full `Price` object associated with `base_price_id`, including product details.  |
| `recharge_config.settings`  | `object`  | Additional settings for recharging.  |
| `recharge_config.settings.min_recharge_amount`  | `number`  | The minimum amount of credit that can be recharged in a single transaction.  |
| `recharge_config.settings.max_recharge_amount`  | `number`  | The maximum amount of credit that can be recharged in a single transaction.  |

**Get credit recharge configuration**

```javascript
import payment from '@blocklet/payment-js';

async function getRechargeConfig(creditCurrencyId) {
  try {
    const config = await payment.paymentCurrencies.getRechargeConfig(creditCurrencyId);
    console.log('Recharge Config:', config);
    if (config.recharge_config) {
      console.log(`Payment URL: ${config.recharge_config.payment_url}`);
    }
  } catch (error) {
    console.error('Error getting recharge config:', error.message);
  }
}

getRechargeConfig('curr_zzzzzzzzzzzzzz'); // ID of a credit currency
```

**Response Example**

```json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "currency_info": {
    "id": "curr_zzzzzzzzzzzzzz",
    "name": "Platform Credits",
    "symbol": "PCC",
    "decimal": 2,
    "type": "credit"
  },
  "recharge_config": {
    "base_price_id": "price_xxxxxxxxxxxxxx",
    "payment_url": "https://your-app.arcblock.io/checkout/pay/pl_xxxxxxxxxxxxxx",
    "basePrice": {
      "id": "price_xxxxxxxxxxxxxx",
      "unit_amount": "1.00",
      // ... other price details
      "product": {
        "id": "prod_xxxxxxxxxxxxxx",
        "name": "Credit Top-up"
      }
    },
    "settings": {
      "min_recharge_amount": 10,
      "max_recharge_amount": 1000
    }
  }
}
```

## Update Recharge Configuration

Updates the recharge configuration for a `credit` type currency. While this can be done programmatically, it is recommended to manage these settings through the PaymentKit dashboard for a better user experience.

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the credit currency to update.  |
| `config`  | `object`  | <strong>Required.</strong> The new configuration object.  |
| `config.base_price_id`  | `string`  | <strong>Required.</strong> The ID of a `Price` object that defines the cost per credit. The price must be active.  |
| `config.payment_link_id`  | `string`  | <em>Optional.</em> The ID of a pre-configured `PaymentLink` to use for recharge.  |
| `config.checkout_url`  | `string`  | <em>Optional.</em> A custom URL for the checkout page.  |
| `config.settings`  | `object`  | <em>Optional.</em> An object for recharge limits.  |
| `config.settings.min_recharge_amount`  | `number`  | <em>Optional.</em> The minimum amount of credits a user can purchase at one time.  |
| `config.settings.max_recharge_amount`  | `number`  | <em>Optional.</em> The maximum amount of credits a user can purchase at one time.  |

### Returns

Returns an object confirming that the recharge configuration has been updated successfully.

**Update credit recharge configuration**

```javascript
import payment from '@blocklet/payment-js';

async function updateRechargeConfig(creditCurrencyId) {
  try {
    const result = await payment.paymentCurrencies.updateRechargeConfig(creditCurrencyId, {
      base_price_id: 'price_yyyyyyyyyyyyyy', // A new price ID
      settings: {
        min_recharge_amount: 5
      }
    });
    console.log(result.message);
  } catch (error) {
    console.error('Error updating recharge config:', error.message);
  }
}

updateRechargeConfig('curr_zzzzzzzzzzzzzz');
```

**Response Example**

```json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "recharge_config": {
    "base_price_id": "price_yyyyyyyyyyyyyy",
    "settings": {
      "min_recharge_amount": 5
    }
  },
  "message": "Recharge config updated successfully"
}
```

---

## Payment Intents

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-payment-intents-381920/

A Payment Intent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process. It is a central object in the PaymentKit API, controlling the flow of funds from the customer to you. A Payment Intent can be associated with a [Checkout Session](/en/docs/payment-kit-sdk/api-reference-checkout-sessions-381920/) for a user-facing payment flow or used directly for server-side operations.

This document details how to manage Payment Intent objects using the SDK.

## The Payment Intent Object

A Payment Intent object contains detailed information about a transaction. When expanded, it can also include related objects.

<strong>Object Properties</strong>

| Property  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the object.  |
| `status`  | `string`  | The status of the payment intent. Possible values are `requires_payment_method`, `requires_confirmation`, `requires_action`, `processing`, `requires_capture`, `canceled`, or `succeeded`.  |
| `amount`  | `string`  | The amount intended to be collected.  |
| `amount_received`  | `string`  | The amount received so far.  |
| `currency_id`  | `string`  | The ID of the currency for this payment.  |
| `customer_id`  | `string`  | The ID of the Customer this Payment Intent is for, if one exists.  |
| `invoice_id`  | `string`  | The ID of the Invoice this Payment Intent is for, if one exists.  |
| `payment_method_id`  | `string`  | The ID of the PaymentMethod used for this Payment Intent.  |
| `metadata`  | `object`  | A set of key-value pairs that you can attach to an object.  |
| `created_at`  | `string`  | Timestamp of when the object was created.  |

<strong>Expanded Objects</strong>

When retrieved, the Payment Intent object can include the following expanded objects:

- `customer`: The full `Customer` object.
- `paymentCurrency`: The full `PaymentCurrency` object.
- `paymentMethod`: The full `PaymentMethod` object.
- `invoice`: The full `Invoice` object (when applicable).
- `subscription`: The full `Subscription` object (when applicable).
- `checkoutSession`: The `CheckoutSession` that created this payment intent.

## Retrieve a Payment Intent

Retrieves the details of a Payment Intent that has previously been created. Client-side retrieval using a publishable key is allowed when the `client_secret` is provided.

**Retrieve a Payment Intent**

```javascript
const paymentIntent = await payment.paymentIntents.retrieve(
  'pi_123456789'
);

console.log(paymentIntent);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the Payment Intent to retrieve.  |

<strong>Returns</strong>

Returns a `PaymentIntent` object if a valid ID was provided. Throws an error otherwise.

**Response Example**

```json
{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "amount_received": "1000",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "invoice_id": "in_xxxxxxxx",
  "payment_method_id": "pm_xxxxxxxx",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    /* ... payment currency details ... */
  },
  "paymentMethod": {
    /* ... payment method details ... */
  },
  "customer": {
    /* ... customer details ... */
  },
  "invoice": {
    /* ... invoice details ... */
  },
  "subscription": null,
  "checkoutSession": {
    /* ... checkout session details ... */
  }
}
```

## Update a Payment Intent

Updates a Payment Intent object by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that only the `metadata` can be updated via this method.

**Update a Payment Intent**

```javascript
const paymentIntent = await payment.paymentIntents.update(
  'pi_123456789',
  {
    metadata: { order_id: '6735' }
  }
);

console.log(paymentIntent);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the Payment Intent to update.  |
| `metadata`  | `object`  | A set of key-value pairs to store on the object.  |

<strong>Returns</strong>

Returns the updated `PaymentIntent` object.

**Response Example**

```json
{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "metadata": {
    "order_id": "6735"
  },
  // ... other properties
}
```

## List all Payment Intents

Returns a list of your Payment Intents. The intents are returned sorted by creation date, with the most recent intents appearing first.

**List Payment Intents**

```javascript
const paymentIntents = await payment.paymentIntents.list({
  limit: 5,
  status: 'succeeded'
});

console.log(paymentIntents);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `status`  | `string`  | Optional. A comma-separated string of statuses to filter by (e.g., `'succeeded,processing'`).  |
| `invoice_id`  | `string`  | Optional. Only return Payment Intents for the given invoice.  |
| `customer_id`  | `string`  | Optional. Only return Payment Intents for the given customer ID.  |
| `customer_did`  | `string`  | Optional. Only return Payment Intents for the given customer DID.  |
| `metadata.{key}`  | `string`  | Optional. Filter by a specific metadata key-value pair.  |
| `page`  | `number`  | Optional. The page number for pagination, starting from 1. Default is `1`.  |
| `pageSize`  | `number`  | Optional. A limit on the number of objects to be returned, between 1 and 100. Default is `20`.  |

<strong>Returns</strong>

A paginated object containing a `list` of `PaymentIntent` objects and pagination details.

**Response Example**

```json
{
  "count": 15,
  "list": [
    {
      "id": "pi_123456789",
      "status": "succeeded",
      // ... other properties
    },
    {
      "id": "pi_987654321",
      "status": "succeeded",
      // ... other properties
    }
    // ... more payment intents
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
```

## Search Payment Intents

Searches for Payment Intents matching a specific query.

**Search Payment Intents**

```javascript
const results = await payment.paymentIntents.search({
  query: 'cus_xxxxxxxx'
});

console.log(results);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `query`  | `string`  | <strong>Required.</strong> The search query string.  |
| `page`  | `number`  | Optional. The page number for pagination, starting from 1. Default is `1`.  |
| `pageSize`  | `number`  | Optional. The number of items per page. Default is `20`.  |

<strong>Returns</strong>

A paginated object containing a `list` of `PaymentIntent` objects that match the search query.

**Response Example**

```json
{
  "count": 1,
  "list": [
    {
      "id": "pi_123456789",
      "customer_id": "cus_xxxxxxxx",
      // ... other properties
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}
```

## Refund a Charge

When a Payment Intent is successful, you can create a refund for the charge. This will create a `Refund` object and attempt to reverse the charge.

**Refund a Charge**

```javascript
const refund = await payment.paymentIntents.refund(
  'pi_123456789',
  {
    amount: '500',
    reason: 'requested_by_customer',
    description: 'Refund for item not received.'
  }
);

console.log(refund);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the Payment Intent to refund.  |
| `amount`  | `string`  | <strong>Required.</strong> A positive string representing how much of this charge to refund. Can refund up to the total amount of the original charge.  |
| `reason`  | `string`  | <strong>Required.</strong> String indicating the reason for the refund. Valid values are: `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, `expired_uncaptured_charge`.  |
| `description`  | `string`  | <strong>Required.</strong> An explanation of the refund.  |

<strong>Returns</strong>

Returns a new `Refund` object.

**Response Example**

```json
{
  "id": "re_abcdef123",
  "type": "refund",
  "livemode": false,
  "amount": "500",
  "description": "Refund for item not received.",
  "status": "pending",
  "reason": "requested_by_customer",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_123456789",
  // ... other refund properties
}
```

---

## Payment Links

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-payment-links-381920/

A Payment Link is a shareable, reusable page to sell a product or service. You can create a link for a specific set of products and prices and share it with multiple customers through various channels. This allows for quick and easy payment collection without building a full checkout flow.

## The Payment Link Object

A Payment Link object contains all the information necessary to present a payment page to a customer. Here are some of its key attributes:

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the payment link object.  |
| `url`  | string  | The URL for the payment page. Customers can be redirected to this URL to make a payment.  |
| `active`  | boolean  | Whether the payment link is currently active and can be used for payments.  |
| `line_items`  | array  | The list of products and prices that will be purchased.  |
| `after_completion`  | object  | Behavior after the purchase is complete, such as redirecting to a URL or showing a confirmation message.  |
| `allow_promotion_codes`  | boolean  | Enables the use of promotion codes on the payment page.  |
| `currency_id`  | string  | The three-letter ISO currency code.  |
| `metadata`  | object  | A set of key-value pairs that you can attach to the object. Useful for storing additional information.  |
| `created_at`  | string  | Timestamp of when the object was created.  |

## Create a Payment Link

Creates a new payment link.

**Create a Payment Link**

```javascript
const paymentLink = await payment.paymentLinks.create({
  line_items: [
    {
      price_id: 'price_xxxxxxxxxxxxxx',
      quantity: 1,
      adjustable_quantity: {
        enabled: true,
        minimum: 1,
        maximum: 10,
      },
    },
  ],
  after_completion: {
    type: 'hosted_confirmation',
    hosted_confirmation: {
      custom_message: 'Thanks for your purchase!',
    },
  },
  metadata: {
    order_id: '6735',
  },
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `line_items`  | array  | <strong>Required.</strong> A list of line item objects, each representing a product to be purchased. See details below.  |
| `name`  | string  | An optional internal name for the payment link.  |
| `lookup_key`  | string  | An optional, unique string that can be used to retrieve the payment link.  |
| `currency_id`  | string  | The ID of the currency for this payment link. If not provided, the default currency is used.  |
| `after_completion`  | object  | Specifies the behavior after a successful payment. See details below.  |
| `allow_promotion_codes`  | boolean  | Set to `true` to allow promotion codes to be redeemed. Defaults to `false`.  |
| `consent_collection`  | object  | Configures consent collection for promotions and terms of service. See details below.  |
| `nft_mint_settings`  | object  | Settings for minting an NFT after the payment is complete. See details below.  |
| `metadata`  | object  | A set of key-value pairs to store additional information.  |

<strong>`line_items`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `price_id`  | string  | <strong>Required.</strong> The ID of the price object.  |
| `quantity`  | number  | <strong>Required.</strong> The quantity of the product being purchased. Must be at least 1.  |
| `adjustable_quantity`  | object  | Configuration that allows the customer to adjust the quantity of this line item on the payment page. See details below.  |

<strong>`line_items.adjustable_quantity`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `enabled`  | boolean  | <strong>Required.</strong> Set to `true` to allow quantity adjustments.  |
| `minimum`  | number  | The minimum quantity the customer can select. Must be 0 or greater.  |
| `maximum`  | number  | The maximum quantity the customer can select. Must be greater than `minimum`.  |

<strong>`after_completion`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `type`  | string  | <strong>Required.</strong> The type of completion behavior. Can be `hosted_confirmation` or `redirect`.  |
| `hosted_confirmation`  | object  | Displays a hosted confirmation message to the customer. Used when `type` is `hosted_confirmation`.  |
| `redirect`  | object  | Redirects the customer to a specific URL. Used when `type` is `redirect`.  |

<strong>`after_completion.hosted_confirmation`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `custom_message`  | string  | An optional custom message to display to the customer. Max 200 characters.  |

<strong>`after_completion.redirect`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `url`  | string  | The URL to redirect the customer to. Max 2048 characters.  |

<strong>`consent_collection`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `promotions`  | string  | Determines how to handle consent for promotional communications. Can be `none`, `opt_in`, or `opt_out`.  |
| `terms_of_service`  | string  | Determines how to handle consent for terms of service. Can be `none`, `opt_in`, or `opt_out`.  |

<strong>`nft_mint_settings`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `enabled`  | boolean  | <strong>Required.</strong> Set to `true` to enable NFT minting after payment.  |
| `factory`  | string  | The factory address for minting the NFT. Required if `enabled` is `true`.  |

### Returns

Returns a `TPaymentLinkExpanded` object if the creation is successful.

**Response**

```json
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ],
  "after_completion": {
    "type": "hosted_confirmation",
    "hosted_confirmation": {
      "custom_message": "Thanks for your purchase!"
    }
  },
  "metadata": {
    "order_id": "6735"
  }
}
```

## Retrieve a Payment Link

Retrieves the details of an existing payment link.

**Retrieve a Payment Link**

```javascript
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The unique identifier or `lookup_key` of the payment link to retrieve.  |

### Returns

Returns a `TPaymentLinkExpanded` object, which includes expanded details about the line items and their associated prices and products.

**Response**

```json
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "price": {
        "id": "price_xxxxxxxxxxxxxx",
        "product_id": "prod_yyyyyyyyyyyyyy",
        "unit_amount": "10.00",
        "product": {
          "id": "prod_yyyyyyyyyyyyyy",
          "name": "My Awesome Product"
        }
      }
    }
  ]
}
```

## Update a Payment Link

Updates a payment link by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that you cannot update an archived payment link.

**Update a Payment Link**

```javascript
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const updatedPaymentLink = await payment.paymentLinks.update(paymentLinkId, {
  active: false,
  metadata: {
    order_id: '6735-updated'
  }
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the payment link to update.  |
| `...`  |  | The second argument is an object containing the fields to update. It supports many of the same parameters as the create method, such as `active`, `line_items`, `metadata`, and `after_completion`. All fields are optional.  |

### Returns

Returns the updated `TPaymentLink` object.

**Response**

```json
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "metadata": {
    "order_id": "6735-updated"
  }
}
```

## List all Payment Links

Returns a list of your payment links.

**List Payment Links**

```javascript
const paymentLinks = await payment.paymentLinks.list({
  active: true,
  limit: 5
});
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `active`  | boolean  | Filters the list to only include active or inactive payment links.  |
| `donation`  | string  | Set to `'hide'` to exclude payment links where `submit_type` is `donate`.  |
| `page`  | number  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | number  | The number of objects to return per page. Defaults to `20`.  |
| `order`  | string  | The order to sort the results by. For example, `'created_at:DESC'`.  |

### Returns

Returns a paginated object containing a `list` of `TPaymentLinkExpanded` objects.

**Response**

```json
{
  "count": 15,
  "list": [
    {
      "id": "plink_xxxxxxxxxxxxxx",
      "active": true
    },
    {
      "id": "plink_yyyyyyyyyyyyyy",
      "active": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
```

## Archive a Payment Link

Deactivates a payment link, making it unusable for payments. This action is reversible by updating the `active` attribute to `true`.

**Archive a Payment Link**

```javascript
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const archivedPaymentLink = await payment.paymentLinks.archive(paymentLinkId);
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the payment link to archive.  |

### Returns

Returns the archived `TPaymentLink` object with its `active` property set to `false`.

**Response**

```json
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx"
}
```

---

## Payment Methods

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-payment-methods-381920/

Payment Method objects represent the different ways a customer can pay, such as with Stripe (credit cards, bank accounts) or through various cryptocurrency networks. This API allows you to configure, manage, and list the payment methods available to your customers.

Each payment method is linked to one or more [Payment Currencies](/en/docs/payment-kit-sdk/api-reference-payment-currencies-381920/), which define the specific currencies accepted through that method.

## The Payment Method Object

A Payment Method object contains all the configuration details for a specific payment provider or network.

**The Payment Method Object**

```json
{
  "id": "pm_123abc",
  "name": "Stripe Credit Cards",
  "description": "Pay with credit card or bank account",
  "type": "stripe",
  "logo": "/methods/stripe.png",
  "active": true,
  "locked": false,
  "livemode": false,
  "default_currency_id": "pc_456def",
  "features": {
    "recurring": true,
    "refund": true,
    "dispute": true
  },
  "confirmation": {
    "type": "callback"
  },
  "settings": {
    "stripe": {
      "publishable_key": "pk_test_...",
      "secret_key": "sk_test_... (encrypted)"
    }
  },
  "payment_currencies": [
    {
      "id": "pc_456def",
      "livemode": false,
      "active": true,
      "locked": true,
      "is_base_currency": false,
      "payment_method_id": "pm_123abc",
      "type": "standard",
      "name": "Dollar",
      "description": "US Dollar",
      "logo": "/currencies/dollar.png",
      "symbol": "USD",
      "decimal": 2,
      "maximum_precision": 2,
      "minimum_payment_amount": "1",
      "maximum_payment_amount": "100000000000",
      "contract": "",
      "metadata": {},
      "created_at": "2023-10-27T10:00:01.000Z",
      "updated_at": "2023-10-27T10:00:01.000Z"
    }
  ],
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Create a Payment Method

Creates a new Payment Method configuration. The required `settings` object varies depending on the `type` of the payment method.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `name`  | `string`  | <strong>Required.</strong> A human-readable name for the payment method (e.g., "Credit Card"). Maximum 32 characters.  |
| `description`  | `string`  | <strong>Required.</strong> A short description of the payment method. Maximum 255 characters.  |
| `type`  | `string`  | <strong>Required.</strong> The type of payment method. Supported values include `stripe`, `ethereum`, and other EVM-compatible chains like `base`.  |
| `settings`  | `object`  | <strong>Required.</strong> A configuration object containing credentials and settings specific to the payment method `type`. See details below.  |
| `logo`  | `string`  | Optional. A URL to a logo for the payment method. If not provided, a default logo will be used based on the `type`.  |

<strong>Stripe Settings Object Properties</strong>

When `type` is `stripe`, the `settings.stripe` object must contain the following properties:

| Name  | Type  | Description  |
|---|---|---|
| `publishable_key`  | `string`  | <strong>Required.</strong> Your Stripe publishable API key.  |
| `secret_key`  | `string`  | <strong>Required.</strong> Your Stripe secret API key.  |

<strong>EVM Chain Settings Object Properties</strong>

When `type` is an EVM chain (e.g., `ethereum`), the `settings.{type}` object must contain the following properties:

| Name  | Type  | Description  |
|---|---|---|
| `api_host`  | `string`  | <strong>Required.</strong> The JSON-RPC API endpoint for the blockchain network.  |
| `explorer_host`  | `string`  | <strong>Required.</strong> The base URL for the blockchain explorer (e.g., `https://etherscan.io`).  |
| `native_symbol`  | `string`  | <strong>Required.</strong> The symbol for the native currency of the chain (e.g., "ETH").  |
| `confirmation`  | `number`  | Optional. The number of block confirmations required to consider a transaction final. Defaults to `1`.  |

<strong>Returns</strong>

Returns the newly created `TPaymentMethodExpanded` object, which includes an array of associated `payment_currencies` that were automatically created.

**Create a Stripe Payment Method**

```javascript
import payment from '@blocklet/payment-js';

async function createStripeMethod() {
  try {
    const stripeMethod = await payment.paymentMethods.create({
      name: 'Credit Card',
      description: 'Pay with Visa, Mastercard, etc.',
      type: 'stripe',
      settings: {
        stripe: {
          publishable_key: 'pk_test_YOUR_PUBLISHABLE_KEY',
          secret_key: 'sk_test_YOUR_SECRET_KEY',
        },
      },
    });
    console.log('Stripe method created:', stripeMethod);
  } catch (error) {
    console.error('Error creating Stripe method:', error.message);
  }
}

createStripeMethod();
```

**Example Response**

```json
{
  "id": "pm_abc123",
  "name": "Credit Card",
  "description": "Pay with Visa, Mastercard, etc.",
  "type": "stripe",
  "active": true,
  // ... other fields
  "payment_currencies": [
    {
      "id": "pc_xyz789",
      "name": "Dollar",
      "symbol": "USD",
      // ... other currency fields
    }
  ]
}
```

## Retrieve a Payment Method

Retrieves the details of an existing Payment Method by its unique ID.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier of the Payment Method to retrieve.  |

<strong>Returns</strong>

Returns the `TPaymentMethodExpanded` object if found, otherwise returns a 404 error.

**Retrieve a Payment Method**

```javascript
import payment from '@blocklet/payment-js';

async function getPaymentMethod(methodId) {
  try {
    const method = await payment.paymentMethods.retrieve(methodId);
    console.log('Retrieved method:', method.name);
  } catch (error) {
    console.error(`Error retrieving payment method ${methodId}:`, error.message);
  }
}

getPaymentMethod('pm_abc123'); // Replace with a valid Payment Method ID
```

## Update a Payment Method

Updates the specified Payment Method by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier of the Payment Method to update.  |
| `data`  | `object`  | <strong>Required.</strong> An object containing the fields to update. See properties below.  |

<strong>Update Data Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `name`  | `string`  | Optional. The new name for the payment method.  |
| `description`  | `string`  | Optional. The new description for the payment method.  |
| `logo`  | `string`  | Optional. The new logo URL for the payment method.  |
| `settings`  | `object`  | Optional. The new settings object. The structure must match the method's `type`. When updating Stripe keys, the webhook signing secret will be reset and must be reconfigured.  |

<strong>Returns</strong>

Returns the updated `TPaymentMethod` object.

**Update a Payment Method**

```javascript
import payment from '@blocklet/payment-js';

async function updatePaymentMethod(methodId) {
  try {
    const updatedMethod = await payment.paymentMethods.update(methodId, {
      description: 'Accept all major credit and debit cards.',
    });
    console.log('Payment method updated:', updatedMethod.description);
  } catch (error) {
    console.error(`Error updating payment method ${methodId}:`, error.message);
  }
}

updatePaymentMethod('pm_abc123'); // Replace with a valid Payment Method ID
```

## List Payment Methods

Returns a list of your Payment Methods. The methods are returned sorted by creation date, with the most recently created methods appearing first.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `active`  | `boolean`  | Optional. A boolean flag to filter payment methods by their active status.  |
| `livemode`  | `boolean`  | Optional. A boolean flag to filter for live or test mode payment methods.  |
| `page`  | `number`  | Optional. The page number for pagination, starting at 1.  |
| `pageSize`  | `number`  | Optional. The number of items to return per page. Defaults to `20`.  |

<strong>Returns</strong>

Returns an array of `TPaymentMethodExpanded` objects.

**List all active Payment Methods**

```javascript
import payment from '@blocklet/payment-js';

async function listActiveMethods() {
  try {
    const methods = await payment.paymentMethods.list({
      active: true,
      livemode: false, // Filter for test methods
    });
    console.log(`Found ${methods.length} active test payment methods:`);
    methods.forEach(method => {
      console.log(`- ${method.name} (Type: ${method.type})`);
    });
  } catch (error) {
    console.error('Error listing payment methods:', error.message);
  }
}

listActiveMethods();
```

**Example Response**

```json
[
  {
    "id": "pm_abc123",
    "name": "Credit Card",
    "type": "stripe",
    "active": true,
    "livemode": false,
    // ... other fields
  },
  {
    "id": "pm_def456",
    "name": "Ethereum",
    "type": "ethereum",
    "active": true,
    "livemode": false,
    // ... other fields
  }
]
```

---

## Prices

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-prices-381920/

A Price object defines how much and how often to charge for a specific product. It associates a price amount and currency with a [Product](/en/docs/payment-kit-sdk/api-reference-products-381920/). For example, a product might have multiple prices, each in a different currency or with a different billing interval.

This document details how to manage Price objects using the SDK.

## The Price Object

A Price object contains all the details about the pricing model for a product.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | string  | Unique identifier for the price object.  |
| `product_id`  | string  | The ID of the product this price is associated with.  |
| `product`  | object  | The expanded Product object.  |
| `active`  | boolean  | Whether the price can be used for new purchases.  |
| `currency_id`  | string  | The ID of the default currency for this price.  |
| `currency`  | object  | The expanded PaymentCurrency object.  |
| `nickname`  | string  | A brief description of the price, displayed to customers.  |
| `type`  | string  | One of `one_time` or `recurring`.  |
| `unit_amount`  | string  | The price in the smallest currency unit (e.g., cents for USD).  |
| `recurring`  | object  | For recurring prices, this hash contains billing interval information. See details below.  |
| `lookup_key`  | string  | A unique, user-defined key to retrieve the price.  |
| `metadata`  | object  | A set of key-value pairs that you can attach to an object.  |
| `currency_options`  | array  | Specifies different pricing for multiple currencies.  |
| `quantity_available`  | number  | The total available quantity for this price. `0` means unlimited.  |
| `quantity_sold`  | number  | The number of units sold.  |
| `quantity_limit_per_checkout`  | number  | The maximum quantity a customer can purchase in a single checkout. `0` means no limit.  |
| `upsell`  | object  | Configuration for upselling to another price.  |

<strong>The</strong> <strong>`recurring`</strong> <strong>Object Properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `interval`  | string  | The frequency at which a subscription is billed. One of `day`, `week`, `month`, or `year`.  |
| `interval_count`  | number  | The number of intervals between subscription billings.  |
| `meter_id`  | string  | The ID of the meter used for usage-based billing.  |

## Create a Price

Creates a new price for an existing product.

**Create a Price**

```javascript
async function createPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      unit_amount: 1500, // e.g., $15.00
      currency_id: 'usd_xxxxxxxxxxxxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
        usage_type: 'licensed'
      },
      nickname: 'Monthly Pro Plan',
      lookup_key: 'pro_monthly_usd',
    });
    console.log('Price created:', price);
  } catch (error) {
    console.error('Error creating price:', error.message);
  }
}

createPrice();
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `product_id`  | string  | <strong>Required.</strong> The ID of the product this price belongs to.  |
| `unit_amount`  | number  | <strong>Required.</strong> The amount to be charged, in the smallest currency unit.  |
| `currency_id`  | string  | <strong>Required.</strong> The ID of the currency for this price.  |
| `type`  | string  | The type of pricing. Can be `one_time` or `recurring`. Defaults to `one_time`.  |
| `active`  | boolean  | Whether the price is active. Defaults to `true`.  |
| `nickname`  | string  | An internal name for the price.  |
| `lookup_key`  | string  | A unique string to reference the price.  |
| `recurring`  | object  | An object containing recurring billing information. Required if `type` is `recurring`.  |
| `currency_options`  | array  | An array of objects to specify prices in different currencies.  |
| `metadata`  | object  | Key-value data to store with the price.  |
| `quantity_available`  | number  | The total available quantity. Defaults to `0` (unlimited).  |
| `quantity_limit_per_checkout`  | number  | The maximum quantity per checkout. Defaults to `0` (no limit).  |

### Returns

Returns the newly created Price object.

**Response**

```json
{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Pro Plan",
  "type": "recurring",
  "unit_amount": "1500",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter_id": null
  },
  "lookup_key": "pro_monthly_usd",
  "metadata": {},
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "Pro Plan"
  },
  "currency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "United States Dollar"
  }
}
```

## Retrieve a Price

Retrieves the details of an existing price.

**Retrieve a Price**

```javascript
async function retrievePrice(priceId) {
  try {
    const price = await payment.prices.retrieve(priceId);
    console.log('Price retrieved:', price);
  } catch (error) {
    console.error('Error retrieving price:', error.message);
  }
}

retrievePrice('price_xxxxxxxxxxxxxx');
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The unique identifier of the price to retrieve. Can also be a `lookup_key`.  |

### Returns

Returns the requested Price object.

## Update a Price

Updates an existing price by setting the values of the parameters passed.

**Update a Price**

```javascript
async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Pro Plan Nickname',
      metadata: { order_id: '6735' },
    });
    console.log('Price updated:', price);
  } catch (error) {
    console.error('Error updating price:', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the price to update. Can also be a `lookup_key`.  |
| `updates`  | object  | An object containing the fields to update. See the create method for a list of updatable fields. Note: Core attributes like `unit_amount` and `recurring` cannot be changed if the price has been used (`locked`).  |

### Returns

Returns the updated Price object.

## List all Prices

Returns a list of your prices. The prices are returned sorted by creation date, with the most recently created prices appearing first.

**List Prices**

```javascript
async function listPrices() {
  try {
    const prices = await payment.prices.list({
      product_id: 'prod_xxxxxxxxxxxxxx',
      active: true,
      limit: 5,
    });
    console.log('Retrieved prices:', prices.list);
  } catch (error) {
    console.error('Error listing prices:', error.message);
  }
}

listPrices();
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `active`  | boolean  | Only return prices with this active status.  |
| `type`  | string  | Only return prices of this type, e.g., `recurring`.  |
| `currency_id`  | string  | Only return prices for this currency ID.  |
| `product_id`  | string  | Only return prices for this product ID.  |
| `lookup_key`  | string  | Only return the price with this lookup key.  |
| `page`  | number  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | number  | The number of items per page. Defaults to `20`.  |

### Returns

Returns a paginated object containing a `list` of Price objects, the total `count`, and `paging` information.

## Search Prices

Searches for prices matching a query string.

**Search Prices**

```javascript
async function searchPrices() {
  try {
    const prices = await payment.prices.search({ query: 'Pro Plan' });
    console.log('Search results:', prices.list);
  } catch (error) {
    console.error('Error searching prices:', error.message);
  }
}

searchPrices();
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `query`  | string  | The search query string.  |
| `page`  | number  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | number  | The number of items per page. Defaults to `20`.  |

### Returns

Returns a paginated object containing a `list` of matching Price objects.

## Archive a Price

Archives a price, preventing it from being used in new checkouts. If a price has been used, it's generally better to archive it than to delete it.

**Archive a Price**

```javascript
async function archivePrice(priceId) {
  try {
    const price = await payment.prices.archive(priceId);
    console.log('Price archived:', price.id, 'Active:', price.active);
  } catch (error) {
    console.error('Error archiving price:', error.message);
  }
}

archivePrice('price_xxxxxxxxxxxxxx');
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the price to archive. Can also be a `lookup_key`.  |

### Returns

Returns the archived Price object with `active` set to `false`.

## Delete a Price

Permanently deletes a price. This action cannot be undone. A price cannot be deleted if it has been used in a transaction or is otherwise locked.

**Delete a Price**

```javascript
async function deletePrice(priceId) {
  try {
    const deletedPrice = await payment.prices.del(priceId);
    console.log('Price deleted:', deletedPrice.id);
  } catch (error) {
    console.error('Error deleting price:', error.message);
  }
}

deletePrice('price_xxxxxxxxxxxxxx');
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the price to delete. Can also be a `lookup_key`.  |

### Returns

Returns the deleted Price object.

## Update Inventory

Manually adjusts the `quantity_sold` for a price. This is useful for tracking inventory outside of the standard checkout flow.

**Update Inventory**

```javascript
async function updateInventory(priceId) {
  try {
    // Increment sold quantity by 2
    const price = await payment.prices.inventory(priceId, {
      quantity: 2,
      action: 'increment',
    });
    console.log('Inventory updated. New quantity sold:', price.quantity_sold);
  } catch (error) {
    console.error('Error updating inventory:', error.message);
  }
}

updateInventory('price_xxxxxxxxxxxxxx');
```

### Parameters

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | <strong>Required.</strong> The ID of the price.  |
| `params`  | object  | An object containing inventory adjustment details.  |

<strong>`params`</strong> <strong>Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `quantity`  | number  | <strong>Required.</strong> The amount to adjust the sold quantity by.  |
| `action`  | string  | <strong>Required.</strong> The adjustment action. Must be `increment` or `decrement`.  |

### Returns

Returns the updated Price object with the new `quantity_sold` value.

---

## Products

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-products-381920/

Product objects represent the goods, services, or digital credits you offer to your customers. You can think of them as the items in your catalog. Each product can have one or more associated prices.

This API allows you to create and manage your product catalog programmatically.

For details on managing the cost and billing schemes for these products, see the [Prices API Reference](/en/docs/payment-kit-sdk/api-reference-prices-381920/).

## The Product Object

A Product object contains details about a single item you sell.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the product object.  |
| `name`  | `string`  | The product's name, meant to be displayable to the customer.  |
| `type`  | `string`  | The type of the product. Can be `service`, `good`, or `credit`. Defaults to `service`.  |
| `active`  | `boolean`  | Whether the product is currently available for purchase.  |
| `description`  | `string`  | An arbitrary string that you can use to describe the product.  |
| `images`  | `string[]`  | A list of URL strings for images of the product.  |
| `metadata`  | `object`  | A set of key-value pairs that you can attach to an object. Useful for storing additional information.  |
| `statement_descriptor`  | `string`  | An optional descriptor that appears on your customer's credit card statement.  |
| `unit_label`  | `string`  | A label that represents a single unit of this product (e.g., 'user', 'license').  |
| `nft_factory`  | `string`  | The address of an NFT factory, if the product is linked to an NFT.  |
| `features`  | `object[]`  | A list of features associated with the product. Each feature object has a `name` property.  |
| `prices`  | `Price[]`  | A list of Price objects associated with this product. This is only included when retrieving a single product or in expanded lists.  |
| `default_price_id`  | `string`  | The ID of the default price for this product.  |
| `created_at`  | `string`  | Timestamp of when the object was created.  |
| `updated_at`  | `string`  | Timestamp of the last update.  |

## Create a Product

Creates a new product object. You can also create one or more prices for the product at the same time.

**Create Product**

```javascript
const product = await payment.products.create({
  name: 'Premium Subscription',
  description: 'Monthly access to premium features.',
  type: 'service',
  prices: [
    {
      unit_amount: 1500, // e.g., 15.00 USD
      currency_id: 'usd_xxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
        usage_type: 'licensed'
      },
    },
  ],
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `name`  | `string`  | <strong>Required</strong>. The product's name.  |
| `type`  | `string`  | The product type. One of `service`, `good`, or `credit`. Defaults to `service`.  |
| `description`  | `string`  | An optional, user-facing description of the product.  |
| `images`  | `string[]`  | A list of URLs for product images.  |
| `metadata`  | `object`  | Key-value data to store with the product.  |
| `statement_descriptor`  | `string`  | A short descriptor for credit card statements. Must contain at least one letter and cannot include `<`, `>`, `"`, `’`, or `\`. Max 22 characters.  |
| `unit_label`  | `string`  | A label for a single unit of the product (e.g., 'seat', 'GB'). Max 12 characters.  |
| `nft_factory`  | `string`  | The address of an associated NFT factory contract.  |
| `features`  | `object[]`  | A list of feature objects, where each object has a `name` property.  |
| `prices`  | `object[]`  | An array of Price objects to create and attach to this product. See the <strong>Price Object Properties</strong> table below.  |

<strong>Price Object Properties</strong>

When creating a product, you can include an array of prices. Each object in the `prices` array can have the following properties:

| Name  | Type  | Description  |
|---|---|---|
| `unit_amount`  | `number`  | <strong>Required</strong>. The price in the smallest currency unit (e.g., cents for USD). Must be greater than 0.  |
| `currency_id`  | `string`  | <strong>Required</strong>. The ID of the currency for this price.  |
| `nickname`  | `string`  | An internal-facing name for the price.  |
| `type`  | `string`  | `one_time` or `recurring`. Defaults to `one_time`.  |
| `recurring`  | `object`  | Required if `type` is `recurring`. An object with an `interval` (`day`, `week`, `month`, or `year`) and optional `interval_count`.  |
| `custom_unit_amount`  | `object`  | Defines a price where the customer can choose the amount. See the Prices API for details.  |

<strong>Returns</strong>

Returns the newly created `Product` object, including the list of any prices that were created.

**Response Example**

```json
{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  "images": [],
  "metadata": {},
  "statement_descriptor": null,
  "unit_label": null,
  "nft_factory": null,
  "features": [],
  "default_price_id": "price_67890",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "prices": [
    {
      "id": "price_67890",
      "product_id": "prod_12345",
      "active": true,
      "type": "recurring",
      "unit_amount": "1500",
      "currency_id": "usd_xxxx",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  ]
}
```

## Retrieve a Product

Retrieves the details of an existing product.

**Retrieve Product**

```javascript
const product = await payment.products.retrieve('prod_12345');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required</strong>. The unique identifier of the product to retrieve.  |

<strong>Returns</strong>

Returns a `Product` object if a valid ID was provided. Otherwise, this call returns an error.

**Response Example**

```json
{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  // ... other product fields
  "prices": [
    // ... list of associated price objects
  ]
}
```

## Update a Product

Updates the specified product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

**Update Product**

```javascript
const product = await payment.products.update('prod_12345', {
  description: 'Updated: Monthly access to all premium features and priority support.',
  metadata: { 'tier': 'premium' }
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required</strong>. The ID of the product to update.  |
| `name`  | `string`  | The product's name.  |
| `description`  | `string`  | An optional, user-facing description of the product.  |
| `images`  | `string[]`  | A list of URLs for product images.  |
| `metadata`  | `object`  | Key-value data to store with the product.  |
| `statement_descriptor`  | `string`  | A short descriptor for credit card statements.  |
| `default_price_id`  | `string`  | The ID of the price to set as the default for this product.  |
| `unit_label`  | `string`  | A label for a single unit of the product.  |
| `features`  | `object[]`  | A list of feature objects.  |

<strong>Returns</strong>

Returns the updated `Product` object.

## List all Products

Returns a paginated list of your products. The products are returned sorted by creation date, with the most recently created products appearing first.

**List Products**

```javascript
const products = await payment.products.list({
  active: true,
  limit: 10
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `active`  | `boolean`  | Only return products with this active status.  |
| `name`  | `string`  | Only return products with this name.  |
| `description`  | `string`  | Only return products with this description.  |
| `type`  | `string`  | Only return products of this type (e.g., `credit`).  |
| `metadata.{key}`  | `string`  | Filter by a specific key-value pair in the metadata. For example, `metadata.tier: 'premium'`.  |
| `page`  | `number`  | The page number to retrieve. Defaults to `1`.  |
| `pageSize`  | `number`  | The number of objects to return per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated list of `Product` objects.

**Response Example**

```json
{
  "count": 50,
  "list": [
    {
      "id": "prod_12345",
      "name": "Premium Subscription",
      // ... other product fields
    },
    {
      "id": "prod_67890",
      "name": "Standard Plan",
      // ... other product fields
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}
```

## Search Products

Returns a list of products that match a search query.

**Search Products**

```javascript
const products = await payment.products.search({ query: 'Premium' });
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `query`  | `string`  | The search query string. The search is performed on fields like `name` and `description`.  |
| `page`  | `number`  | The page number to retrieve. Defaults to `1`.  |
| `pageSize`  | `number`  | The number of objects to return per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated list of `Product` objects that match the search query.

## Archive a Product

Archives a product, making it unavailable for new purchases. This action toggles the `active` status of the product. Archiving a product will not affect existing subscriptions or purchases.

**Archive Product**

```javascript
const product = await payment.products.archive('prod_12345');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required</strong>. The ID of the product to archive.  |

<strong>Returns</strong>

Returns the updated `Product` object with its `active` status set to `false` (or `true` if it was already archived).

## Delete a Product

Permanently deletes a product. This action cannot be undone. A product can only be deleted if it has no prices or if none of its prices have been used in any transactions.

**Delete Product**

```javascript
const deletedProduct = await payment.products.del('prod_12345');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required</strong>. The ID of the product to delete.  |

<strong>Returns</strong>

Returns the deleted `Product` object.

---

## Promotion Codes

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-promotion-codes-381920/

A Promotion Code is a specific, user-facing code that customers can enter at checkout to receive a discount. Each Promotion Code is linked to a parent [Coupon](/en/docs/payment-kit-sdk/api-reference-coupons-381920/), which defines the actual discount (e.g., 20% off, $10 off). This two-level structure allows you to create multiple unique codes that all point to the same underlying discount, making it easy to track different marketing campaigns or distribution channels.

This API allows you to create, manage, and track the usage of Promotion Codes.

## The Promotion Code Object

A promotion code object contains all the information about a specific code, including its parent coupon, usage limits, and restrictions.

- **id** `string` — Unique identifier for the promotion code.
- **coupon_id** `string` — The ID of the coupon this promotion code is associated with.
- **code** `string` — The user-facing code that customers enter to apply the discount.
- **description** `string` — An internal description of the promotion code.
- **active** `boolean` — Whether the promotion code is currently active and can be used.
- **max_redemptions** `number` — The maximum number of times this promotion code can be redeemed.
- **times_redeemed** `number` — The number of times this promotion code has been redeemed.
- **expires_at** `number` — A Unix timestamp indicating when the promotion code expires.
- **verification_type** `string` — The method used to verify eligibility for the discount. Can be 'code', 'nft', 'vc', or 'user_restricted'.
- **nft_config** `object` — Configuration for NFT-based verification.
- **vc_config** `object` — Configuration for Verifiable Credential-based verification.
- **customer_dids** `string[]` — An array of customer DIDs who are eligible to use this code.
- **restrictions** `object` — A set of restrictions that apply to this promotion code.
- **metadata** `object` — A set of key-value pairs that you can attach to an object.
- **coupon** `object` — The expanded coupon object associated with this promotion code.
- **livemode** `boolean` — Indicates if the object exists in live mode or test mode.
- **created_at** `string` — Timestamp of when the object was created.
- **updated_at** `string` — Timestamp of when the object was last updated.

## Create a Promotion Code

Creates a new promotion code object.

### Parameters

- **coupon_id** `string` *(required)* — The ID of the coupon to associate with this promotion code.
- **code** `string` — The user-facing code. If not provided, a random code will be generated. Maximum 16 characters.
- **description** `string` — An optional internal description for the code. Maximum 250 characters.
- **active** `boolean` (default: `true`) — Whether the promotion code is active. Defaults to true.
- **max_redemptions** `number` — The maximum number of times the promotion code can be redeemed.
- **expires_at** `number` — A Unix timestamp after which the promotion code is no longer valid.
- **verification_type** `string` (default: `code`) — Specifies the verification method. Can be code, nft, vc, or user_restricted.
- **nft_config** `object` — Configuration for NFT-based verification. Required if verification_type is nft.
  - **addresses** `string[]` — List of contract addresses.
  - **tags** `string[]` — List of NFT tags.
  - **trusted_issuers** `string[]` — List of trusted issuer DIDs.
  - **trusted_parents** `string[]` — List of trusted parent collection IDs.
  - **min_balance** `number` (default: `1`) — Minimum balance of the required NFT the user must hold.
- **vc_config** `object` — Configuration for Verifiable Credential-based verification. Required if verification_type is vc.
  - **roles** `string[]` — List of required roles in the VC.
  - **trusted_issuers** `string[]` — List of trusted issuer DIDs for the VC.
- **customer_dids** `string[]` — A list of customer DIDs that are allowed to use this promotion code. Required if verification_type is user_restricted.
- **restrictions** `object` — Defines the conditions for the promotion code to apply.
  - **currency_options** `object` — Currency-specific minimum amounts required to apply the promotion code.
    - **{currency_code}** `object`
      - **minimum_amount** `number` *(required)* — The minimum transaction amount in the specified currency.
  - **first_time_transaction** `boolean` — If true, the promotion code only applies to the customer's first transaction.
- **metadata** `object` — A set of key-value pairs to store additional information about the object.

### Returns

Returns the created Promotion Code object.

**Create a promotion code**

```javascript
import payment from '@blocklet/payment-js';

async function createPromotionCode() {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: 'coupon_xxxxxxxxxxxxxx', // Replace with a valid Coupon ID
      code: 'SUMMER25',
      description: '25% off for the summer sale',
      max_redemptions: 100,
      expires_at: Math.floor(new Date('2024-09-01').getTime() / 1000),
      active: true,
    });
    console.log('Promotion Code created:', promotionCode);
  } catch (error) {
    console.error('Error creating promotion code:', error.message);
  }
}

createPromotionCode();
```

### Example Response

```json
{
  "id": "pc_xxxxxxxxxxxxxx",
  "coupon_id": "coupon_xxxxxxxxxxxxxx",
  "code": "SUMMER25",
  "description": "25% off for the summer sale",
  "active": true,
  "max_redemptions": 100,
  "times_redeemed": 0,
  "expires_at": 1725148800,
  "verification_type": "code",
  "nft_config": null,
  "vc_config": null,
  "customer_dids": null,
  "restrictions": {},
  "metadata": {},
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "coupon": {
    "id": "coupon_xxxxxxxxxxxxxx",
    "name": "Summer Sale",
    "percent_off": 25,
    // ... other coupon details
  }
}
```

## Retrieve a Promotion Code

Retrieves the details of an existing promotion code.

### Parameters

- **id** `string` *(required)* — The unique identifier of the promotion code to retrieve.

### Returns

Returns the Promotion Code object.

**Retrieve a promotion code**

```javascript
import payment from '@blocklet/payment-js';

async function getPromotionCode(promotionCodeId) {
  try {
    const promotionCode = await payment.promotionCodes.retrieve(promotionCodeId);
    console.log('Retrieved Promotion Code:', promotionCode);
  } catch (error) {
    console.error('Error retrieving promotion code:', error.message);
  }
}

getPromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID
```

## Update a Promotion Code

Updates the specified promotion code by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that once a promotion code has been used, only its `metadata` can be updated.

### Parameters

- **id** `string` *(required)* — The unique identifier of the promotion code to update.
- **description** `string` — An optional internal description for the code. Maximum 250 characters.
- **active** `boolean` — Whether the promotion code is active.
- **max_redemptions** `number` — The maximum number of times the promotion code can be redeemed.
- **expires_at** `number` — A Unix timestamp after which the promotion code is no longer valid.
- **restrictions** `object` — Defines the conditions for the promotion code to apply.
- **metadata** `object` — A set of key-value pairs to store additional information about the object.

### Returns

Returns the updated Promotion Code object.

**Update a promotion code**

```javascript
import payment from '@blocklet/payment-js';

async function updatePromotionCode(promotionCodeId) {
  try {
    const updatedPromotionCode = await payment.promotionCodes.update(promotionCodeId, {
      description: 'Updated summer sale description',
      metadata: { campaign_id: 'summer-2024' },
    });
    console.log('Promotion Code updated:', updatedPromotionCode);
  } catch (error) {
    console.error('Error updating promotion code:', error.message);
  }
}

updatePromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID
```

## List Promotion Codes

Returns a list of your promotion codes.

### Parameters

- **page** `number` (default: `1`) — The page number for pagination.
- **pageSize** `number` (default: `20`) — The number of items per page.
- **coupon_id** `string` — Filter promotion codes by the associated coupon ID.
- **active** `boolean` — Filter promotion codes by their active status.

### Returns

A paginated list of Promotion Code objects.

**List promotion codes**

```javascript
import payment from '@blocklet/payment-js';

async function listPromotionCodes() {
  try {
    const promotionCodes = await payment.promotionCodes.list({
      active: true,
      pageSize: 5,
    });
    console.log('Active Promotion Codes:', promotionCodes.list);
  } catch (error) {
    console.error('Error listing promotion codes:', error.message);
  }
}

listPromotionCodes();
```

### Example Response

```json
{
  "count": 50,
  "list": [
    {
      "id": "pc_xxxxxxxxxxxxxx",
      "code": "SUMMER25",
      // ... other promotion code details
    }
    // ... more promotion codes
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
```

## Archive a Promotion Code

Deactivates a promotion code, making it no longer redeemable. This action is irreversible.

### Parameters

- **id** `string` *(required)* — The unique identifier of the promotion code to archive.

### Returns

Returns the archived Promotion Code object with `active` set to `false`.

**Archive a promotion code**

```javascript
import payment from '@blocklet/payment-js';

async function archivePromotionCode(promotionCodeId) {
  try {
    const archivedCode = await payment.promotionCodes.archive(promotionCodeId);
    console.log('Promotion Code archived:', archivedCode);
  } catch (error) {
    console.error('Error archiving promotion code:', error.message);
  }
}

archivePromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID
```

## Delete a Promotion Code

Deletes a promotion code. This action is only possible if the promotion code has not been redeemed. If it has been used, it will be locked and cannot be deleted; you should archive it instead.

### Parameters

- **id** `string` *(required)* — The unique identifier of the promotion code to delete.

### Returns

Returns the deleted Promotion Code object.

**Delete a promotion code**

```javascript
import payment from '@blocklet/payment-js';

async function deletePromotionCode(promotionCodeId) {
  try {
    const deletedCode = await payment.promotionCodes.del(promotionCodeId);
    console.log('Promotion Code deleted:', deletedCode);
  } catch (error) {
    console.error('Error deleting promotion code:', error.message);
  }
}

deletePromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with an unused Promotion Code ID
```

## Check if Used

Checks whether a promotion code has been redeemed at least once.

### Parameters

- **id** `string` *(required)* — The unique identifier of the promotion code to check.

### Returns

An object containing a boolean `used` property.

**Check if a promotion code is used**

```javascript
import payment from '@blocklet/payment-js';

async function checkUsage(promotionCodeId) {
  try {
    const result = await payment.promotionCodes.used(promotionCodeId);
    console.log(`Is promotion code used? ${result.used}`);
  } catch (error) {
    console.error('Error checking promotion code usage:', error.message);
  }
}

checkUsage('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID
```

### Example Response

```json
{
  "used": true
}
```

## Retrieve by Code

Retrieves a promotion code's details by its user-facing code string.

### Parameters

- **code** `string` *(required)* — The user-facing code string.

### Returns

Returns the Promotion Code object.

**Retrieve a promotion code by its code string**

```javascript
import payment from '@blocklet/payment-js';

async function getByCode(code) {
  try {
    const promotionCode = await payment.promotionCodes.byCode(code);
    console.log('Found promotion code:', promotionCode);
  } catch (error) {
    console.error('Error retrieving promotion code by code:', error.message);
  }
}

getByCode('SUMMER25');
```

## List Redemptions

Retrieves a list of customers and subscriptions that have redeemed a specific promotion code.

### Parameters

- **id** `string` *(required)* — The unique identifier of the promotion code.
- **page** `number` (default: `1`) — The page number for pagination.
- **pageSize** `number` (default: `20`) — The number of items per page.
- **type** `'customer' | 'subscription'` — The type of redemption to list. Can be customer or subscription.

### Returns

An object containing redemption data, including lists of customers and subscriptions.

**List redemptions for a promotion code**

```javascript
import payment from '@blocklet/payment-js';

async function listRedemptions(promotionCodeId) {
  try {
    const redemptions = await payment.promotionCodes.redemptions({
      id: promotionCodeId,
      type: 'customer',
      pageSize: 10
    });
    console.log('Redemptions:', redemptions);
  } catch (error) {
    console.error('Error listing redemptions:', error.message);
  }
}

listRedemptions('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID
```

### Example Response

```json
{
  "count": 5,
  "subscriptions": [],
  "customers": [
    {
      "id": "cus_yyyyyyyyyyyyyy",
      "did": "did:abt:z...",
      // ... other customer details
    }
    // ... more customers
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

---

## Refunds

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-refunds-381920/

Refund objects represent the return of funds to a customer for a previous charge. You can create new refunds, retrieve details for an existing one, and list all refunds for accounting purposes. When a refund is created, it is initially in a `pending` state and will be processed asynchronously.

## The Refund Object

A typical Refund object contains the following key attributes:

- <strong>id</strong>: Unique identifier for the refund object.
- <strong>amount</strong>: The total amount refunded, in the smallest currency unit (e.g., cents).
- <strong>currency_id</strong>: The identifier of the currency used for the refund.
- <strong>status</strong>: The current status of the refund. Can be `pending`, `succeeded`, `failed`, or `canceled`.
- <strong>reason</strong>: The reason for the refund. Possible values include `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, or `expired_uncaptured_charge`.
- <strong>payment_intent_id</strong>: The ID of the Payment Intent that was refunded.
- <strong>customer_id</strong>: The ID of the Customer to whom the refund was issued.
- <strong>description</strong>: A description of the refund.
- <strong>metadata</strong>: A set of key-value pairs that you can attach to the object for your own reference.
- <strong>created_at</strong>: The timestamp when the refund was created.

## Create a Refund

Creates a `Refund` object to refund a charge that has previously been created. This can be for the full amount of the charge or a partial amount.

**Create a Refund**

```javascript
import payment from '@blocklet/payment-js';

async function issueRefund() {
  try {
    const refund = await payment.refunds.create({
      payment_intent_id: 'pi_xxxxxxxxxxxx',
      amount: '50.00', // Note: amount is a string representing the value in major units (e.g., dollars)
      currency_id: 'usd_xxxxxxxx',
      customer_id: 'cus_xxxxxxxx',
      payment_method_id: 'pm_xxxxxxxx',
      reason: 'requested_by_customer',
      description: 'Refund for order #54321',
      metadata: { order_id: '54321' }
    });
    console.log('Refund initiated:', refund);
  } catch (error) {
    console.error('Error creating refund:', error.message);
  }
}

issueRefund();
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `amount`  | `string`  | <strong>Required.</strong> A positive string representing how much of this charge to refund. Cannot refund more than the charge's remaining refundable amount.  |
| `currency_id`  | `string`  | <strong>Required.</strong> The identifier of the currency for the refund.  |
| `customer_id`  | `string`  | <strong>Required.</strong> The identifier of the customer associated with the refund.  |
| `payment_method_id`  | `string`  | <strong>Required.</strong> The identifier of the payment method used for the original charge.  |
| `payment_intent_id`  | `string`  | <strong>Required.</strong> The identifier of the PaymentIntent to refund.  |
| `reason`  | `string`  | <strong>Required.</strong> String indicating the reason for the refund. Supported values are `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, `expired_uncaptured_charge`.  |
| `description`  | `string`  | <strong>Required.</strong> An arbitrary string attached to the object. Often useful for displaying to users. Maximum 200 characters.  |
| `metadata`  | `object`  | Optional. A set of key-value pairs that you can attach to a refund object. This can be useful for storing additional information in a structured format.  |
| `invoice_id`  | `string`  | Optional. The ID of the invoice that's associated with this refund.  |
| `subscription_id`  | `string`  | Optional. The ID of the subscription that's associated with this refund.  |

<strong>Returns</strong>

Returns the created Refund object.

**Response Example**

```json
{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "pending",
  "description": "Refund for order #54321",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z"
}
```

## Retrieve a Refund

Retrieves the details of an existing refund by its unique ID.

**Retrieve a Refund**

```javascript
import payment from '@blocklet/payment-js';

async function getRefundDetails(refundId) {
  try {
    const refund = await payment.refunds.retrieve(refundId);
    console.log('Refund details:', refund);
  } catch (error) {
    console.error(`Error retrieving refund ${refundId}:`, error.message);
  }
}

getRefundDetails('ref_xxxxxxxxxxxx');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier of the refund to retrieve.  |

<strong>Returns</strong>

Returns the `Refund` object if a valid ID was provided. Throws an error otherwise.

**Response Example**

```json
{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "description": "Refund for order #54321",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "customer": { ... },
  "paymentCurrency": { ... },
  "paymentIntent": { ... },
  "paymentMethod": { ... }
}
```

## List all Refunds

Returns a paginated list of all refunds. You can filter the list based on various criteria.

**List Refunds**

```javascript
import payment from '@blocklet/payment-js';

async function listSuccessfulRefunds() {
  try {
    const response = await payment.refunds.list({
      status: 'succeeded',
      pageSize: 10
    });
    console.log(`Found ${response.count} successful refunds.`);
    response.list.forEach(refund => {
      console.log(`- Refund ID: ${refund.id}, Amount: ${refund.amount}`);
    });
  } catch (error) {
    console.error('Error listing refunds:', error.message);
  }
}

listSuccessfulRefunds();
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `page`  | `number`  | Optional. The page number for pagination, starting from 1. Defaults to `1`.  |
| `pageSize`  | `number`  | Optional. The number of objects to return per page. Defaults to `20`.  |
| `status`  | `string`  | Optional. A comma-separated string to filter refunds by status (e.g., `'succeeded,pending'`).  |
| `invoice_id`  | `string`  | Optional. Only return refunds for the given invoice.  |
| `subscription_id`  | `string`  | Optional. Only return refunds for the given subscription.  |
| `currency_id`  | `string`  | Optional. Only return refunds for the given currency.  |
| `customer_id`  | `string`  | Optional. Only return refunds for the given customer.  |

<strong>Returns</strong>

Returns a paginated object containing a `list` of Refund objects, the total `count`, and `paging` information.

**Response Example**

```json
{
  "count": 15,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "status": "succeeded",
      // ... other refund fields
    }
    // ... more refund objects
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

## Search for Refunds

Performs a search query against your refunds. This is useful for building custom search functionality.

**Search Refunds**

```javascript
import payment from '@blocklet/payment-js';

async function searchForRefund(query) {
  try {
    const response = await payment.refunds.search({ q: query });
    console.log(`Search results for '${query}':`);
    response.list.forEach(refund => {
      console.log(`- Refund ID: ${refund.id}`);
    });
  } catch (error) {
    console.error('Error searching refunds:', error.message);
  }
}

searchForRefund('customer_id:cus_xxxxxxxx');
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `q`  | `string`  | <strong>Required.</strong> The search query string. Supports key-value filtering (e.g., `status:succeeded`).  |
| `page`  | `number`  | Optional. The page number for pagination. Defaults to `1`.  |
| `pageSize`  | `number`  | Optional. The number of objects to return per page. Defaults to `20`.  |
| `o`  | `string`  | Optional. Specifies the order of the results. Use `asc` for ascending or `desc` for descending. Defaults to `desc` based on `created_at`.  |

<strong>Returns</strong>

Returns a paginated object containing a `list` of matching Refund objects, the total `count`, and `paging` information.

**Response Example**

```json
{
  "count": 1,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "customer_id": "cus_xxxxxxxx",
      "status": "succeeded",
      // ... other refund fields
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}
```

---

## Settings

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-settings-381920/

The Settings API allows you to manage various configurations within PaymentKit, such as creating donation widgets or setting up notification handlers. Each setting is a configurable resource identified by its `type` and `mountLocation`.

## The Setting Object

A Setting object contains the configuration for a specific feature.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the setting object.  |
| `type`  | `string`  | The type of setting, e.g., `'donate'`, `'notification'`.  |
| `mount_location`  | `string`  | A unique identifier for where the setting is used, often a URL path or component name.  |
| `description`  | `string`  | A human-readable description of the setting.  |
| `settings`  | `object`  | An object containing the specific configuration for this setting type. See details below.  |
| `active`  | `boolean`  | Whether the setting is currently active.  |
| `livemode`  | `boolean`  | `true` if the object exists in live mode, `false` if it exists in test mode.  |
| `component_did`  | `string`  | The DID of the component that created this setting.  |
| `created_at`  | `string`  | Timestamp of when the setting was created.  |
| `updated_at`  | `string`  | Timestamp of when the setting was last updated.  |

### The settings object for donate

| Attribute  | Type  | Description  |
|---|---|---|
| `amount`  | `object`  | Configuration for donation amounts.  |
| `btnText`  | `string`  | The text displayed on the donation button. Default: `'Donate'`.  |
| `historyType`  | `'table' \| 'avatar'`  | The display style for donation history. Default: `'avatar'`.  |

<strong>`amount`</strong> <strong>object properties</strong>

| Attribute  | Type  | Description  |
|---|---|---|
| `presets`  | `string[]`  | An array of predefined donation amounts. Required if `custom` is `false`.  |
| `preset`  | `string`  | The default selected amount from the presets.  |
| `custom`  | `boolean`  | Whether to allow custom donation amounts.  |
| `minimum`  | `string`  | The minimum allowed amount for custom donations. Required if `custom` is `true`.  |
| `maximum`  | `string`  | The maximum allowed amount for custom donations. Required if `custom` is `true`.  |

### The settings object for notification

| Attribute  | Type  | Description  |
|---|---|---|
| `self_handle`  | `boolean`  | If `true`, indicates that the component will handle the notification events itself.  |
| `include_events`  | `string[]`  | An array of event types to be included in notifications.  |
| `exclude_events`  | `string[]`  | An array of event types to be excluded from notifications.  |

## Create a Setting

Creates a new setting object.

**Create a new setting**

```javascript
const setting = await payment.settings.create({
  type: 'donate',
  mountLocation: '/community/donate',
  description: 'Community Donation Page',
  settings: {
    amount: {
      presets: ['5', '10', '25'],
      preset: '10',
      custom: true,
      minimum: '1',
      maximum: '1000',
    },
    btnText: 'Support Us',
  },
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `type`  | `string`  | <strong>Required.</strong> The type of setting to create (e.g., `'donate'`, `'notification'`).  |
| `mountLocation`  | `string`  | <strong>Required.</strong> A unique identifier for where the setting will be used.  |
| `description`  | `string`  | <strong>Required.</strong> A description for the setting.  |
| `settings`  | `object`  | Optional. An object with configuration specific to the `type`.  |
| `active`  | `boolean`  | Optional. Whether the setting is active. Defaults to `true`.  |
| `livemode`  | `boolean`  | Optional. Specifies the mode. Defaults to `true`.  |
| `componentDid`  | `string`  | Optional. The DID of the component creating the setting.  |

<strong>Returns</strong>

The newly created setting object.

**Response**

```json
{
  "id": "set_1a2b3c4d5e6f7g8h",
  "type": "donate",
  "mount_location": "/community/donate",
  "description": "Community Donation Page",
  "settings": {
    "amount": {
      "presets": ["5", "10", "25"],
      "preset": "10",
      "custom": true,
      "minimum": "1",
      "maximum": "1000"
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "active": true,
  "livemode": true,
  "component_did": "z1...",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Retrieve a Setting

Retrieves the details of an existing setting by its ID or `mountLocation`.

**Retrieve a setting**

```javascript
const settingId = 'set_1a2b3c4d5e6f7g8h';
const setting = await payment.settings.retrieve(settingId);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier or `mountLocation` of the setting to retrieve.  |

<strong>Returns</strong>

The setting object if found, otherwise an error is thrown.

**Response**

```json
{
  "id": "set_1a2b3c4d5e6f7g8h",
  "type": "donate",
  "mount_location": "/community/donate",
  "description": "Community Donation Page",
  "settings": {
    "amount": {
      "presets": ["5", "10", "25"],
      "preset": "10",
      "custom": true,
      "minimum": "1",
      "maximum": "1000"
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "active": true,
  "livemode": true,
  "component_did": "z1...",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Update a Setting

Updates the specified setting by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

**Update a setting**

```javascript
const settingId = 'set_1a2b3c4d5e6f7g8h';
const updatedSetting = await payment.settings.update(settingId, {
  description: 'Updated Community Donation Page',
  active: false,
  settings: {
    btnText: 'Donate Now',
  },
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier or `mountLocation` of the setting to update.  |
| `data`  | `object`  | <strong>Required.</strong> An object containing the fields to update.  |

<strong>`data`</strong> <strong>object properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | Optional. An updated description for the setting.  |
| `active`  | `boolean`  | Optional. Whether the setting is active.  |
| `settings`  | `object`  | Optional. An object with setting-specific fields to update. This will be merged with the existing settings.  |

<strong>Returns</strong>

The updated setting object.

**Response**

```json
{
  "id": "set_1a2b3c4d5e6f7g8h",
  "type": "donate",
  "mount_location": "/community/donate",
  "description": "Updated Community Donation Page",
  "settings": {
    "amount": {
      "presets": ["5", "10", "25"],
      "preset": "10",
      "custom": true,
      "minimum": "1",
      "maximum": "1000"
    },
    "btnText": "Donate Now",
    "historyType": "avatar"
  },
  "active": false,
  "livemode": true,
  "component_did": "z1...",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}
```

## Delete a Setting

Permanently deletes a setting. It cannot be undone.

**Delete a setting**

```javascript
const settingId = 'set_1a2b3c4d5e6f7g8h';
const response = await payment.settings.del(settingId);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier or `mountLocation` of the setting to delete.  |

<strong>Returns</strong>

A confirmation message.

**Response**

```json
{
  "message": "Setting set_1a2b3c4d5e6f7g8h deleted"
}
```

---

## Subscription Items

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-subscription-items-381920/

Subscription Items represent a specific product and price that a customer is subscribed to. They are components of a [Subscription](/en/docs/payment-kit-sdk/api-reference-subscriptions-381920/) and are essential for managing recurring billing, especially for plans with metered usage.

This API allows you to create, retrieve, update, and delete subscription items. Crucially, it also provides methods for reporting usage for metered billing.

## The Subscription Item Object

A Subscription Item object contains details about a specific item within a subscription.

**The TSubscriptionItemExpanded Object**

```typescript
interface TSubscriptionItemExpanded {
  id: string; // Unique identifier for the subscription item
  subscription_id: string; // The ID of the subscription this item belongs to
  price_id: string; // The ID of the price associated with this item
  quantity: number; // The quantity of the price
  billing_thresholds: object | null; // Usage-based billing thresholds
  metadata: object | null; // A set of key-value pairs for additional information
  created_at: number; // Timestamp of creation
  updated_at: number; // Timestamp of last update
  price: TPrice; // The expanded Price object
}
```

## Create a Subscription Item

Adds a new item (a product and price) to an existing subscription.

**Create Subscription Item**

```javascript
const subscriptionItem = await payment.subscriptionItems.create({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
  price_id: 'price_xxxxxxxxxxxxxx',
  quantity: 1,
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `subscription_id`  | `string`  | <strong>Required.</strong> The ID of the subscription to add this item to.  |
| `price_id`  | `string`  | <strong>Required.</strong> The ID of the price to subscribe the customer to.  |
| `quantity`  | `number`  | The quantity of the price. Defaults to `1`.  |
| `billing_thresholds`  | `object`  | Usage-based billing thresholds for this item.  |
| `metadata`  | `object`  | A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.  |

<strong>Returns</strong>

Returns the newly created `TSubscriptionItem` object.

## Retrieve a Subscription Item

Retrieves the details of an existing subscription item.

**Retrieve Subscription Item**

```javascript
const subscriptionItem = await payment.subscriptionItems.retrieve(
  'si_xxxxxxxxxxxxxx' // Subscription Item ID
);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The unique identifier of the subscription item to retrieve.  |

<strong>Returns</strong>

Returns a `TSubscriptionItemExpanded` object if a valid ID was provided.

## Update a Subscription Item

Updates the properties of a subscription item. You can update the `price_id`, `quantity`, and `metadata`.

**Update Subscription Item**

```javascript
const subscriptionItem = await payment.subscriptionItems.update(
  'si_xxxxxxxxxxxxxx', // Subscription Item ID
  {
    quantity: 2,
  }
);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the subscription item to update.  |
| `updates`  | `object`  | An object containing the fields to update.  |

<strong>Updateable Fields</strong>

| Name  | Type  | Description  |
|---|---|---|
| `price_id`  | `string`  | The ID of the new price for this item.  |
| `quantity`  | `number`  | The new quantity for this item.  |
| `billing_thresholds`  | `object`  | Usage-based billing thresholds for this item.  |
| `metadata`  | `object`  | A set of key-value pairs to update.  |

<strong>Returns</strong>

Returns the updated `TSubscriptionItem` object.

## List Subscription Items

Returns a list of subscription items for a given subscription.

**List Subscription Items**

```javascript
const subscriptionItems = await payment.subscriptionItems.list({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `subscription_id`  | `string`  | <strong>Required.</strong> The ID of the subscription whose items you want to list.  |
| `page`  | `number`  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | `number`  | The number of items to return per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated list of `TSubscriptionItemExpanded` objects.

## Delete a Subscription Item

Deletes an item from a subscription. This is a permanent action.

**Delete Subscription Item**

```javascript
const deletedItem = await payment.subscriptionItems.del(
  'si_xxxxxxxxxxxxxx', // Subscription Item ID
  {
    clear_usage: true, // Optional
  }
);
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the subscription item to delete.  |
| `body.clear_usage`  | `boolean`  | If `true`, all usage records for a metered price will be cleared. Defaults to `false`.  |

<strong>Returns</strong>

Returns the deleted `TSubscriptionItem` object.

## Create a Usage Record

For `metered` prices, you must report usage to bill your customers correctly. This method creates a usage record for a specified subscription item.

**Create Usage Record**

```javascript
const usageRecord = await payment.subscriptionItems.createUsageRecord({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
  quantity: 100,
  action: 'increment',
  timestamp: Math.floor(Date.now() / 1000),
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `subscription_item_id`  | `string`  | <strong>Required.</strong> The ID of the subscription item to report usage for.  |
| `quantity`  | `number`  | <strong>Required.</strong> The quantity of usage to report. Must be a positive integer.  |
| `action`  | `string`  | Determines how the reported `quantity` is applied. Can be `increment` (adds to existing usage) or `set` (overwrites usage at the given timestamp). Defaults to `increment`.  |
| `timestamp`  | `number`  | The UNIX timestamp for the usage event. Must be within the current billing period. Defaults to the current time.  |

<strong>Returns</strong>

Returns the created `TUsageRecord` object.

## List Usage Record Summaries

For a given subscription item, returns a list of usage record summaries, aggregated by billing period (invoice).

**List Usage Record Summaries**

```javascript
const summaries = await payment.subscriptionItems.listUsageRecordSummaries({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `subscription_item_id`  | `string`  | <strong>Required.</strong> The ID of the subscription item.  |
| `page`  | `number`  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | `number`  | The number of items to return per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated list of `TUsageRecordSummary` objects.

**The TUsageRecordSummary Object**

```typescript
interface TUsageRecordSummary {
  invoice_id: string; // ID of the invoice for this period
  subscription_item_id: string;
  total_usage: number; // Total usage for the period
  period: {
    start: number; // Start of the billing period (UNIX timestamp)
    end: number; // End of the billing period (UNIX timestamp)
  };
}
```

## List Usage Records

Retrieves a list of individual usage records for a subscription item. This provides a detailed, non-aggregated view of all reported usage.

**List Usage Records**

```javascript
const records = await payment.subscriptionItems.listUsageRecords({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
});
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `subscription_item_id`  | `string`  | <strong>Required.</strong> The ID of the subscription item.  |
| `start`  | `number`  | A UNIX timestamp to filter usage records after this time.  |
| `end`  | `number`  | A UNIX timestamp to filter usage records before or at this time.  |
| `page`  | `number`  | The page number for pagination. Defaults to `1`.  |
| `pageSize`  | `number`  | The number of items to return per page. Defaults to `20`.  |

<strong>Returns</strong>

A paginated list of `TUsageRecord` objects.

**The TUsageRecord Object**

```typescript
interface TUsageRecord {
  id: string;
  subscription_item_id: string;
  quantity: number;
  timestamp: number; // UNIX timestamp of the record
  billed: boolean; // Whether this usage has been billed
}
```

---

## Subscriptions

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-subscriptions-381920/

Subscriptions are used to manage recurring payment plans for customers. The Subscriptions API allows you to create, retrieve, update, cancel, and manage the lifecycle of these recurring billing arrangements.

For managing the individual items within a subscription, see the [Subscription Items](/en/docs/payment-kit-sdk/api-reference-subscription-items-381920/) API.

## Retrieve a Subscription

Fetches the details of an existing subscription by its unique identifier.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | string  | The ID of the subscription to retrieve.  |

<strong>Returns</strong>

Returns a subscription object if a valid ID was provided. The `TSubscriptionExpanded` object includes the following properties:

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the subscription.  |
| `status`  | `string`  | The status of the subscription (e.g., `active`, `trialing`, `past_due`, `canceled`).  |
| `customer_id`  | `string`  | The ID of the customer associated with this subscription.  |
| `currency_id`  | `string`  | The ID of the currency used for this subscription.  |
| `current_period_start`  | `number`  | The start of the current billing period as a Unix timestamp.  |
| `current_period_end`  | `number`  | The end of the current billing period as a Unix timestamp.  |
| `items`  | `TSubscriptionItem[]`  | An array of subscription items associated with this subscription.  |
| `customer`  | `TCustomer`  | The expanded customer object.  |
| `paymentCurrency`  | `TPaymentCurrency`  | The expanded payment currency object.  |
| `paymentMethod`  | `TPaymentMethod`  | The expanded payment method object.  |
| `metadata`  | `object`  | A set of key-value pairs that you can attach to an object.  |

<strong>Example</strong>

**Retrieving a subscription**

```javascript
async function getSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('Subscription retrieved:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error retrieving subscription:', error.message);
  }
}

// Example usage:
getProductDetails('sub_xxxxxxxxxxxxxx');
```

<strong>Example Response</strong>

```json
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "currency_id": "curr_xxxxxxxxxxxxxx",
  "current_period_start": 1672531200,
  "current_period_end": 1675209600,
  "items": [
    {
      "id": "si_xxxxxxxxxxxxxx",
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1
    }
  ],
  "customer": { /* ... customer details ... */ },
  "paymentCurrency": { /* ... currency details ... */ },
  "paymentMethod": { /* ... method details ... */ },
  "metadata": {}
}
```

## Update a Subscription

Updates an existing subscription by setting the values of the parameters passed.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription to update.  |
| `data`  | `object`  | An object containing the fields to update. See details below.  |

<strong>Data Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `description`  | `string`  | An optional description for the subscription.  |
| `metadata`  | `object`  | A set of key-value pairs to store with the subscription.  |
| `payment_behavior`  | `string`  | Determines how to handle payments. Can be `allow_incomplete`, `error_if_incomplete`, or `pending_if_incomplete`.  |
| `proration_behavior`  | `string`  | Determines how to handle prorations. Can be `always_invoice`, `create_prorations`, or `none`.  |
| `trial_end`  | `number` \| `string`  | Unix timestamp indicating the end of the trial period. Can also be `'now'`.  |
| `items`  | `SubscriptionUpdateItem[]`  | An array of items to update on the subscription. See details below.  |

<strong>SubscriptionUpdateItem Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of an existing subscription item to update or delete.  |
| `price_id`  | `string`  | The ID of the price for a new subscription item.  |
| `quantity`  | `number`  | The quantity for the subscription item.  |
| `deleted`  | `boolean`  | Set to `true` to delete this subscription item.  |
| `clear_usage`  | `boolean`  | For metered billing, indicates whether to clear usage on deletion.  |

<strong>Returns</strong>

Returns the updated subscription object.

<strong>Example</strong>

**Updating a subscription's metadata**

```javascript
async function updateSubscriptionMetadata(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.update(subscriptionId, {
      metadata: {
        order_id: 'order_12345'
      }
    });
    console.log('Subscription updated:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error updating subscription:', error.message);
  }
}

// Example usage:
updateSubscriptionMetadata('sub_xxxxxxxxxxxxxx');
```

<strong>Example Response</strong>

```json
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "metadata": {
    "order_id": "order_12345"
  }
  // ... other subscription properties
}
```

## List Subscriptions

Returns a paginated list of subscriptions. You can filter the list based on various criteria.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `status`  | `string`  | Filter subscriptions by status (e.g., `'active'`, `'trialing'`). Comma-separated for multiple values.  |
| `customer_id`  | `string`  | Filter subscriptions by a specific customer ID.  |
| `customer_did`  | `string`  | Filter subscriptions by a specific customer DID.  |
| `metadata.{key}`  | `string`  | Filter by custom metadata fields.  |
| `order`  | `string` \| `string[]`  | Sort order (e.g., `'created_at:DESC'`).  |
| `activeFirst`  | `boolean`  | If `true`, active and trialing subscriptions are listed first.  |
| `page`  | `number`  | The page number for pagination (default: `1`).  |
| `pageSize`  | `number`  | The number of items per page (default: `20`).  |

<strong>Returns</strong>

Returns a paginated list of subscription objects.

| Name  | Type  | Description  |
|---|---|---|
| `list`  | `TSubscriptionExpanded[]`  | An array of subscription objects for the current page.  |
| `count`  | `number`  | The total number of subscriptions matching the query.  |
| `paging`  | `object`  | An object containing pagination details (`page`, `pageSize`).  |

<strong>Example</strong>

**Listing all active subscriptions**

```javascript
async function listActiveSubscriptions() {
  try {
    const response = await payment.subscriptions.list({
      status: 'active',
      pageSize: 10
    });
    console.log(`Found ${response.count} active subscriptions.`);
    console.log('First page:', response.list);
    return response;
  } catch (error) {
    console.error('Error listing subscriptions:', error.message);
  }
}

// Example usage:
listActiveSubscriptions();
```

<strong>Example Response</strong>

```json
{
  "count": 50,
  "list": [
    {
      "id": "sub_xxxxxxxxxxxxxx",
      "status": "active"
      // ... other subscription properties
    }
    // ... more subscriptions
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
```

## Search Subscriptions

Performs a search for subscriptions based on a query string.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `query`  | `string`  | The search string to match against subscription fields.  |
| `page`  | `number`  | The page number for pagination (default: `1`).  |
| `pageSize`  | `number`  | The number of items per page (default: `20`).  |

<strong>Returns</strong>

Returns a paginated list of subscription objects matching the search query.

<strong>Example</strong>

**Searching for a subscription**

```javascript
async function searchForSubscription(query) {
  try {
    const response = await payment.subscriptions.search({ query });
    console.log(`Search results for "${query}":`, response.list);
    return response;
  } catch (error) {
    console.error('Error searching subscriptions:', error.message);
  }
}

// Example usage:
searchForSubscription('some_customer_did');
```

## Cancel a Subscription

Cancels a customer's subscription. The subscription can be canceled immediately or at the end of the current billing period.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription to cancel.  |
| `body`  | `object`  | An object containing cancellation details.  |

<strong>Body Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `at`  | `string`  | When to cancel. Can be `'now'`, `'current_period_end'`, or `'custom'`. Default is `'current_period_end'`.  |
| `time`  | `number` \| `string`  | Required if `at` is `'custom'`. A future Unix timestamp for cancellation.  |
| `refund`  | `string`  | Specifies if a refund should be issued. Can be `'none'`, `'proration'`, or `'last'`.  |
| `feedback`  | `string`  | Customer feedback for the cancellation.  |
| `comment`  | `string`  | Internal comment about the cancellation.  |
| `reason`  | `string`  | The reason for cancellation (e.g., `'cancellation_requested'`).  |

<strong>Returns</strong>

Returns the updated subscription object with cancellation details.

<strong>Example</strong>

**Canceling a subscription at period end**

```javascript
async function cancelSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end',
      reason: 'cancellation_requested'
    });
    console.log('Subscription scheduled for cancellation:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error canceling subscription:', error.message);
  }
}

// Example usage:
cancelSubscription('sub_xxxxxxxxxxxxxx');
```

## Recover a Subscription

Reactivates a subscription that has been scheduled for cancellation but has not yet been canceled.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription to recover.  |

<strong>Returns</strong>

Returns the updated, active subscription object.

<strong>Example</strong>

**Recovering a canceled subscription**

```javascript
async function recoverSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.recover(subscriptionId);
    console.log('Subscription recovered:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error recovering subscription:', error.message);
  }
}

// Example usage:
recoverSubscription('sub_xxxxxxxxxxxxxx');
```

## Pause a Subscription

Pauses payment collection for a subscription.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription to pause.  |
| `body`  | `object`  | An object containing pause details.  |

<strong>Body Object Properties</strong>

| Name  | Type  | Description  |
|---|---|---|
| `behavior`  | `string`  | The behavior of invoices created while paused. Can be `'keep_as_draft'`, `'mark_uncollectible'`, or `'void'`.  |
| `resumes_at`  | `number`  | A Unix timestamp for when the subscription should automatically resume.  |

<strong>Returns</strong>

Returns the updated subscription object with a `paused` status.

<strong>Example</strong>

**Pausing a subscription**

```javascript
async function pauseSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.pause(subscriptionId, {
      behavior: 'keep_as_draft'
    });
    console.log('Subscription paused:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error pausing subscription:', error.message);
  }
}

// Example usage:
pauseSubscription('sub_xxxxxxxxxxxxxx');
```

## Resume a Subscription

Resumes payment collection for a paused subscription.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription to resume.  |

<strong>Returns</strong>

Returns the updated, active subscription object.

<strong>Example</strong>

**Resuming a subscription**

```javascript
async function resumeSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.resume(subscriptionId);
    console.log('Subscription resumed:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error resuming subscription:', error.message);
  }
}

// Example usage:
resumeSubscription('sub_xxxxxxxxxxxxxx');
```

## Delete a Subscription

Permanently deletes a subscription and all its related data. This action is irreversible and should only be used in non-production environments.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription to delete.  |

<strong>Returns</strong>

Returns the deleted subscription object.

<strong>Example</strong>

**Deleting a subscription**

```javascript
async function deleteSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.del(subscriptionId);
    console.log('Subscription deleted:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error deleting subscription:', error.message);
  }
}

// Example usage:
deleteSubscription('sub_xxxxxxxxxxxxxx');
```

## List Overdue Invoices

Retrieves a list of overdue (uncollectible) invoices for a specific subscription, along with a summary of the amounts due.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the subscription.  |

<strong>Returns</strong>

Returns an object containing the subscription, a list of overdue invoices, and a summary of the total amounts owed per currency.

| Name  | Type  | Description  |
|---|---|---|
| `subscription`  | `TSubscription`  | The subscription object.  |
| `invoices`  | `TInvoice[]`  | An array of overdue invoice objects.  |
| `summary`  | `object`  | An object summarizing the total overdue amount for each currency.  |

<strong>Example</strong>

**Fetching overdue invoices**

```javascript
async function getOverdueInvoices(subscriptionId) {
  try {
    const result = await payment.subscriptions.overdueInvoices(subscriptionId);
    console.log('Overdue Invoices Summary:', result.summary);
    console.log('Invoices:', result.invoices);
    return result;
  } catch (error) {
    console.error('Error fetching overdue invoices:', error.message);
  }
}

// Example usage:
getOverdueInvoices('sub_xxxxxxxxxxxxxx');
```

## Return Stake

Initiates the process of returning staked funds associated with a canceled subscription that used an ArcBlock payment method.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | The ID of the canceled subscription.  |

<strong>Returns</strong>

Returns an object indicating the success of scheduling the stake return job.

| Name  | Type  | Description  |
|---|---|---|
| `success`  | `boolean`  | `true` if the stake return job was successfully scheduled.  |
| `subscriptionId`  | `string`  | The ID of the subscription for which the stake is being returned.  |

<strong>Example</strong>

**Returning a stake**

```javascript
async function returnSubscriptionStake(subscriptionId) {
  try {
    const result = await payment.subscriptions.returnStake(subscriptionId);
    console.log('Stake return initiated:', result);
    return result;
  } catch (error) {
    console.error('Error returning stake:', error.message);
  }
}

// Example usage:
returnSubscriptionStake('sub_xxxxxxxxxxxxxx');
```

---

## Webhook Endpoints

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/api-reference-webhook-endpoints-381920/

Webhook endpoints allow PaymentKit to send asynchronous event notifications to your server. This is essential for handling events like successful payments, subscription updates, or failed charges. By creating and managing webhook endpoints, you can ensure your application stays in sync with the state of your payments and customers.

For a conceptual overview and best practices on securing your webhooks, please refer to our guide on [Webhooks](/en/docs/payment-kit-sdk/core-concepts-webhooks-381920/).

## Create a Webhook Endpoint

Creates a new endpoint for receiving webhook events from PaymentKit.

### Parameters

| Name  | Type  | Description  | Required  |
|---|---|---|---|
| `url`  | `string`  | The URL of your server that will receive the webhook POST requests.  | Yes  |
| `enabled_events`  | `string[]`  | An array of event types that you want to send to this endpoint.  | Yes  |
| `description`  | `string`  | An optional description for the webhook endpoint.  | No  |
| `status`  | `'enabled' \| 'disabled'`  | Optional. The status of the endpoint. If not provided, it defaults to `enabled`.  | No  |
| `metadata`  | `Record<string, any>`  | Optional. A set of key-value pairs that you can attach to the object for your own reference.  | No  |

### Returns

Returns the created `WebhookEndpoint` object if the call is successful.

### Example

**Create Endpoint**

```javascript
async function createWebhookEndpoint() {
  try {
    const endpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/my/webhook/handler',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.updated',
      ],
      description: 'Endpoint for production events',
    });
    console.log('Webhook Endpoint Created:', endpoint);
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

createWebhookEndpoint();
```

### Example Response

**Response**

```json
{
  "id": "we_1a2b3c4d5e6f7g8h",
  "url": "https://example.com/my/webhook/handler",
  "description": "Endpoint for production events",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.updated"
  ],
  "status": "enabled",
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {}
}
```

## Retrieve a Webhook Endpoint

Retrieves the details of an existing webhook endpoint by its unique identifier.

### Parameters

| Name  | Type  | Description  | Required  |
|---|---|---|---|
| `id`  | `string`  | The unique identifier of the webhook endpoint.  | Yes  |

### Returns

Returns the `WebhookEndpoint` object corresponding to the provided ID.

### Example

**Retrieve Endpoint**

```javascript
async function retrieveWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.retrieve(endpointId);
    console.log('Retrieved Webhook Endpoint:', endpoint);
  } catch (error) {
    console.error('Error retrieving webhook endpoint:', error.message);
  }
}

retrieveWebhookEndpoint('we_1a2b3c4d5e6f7g8h');
```

## Update a Webhook Endpoint

Updates an existing webhook endpoint by setting the values of the parameters passed.

### Parameters

| Name  | Type  | Description  | Required  |
|---|---|---|---|
| `id`  | `string`  | The identifier of the webhook endpoint to update.  | Yes  |
| `url`  | `string`  | The URL of your server that will receive the webhook POST requests.  | No  |
| `description`  | `string`  | An optional description for the webhook endpoint.  | No  |
| `enabled_events`  | `string[]`  | An array of event types that you want to send to this endpoint.  | No  |
| `status`  | `'enabled' \| 'disabled'`  | The status of the endpoint. Use `disabled` to temporarily stop sending events.  | No  |
| `metadata`  | `Record<string, any>`  | A set of key-value pairs that you can attach to the object.  | No  |

### Returns

Returns the updated `WebhookEndpoint` object.

### Example

**Update Endpoint**

```javascript
async function updateWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.update(endpointId, {
      description: 'New updated description',
      status: 'disabled',
    });
    console.log('Webhook Endpoint Updated:', endpoint);
  } catch (error) {
    console.error('Error updating webhook endpoint:', error.message);
  }
}

updateWebhookEndpoint('we_1a2b3c4d5e6f7g8h');
```

## List all Webhook Endpoints

Returns a paginated list of all your webhook endpoints.

### Parameters

| Name  | Type  | Description  | Required  |
|---|---|---|---|
| `status`  | `string`  | Optional. A comma-separated list of statuses to filter by (e.g., `'enabled'` or `'enabled,disabled'`).  | No  |
| `page`  | `number`  | Optional. The page number for pagination, starting from 1. Defaults to `1`.  | No  |
| `pageSize`  | `number`  | Optional. The number of items to return per page, between 1 and 100. Defaults to `20`.  | No  |

### Returns

Returns a paginated object containing a `list` of `WebhookEndpoint` objects, a `count` of total items, and `paging` information.

### Example

**List Endpoints**

```javascript
async function listWebhookEndpoints() {
  try {
    const endpoints = await payment.webhookEndpoints.list({
      status: 'enabled',
      pageSize: 5,
    });
    console.log(`Found ${endpoints.count} enabled endpoints:`);
    endpoints.list.forEach(ep => console.log(`- ${ep.id} (${ep.url})`));
  } catch (error) {
    console.error('Error listing webhook endpoints:', error.message);
  }
}

listWebhookEndpoints();
```

## Delete a Webhook Endpoint

Permanently deletes a webhook endpoint. This action is irreversible.

### Parameters

| Name  | Type  | Description  | Required  |
|---|---|---|---|
| `id`  | `string`  | The unique identifier of the webhook endpoint to delete.  | Yes  |

### Returns

Returns the deleted `WebhookEndpoint` object.

### Example

**Delete Endpoint**

```javascript
async function deleteWebhookEndpoint(endpointId) {
  try {
    const deletedEndpoint = await payment.webhookEndpoints.del(endpointId);
    console.log('Webhook Endpoint Deleted:', deletedEndpoint);
  } catch (error) {
    console.error('Error deleting webhook endpoint:', error.message);
  }
}

deleteWebhookEndpoint('we_1a2b3c4d5e6f7g8h');
```

## The Webhook Endpoint Object

The `WebhookEndpoint` object represents a configured destination for event notifications.

| Attribute  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | Unique identifier for the webhook endpoint object.  |
| `url`  | `string`  | The endpoint's URL for receiving webhook POST requests.  |
| `description`  | `string`  | An optional, user-provided description of the endpoint.  |
| `enabled_events`  | `string[]`  | The list of event types this endpoint is subscribed to.  |
| `status`  | `string`  | The current status of the webhook endpoint (`enabled` or `disabled`).  |
| `api_version`  | `string`  | The API version used to render the event data sent to the endpoint.  |
| `livemode`  | `boolean`  | `true` if the object exists in live mode, or `false` if in test mode.  |
| `metadata`  | `object`  | A set of key-value pairs attached to the object.  |
| `created_at`  | `string`  | An ISO 8601 timestamp indicating when the object was created.  |
| `updated_at`  | `string`  | An ISO 8601 timestamp indicating when the object was last updated.  |

---

## Core Concepts

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-381920/

The PaymentKit Node.js SDK is designed to handle a wide range of billing scenarios. This section provides practical guides for implementing the most common payment workflows. Whether you're setting up simple one-time charges, managing recurring subscriptions, or building a sophisticated credit-based system, these guides will walk you through the key concepts and implementation steps.

Each guide focuses on a specific billing model, providing code examples and explanations to help you integrate payments quickly and effectively.

::::card-group
::link-card{title="One-Time Payments" description="Learn how to create single charges for goods or services using Checkout Sessions, Payment Intents, or Payment Links." icon="shopping-cart" href="/en/docs/payment-kit-sdk/core-concepts-one-time-payments-381920/"}
::link-card{title="Subscriptions" description="Implement recurring billing for your products and services, and learn how to manage the subscription lifecycle." icon="refresh" href="/en/docs/payment-kit-sdk/core-concepts-subscriptions-381920/"}
::link-card{title="Credit-Based Billing" description="Set up usage metering, grant credits to customers, and track consumption for pay-as-you-go billing models." icon="wallet" href="/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/"}
::link-card{title="Credit Top-Up" description="Configure credit currencies to allow customers to purchase credits and add them to their account balance." icon="plus" href="/en/docs/payment-kit-sdk/core-concepts-credit-top-up-381920/"}
::link-card{title="Webhooks" description="Receive and handle asynchronous events from the PaymentKit API to automate backend processes and workflows." icon="link" href="/en/docs/payment-kit-sdk/core-concepts-webhooks-381920/"}
::::

After exploring these core concepts, you may want to dive deeper into the specific methods and parameters available. For a comprehensive overview of all SDK functionalities, please see the [API Reference](/en/docs/payment-kit-sdk/api-reference-381920/).

---

## Credit-Based Billing

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/

Credit-based billing is a flexible, pay-as-you-go model perfect for services where usage varies, such as API calls, data storage, or compute time. Instead of a fixed recurring fee, customers consume credits that they have either purchased or been granted.

This guide will walk you through the end-to-end process of setting up and managing a credit-based billing system using the PaymentKit SDK. The core components you'll work with are:

- <strong>Meters</strong>: Define and track the usage of a specific feature.
- <strong>Credit Grants</strong>: Issue credits to your customers.
- <strong>Meter Events</strong>: Report customer usage as it happens.
- <strong>Credit Transactions</strong>: A ledger of all credit activities, including grants and consumptions.

## The Credit Billing Workflow

![Credit-Based Billing](https://media.arcblock.io/lib/c4/c4efe58a5a3c7870.w1600.webp)

## Step 1: Create a Meter to Track Usage

A Meter is a resource that tracks the consumption of a specific feature. You define what event to track, how to aggregate the usage (e.g., sum of all values), and the unit of measurement.

**Create a Meter**

```javascript
import payment from '@blocklet/payment-js';

async function setupMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.v1',
      aggregation_method: 'sum',
      unit: 'calls',
      description: 'Tracks the number of API calls made by a customer.'
    });
    console.log('Meter created:', meter.id);
    return meter;
  } catch (error) {
    console.error('Error creating meter:', error.message);
  }
}

setupMeter();
```

In this example, we create a meter named 'API Calls' that listens for an event called `api.calls.v1`. The `aggregation_method: 'sum'` tells PaymentKit to add up the `value` from all reported events to calculate total usage.

## Step 2: Grant Credits to a Customer

Once you have a meter, you need to give customers credits to spend. You can grant credits as a promotional bonus or after they've made a purchase. Each credit grant specifies an amount, a currency, and the customer it belongs to.

**Grant Promotional Credits**

```javascript
import payment from '@blocklet/payment-js';

async function grantNewUserBonus(customerId, currencyId) {
  try {
    const thirtyDaysFromNow = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60);
    const creditGrant = await payment.creditGrants.create({
      customer_id: customerId, // e.g., 'cus_xxx'
      currency_id: currencyId, // e.g., 'pc_xxx'
      amount: '1000',
      name: 'New User Bonus',
      category: 'promotional', // Can be 'paid' or 'promotional'
      expires_at: thirtyDaysFromNow
    });
    console.log('Credit grant created:', creditGrant.id);
    return creditGrant;
  } catch (error) {
    console.error('Error creating credit grant:', error.message);
  }
}

// grantNewUserBonus('cus_xxx', 'pc_xxx');
```

This code grants 1,000 promotional credits to a customer, which will expire in 30 days. Credits categorized as `paid` are typically used before `promotional` ones.

## Step 3: Report Usage with Meter Events

When a customer uses a metered feature, your application must report it to PaymentKit by creating a Meter Event. This event should match the `event_name` of the meter you created.

To prevent duplicate usage reports from network issues or retries, always include a unique `identifier` for each event. PaymentKit will process only the first event received with a given identifier.

**Report a Usage Event**

```javascript
import payment from '@blocklet/payment-js';

async function reportApiCall(customerId, subscriptionId) {
  try {
    const meterEvent = await payment.meterEvents.create({
      event_name: 'api.calls.v1', // Must match the meter's event_name
      payload: {
        customer_id: customerId, // 'cus_xxx'
        value: '10', // The amount of usage to report
        subscription_id: subscriptionId, // Optional: associate with a subscription
      },
      identifier: `unique_api_call_${Date.now()}` // Idempotency key
    });
    console.log('Meter event reported:', meterEvent.id);
    return meterEvent;
  } catch (error) {
    console.error('Error reporting meter event:', error.message);
  }
}

// reportApiCall('cus_xxx', 'sub_xxx');
```

When this event is processed, PaymentKit will automatically find the customer's active credit grants and deduct 10 credits from their balance.

## Step 4: Check Credit Balances

You can check a customer's remaining credit balance at any time using the `summary` method. This is useful for displaying the balance in your application's UI.

**Check Credit Summary**

```javascript
import payment from '@blocklet/payment-js';

async function checkCreditBalance(customerId) {
  try {
    const creditSummary = await payment.creditGrants.summary({
      customer_id: customerId, // 'cus_xxx'
    });
    console.log('Credit Summary:', creditSummary);
    return creditSummary;
  } catch (error) {
    console.error('Error fetching credit summary:', error.message);
  }
}

// checkCreditBalance('cus_xxx');
```

<strong>Example Response</strong>

```json
{
  "pc_xxx": { // currency_id
    "paymentCurrency": {
      "id": "pc_xxx",
      "name": "Credit",
      "symbol": "C",
      "decimal": 2,
      "type": "credit"
    },
    "totalAmount": "1000.00",
    "remainingAmount": "990.00",
    "grantCount": 1
  }
}
```

The response is grouped by currency, showing the total granted credits and the amount remaining for the specified customer.

## Step 5: View Transaction History

To see a detailed audit log of all credit activities for a customer—including grants, consumptions, and expirations—you can list their credit transactions.

**List Credit Transactions**

```javascript
import payment from '@blocklet/payment-js';

async function getTransactionHistory(customerId) {
  try {
    const transactions = await payment.creditTransactions.list({
      customer_id: customerId, // 'cus_xxx'
      pageSize: 10
    });
    console.log(`Found ${transactions.total} transactions.`);
    transactions.data.forEach(tx => {
      console.log(`- ID: ${tx.id}, Type: ${tx.type}, Amount: ${tx.amount}, Balance: ${tx.running_balance}`);
    });
    return transactions;
  } catch (error) {
    console.error('Error listing credit transactions:', error.message);
  }
}

// getTransactionHistory('cus_xxx');
```

This provides a complete history, allowing you to trace every change to a customer's credit balance.

## Next Steps

You now have a complete overview of the credit-based billing workflow. For more detailed information on each component, including all available parameters and methods, please refer to the API reference documentation.

::::card-group
::link-card{title="Meters API Reference" description="Explore all methods for creating and managing meters." icon="activity" href="/en/docs/payment-kit-sdk/api-reference-meters-381920/"}
::link-card{title="Meter Events API Reference" description="Learn more about reporting usage and fetching statistics." icon="radio" href="/en/docs/payment-kit-sdk/api-reference-meter-events-381920/"}
::link-card{title="Credit Grants API Reference" description="See how to manage credit grants and balances." icon="gift" href="/en/docs/payment-kit-sdk/api-reference-credit-grants-381920/"}
::link-card{title="Credit Transactions API Reference" description="Get details on retrieving transaction history." icon="clock" href="/en/docs/payment-kit-sdk/api-reference-credit-transactions-381920/"}
::::

To learn how customers can purchase credits or set up automatic recharges, see the [Credit Top-Up](/en/docs/payment-kit-sdk/core-concepts-credit-top-up-381920/) guide.

---

## Credit Top-Up

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-credit-top-up-381920/

PaymentKit's credit-based billing system allows customers to replenish their credit balance through top-ups. You can configure a credit currency to be rechargeable, enabling both manual one-time top-ups and automatic recharges when the balance falls below a set threshold.

This guide will walk you through the process of programmatically setting up a credit currency for top-ups. The actual auto-recharge settings for a customer (e.g., the low-balance threshold and recharge amount) are managed directly by the customer through the Payment Kit billing portal, ensuring a seamless user experience.

## Top-Up Workflow Overview

Before diving into the implementation, it's helpful to understand the entire top-up process from the user's perspective. When a credit currency is configured for recharge, a checkout link is generated. Your application redirects the user to this link to complete the payment, and PaymentKit automatically handles granting the credits upon success.

![Credit Top-Up](https://media.arcblock.io/lib/0f/0f24f905e0fcf9dd.w1600.webp)

## Step 1: Create a Top-Up Package

A top-up package is a standard `Product` and `Price` that defines how many credits a customer receives and how much they pay. The key is to embed a `credit_config` object in the product's metadata.

First, create a product that represents the credit pack. The metadata should specify which credit currency this product replenishes and the amount of credits granted upon purchase.

**Create a Product for the Top-Up Package**

```javascript
const topUpProduct = await payment.products.create({
  name: '1000 Credits Pack',
  description: 'Top up your account with 1000 credits.',
  type: 'service',
  metadata: {
    // This product grants credits when purchased
    credit_config: {
      currency_id: 'pc_credit_xxxxxx', // The ID of your credit currency
      amount: '1000', // Amount of credits to grant
    },
  },
});
```

Next, create a one-time price for this product. This price will determine the cost and the payment currency (e.g., USDT, ETH) for the top-up.

**Create a Price for the Top-Up Package**

```javascript
const topUpPrice = await payment.prices.create({
  product_id: topUpProduct.id,
  type: 'one_time',
  unit_amount: '10', // e.g., 10 USDT
  currency_id: 'pc_usdt_xxxxxx', // The currency used to pay for the credits
});
```

## Step 2: Configure the Credit Currency

Once you have a price for your top-up package, you need to link it to your credit currency. This is done using the `updateRechargeConfig` method, which designates your new price as the base package for recharges.

### updateRechargeConfig(id, data)

This method associates a `base_price_id` with a credit currency, enabling it for top-ups.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the credit currency to configure (e.g., `pc_credit_xxxxxx`).  |
| `data.base_price_id`  | `string`  | <strong>Required.</strong> The ID of the `Price` object that serves as the top-up package.  |

<strong>Example</strong>

**Configure a Credit Currency for Recharge**

```javascript
import payment from '@blocklet/payment-js';

async function configureRecharge() {
  try {
    const creditCurrencyId = 'pc_credit_xxxxxx'; // Your credit currency ID
    const topUpPriceId = 'price_yyyyyyyy'; // The price ID from Step 1

    const updatedCurrency = await payment.paymentCurrencies.updateRechargeConfig(
      creditCurrencyId,
      {
        base_price_id: topUpPriceId,
      }
    );

    console.log('Recharge config updated:', updatedCurrency.recharge_config);
  } catch (error) {
    console.error('Error configuring recharge:', error.message);
  }
}

configureRecharge();
```

<strong>Example Response</strong>

```json
{
  "currency_id": "pc_credit_xxxxxx",
  "recharge_config": {
    "base_price_id": "price_yyyyyyyy"
  },
  "message": "Recharge config updated successfully"
}
```

## Step 3: Retrieve the Recharge Configuration

To initiate a top-up, your application needs to fetch the `payment_url`. Use the `getRechargeConfig` method to retrieve the full recharge configuration, including the checkout URL and details about the base price.

### getRechargeConfig(id)

Fetches the recharge configuration for a specified credit currency.

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `id`  | `string`  | <strong>Required.</strong> The ID of the credit currency.  |

<strong>Returns</strong>

Returns an object containing the currency information and its `recharge_config`. The `payment_url` within the configuration is the link you'll use to direct users to the checkout page.

<strong>Example</strong>

**Get the Top-Up URL**

```javascript
import payment from '@blocklet/payment-js';

async function getTopUpLink(creditCurrencyId) {
  try {
    const config = await payment.paymentCurrencies.getRechargeConfig(creditCurrencyId);

    if (config.recharge_config && config.recharge_config.payment_url) {
      console.log('Redirect user to this URL:', config.recharge_config.payment_url);
      return config.recharge_config.payment_url;
    } else {
      console.log('Recharge is not configured for this currency.');
      return null;
    }
  } catch (error) {
    console.error('Error fetching recharge config:', error.message);
  }
}

getTopUpLink('pc_credit_xxxxxx');
```

<strong>Example Response</strong>

```json
{
  "currency_id": "pc_credit_xxxxxx",
  "currency_info": {
    "id": "pc_credit_xxxxxx",
    "name": "App Credits",
    "symbol": "CRD",
    "decimal": 2,
    "type": "credit"
  },
  "recharge_config": {
    "base_price_id": "price_yyyyyyyy",
    "basePrice": {
      "id": "price_yyyyyyyy",
      "unit_amount": "1000",
      "currency_id": "pc_usdt_xxxxxx",
      // ... other price details
      "product": {
        "id": "prod_zzzzzzzz",
        "name": "1000 Credits Pack",
        // ... other product details
      }
    },
    "payment_url": "https://payment.arcblock.io/checkout/pay/pl_xxxxxxxx"
  }
}
```

With these steps complete, your credit currency is now fully enabled for top-ups. Your application can fetch the payment URL and provide a seamless way for users to add more credits to their accounts. For more details on the broader credit system, see the [Credit-Based Billing](/en/docs/payment-kit-sdk/core-concepts-credit-billing-381920/) guide.

---

## Discounts

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-discounts-381920/

PaymentKit offers a flexible discount system using Coupons and Promotion Codes. This allows you to provide various types of discounts to your customers, such as percentage-off, fixed amount-off, and limited-time offers.

- <strong>Coupons</strong>: Define the core discount rules, such as the discount percentage or amount, duration (e.g., once, forever, repeating), and maximum total redemptions.
- <strong>Promotion Codes</strong>: These are the customer-facing codes that are linked to a coupon. They can have their own set of rules, such as individual redemption limits, expiration dates, and restrictions (e.g., for first-time customers only).

You can think of a Coupon as a template for a discount, and Promotion Codes as specific instances of that discount that customers can use.

For a detailed breakdown of all available API operations, see the [Coupons API Reference](/en/docs/payment-kit-sdk/api-reference-coupons-381920/) and [Promotion Codes API Reference](/en/docs/payment-kit-sdk/api-reference-promotion-codes-381920/).

## How Discounts Work

The following diagram illustrates the relationship between Coupons, Promotion Codes, and their application during a transaction.

![Discounts](https://media.arcblock.io/lib/60/60003f73797b792c.w1600.webp)

## Creating Coupons

A Coupon object contains information about a discount, such as whether it's a percentage or a fixed amount. You can create coupons and then attach promotion codes to them.

### Create a Coupon with Promotion Codes

You can create a coupon and one or more associated promotion codes in a single API call. This is useful for setting up a new campaign quickly.

**Create Coupon with Promo Code**

```javascript
import payment from '@blocklet/payment-js';

async function createDiscountCampaign() {
  try {
    const result = await payment.coupons.create({
      name: 'New User Discount',
      percent_off: 20,
      duration: 'once',
      max_redemptions: 1000, // Max redemptions for the coupon itself
      promotion_codes: [
        {
          code: 'WELCOME20',
          description: 'Welcome discount for new users',
          max_redemptions: 100, // Max redemptions for this specific code
          expires_at: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60) // 30 days from now
        }
      ]
    });

    console.log('Coupon created:', result.coupon);
    console.log('Promotion codes created:', result.promotion_codes);
  } catch (error) {
    console.error('Error creating coupon:', error.message);
  }
}

createDiscountCampaign();
```

<strong>Parameters</strong>

- **name** `string` *(required)* — The name of the coupon, for internal display.
- **percent_off** `number` — A percentage (0-100) that will be taken off the subtotal. Must not be provided if `amount_off` is set.
- **amount_off** `string` — A fixed amount to be taken off the subtotal. Must not be provided if `percent_off` is set.
- **currency_id** `string` — Required if amount_off is set. The ID of the currency for the fixed amount discount.
- **duration** `string` *(required)* — Describes how long the discount will be applied. Can be once, forever, or repeating.
- **duration_in_months** `number` — If duration is repeating, the number of months the coupon applies.
- **max_redemptions** `number` — The maximum number of times the coupon can be redeemed.
- **redeem_by** `number` — A Unix timestamp specifying the expiration date for the coupon.
- **promotion_codes** `array` — An array of promotion code objects to create and attach to this coupon.
  - **code** `string` — The customer-facing code. If omitted, a random code will be generated.
  - **max_redemptions** `number` — Maximum number of times this specific promotion code can be used.
  - **expires_at** `number` — Unix timestamp for when this promotion code expires.
  - **description** `string` — An optional description for the promotion code.
- **metadata** `object` — A set of key-value pairs to store additional information.

## Creating Promotion Codes

While you can create promotion codes along with a coupon, you can also create them separately and attach them to an existing coupon. This is useful for generating multiple unique codes for a single campaign.

### Create a Standalone Promotion Code

**Create Promotion Code**

```javascript
import payment from '@blocklet/payment-js';

async function createPromoCode(couponId) {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: couponId, // ID of an existing coupon
      code: 'SAVE15NOW',
      description: 'Save 15% on your next purchase',
      max_redemptions: 500,
      restrictions: {
        first_time_transaction: true, // Only for new customers
      }
    });
    console.log('Promotion code created:', promotionCode);
  } catch (error) {
    console.error('Error creating promotion code:', error.message);
  }
}

createPromoCode('coupon_xxx'); // Replace with your actual coupon ID
```

<strong>Parameters</strong>

- **coupon_id** `string` *(required)* — The ID of the coupon this promotion code should be attached to.
- **code** `string` — The customer-facing code. If omitted, a random code will be generated.
- **active** `boolean` (default: `true`) — Whether the promotion code is currently active.
- **max_redemptions** `number` — Maximum number of times this specific promotion code can be used.
- **expires_at** `number` — Unix timestamp for when this promotion code expires.
- **restrictions** `object` — Applies restrictions to this promotion code.
  - **first_time_transaction** `boolean` — If true, the promotion code can only be redeemed by customers with no prior payments.
  - **minimum_amount** `number` — The minimum transaction amount required to use the code.
  - **minimum_amount_currency** `string` — The currency for the minimum amount.
- **metadata** `object` — A set of key-value pairs to store additional information.

## Applying Discounts at Checkout

To allow customers to enter a promotion code on the checkout page, you must explicitly enable this option when creating a Checkout Session or a Payment Link.

### Enable on a Checkout Session

Set the `allow_promotion_codes` parameter to `true` when creating a Checkout Session. This will add a field to the payment page for customers to enter their code.

**Enable Promotion Codes**

```javascript
import payment from '@blocklet/payment-js';

async function createCheckoutWithDiscounts() {
  try {
    const session = await payment.checkout.sessions.create({
      success_url: 'https://example.com/success',
      cancel_url: 'https://example.com/cancel',
      mode: 'payment',
      line_items: [
        { price_id: 'price_xxx', quantity: 1 }
      ],
      allow_promotion_codes: true // This enables the promo code field
    });
    console.log('Checkout session created with promotion codes enabled:', session.url);
  } catch (error) {
    console.error('Error creating checkout session:', error.message);
  }
}

createCheckoutWithDiscounts();
```

### Enable on a Payment Link

The same logic applies to reusable Payment Links. Setting `allow_promotion_codes` to `true` ensures that anyone using the link can apply a valid promotion code.

**Enable on Payment Link**

```javascript
import payment from '@blocklet/payment-js';

async function createPaymentLinkWithDiscounts() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [{
        price_id: 'price_xxx',
        quantity: 1,
      }],
      allow_promotion_codes: true,
    });
    console.log('Payment link created with promotion codes enabled:', paymentLink.url);
  } catch (error) {
    console.error('Error creating payment link:', error.message);
  }
}

createPaymentLinkWithDiscounts();
```

## Managing Discounts

The SDK provides various methods to manage and track your discounts.

### Retrieve a Promotion Code by its Code

You can fetch a promotion code's details directly using the customer-facing code string.

**Get Promotion Code by Code**

```javascript
import payment from '@blocklet/payment-js';

async function getPromoDetails(code) {
  try {
    const promoByCode = await payment.promotionCodes.byCode(code);
    console.log('Found promotion code:', promoByCode);
    // You can now access the associated coupon details
    console.log('Discount:', promoByCode.coupon);
  } catch (error) {
    console.error(`Promotion code '${code}' not found or an error occurred:`, error.message);
  }
}

getPromoDetails('WELCOME20');
```

### Check Coupon Usage

Determine if a coupon has been redeemed at least once. This is useful for deciding whether a coupon's rules can still be edited.

**Check Coupon Usage**

```javascript
import payment from '@blocklet/payment-js';

async function checkCouponUsage(couponId) {
  try {
    const { used } = await payment.coupons.used(couponId);
    if (used) {
      console.log(`Coupon ${couponId} has been used and its rules are now locked.`);
    } else {
      console.log(`Coupon ${couponId} has not been used yet.`);
    }
  } catch (error) {
    console.error('Error checking coupon usage:', error.message);
  }
}

checkCouponUsage('coupon_xxx'); // Replace with a valid coupon ID
```

### List Redemptions

You can retrieve a paginated list of customers or subscriptions that have redeemed a specific coupon or promotion code.

**List Coupon Redemptions**

```javascript
import payment from '@blocklet/payment-js';

async function getCouponRedemptions(couponId) {
  try {
    const redemptions = await payment.coupons.redemptions(couponId, {
      type: 'customer', // or 'subscription'
      page: 1,
      pageSize: 10
    });
    console.log(`Found ${redemptions.count} customer redemptions for coupon ${couponId}:`);
    redemptions.customers.forEach(customer => {
      console.log(`- Customer ID: ${customer.id}`);
    });
  } catch (error) {
    console.error('Error getting redemptions:', error.message);
  }
}

getCouponRedemptions('coupon_xxx'); // Replace with a valid coupon ID
```

---

## One-Time Payments

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-one-time-payments-381920/

PaymentKit offers several flexible ways to handle one-time charges for goods or services. This guide will walk you through the three primary methods available in the Node.js SDK, helping you choose the best approach for your specific needs.

Each method caters to a different use case, from fully-hosted payment pages to deeply integrated custom payment flows.

::::card-group
::link-card{title="Checkout Sessions" description="The quickest way to get started. Redirect users to a secure, pre-built payment page hosted by PaymentKit." icon="layout"}
::link-card{title="Payment Links" description="Create a shareable, reusable link to a payment page. Ideal for social media, emails, or simple buy buttons." icon="link"}
::link-card{title="Payment Intents" description="The foundational object for payments. Use it for building custom payment UIs and managing the charge lifecycle." icon="routes"}
::::

## Checkout Sessions

A Checkout Session is the easiest way to accept payments. It creates a secure, hosted payment page that takes care of the entire checkout process. You simply create a session, redirect your customer to the provided URL, and PaymentKit handles the rest.

This approach is ideal for standard e-commerce flows, donation buttons, or any scenario where you want a fast, secure, and fully-featured checkout experience without building the UI yourself.

### How It Works

::::steps
:::step{title="Create the Session"}
Your server uses the SDK to create a session, specifying line items, success and cancellation URLs, and other details.
:::

:::step{title="Redirect the Customer"}
The API returns a session object containing a `url`. You redirect your customer to this URL.
:::

:::step{title="Customer Pays"}
The customer completes the payment on the hosted page.
:::

:::step{title="Redirect Back"}
PaymentKit redirects the customer back to your `success_url` or `cancel_url`.
:::
::::

### Example: Creating a Checkout Session

Here’s how to create a session for a one-time payment.

**Create Checkout Session**

```javascript
import payment from '@blocklet/payment-js';

async function createCheckoutSession() {
  try {
    const session = await payment.checkout.sessions.create({
      mode: 'payment', // Specifies a one-time payment
      success_url: 'https://your-site.com/payment-success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://your-site.com/payment-cancelled',
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // Replace with your Price ID
          quantity: 1,
        },
      ],
      expires_at: Math.floor(Date.now() / 1000) + (30 * 60), // Session expires in 30 minutes
    });

    console.log('Checkout Session URL:', session.url);
    // Now, redirect your user to session.url
  } catch (error) {
    console.error('Error creating session:', error.message);
  }
}

createCheckoutSession();
```

After creating the session, the `session.url` should be used to redirect the customer to the payment page. For a complete list of parameters and options, see the [Checkout Sessions API Reference](/en/docs/payment-kit-sdk/api-reference-checkout-sessions-381920/).

## Payment Links

Payment Links provide a way to create a reusable link to a checkout page for a specific product. Once created, you can share this link across multiple channels like email, social media, or embed it in a simple "Buy Now" button on your website. They are perfect for selling a single item or service without requiring a full shopping cart integration.

### How It Works

::::steps
:::step{title="Create the Link"}
Use the SDK to create a Payment Link, specifying one or more line items.
:::

:::step{title="Share the URL"}
The API returns a permanent `url` for the link.
:::

:::step{title="Customer Pays"}
Any customer who visits the URL can complete the payment.
:::
::::

### Example: Creating a Payment Link

**Create Payment Link**

```javascript
import payment from '@blocklet/payment-js';

async function createPaymentLink() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // Replace with your Price ID
          quantity: 1,
        },
      ],
      metadata: {
        campaign: 'summer_sale_2024'
      }
    });

    console.log('Shareable Payment Link:', paymentLink.url);
  } catch (error) {
    console.error('Error creating payment link:', error.message);
  }
}

createPaymentLink();
```

You can also update a payment link, for example, to archive it when it's no longer needed using `payment.paymentLinks.archive(id)`. For more details, visit the [Payment Links API Reference](/en/docs/payment-kit-sdk/api-reference-payment-links-381920/).

## Payment Intents

The Payment Intent object is the backbone of any transaction in PaymentKit. It tracks the lifecycle of a payment from creation to completion, handling various authentication steps and status changes along the way. While Checkout Sessions and Payment Links create and manage Payment Intents for you automatically, you can interact with them directly for more advanced use cases, such as building a custom payment form or handling post-payment actions.

Direct interaction with Payment Intents is typically for managing existing payments, like issuing refunds.

### Example: Refunding a Payment

After a payment is successful (e.g., via a Checkout Session), you can retrieve the associated Payment Intent ID and use it to process a refund.

**Refund a Payment**

```javascript
import payment from '@blocklet/payment-js';

// The Payment Intent ID is typically obtained from a completed Checkout Session
// or through a webhook event.
const paymentIntentId = 'pi_xxxxxxxxxxxxxx';

async function refundPayment(pi_id) {
  try {
    const refund = await payment.paymentIntents.refund(pi_id, {
      amount: '10.00', // The amount to refund
      reason: 'requested_by_customer',
      description: 'Customer was not satisfied with the product.',
    });

    console.log('Refund processed successfully:', refund.id);
  } catch (error) {
    console.error(`Error refunding payment ${pi_id}:`, error.message);
  }
}

refundPayment(paymentIntentId);
```

This gives you granular control over the payment lifecycle after the initial charge has been made. For a full list of management capabilities, see the [Payment Intents API Reference](/en/docs/payment-kit-sdk/api-reference-payment-intents-381920/).

Now that you understand how to create one-time charges, you may want to learn how to implement [Subscriptions](/en/docs/payment-kit-sdk/core-concepts-subscriptions-381920/) for recurring billing or set up [Webhooks](/en/docs/payment-kit-sdk/core-concepts-webhooks-381920/) to receive real-time notifications about payment events.

---

## Subscriptions

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-subscriptions-381920/

Subscriptions are the cornerstone of recurring revenue, allowing you to charge customers on a repeating schedule for your products and services. In PaymentKit, a subscription is created when a customer purchases a product with a recurring price.

This guide will walk you through the entire subscription lifecycle, from creation via a Checkout Session to managing its status and handling usage-based billing. Before proceeding, ensure you have created your [Products](/en/docs/payment-kit-sdk/api-reference-products-381920/) and [Prices](/en/docs/payment-kit-sdk/api-reference-prices-381920/).

## The Subscription Lifecycle

A subscription progresses through various statuses depending on payment events, trial periods, and management actions. Understanding this lifecycle is key to managing your customers effectively.

![Subscriptions](https://media.arcblock.io/lib/1c/1c3959dbd9fda298.w1600.webp)

Here are the primary statuses a subscription can have:

- `active`: The subscription is in good standing and payments are up-to-date.
- `trialing`: The customer is in a free trial period.
- `past_due`: The most recent payment attempt failed, and PaymentKit is retrying the charge.
- `canceled`: The subscription has been canceled and will not renew.
- `incomplete`: The initial payment for the subscription failed.
- `incomplete_expired`: The initial payment failed, and the retry period has expired.
- `paused`: The subscription is temporarily paused and will not generate invoices.

## Creating a Subscription

Subscriptions are not created directly. Instead, you create a [Checkout Session](/en/docs/payment-kit-sdk/api-reference-checkout-sessions-381920/) with `mode: 'subscription'`. This session guides the customer through the payment process, and upon successful completion, a subscription is automatically created.

**Create a Subscription via Checkout**

```javascript
import payment from '@blocklet/payment-js';

async function createSubscriptionCheckout() {
  try {
    const session = await payment.checkout.sessions.create({
      success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://example.com/cancel',
      mode: 'subscription',
      line_items: [
        { price_id: 'price_xxx', quantity: 1 } // Replace with your recurring price ID
      ],
      subscription_data: {
        trial_period_days: 14, // Optional: 14-day free trial
        metadata: {
          project_id: 'proj_123',
        },
      },
    });
    console.log('Checkout session created:', session.url);
    // Redirect your customer to session.url
  } catch (error) {
    console.error('Error creating checkout session:', error.message);
  }
}

createSubscriptionCheckout();
```

In this example, a checkout session is created for a product with a recurring price. Once the customer completes the payment, a new subscription will be created in a `trialing` state for 14 days before the first charge occurs.

## Managing an Existing Subscription

Once a subscription is created, you can manage it using the `payment.subscriptions` resource.

### Retrieve a Subscription

Fetch the details of a specific subscription using its ID.

**Retrieve a Subscription**

```javascript
async function getSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log(`Status of ${subscription.id}: ${subscription.status}`);
    console.log('Current period ends:', new Date(subscription.current_period_end * 1000));
  } catch (error) {
    console.error('Error retrieving subscription:', error.message);
  }
}

getSubscription('sub_xxx'); // Replace with a valid subscription ID
```

### List Subscriptions

You can list all subscriptions or filter them by properties like customer ID or status.

**List Subscriptions**

```javascript
async function listActiveSubscriptionsForCustomer(customerId) {
  try {
    const subscriptions = await payment.subscriptions.list({
      customer_id: customerId,
      status: 'active',
      activeFirst: true,
      order: 'created_at:DESC',
    });

    console.log(`Found ${subscriptions.total} active subscriptions for customer ${customerId}:`);
    subscriptions.data.forEach(sub => {
      console.log(`- ID: ${sub.id}, Status: ${sub.status}`);
    });
  } catch (error) {
    console.error('Error listing subscriptions:', error.message);
  }
}

listActiveSubscriptionsForCustomer('cus_xxx'); // Replace with a valid customer ID
```

### Cancel a Subscription

Canceling a subscription is a common requirement. You can choose to cancel it immediately or at the end of the current billing period.

**Cancel a Subscription**

```javascript
async function cancelSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end', // The subscription remains active until the billing cycle ends.
      // Use 'now' to cancel immediately.
      reason: 'cancellation_requested',
      feedback: 'User no longer needs the service.',
    });
    console.log(`Subscription ${subscription.id} scheduled for cancellation.`);
  } catch (error) {
    console.error('Error canceling subscription:', error.message);
  }
}

cancelSubscription('sub_xxx'); // Replace with a valid subscription ID
```

### Pause and Resume a Subscription

For temporary holds on service, you can pause and later resume a subscription.

**Pause and Resume**

```javascript
async function manageSubscriptionPause(subscriptionId) {
  try {
    // Pause the subscription
    let subscription = await payment.subscriptions.pause(subscriptionId);
    console.log(`Subscription ${subscription.id} is now ${subscription.status}.`);

    // After some time, resume it
    subscription = await payment.subscriptions.resume(subscriptionId);
    console.log(`Subscription ${subscription.id} is now ${subscription.status}.`);

  } catch (error) {
    console.error('Error managing subscription pause state:', error.message);
  }
}

manageSubscriptionPause('sub_xxx'); // Replace with a valid subscription ID
```

## Reporting Usage for Metered Billing

If your subscription uses a price with `usage_type: 'metered'`, you must report usage throughout the billing period. This is done by creating usage records for a specific subscription item.

**Report Usage**

```javascript
async function reportApiUsage(subscriptionItemId) {
  try {
    const usageRecord = await payment.subscriptionItems.createUsageRecord({
      subscription_item_id: subscriptionItemId,
      quantity: 100, // The amount of usage to report
      action: 'increment', // 'increment' adds to existing usage, 'set' overwrites it.
      timestamp: Math.floor(Date.now() / 1000), // The time the usage occurred
    });
    console.log('Usage record created:', usageRecord.id);
  } catch (error) {
    console.error('Error reporting usage:', error.message);
  }
}

// You can find the subscription_item_id on the subscription object.
reportApiUsage('si_xxx'); // Replace with a valid subscription item ID
```

At the end of the billing period, PaymentKit will sum up all reported usage and bill the customer accordingly.

## Next Steps

You now have a solid understanding of how to manage subscriptions. To dive deeper, explore the detailed API documentation and learn how to listen for subscription-related events.

::::card-group
::link-card{title="Subscriptions API Reference" description="Explore all available methods and parameters for managing subscriptions." icon="book-open" href="/en/docs/payment-kit-sdk/api-reference-subscriptions-381920/"}
::link-card{title="Webhooks Guide" description="Learn how to receive real-time notifications for events like `customer.subscription.created` and `customer.subscription.updated`." icon="link" href="/en/docs/payment-kit-sdk/core-concepts-webhooks-381920/"}
::::

---

## Webhooks

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/core-concepts-webhooks-381920/

Webhooks are a vital mechanism for building reliable and scalable integrations with PaymentKit. Instead of constantly polling the API for status changes, you can configure a webhook endpoint, and PaymentKit will send real-time HTTP POST notifications to your specified URL whenever certain events occur in your account.

This is the recommended way to handle asynchronous events like successful payments, subscription updates, or completed checkouts. By using webhooks, you can automate backend processes such as fulfilling orders, granting access to services, or updating customer records.

For a detailed list of all webhook management methods, see the [Webhook Endpoints API Reference](/en/docs/payment-kit-sdk/api-reference-webhook-endpoints-381920/).

## How Webhooks Work

The process is straightforward:

::::steps
:::step{title="Event Occurs"}
An action takes place in your PaymentKit account, such as a subscription being created or a payment succeeding. This generates an event object.
:::

:::step{title="Notification Sent"}
PaymentKit sends a `POST` request containing the event object in JSON format to the webhook endpoint URL you've registered.
:::

:::step{title="Your Server Responds"}
Your server receives the request and should return a `200 OK` status code immediately to acknowledge receipt. Any other status code indicates a failure, and PaymentKit may attempt to resend the event.
:::

:::step{title="Process the Event"}
After sending the success response, your server can safely process the event's payload to perform business logic, like updating your database or sending an email to the customer.
:::
::::

The following diagram illustrates this workflow:

![Webhooks](https://media.arcblock.io/lib/0e/0ea8151bf542c12e.w1600.webp)

## Create a Webhook Endpoint

To start receiving events, you must register a webhook endpoint. This involves providing your server's URL and specifying which event types you want to subscribe to.

**Create a Webhook Endpoint**

```javascript
import payment from '@blocklet/payment-js';

async function setupWebhook() {
  try {
    const webhookEndpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/webhook',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.created',
        'customer.subscription.updated',
        'customer.subscription.deleted',
        'payment_intent.succeeded',
      ],
    });
    console.log('Webhook endpoint created:', webhookEndpoint.id);
    return webhookEndpoint;
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

setupWebhook();
```

<strong>Parameters</strong>

| Name  | Type  | Description  |
|---|---|---|
| `url`  | `string`  | The URL of the endpoint on your server that will receive the webhook `POST` requests.  |
| `enabled_events`  | `string[]`  | An array of event type strings you want to subscribe to. Use `['*']` to receive all event types.  |

<strong>Example Response</strong>

```json
{
  "id": "wh_xxxxxxxxxxxxxx",
  "url": "https://example.com/webhook",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.created"
  ],
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
```

## Handling Incoming Events

Your webhook handler should be prepared to receive a `POST` request with a JSON body. Below is a basic example using Express.js to illustrate how to parse and handle an incoming event.

**Express.js Webhook Handler**

```javascript
const express = require('express');
const app = express();

// It's important to use a raw body parser to verify signatures
app.post('/webhook', express.json({ type: 'application/json' }), (request, response) => {
  const event = request.body;

  // Handle the event based on its type
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('Payment was successful for:', paymentIntent.amount);
      // TODO: Fulfill the purchase
      break;
    case 'customer.subscription.created':
      const subscription = event.data.object;
      console.log('New subscription started:', subscription.id);
      // TODO: Provision the service for the customer
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  // Acknowledge receipt of the event
  response.status(200).send();
});

app.listen(3000, () => console.log('Webhook server listening on port 3000'));
```

### Best Practices

- <strong>Respond Quickly</strong>: Acknowledge the event by returning a `2xx` status code as soon as possible. Perform complex logic in a background job to avoid timeouts.
- <strong>Handle Idempotency</strong>: Webhooks may be delivered more than once. Design your event processing logic to be idempotent to prevent duplicate actions (e.g., check if an order has already been fulfilled before processing it again).
- <strong>Verify Signatures</strong>: For security, it's crucial to verify that incoming webhook requests originate from PaymentKit. Each webhook event includes a signature in its headers that you can verify using your endpoint's secret.

## Managing Webhook Endpoints

You can also programmatically manage your endpoints using the SDK.

- <strong>Retrieve an Endpoint</strong>: Fetch the details of a specific endpoint. ```javascript const webhook = await payment.webhookEndpoints.retrieve('wh_xxx'); ```
- <strong>Update an Endpoint</strong>: Change the URL or the list of enabled events. ```javascript const updatedWebhook = await payment.webhookEndpoints.update('wh_xxx', {   url: 'https://new.example.com/webhook',   enabled_events: ['checkout.session.completed'], }); ```
- <strong>List Endpoints</strong>: Retrieve a paginated list of all your webhook endpoints. ```javascript const webhookList = await payment.webhookEndpoints.list({ pageSize: 10 }); ```
- <strong>Delete an Endpoint</strong>: Permanently remove a webhook endpoint. ```javascript await payment.webhookEndpoints.del('wh_xxx'); ```

---

## Environments

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/environments-381920/

The PaymentKit SDK operates in two distinct modes: <strong>Live Mode</strong> for processing real transactions and <strong>Test Mode</strong> for development and testing. Every API request is executed in one of these environments. By default, the SDK is initialized in Live Mode.

It is crucial to use Test Mode during development to build and verify your integration without affecting your live data or incurring real charges.

## Programmatic Configuration

You can dynamically switch between Live and Test modes within your application using the methods provided on the `payment.environments` object. This is the recommended approach for managing environments.

### Set Live Mode

To explicitly activate Live Mode, use the `setLivemode` method. All subsequent API calls will be directed to the production environment.

**Setting Live Mode**

```javascript
import payment from '@blocklet/payment-js';

// Activate Live Mode for production transactions
payment.environments.setLivemode(true);
```

Setting `setLivemode(false)` is equivalent to activating Test Mode.

### Set Test Mode

To activate Test Mode for development, use the `setTestmode` method. This ensures that all API calls are sandboxed and will not interact with your live data.

**Setting Test Mode**

```javascript
import payment from '@blocklet/payment-js';

// Activate Test Mode for development and testing
payment.environments.setTestmode(true);
```

Setting `setTestmode(false)` is equivalent to activating Live Mode.

## Checking the Active Mode

You can programmatically check which mode the SDK is currently configured to use.

### Check Live Mode

The `getLivemode` method returns `true` if the SDK is currently in Live Mode.

**Checking Live Mode**

```javascript
import payment from '@blocklet/payment-js';

const isLive = payment.environments.getLivemode();
console.log(`SDK is in Live Mode: ${isLive}`);
// Expected output: SDK is in Live Mode: true
```

### Check Test Mode

The `getTestmode` method returns `true` if the SDK is currently in Test Mode.

**Checking Test Mode**

```javascript
import payment from '@blocklet/payment-js';

payment.environments.setTestmode(true);

const isTest = payment.environments.getTestmode();
console.log(`SDK is in Test Mode: ${isTest}`);
// Expected output: SDK is in Test Mode: true
```

## How It Works

Once you set an environment mode, all subsequent API calls made through the SDK will automatically include the necessary `livemode` parameter in the request. This ensures your requests are routed to the correct PaymentKit environment without needing to specify it in every call.

**Example API Call in Test Mode**

```javascript
import payment from '@blocklet/payment-js';

// Ensure the SDK is in Test Mode
payment.environments.setTestmode(true);

console.log(`Operating in Test Mode: ${payment.environments.getTestmode()}`);

async function listTestCustomers() {
  try {
    // This API call will be sent to the test environment
    const customers = await payment.customers.list({ pageSize: 5 });
    console.log('Fetched test customers:', customers.data);
  } catch (error) {
    console.error('Error fetching test customers:', error.message);
  }
}

listTestCustomers();
```

Properly managing your environments is a critical step for a safe and reliable integration. Now that you understand how to configure the SDK, you can proceed to implement payment flows.

Next, dive into practical guides for implementing common payment workflows.

:::action-card{title="Core Concepts" description="Learn how to implement one-time payments, subscriptions, and credit-based billing." icon="book-open"}
::action{label="Read More" href="/en/docs/payment-kit-sdk/core-concepts-381920/" variant="primary"}
:::

---

## Getting Started

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/getting-started-381920/

This guide will walk you through the essential steps to get the PaymentKit Node.js SDK up and running in your project. In just a few minutes, you'll install the SDK, configure it for the test environment, and make your first API call.

## 1. Installation

First, add the PaymentKit SDK to your project using npm. Open your terminal and run the following command:

**Installation Command**

```bash
npm install @blocklet/payment-js
```

## 2. Configuration

Before making any API calls, you need to configure the SDK. At a minimum, you must import the library and set the environment. For development and testing, it's highly recommended to use the test environment to avoid processing real transactions.

Create a new file, for example `index.js`, and add the following code to initialize the SDK in test mode:

**Initialize the SDK**

```javascript
import payment from '@blocklet/payment-js';

// Use the test environment to avoid real charges during development
payment.environments.setTestMode(true);

console.log('PaymentKit SDK configured for test mode.');
```

For more details on managing different environments, see the [Environments](/en/docs/payment-kit-sdk/environments-381920/) documentation.

## 3. Make Your First API Call

Now that the SDK is configured, you're ready to interact with the PaymentKit API. Let's try a simple, read-only operation: listing all subscriptions. This is a great way to verify that your configuration is correct.

Add the following asynchronous function to your `index.js` file and call it:

**List Subscriptions**

```javascript
import payment from '@blocklet/payment-js';

// Use the test environment
payment.environments.setTestMode(true);

async function listSubscriptions() {
  try {
    console.log('Fetching subscriptions...');
    const subscriptions = await payment.subscriptions.list({
      order: 'updated_at:ASC', // Sort by update time
      pageSize: 5,           // Limit to 5 results
    });

    if (subscriptions.data.length > 0) {
      console.log(`Successfully retrieved ${subscriptions.data.length} subscriptions:`);
      subscriptions.data.forEach(sub => {
        console.log(`- ID: ${sub.id}, Status: ${sub.status}`);
      });
    } else {
      console.log('No subscriptions found. This is expected if you have not created any yet.');
    }

  } catch (error) {
    console.error('An error occurred:', error.message);
  }
}

listSubscriptions();
```

Run the file from your terminal:

```bash
node index.js
```

You should see a list of your test subscriptions or a message indicating that none were found. Congratulations, you've successfully integrated the PaymentKit SDK!

## Next Steps

You are now ready to explore the core features of the PaymentKit SDK. Here are some suggestions for what to learn next:

::::card-group
::link-card{title="Core Concepts" description="Dive into practical guides for implementing common payment workflows like one-time payments, subscriptions, and credit-based billing." icon="book-open" href="/en/docs/payment-kit-sdk/core-concepts-381920/"}
::link-card{title="API Reference" description="Explore the detailed documentation for every SDK resource and method, including all parameters and return values." icon="code-2" href="/en/docs/payment-kit-sdk/api-reference-381920/"}
::::

---

## Overview

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/overview-381920/

The PaymentKit Node.js SDK provides a convenient wrapper around the PaymentKit REST API, enabling you to build powerful and flexible payment experiences directly within your Node.js applications. Whether you're handling one-time purchases, managing recurring subscriptions, or implementing sophisticated credit-based billing models, this SDK simplifies the integration process with a clean, modern, and fully-typed interface.

It is an isomorphic SDK that can be used in both Node.js environments and modern browsers.

## Key Features

::::card-group
::link-card{title="Comprehensive Payment Models" description="Easily implement one-time payments with Checkout Sessions or manage recurring revenue with our robust Subscriptions API." icon="shopping-cart"}
::link-card{title="Flexible Product Catalog" description="Create and manage your products and their pricing structures, including support for multiple currencies and recurring intervals." icon="box"}
::link-card{title="Credit-Based Billing" description="Build usage-based products with our advanced metering system. Track usage, grant credits to customers, and automatically deduct credits as services are consumed." icon="wallet"}
::link-card{title="Full Customer Management" description="Create, retrieve, update, and manage your customer records, providing a seamless experience for your users." icon="users"}
::link-card{title="Real-time Event Handling" description="Use Webhooks to receive and react to asynchronous events from the PaymentKit API, such as completed payments or subscription updates." icon="link"}
::link-card{title="Developer-First Experience" description="Built with TypeScript, the SDK offers full type safety and autocompletion, helping you catch errors early and build with confidence." icon="code"}
::::

## How It Works

The SDK acts as an intermediary between your application and the PaymentKit API. You interact with simple JavaScript methods, and the SDK handles the underlying HTTP requests, authentication, and error handling.

![Overview](https://media.arcblock.io/lib/f1/f19e7449c9a0071f.w1600.webp)

## Next Steps

Ready to integrate? Our Getting Started guide will walk you through installation, configuration, and your first API call in minutes.

:::action-card{title="Get Started" description="Follow our step-by-step guide to get the SDK up and running in your project." icon="rocket"}
::action{label="Start Building" href="/en/docs/payment-kit-sdk/getting-started-381920/" variant="primary"}
:::

---

## SDK Structure

URL: https://www.arcblock.io/en/docs/payment-kit-sdk/sdk-structure-381920/

The PaymentKit Node.js SDK is built on a modular, resource-oriented architecture. This design ensures that interactions with different parts of the PaymentKit API are consistent, predictable, and robust. At its core, the SDK uses a central utility to generate methods for each API resource (like Customers, Products, etc.), which handles all communication with the underlying PaymentKit Blocklet.

This structure abstracts away the complexities of inter-component communication, allowing you to focus on your application's business logic.

![SDK Structure](https://media.arcblock.io/lib/2d/2dd53a53d9de089a.w1600.webp)

## The Resource Factory

Each resource exposed by the SDK (e.g., `products`, `customers`, `subscriptions`) is a collection of methods generated by a central factory. This factory pattern ensures that all API methods share a consistent signature and behavior. The primary functions responsible for this are `createResourceMethod` and `createResourceCreateMethod`.

These factories take a specification that defines the HTTP method and API path, and return an asynchronous function that handles the full request lifecycle.

Here is a conceptual look at how the `products` resource is constructed internally:

**Conceptual Example**

```javascript
import { createResourceMethod, createResourceCreateMethod } from './resource';

// This is a simplified example to illustrate the pattern.
const products = {
  // Method for creating a new resource
  create: createResourceCreateMethod({ method: 'POST', path: '/v1/products' }),

  // Methods for retrieving, updating, listing, and deleting
  retrieve: createResourceMethod({ method: 'GET', path: '/v1/products/{id}' }),
  update: createResourceMethod({ method: 'PUT', path: '/v1/products/{id}' }),
  list: createResourceMethod({ method: 'GET', path: '/v1/products' }),
  del: createResourceMethod({ method: 'DELETE', path: '/v1/products/{id}' }),
};
```

This approach allows the SDK to be easily maintained and extended while providing a uniform developer experience across all API endpoints.

## Automatic Component Handling

Before any API request is sent, the SDK automatically ensures that the PaymentKit Blocklet is running and available. This is managed by the `ensureComponentRunning` utility.

When you call an SDK method:

1. The SDK first checks the status of the PaymentKit component.
2. If the component is not running, it will wait for it to start.
3. Once the component is confirmed to be running, the API request is dispatched.
4. If the component fails to start, the method call will throw an error.

This built-in check removes the burden of manually managing the PaymentKit component's lifecycle from your application code, preventing common errors and race conditions.

All communication is ultimately handled by the `@blocklet/sdk`'s `component.call` function, which provides the low-level mechanism for secure, inter-blocklet communication.

## Seamless Environment Management

The resource factories also automatically inject the `livemode` parameter into every API request based on the SDK's current configuration. Whether you are operating in live or test mode, the SDK handles passing the correct parameter to the PaymentKit API without any extra effort on your part.

This means you can switch between environments with a single configuration change, and all subsequent API calls will be routed correctly.

:::action-card{title="Configuring Environments" description="To learn how to switch between live and test modes, please see the Environments configuration guide." icon="settings"}
::action{label="Learn More" href="/en/docs/payment-kit-sdk/environments-381920/" variant="primary"}
:::

---

## Web Device

URL: https://www.arcblock.io/en/docs/web-device/

---

## AUP layout boundary

URL: https://www.arcblock.io/en/docs/web-device/aup-reference/

Web Device reads AUP in two adjacent but different contexts:

| Context | What it is for | Do not assume |
| --- | --- | --- |
| A static AUP-tree renderer | Rendering a supported semantic tree to HTML | Every native primitive or widget is supported |
| A page `layout.aup` | Arranging a site page through the Web layout/component model | Arbitrary native primitives may be used as layout sections |

For a new Web page, use `pages/<name>/layout.aup` and site/theme components with explicit props. The layout lookup is locale AUP, default AUP, locale JSON, default JSON, then convention/default fallback. The JSON forms are compatibility input; new source should favor AUP.

## Layout validation boundary

The Web layout validator recognizes the component model and rejects native primitive/widget sections that do not belong in this layout context. This is why an AUP primitive existing in the protocol registry is not sufficient evidence that it can be placed directly in a Web page layout.

The full AUP language, node/event/data semantics, and target capability boundaries are outside this board. This board documents only how a Web Device site consumes that language.

For a task walkthrough, see [Build a page with AUP](../pages-and-aup/); for a reusable presentation contract, see [Component resolution](../built-in-components/).

---

## Author a site

URL: https://www.arcblock.io/en/docs/web-device/author/

This section organizes the work of changing a site: configure site-wide behavior, compose pages and content, then extend it with components and themes. The pages state their current version boundary rather than turning incomplete contracts into a shortcut.

## Read in this order

1. [Site-wide configuration](../site-configuration/) for the current configuration responsibilities and legacy boundary.
2. [Compose pages and layouts](../pages-layouts/) for the page-level composition model.
3. [Bind content to a page](../sources-bindings/) for named, scoped content data.
4. [Use and override components](../components-overrides/) for the beta.25 component rule and resolver order.
5. [Themes and tokens](../themes-tokens/) for visual values, not for an assumed theme-overlay selector.
6. [Web Device Content Markdown](../content-markdown/) for content-item syntax with source and rendered-result evidence.
7. [Restrict who can read a page](../content-access/) for collection defaults, record `access`, and the serve-time gate.
8. [Bookmark and note (save capability)](../save-capability/) for `blocklet.yaml` `save:`, chrome modes, and the bookmark/annotate actions.

---

## Component resolution

URL: https://www.arcblock.io/en/docs/web-device/built-in-components/

Web Device does not have one context-free, eternal component catalog. A component is resolved from layered sources, and the exact contract belongs to the `manifest.json` and renderer implementation in the target runtime/theme/site.

This page is a **resolution and authoring guide** with concrete layout-component examples (source + real layout proof routes). The full one-component-per-page catalog from the reference matrix lives under [theme components](../components/) and [site components](../components/site/content-card/) (and siblings). Do not treat this page as a link-only hub; do not treat the catalog hubs as a substitute for this how-to.

## Sample contract (layout path)

This page is a **layout-component** sample path, not a Markdown-directive live page. Layout components render only when a `layout.aup` (or named layout) mounts them into a page shell. The tables and fences below are copyable author source; the **real render surface** is a site page that already mounts the component, not a second fake HTML mock inside this document.

| Field | Value |
| --- | --- |
| Purpose | Resolve and author theme/site layout components with explicit empty states |
| Boundaries | Not Markdown directives; not AUP document primitives; no invented props beyond manifest |
| Author entry | `layout.aup` / named `layouts/*.aup` · `component … component=…` |
| Surface | **layout** (and narrow); site pages that use the component |
| Public status | `released` for components this site actually mounts |
| Fallback / failure | Empty `items` → `emptyText` line (or nothing if `emptyText=""`); empty breadcrumb props → no nav |
| Verification | Manifest paths · live site routes listed below · `arc --version` = `2.0.0-beta.32` |

## Resolution layers

For the current runtime, the resolver assembles a component from:

1. the runtime surface;
2. `themes/default/components`;
3. an optional active theme overlay;
4. the site’s `.web/components`.

Same-named files from a later layer override earlier files. This lets a site override a provided component narrowly, but it also means a component name mentioned in an older article is not automatically a portable contract for every theme/version.

## Keep three component surfaces separate

| Surface | What proves its contract | Current documentation path |
| --- | --- | --- |
| Markdown in a content item | Content-reader syntax and its rendered document result | [Web Device Content Markdown](../content-markdown/) |
| AUP primitive on a target | That target's renderer, capability boundary, and acceptance | Keep its target-specific evidence separate from this Web layout reference |
| `.web` or theme component | Its resolved manifest, renderer, layout section, and page result | This page and [Use and override components](../components-overrides/) |

Do not promote an example from one surface into a contract for another. A Markdown card is not a `.web` component API, and a primitive accepted by an AUP parser is not automatically a layout section.

## `content-card` (theme + site override)

**Resolution:** default theme `themes/default/components/content-card/` · this site may override via `blocklets/arcblock/.web/components/content-card/`.

**Manifest props (author-facing):** `title`, `description`, `eyebrow`, `items`, `basePath`, `variant`, `readMoreHref`, `emptyText`, `headingLevel`, `itemHeadingLevel`.

`items` entries commonly carry `title` / `slug` / `excerpt` / `category` (or `meta.*`). No `slug` means the card is not a destination link (unlinked chrome, not a dead `/#/` anchor).

### Author source (layout fragment)

```aup
component reading slot=featured-reading component=content-card \
  variant=fleet \
  title="Featured" \
  description="Hand-picked entries" \
  basePath="/$locale/" \
  emptyText="No content has been published yet." \
  items=[{title: "Example", category: "Guide", excerpt: "Short blurb", slug: "articles/example"}]
```

Empty list with an explicit message:

```aup
component reading slot=featured-reading component=content-card \
  title="Featured" \
  emptyText="No content has been published yet." \
  items=[]
```

When another surface owns the list chrome (for example search results), pass `emptyText=""` so this component renders **nothing** for the empty state instead of a second empty line.

### Real render surface (not this docs body)

| Locale-agnostic proof | Notes |
| --- | --- |
| Site home / product landings that mount `content-card` | e.g. `/en/`, product pages under `pages/*/layout.aup` |
| Empty state | Only visible when `items` is empty **and** `emptyText` is non-empty |

This Markdown page **does not** live-render `content-card`; claiming a screenshot mock here would break the live-example contract.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `items=[]` and default `emptyText` | One empty-state line (“No content has been published yet.” unless overridden) |
| `items=[]` and `emptyText=""` | No empty-state node |
| Item without `slug` | Unlinked card chrome |
| Invented prop not in manifest | Not a portable contract — confirm in target `manifest.json` / `render.js` |

## `page-breadcrumb` (site component)

**Resolution:** site-only `blocklets/arcblock/.web/components/page-breadcrumb/` (not a default-theme universal catalog entry).

**Manifest props:** `items` (`[{ label, href }]` — `href` without locale prefix; last item is current), `currentLabel` (trailing crumb, often `$meta.name`), `collection` (today: `events` for layouts that cannot resolve an `i18n` block).

### Author source (layout fragment)

From this site’s event detail layout (`pages/events/[slug]/layout.aup`):

```aup
component crumb slot=purpose component=page-breadcrumb \
  items=[{label: "Events", href: "/events/"}] \
  currentLabel=$meta.name
```

`currentLabel` is a **top-level** prop because `$meta.*` only resolves at a prop’s own top level. Do not nest `$meta.name` only inside a map entry if you need the live page title.

### Real render surface

| Route pattern | Notes |
| --- | --- |
| `/en/events/<slug>/` (and zh) | Breadcrumb back to Events + current title |
| Product / glossary detail layouts that mount `page-breadcrumb` | Same component, different `items` |

### Failure and limits

| Situation | Expected result |
| --- | --- |
| No `items`, no `collection`, no `currentLabel` | Component returns empty HTML (no nav) |
| `href` on the last crumb | Last crumb still renders as current (non-link) |
| Named layout `i18n` for labels when using only `collection` | Prefer `collection` or explicit `items` — named layouts do not resolve layout `i18n` the way page layouts do |

## Review a component before using it

1. Locate the component in the target resolution path.
2. Read its `manifest.json` for declared contract and its `render.js` for the actual accepted props/slots.
3. Use an explicit empty state for optional lists or media.
4. Run the site locally and inspect the actual page in each supported locale and viewport.

Do not paste a component’s implementation into a page just because its manifest is inconvenient to read. If the input contract is unclear, confirm it from the target manifest and runtime before using it; do not invent props.

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-12` · `arc --version` → `2.0.0-beta.32` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `content-card` · `page-breadcrumb` |
| Manifest / render | `.web/components/content-card/{manifest.json,render.js}` · `.web/components/page-breadcrumb/{manifest.json,render.js}` · theme default `content-card` |
| Unit catalogs | [components hub](../components/) · [surfaces hub](../surfaces/) · e.g. [content-card unit](../components/content-card/) · [page-breadcrumb unit](../components/site/page-breadcrumb/) |
| Layout sources | e.g. `pages/events/[slug]/layout.aup`, `pages/index/layout.aup`, product `layout.aup` files |
| Docs route (this contract text) | `/en/docs/web-device/built-in-components/` · `/zh/docs/web-device/built-in-components/` |
| Live layout proof | Open an event detail and home (or product) page after `arc service start --blocklet blocklets/arcblock --port 4900` |
| Accept | Breadcrumb/list cards appear on those **layout** pages; empty-state rules match the table; this docs page stays source-only for layout components |

For authoring a site-owned component, see [Use and override components](../components-overrides/). For AUP tree versus Web layout boundaries, see [AUP layout boundary](../aup-reference/).

---

## Layout components

URL: https://www.arcblock.io/en/docs/web-device/components/

This hub lists every **Web Device layout component** unit page: default theme packages and this site's `.web/components` overrides/additions.

**These are layout components — not AUP primitives; not AUP Web-only widgets; not Markdown directives.**

Each link opens a **single-component** page. Do not treat this hub as the capability contract.

## Default theme (23)

Source: `providers/runtime/web-device/themes/default/components/<name>/`

- [`access-gate`](./access-gate/)
- [`content-card`](./content-card/)
- [`detail-content`](./detail-content/)
- [`detail-sidebar`](./detail-sidebar/)
- [`event-card`](./event-card/)
- [`event-hero`](./event-hero/)
- [`hero-banner`](./hero-banner/)
- [`news-ticker`](./news-ticker/)
- [`page-sections`](./page-sections/)
- [`page-stack`](./page-stack/)
- [`platform-stack`](./platform-stack/)
- [`portal-footer`](./portal-footer/)
- [`portal-header`](./portal-header/)
- [`post-hero`](./post-hero/)
- [`product-frame`](./product-frame/)
- [`product-frame-gallery`](./product-frame-gallery/)
- [`product-hero`](./product-hero/)
- [`product-showcase`](./product-showcase/)
- [`related-content`](./related-content/)
- [`site-home`](./site-home/)
- [`tag-list`](./tag-list/)
- [`tech-hero`](./tech-hero/)
- [`technology-card`](./technology-card/)

## Site `.web/components` (17)

Source: `blocklets/arcblock/.web/components/<name>/`  
Resolution: site override > theme default.

- [site `container-members`](./site/container-members/)
- [site `content-card`](./site/content-card/)
- [site `editorial-feed`](./site/editorial-feed/)
- [site `event-detail`](./site/event-detail/)
- [site `glossary-index`](./site/glossary-index/)
- [site `globe`](./site/globe/)
- [site `landing-hero`](./site/landing-hero/)
- [site `landing-shell`](./site/landing-shell/)
- [site `leaf-shadow`](./site/leaf-shadow/)
- [site `object-card`](./site/object-card/)
- [site `page-breadcrumb`](./site/page-breadcrumb/)
- [site `period-index`](./site/period-index/)
- [site `product-meta`](./site/product-meta/)
- [site `related-objects`](./site/related-objects/)
- [site `site-footer`](./site/site-footer/)
- [site `term-meta`](./site/term-meta/)
- [site `topic-meta`](./site/topic-meta/)

`globe` and `leaf-shadow` are also being added to the ARC default theme ([ArcBlock/arc#5329](https://github.com/ArcBlock/arc/issues/5329)). Until this site runs that `arc`, the site packages above are the running contract. Site tracking: [#464](https://github.com/ArcBlock/arcblock-site/issues/464).

## Counts

| Layer | Count |
| --- | ---: |
| Default theme layout components | 23 |
| Site layout components | 17 |
| Unit pages under `components/` | 40 |

Also see [Surfaces](../surfaces/) and [Markdown directives & structures](../markdown/).

---

## Use and override components

URL: https://www.arcblock.io/en/docs/web-device/components-overrides/

Use a Web component for presentation you expect to reuse: a header, article card, editorial band, or responsive device frame. Keep page data and content objects outside the component so the component remains a presentation boundary.

## Create a complete site component

Put a component under `.web/components/<name>/`:

```text
.web/components/article-card/
├── manifest.json
├── render.js
└── style.css          # required by this beta.25 guide
```

The current source resolver requires `manifest.json` and `render.js` for a new component and can resolve a component without `style.css`. That is not the authoring rule for this documented target: the verified `2.0.0-beta.25` CLI requires `style.css` for a new standalone component. Include all three files in every beta.25 starter or site component; recheck this narrow rule when changing runtime version. If a component needs a browser-side script, its manifest must declare `hasScript: true` and the directory must provide `script.js`.

`render.js` exports `render(ctx)`. The renderer context supplies `props`, `slots`, `t()`, `locale`, `escapeHtml()`, `icon()`, and `pagination()`. Treat that as trusted site code: it is not a sandbox for untrusted third-party plugins.

## Know what overrides what

The current resolver assembles a component in this order:

1. the runtime surface;
2. `themes/default/components`;
3. an optional active theme overlay;
4. the site’s `.web/components`.

A later same-named layer overrides an earlier one. For a component that already exists below it, a theme or site can override only one file, for example `style.css`, and inherit the rest. A completely new component name must provide the complete component definition; a lone stylesheet is not a new component.

Local `.web/themes/` and a shared theme library are alternatives, not two theme sources that automatically stack. Do not assume a local theme plus a library theme will compose unless the exact target setup has been verified.

## Keep page layouts simple

Use a component from a page layout with declared props and an explicit empty state. Avoid copying its HTML into several page layouts merely because the first use is small. Conversely, do not turn one-off page structure into a global component without a second real use; that creates an opaque abstraction with no reuse benefit.

After changing a component, run the local validation chain and inspect every consuming page in both its wide and narrow layout. A watcher may invalidate local page cache during development, but automatic hot refresh is not an unconditional product guarantee; reload and recheck when a result looks stale.

See [Themes and tokens](../themes-tokens/) for visual-system configuration and [Component resolution](../built-in-components/) for the boundary between runtime/theme components and site-owned components.

---

## `access-gate`

URL: https://www.arcblock.io/en/docs/web-device/components/access-gate/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/access-gate/` (`manifest.json` + `render.js` + `style.css`). Resolved through the layout component chain (runtime surface → theme → optional site override). SiteServer mounts it into the article body slot on a denied detail; you do not put it in `layout.aup` yourself.

## Purpose

The stop under a first-screen teaser (or alone when `preview: false`). Title stays in `post-hero`. This component is the rule, the message, and the Sign in action.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix other layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.
- The component never receives the protected body. `excerpt` is a declared public field only.
- `seoStrategy` on the manifest is `none`. Gated pages force `noindex` in SiteServer, not here.

## Author entry

Not a hand-written `layout.aup` section. The runtime resolves `access-gate` after `decideWebAccess` returns `preview-shell` or `promo-shell`.

Common props (from manifest): `kind`, `requiredRole`, `excerpt`, `loginHref`, `signInLabel`, `message`, `signedIn`.

| Prop | Values / default |
| --- | --- |
| `kind` | `preview-shell` or `promo-shell` |
| `requiredRole` | Role the caller is missing |
| `excerpt` | Declared excerpt. Empty when a teaser is already in the page |
| `loginHref` | Default `/.well-known/service/login`. Live pages pass `return_to` and `cancel_to` for the current path |
| `signInLabel` | Default `Sign in` (locale copy from SiteServer) |
| `message` | Default: preview → `The rest of this piece is for {role}.`; promo → `This piece is for {role}.` Named roles `member` / `admin` / `owner` become `members` / `admins` / `owners`. Any other string is shown as-is; missing role → `signed-in readers` |
| `signedIn` | `true` omits the Sign in button |

If the theme package is missing, `renderAccessGateMarkup` in `packages/core/src/blocklet/web-access-gate.ts` emits the same markup.

## Surfaces

layout body slot on a denied content detail. Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing package → core markup. Missing `loginHref` → `/.well-known/service/login`. `signedIn: true` → no button.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by a denied content detail in site chrome. Open any listed record whose `access` is above the caller, signed out.

Live anonymous HTML (ARC `2.0.0-beta.35`, 2026-08-15):

```html
<aside class="access-gate" data-kind="promo-shell" data-required-role="admin">
  <div class="access-gate-rule" aria-hidden="true"></div>
  <p class="access-gate-message">The rest of this piece is for admins.</p>
  <p class="access-gate-action">
    <a class="access-gate-signin"
       href="/.well-known/service/login?return_to=%2Fen%2Farticles%2Faccess-fixture-team%2F&amp;cancel_to=%2Fen%2Farticles%2Faccess-fixture-team%2F">Sign in</a>
  </p>
</aside>
```

`data-kind` stays `promo-shell` when `preview` is omitted. The message uses preview phrasing because a teaser is present.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/access-gate/` |
| Manifest | `…/access-gate/manifest.json` |
| Renderer | `…/access-gate/render.js` |
| Styles | `…/access-gate/style.css` |
| Fallback markup | `packages/core/src/blocklet/web-access-gate.ts` (`renderAccessGateMarkup`) |
| Mount | `providers/runtime/web-device/src/site-server.ts` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `access-gate` |

## Notes

Shipped in [arc#4065](https://github.com/ArcBlock/arc/pull/4065). Author fields: [Restrict who can read a page](../../content-access/).

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `content-card`

URL: https://www.arcblock.io/en/docs/web-device/components/content-card/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/content-card/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Card list for blog posts, news, and similar content items on layout surfaces.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

- **Site override exists:** [site `content-card`](../site/content-card/) may replace files from this theme package.

## Author entry

layout.aup section · `component … component=content-card`

Common author-facing props (from manifest): `title`, `headingLevel`, `itemHeadingLevel`, `description`, `eyebrow`, `items`, `basePath`, `variant`, `readMoreHref`, `emptyText`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Empty items → emptyText line (or nothing if emptyText is empty).

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/content-card/` |
| Manifest | `…/content-card/manifest.json` |
| Renderer | `…/content-card/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `content-card` |

## Notes

This site may override via `.web/components/content-card/`. See the site override page for this name.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `detail-content`

URL: https://www.arcblock.io/en/docs/web-device/components/detail-content/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/detail-content/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Detail page layout with centered content and optional reading navigation slots.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): No author props declared (structural / slot-driven).

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/detail-content/` |
| Manifest | `…/detail-content/manifest.json` |
| Renderer | `…/detail-content/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `detail-content` |

## Notes

Structural layout component, not a content card.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `detail-sidebar`

URL: https://www.arcblock.io/en/docs/web-device/components/detail-sidebar/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/detail-sidebar/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Detail page layout with main content and sticky sidebar slots.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): No author props declared (structural / slot-driven).

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/detail-sidebar/` |
| Manifest | `…/detail-sidebar/manifest.json` |
| Renderer | `…/detail-sidebar/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `detail-sidebar` |

## Notes

Structural layout component.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `event-card`

URL: https://www.arcblock.io/en/docs/web-device/components/event-card/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/event-card/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Event list with calendar date blocks, status indicators, and location/format badges, grouped by upcoming/past.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup / list

Common author-facing props (from manifest): `items`, `basePath`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing fields degrade to plain text chrome.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/event-card/` |
| Manifest | `…/event-card/manifest.json` |
| Renderer | `…/event-card/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `event-card` |

## Notes

Theme list chrome for events collection.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `event-hero`

URL: https://www.arcblock.io/en/docs/web-device/components/event-hero/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/event-hero/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Event detail hero with date, location, format badge, and registration CTA.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `title`, `date`, `endDate`, `time`, `location`, `format`, `status`, `registrationUrl`, `price`, `tags`, `coverImage`, `slug`, `excerpt`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing media → no media block.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/event-hero/` |
| Manifest | `…/event-hero/manifest.json` |
| Renderer | `…/event-hero/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `event-hero` |

## Notes

Object detail hero, not a Markdown directive.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `hero-banner`

URL: https://www.arcblock.io/en/docs/web-device/components/hero-banner/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/hero-banner/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Homepage hero with title, subtitle, and primary/secondary CTAs.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `title`, `subtitle`, `primaryAction`, `secondaryAction`, `keywords`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing media → no media block.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/hero-banner/` |
| Manifest | `…/hero-banner/manifest.json` |
| Renderer | `…/hero-banner/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `hero-banner` |

## Notes

May ship with script.js for motion.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `news-ticker`

URL: https://www.arcblock.io/en/docs/web-device/components/news-ticker/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/news-ticker/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Scrolling news headlines driven by a data source.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `items`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`experimental`

## Fallback

—

## Sample

No docs-safe live sample on this site yet. Use the evidence paths as source-only reference. Experimental units must not be described as released product capability.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/news-ticker/` |
| Manifest | `…/news-ticker/manifest.json` |
| Renderer | `…/news-ticker/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `news-ticker` |

## Notes

Not the AUP Web-only widget `ticker`. Experimental — no docs-safe sample contract yet.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `page-sections`

URL: https://www.arcblock.io/en/docs/web-device/components/page-sections/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/page-sections/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Wrap each layout slot in a <section> with optional header and variant.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): No author props declared (structural / slot-driven).

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/page-sections/` |
| Manifest | `…/page-sections/manifest.json` |
| Renderer | `…/page-sections/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `page-sections` |

## Notes

Section chrome only.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `page-stack`

URL: https://www.arcblock.io/en/docs/web-device/components/page-stack/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/page-stack/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Simple vertical stacking of layout slots without section wrappers.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): No author props declared (structural / slot-driven).

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/page-stack/` |
| Manifest | `…/page-stack/manifest.json` |
| Renderer | `…/page-stack/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `page-stack` |

## Notes

Minimal stack layout.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `platform-stack`

URL: https://www.arcblock.io/en/docs/web-device/components/platform-stack/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/platform-stack/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Layered technology-stack diagram with optional highlight for the current product or technology.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `highlight`, `highlightLayer`, `compact`, `layers`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/platform-stack/` |
| Manifest | `…/platform-stack/manifest.json` |
| Renderer | `…/platform-stack/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `platform-stack` |

## Notes

Layers come from site content bindings.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `portal-footer`

URL: https://www.arcblock.io/en/docs/web-device/components/portal-footer/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/portal-footer/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Multi-column portal footer with links across content sections.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `fleetHosts`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/portal-footer/` |
| Manifest | `…/portal-footer/manifest.json` |
| Renderer | `…/portal-footer/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `portal-footer` |

## Notes

Distinct from this site's `site-footer` layout component (they can coexist).

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `portal-header`

URL: https://www.arcblock.io/en/docs/web-device/components/portal-header/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/portal-header/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Mega-nav portal header with site name and navigation sections.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup section

Common author-facing props (from manifest): `siteName`, `nav`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Empty nav needs an explicit empty state.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/portal-header/` |
| Manifest | `…/portal-header/manifest.json` |
| Renderer | `…/portal-header/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `portal-header` |

## Notes

May ship with script.js. Not AUP widget `app-header`.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `post-hero`

URL: https://www.arcblock.io/en/docs/web-device/components/post-hero/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/post-hero/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Blog/post header with cover, title, author, date, and tags.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `title`, `date`, `author`, `readingTime`, `tags`, `coverImage`, `coverAlt`, `slug`, `contentType`, `eyebrow`, `eyebrowHref`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing media → no media block.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/post-hero/` |
| Manifest | `…/post-hero/manifest.json` |
| Renderer | `…/post-hero/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `post-hero` |

## Notes

Object detail hero for articles.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `product-frame`

URL: https://www.arcblock.io/en/docs/web-device/components/product-frame/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/product-frame/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

CSS-only device, browser, or terminal shell for a verified product screenshot or command transcript.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `kind`, `orientation`, `src`, `alt`, `caption`, `command`, `output`, `size`, `placeholder`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

No image → empty frame.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/product-frame/` |
| Manifest | `…/product-frame/manifest.json` |
| Renderer | `…/product-frame/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `product-frame` |

## Notes

Product landing evidence chrome.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `product-frame-gallery`

URL: https://www.arcblock.io/en/docs/web-device/components/product-frame-gallery/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/product-frame-gallery/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Responsive gallery of one or more CSS-only product evidence frames.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `items`, `layout`, `label`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

No images → empty gallery.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/product-frame-gallery/` |
| Manifest | `…/product-frame-gallery/manifest.json` |
| Renderer | `…/product-frame-gallery/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `product-frame-gallery` |

## Notes

Companion to product-frame.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `product-hero`

URL: https://www.arcblock.io/en/docs/web-device/components/product-hero/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/product-hero/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Product landing hero with title, tagline, category badge, and tags.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `title`, `excerpt`, `category`, `tags`, `coverImage`, `slug`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing media → no media block.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/product-hero/` |
| Manifest | `…/product-hero/manifest.json` |
| Renderer | `…/product-hero/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `product-hero` |

## Notes

Product object hero.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `product-showcase`

URL: https://www.arcblock.io/en/docs/web-device/components/product-showcase/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/product-showcase/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Product feature cards with title, description, and action button.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `items`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/product-showcase/` |
| Manifest | `…/product-showcase/manifest.json` |
| Renderer | `…/product-showcase/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `product-showcase` |

## Notes

May ship with script.js.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `related-content`

URL: https://www.arcblock.io/en/docs/web-device/components/related-content/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/related-content/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Related content section showing cross-linked items from layout bindings.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup + refs

Common author-facing props (from manifest): `items`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`experimental`

## Fallback

No relations → empty.

## Sample

No docs-safe live sample on this site yet. Use the evidence paths as source-only reference. Experimental units must not be described as released product capability.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/related-content/` |
| Manifest | `…/related-content/manifest.json` |
| Renderer | `…/related-content/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `related-content` |

## Notes

This site commonly uses `related-objects` instead. Experimental.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `site-home`

URL: https://www.arcblock.io/en/docs/web-device/components/site-home/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/site-home/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Fleet homepage shell with brand hero, site-specific visuals, and proof sections.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `eyebrow`, `title`, `headline`, `description`, `visualKind`, `support`, `detail`, `closing`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/site-home/` |
| Manifest | `…/site-home/manifest.json` |
| Renderer | `…/site-home/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `site-home` |

## Notes

May ship with script.js for motion.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## site `container-members`

URL: https://www.arcblock.io/en/docs/web-device/components/site/container-members/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/container-members/`. Resolution priority: site override > theme default.

## Purpose

Everything inside one container, with the member the reader is standing on marked. Collection-agnostic.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

layout.aup

Common author-facing props (from manifest): `items`, `rootItems`, `current`, `basePath`, `title`, `variant`, `orderBy`, `numberField`, `dateField`, `endField`, `utilityField`, `utilityPrefix`, `metaFields`, `metaLabels`, `copy`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/container-members/` |
| Manifest | `…/container-members/manifest.json` |
| Renderer | `…/container-members/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `container-members` |

## Notes

Site-only layout component.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `content-card`

URL: https://www.arcblock.io/en/docs/web-device/components/site/content-card/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/content-card/`. Resolution priority: site override > theme default.

- **Site override of theme component:** [theme `content-card`](../../content-card/).

## Purpose

Generic content card for blog posts, news, and events — **site override** of the default theme component.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

layout.aup / list

Common author-facing props (from manifest): `title`, `headingLevel`, `itemHeadingLevel`, `description`, `eyebrow`, `items`, `basePath`, `variant`, `readMoreHref`, `emptyText`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

Empty list → emptyText (or nothing if empty).

## Sample

Docs-safe sample verified under #290 on a related path. See related authoring guide linked below for any remaining multi-unit history; this page is the unit contract.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/content-card/` |
| Manifest | `…/content-card/manifest.json` |
| Renderer | `…/content-card/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `content-card` |

## Notes

**Site override** of theme `content-card`. Resolution: site > theme. See theme page for default-theme contract.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `editorial-feed`

URL: https://www.arcblock.io/en/docs/web-device/components/site/editorial-feed/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/editorial-feed/`. Resolution priority: site override > theme default.

## Purpose

Quiet, localized editorial feed for a landing-page archive or topic-related articles.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

collection layout

Common author-facing props (from manifest): `title`, `description`, `items`, `basePath`, `readMoreHref`, `emptyText`, `kind`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

Empty feed → emptyText.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/editorial-feed/` |
| Manifest | `…/editorial-feed/manifest.json` |
| Renderer | `…/editorial-feed/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `editorial-feed` |

## Notes

Site-only list chrome.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `event-detail`

URL: https://www.arcblock.io/en/docs/web-device/components/site/event-detail/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/event-detail/`. Resolution priority: site override > theme default.

## Purpose

Renders an event as when/where facts, absolute dates, venues, and contribution links.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

object layout

Common author-facing props (from manifest): `start`, `end`, `time`, `timezone`, `status`, `format`, `host`, `organizer`, `venues`, `contributions`, `links`, `topics`, `participants`, `basePath`, `eventItems`, `datesCheckedAt` …

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/event-detail/` |
| Manifest | `…/event-detail/manifest.json` |
| Renderer | `…/event-detail/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `event-detail` |

## Notes

Site-only event object chrome.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `globe`

URL: https://www.arcblock.io/en/docs/web-device/components/site/globe/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/globe/`. Resolution: site override > theme default.

This site ships the package today. The same four files are being added to the ARC default theme (`providers/runtime/web-device/themes/default/components/globe/`, [ArcBlock/arc#5329](https://github.com/ArcBlock/arc/issues/5329)). Until this site runs an `arc` that includes that theme package, treat the site copy as the source of truth. Site tracking: [#464](https://github.com/ArcBlock/arcblock-site/issues/464).

## Purpose

Minimal COBE WebGL globe. Use it as an inline figure, a large scene, or a backdrop behind other layout sections.

A still PNG of the earth is a diagram. A globe that turns (and that the reader can drag) gives the page a location and a reason to stay. Homepage backdrop, product page, or a figure between paragraphs of an essay: same component.

## Live

Figure and scene on a blank stage (this site's lab):

::embed{url="/en/globe-lab/"}

In-article figures, scene, and a named look: [showcase article](/en/articles/globe-on-the-page/). Homepage backdrop: [`/en/`](/en/).

## Not this component

| Thing | Why it is different |
| --- | --- |
| AUP primitive `globe` (decks) | Renders `aup-globe-shell`. Map-shaped shell, not COBE. |
| Markdown `::globe` | Generic / unknown document type. Does not load this package. |
| GIS / choropleth | This component draws land dots, optional markers, optional arcs. It does not color regions from a table. |

Author entry is **only** `component=globe` in `layout.aup` (or a named layout under `layouts/`).

## When to use

- Homepage or landing backdrop behind a sentence: the page feels placed, not typed into a blank field.
- A figure in an article when the piece is about a network, a team, or a route. Drag is on.
- A named look (`builders`, `users`, `ai`, `chain`) that a script can change live without swapping images.

## When not to use

- You need a real map (tiles, labels, region fill).
- Markdown `::globe` is the AUP deck primitive, not this component. For in-body demos, mount `component=globe` once in the page layout (loads script + CSS), then emit the same markup `render.js` emits. See the [showcase article](/en/articles/globe-on-the-page/) source.
- You are targeting only phones with `variant=backdrop`: the script skips backdrop below 760px except on `#xy-globe` (the homepage slot).

## Author entry

layout.aup

### Minimal backdrop (homepage pattern)

```
component globe slot=xy-globe component=globe
    variant=backdrop
    effect=builders
```

### Figure or scene (lab / article pattern)

```
component scene slot=cobe-scene component=globe
    variant=scene
    size=560
    preset=cities
component figure slot=cobe-figure component=globe
    variant=figure
    size=360
    preset=cities
```

Live hosts on this site:

- Homepage: `/en/` (`variant=backdrop effect=builders`)
- Lab: `/en/globe-lab/`
- Showcase article: [`/en/articles/globe-on-the-page/`](/en/articles/globe-on-the-page/)

## Props

From `manifest.json`. Invented names are not portable.

| Prop | Type | Default | Role |
| --- | --- | --- | --- |
| `variant` | string | `figure` | `figure` (inline, drag on) · `scene` (large stage) · `backdrop` (behind copy, drag off) |
| `size` | number | figure 360 · scene 560 · backdrop 720 | CSS pixel size of the square canvas |
| `theme` | string | `auto` | `auto` follows `html[data-mode]` · `light` · `dark` |
| `rotate` | string/boolean | `true` | Auto-rotate. Forced off when `prefers-reduced-motion: reduce` |
| `speed` | number | `0.0025` (script look uses `0.0026`) | Rotation increment per frame |
| `theta` | number | `0.22` | Vertical tilt, radians |
| `scale` | number | `1` | Globe scale |
| `samples` | number | `16000` | Land-dot density |
| `drag` | string/boolean | `true` for figure, `false` for backdrop | Pointer-drag to rotate |
| `effect` | string | empty → `builders` look if nothing else set | Named look: `builders` · `users` · `ai` · `chain` · `cjk` · `already` (aliases: `late`, `new-year`, `year-end`) |
| `preset` | string | empty | Marker preset: `cities` |
| `markers` | array | `[]` | `[{ lat, lon, size? }]` or `{ location: [lat, lon], size? }`. `size` is relative to globe radius |
| `arcs` | array | `[]` | `[{ from: [lat, lon], to: [lat, lon] }]` or `{ fromLat, fromLon, toLat, toLon }` |

String forms also parse: JSON text, or `lat,lon,size;lat,lon,size` for markers.

Marker/arc props override the named `effect` / `preset` when non-empty.

## Live update

Dispatch on `document`:

```js
document.dispatchEvent(new CustomEvent("site-globe:effect", { detail: { effect: "users" } }));
```

Every `.site-globe` on the page that exposed `__globeSetEffect` switches look. Use this from other page scripts. Do not poke canvas uniforms yourself.

## Surfaces

layout. Not the document Markdown directive surface.

## Public status

`released` on this site (homepage, lab, showcase article). Theme promotion is in progress in `ArcBlock/arc`; do not document the theme package as already shipping in the `arc` binary this site currently runs.

## Fallback

| Situation | Result |
| --- | --- |
| No WebGL | Empty square; page copy still reads |
| `prefers-reduced-motion: reduce` | No auto-rotate, no drag |
| `variant=backdrop` and width ≤ 760, not `#xy-globe` | Script does not bind |
| Missing markers and no preset/effect | `builders` look |

## Sample honesty

Live lab is embedded above. Homepage and the showcase article are the other running hosts. Copy AUP from the fences on this page; do not invent props.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/globe/` |
| Manifest | `…/globe/manifest.json` |
| Renderer | `…/globe/render.js` |
| Script | `…/globe/script.js` (COBE 2.0.1, MIT, Shu Ding) |
| Style | `…/globe/style.css` |
| Homepage mount | `pages/index/layout.aup` · `#xy-globe` |
| Lab | `pages/globe-lab/layout.aup` |
| Article layout | `layouts/globe-on-the-page.aup` |
| Internal matrix | `docs/aup/capability-matrix.md` §5 |

## Notes

- Class names are `site-globe` / `site-globe-canvas` (historical). Select those, not `aup-globe-shell`.
- Accent color for markers/arcs comes from `--color-accent`.
- Dark mode reads `html[data-mode="dark"]`.

## Related

- [Components hub](../../)
- [Showcase article](/en/articles/globe-on-the-page/)
- [Use and override components](../../../components-overrides/)

---

## site `glossary-index`

URL: https://www.arcblock.io/en/docs/web-device/components/site/glossary-index/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/glossary-index/`. Resolution priority: site override > theme default.

## Purpose

A–Z index of the site vocabulary: glossary terms and product names together.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

glossary collection

Common author-facing props (from manifest): `terms`, `basePath`, `productItems`, `productBase`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

Empty index → empty.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/glossary-index/` |
| Manifest | `…/glossary-index/manifest.json` |
| Renderer | `…/glossary-index/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `glossary-index` |

## Notes

May include script.js.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `landing-hero`

URL: https://www.arcblock.io/en/docs/web-device/components/site/landing-hero/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/landing-hero/`. Resolution priority: site override > theme default.

## Purpose

Editorial landing-page hero with restrained, content-specific visual trace.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

landing layout

Common author-facing props (from manifest): `title`, `subtitle`, `primaryAction`, `secondaryAction`, `variant`, `headlineVariant`, `maxLines`, `displayPrefix`, `displayAccent`, `trace`, `traceKicker`, `traceText`, `geometry`, `geometryModifier`, `glyphField`, `heroVisual`

`heroVisual` (e.g. `heroVisual=webgl`) switches to a full-bleed visual layer behind the copy — see [Hero lab](../../../hero-lab/) for working `webgl-hero` widget candidates with exact config. Suppresses `trace`/`geometry` when set.

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

Missing media → no media block.

## Sample

Used on product landing pages under `pages/*/layout.aup`. Not prioritized as an in-docs live mock (layout surface only).

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/landing-hero/` |
| Manifest | `…/landing-hero/manifest.json` |
| Renderer | `…/landing-hero/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `landing-hero` |

## Notes

Product landing path; not prioritized as a docs content sample. May include script.js.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `landing-shell`

URL: https://www.arcblock.io/en/docs/web-device/components/site/landing-shell/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/landing-shell/`. Resolution priority: site override > theme default.

## Purpose

Landing-page layout shell with scoped editorial presentation.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

landing layout

Common author-facing props (from manifest): No author props declared (structural / slot-driven).

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

Used on product landing pages under `pages/*/layout.aup`. Not prioritized as an in-docs live mock (layout surface only).

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/landing-shell/` |
| Manifest | `…/landing-shell/manifest.json` |
| Renderer | `…/landing-shell/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `landing-shell` |

## Notes

Shell only; pairs with landing-hero and related sections.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `leaf-shadow`

URL: https://www.arcblock.io/en/docs/web-device/components/site/leaf-shadow/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/leaf-shadow/`. Resolution: site override > theme default.

This site ships the package today. The player is being added to the ARC default theme (`providers/runtime/web-device/themes/default/components/leaf-shadow/`, [ArcBlock/arc#5329](https://github.com/ArcBlock/arc/issues/5329)). The owned gobo MP4s stay in this site. Until this site runs an `arc` that includes the theme package, treat the site copy as the source of truth. Site tracking: [#464](https://github.com/ArcBlock/arcblock-site/issues/464).

## Purpose

Moving canopy-light (or any optical gobo) over a page or a section. Video loop when `src` is set; procedural WebGL leaf field when it is not. Blend is `mix-blend-multiply`.

Type on a white field is a document. Light moving over the type is a room: same words, a time of day, a reason to stay. Landing pages stop reading as a CMS template. Switch the clip (canopy, window, water, rain) and the mood changes without rewriting the copy.

## Live

Full-page overlay and HUD (this site's lab):

::embed{url="/en/leaf-shadow-lab/"}

The showcase article wears the same overlay on a real essay: [Light on the page, not a picture of trees](/en/articles/leaf-shadow-overlay/).

## Not this component

| Thing | Why it is different |
| --- | --- |
| A photograph of the scene | Overlay must be **projection on a pale surface**, not a subject photo |
| AUP widgets / Markdown directives | Author entry is layout only |
| Third-party shadow videos | Do not copy other sites' loops into this repo |

## When to use

- Full-page atmosphere (`variant=overlay`) on a landing, a long read, or a lab. The type stays the type; the weather sits on top.
- Section-local wash (`variant=wash`) inside a positioned ancestor, when only one block should pick up the light.
- Switching among owned clips in a lab HUD, or minting a new clip with `gobo-loop` from a sentence.

## When not to use

- The file is a portrait, UI screenshot, or readable type. Multiply will print it onto every paragraph.
- The clip is still several megabytes. Compress first.
- You need the overlay inside Markdown body with no layout. Put `leaf-shadow` in `layout.aup` or a named layout.

## Author entry

layout.aup

### Overlay with a gobo (lab / article pattern)

```
component fx slot=leaf-fx component=leaf-shadow
    variant=overlay
    intensity=0.2
    controls=true
    src="/en/articles/leaf-shadow-gobo/canopy.mp4"
```

Prefer a layout whose ancestors do not create a containing block for `position: fixed` (`transform`, `filter`, or a late-in-flow slot like `detail-content`'s `after-content`). `landing-shell` is the proven host on this site. The overlay layer is `position: fixed; inset: 0`; the HUD is also `position: fixed` and will pin to the wrong box if the host is transformed.

### Procedural fallback (no `src`)

```
component fx slot=leaf-fx component=leaf-shadow
    variant=overlay
    intensity=0.28
```

Live hosts on this site:

- Lab: `/en/leaf-shadow-lab/`
- Showcase article: [`/en/articles/leaf-shadow-overlay/`](/en/articles/leaf-shadow-overlay/)
- Four owned clips: `/en/articles/leaf-shadow-gobo/{canopy,window,caustic,rain-ripple}.mp4`

Those MP4s sit in `content/articles/leaf-shadow-gobo/` **without** `content.md`, so they are not listed as articles.

## Props

From `manifest.json`.

| Prop | Type | Default | Role |
| --- | --- | --- | --- |
| `variant` | string | `overlay` | `overlay` = fixed full page · `wash` = absolute, section-local |
| `intensity` | number | `0.2` with `src`, else `0.28` | Opacity 0–1 |
| `speed` | number | `1` | Drift speed (procedural canvas) |
| `angle` | number | `0.35` | Light shear 0–1 (procedural canvas) |
| `controls` | boolean | `false` | HUD: toggle + intensity (this site also adds clip buttons) |
| `src` | string | empty | Looping gobo URL. When set, video replaces the canvas |

## HUD protocol (script.js)

Buttons are `data-leaf-act`:

| `data-leaf-act` | `data-v` | Effect |
| --- | --- | --- |
| `toggle` | — | Pause/hide the layer |
| `intensity` | `0.12` / `0.2` / `0.45` | Opacity |
| `src` | URL | Swap the video (`setSrc`) |

The **theme** package HUD is toggle + intensity only. It must not hardcode this site's `/en/articles/leaf-shadow-gobo/…` URLs. This **site** package adds four `src` buttons for the owned demos. `script.js` already handles `data-leaf-act="src"` in both copies.

The HUD is `pointer-events: auto`. The layer is `pointer-events: none`, so page links stay clickable.

## Mint a new clip: `gobo-loop`

Skill: `.claude/skills/gobo-loop/SKILL.md`.

1. Rewrite the user's scene as **projection on a pale wall or floor**. No subject portrait, furniture, or readable text.
2. Generate a 16:9 still of that projection.
3. Image-to-video, 6 seconds, 720p, camera locked, soft optical motion only.
4. Compress:

```bash
bash .claude/skills/gobo-loop/scripts/compress-gobo.sh <in.mp4> blocklets/arcblock/content/articles/leaf-shadow-gobo/<slug>.mp4
```

Target **100–400 KB**, no audio, 12 fps. If `ffmpeg` is missing, stop and report the uncompressed path. Do not commit a 1 MB+ clip as done.

5. Point `src` at `/en/articles/leaf-shadow-gobo/<slug>.mp4`. Confirm `mix-blend-multiply` at intensity 0.2 looks like light on paper, not a photo glued on the page.

Failed animal silhouettes (sleeping cat, golden retriever) were deleted. Do not revive them without a new still that reads as umbra.

## Surfaces

layout. Not the document Markdown directive surface.

## Public status

`released` on this site (lab + showcase article + four gobo files). Theme promotion of the **player** is in progress in `ArcBlock/arc`. Do not document the theme package as already shipping in the `arc` binary this site currently runs. The MP4s are site media, not theme assets.

## Fallback

| Situation | Result |
| --- | --- |
| No `src` | Procedural canvas |
| `prefers-reduced-motion: reduce` | Video/canvas paused; intensity capped near 0.16 |
| Dark mode + video overlay | Stays `mix-blend-mode: multiply` (see style.css) |
| Dark mode + procedural overlay | `mix-blend-mode: screen` |
| Missing file at `src` | Empty video element; no overlay texture |
| `controls=false` | No HUD; `aria-hidden="true"` on the root |

## Sample honesty

Live lab is embedded above. The showcase article is the running overlay on a real essay. Copy AUP from the fences on this page.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/leaf-shadow/` |
| Manifest | `…/leaf-shadow/manifest.json` |
| Renderer | `…/leaf-shadow/render.js` |
| Script | `…/leaf-shadow/script.js` |
| Style | `…/leaf-shadow/style.css` |
| Lab | `pages/leaf-shadow-lab/layout.aup` |
| Article layout | `layouts/leaf-shadow-overlay.aup` |
| Gobo files | `content/articles/leaf-shadow-gobo/*.mp4` |
| Skill | `.claude/skills/gobo-loop/SKILL.md` |
| Compress | `.claude/skills/gobo-loop/scripts/compress-gobo.sh` |
| Internal matrix | `docs/aup/capability-matrix.md` §5 |

## Related

- [Components hub](../../)
- [Showcase article](/en/articles/leaf-shadow-overlay/)
- [Use and override components](../../../components-overrides/)

---

## site `object-card`

URL: https://www.arcblock.io/en/docs/web-device/components/site/object-card/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/object-card/`. Resolution priority: site override > theme default.

## Purpose

Resolve page-referenced objects against live records and render their current state.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

collection / object layout

Common author-facing props (from manifest): `title`, `description`, `refs`, `objects`, `basePath`, `emptyText`, `objectBase`, `badgeField`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/object-card/` |
| Manifest | `…/object-card/manifest.json` |
| Renderer | `…/object-card/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `object-card` |

## Notes

May include script.js.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `page-breadcrumb`

URL: https://www.arcblock.io/en/docs/web-device/components/site/page-breadcrumb/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/page-breadcrumb/`. Resolution priority: site override > theme default.

## Purpose

One-line trail back to the collection a detail page belongs to.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

layout.aup

Common author-facing props (from manifest): `items`, `currentLabel`, `collection`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

Empty trail → no nav.

## Sample

Docs-safe sample verified under #290 on a related path. See related authoring guide linked below for any remaining multi-unit history; this page is the unit contract.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/page-breadcrumb/` |
| Manifest | `…/page-breadcrumb/manifest.json` |
| Renderer | `…/page-breadcrumb/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `page-breadcrumb` |

## Notes

Not the AUP widget `breadcrumb`. Site-only layout component.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `period-index`

URL: https://www.arcblock.io/en/docs/web-device/components/site/period-index/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/period-index/`. Resolution priority: site override > theme default.

## Purpose

A dated collection as three stacked bands of decreasing density: ahead, recent, older.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

time-index layout

Common author-facing props (from manifest): `items`, `dateField`, `endField`, `period`, `basePath`, `excerptField`, `metaFields`, `metaLabels`, `copy`, `variant`, `title`, `eyebrow`, `headingLevel`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/period-index/` |
| Manifest | `…/period-index/manifest.json` |
| Renderer | `…/period-index/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `period-index` |

## Notes

Site-only period chrome.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `product-meta`

URL: https://www.arcblock.io/en/docs/web-device/components/site/product-meta/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/product-meta/`. Resolution priority: site override > theme default.

## Purpose

Where a product stands now, and where it went if it moved (superseded, merged, renamed).

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

product object layout

Common author-facing props (from manifest): `title`, `status`, `version`, `supersededBy`, `mergedInto`, `partOf`, `renamedFrom`, `aliases`, `homepage`, `productItems`, `basePath`, `learnMore`, `forms`, `refs`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/product-meta/` |
| Manifest | `…/product-meta/manifest.json` |
| Renderer | `…/product-meta/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `product-meta` |

## Notes

Site-only product metadata chrome.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `related-objects`

URL: https://www.arcblock.io/en/docs/web-device/components/site/related-objects/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/related-objects/`. Resolution priority: site override > theme default.

## Purpose

Everything on this site that points at the current subject, or that it points at.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

layout + content refs

Common author-facing props (from manifest): `title`, `slug`, `selfType`, `limitPerGroup`, `emptyText`, `articleItems`, `productItems`, `eventItems`, `docItems`, `termItems`, `placeItems`, `refs`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

No relations → empty.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/related-objects/` |
| Manifest | `…/related-objects/manifest.json` |
| Renderer | `…/related-objects/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `related-objects` |

## Notes

This site's path relative to theme `related-content`.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `site-footer`

URL: https://www.arcblock.io/en/docs/web-device/components/site/site-footer/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/site-footer/`. Resolution priority: site override > theme default.

## Purpose

Site footer with verified global anchors, legal links, and an optional connection slot.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

layout.aup

Common author-facing props (from manifest): `connection`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/site-footer/` |
| Manifest | `…/site-footer/manifest.json` |
| Renderer | `…/site-footer/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `site-footer` |

## Notes

Not theme `portal-footer` (they can coexist).

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `term-meta`

URL: https://www.arcblock.io/en/docs/web-device/components/site/term-meta/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/term-meta/`. Resolution priority: site override > theme default.

## Purpose

A term's place in the vocabulary: origin, aliases, neighbouring terms.

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

term object layout

Common author-facing props (from manifest): `title`, `origin`, `aliases`, `seeAlso`, `terms`, `learnMore`, `basePath`, `partOf`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/term-meta/` |
| Manifest | `…/term-meta/manifest.json` |
| Renderer | `…/term-meta/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `term-meta` |

## Notes

Glossary term chrome.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## site `topic-meta`

URL: https://www.arcblock.io/en/docs/web-device/components/site/topic-meta/

**Web Device layout component (this site) — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Site package: `blocklets/arcblock/.web/components/topic-meta/`. Resolution priority: site override > theme default.

## Purpose

Definition behind a tag, shown on the tag page (looks up the site's own vocabulary).

## Boundaries

- Site-only unless a theme package with the same name also exists (then this page is the override contract).
- Do not document AUP primitives or MD directives on this page.
- Do not invent props beyond the site `manifest.json`.

## Author entry

topic object layout

Common author-facing props (from manifest): `title`, `termItems`, `productItems`

## Surfaces

layout (and docs shell where mounted).

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Site package | `blocklets/arcblock/.web/components/topic-meta/` |
| Manifest | `…/topic-meta/manifest.json` |
| Renderer | `…/topic-meta/render.js` (when present) |
| Internal matrix | `docs/aup/capability-matrix.md` §5 (internal, non-routed) |
| Matrix row concept | site layout-component · `topic-meta` |

## Notes

Tag/topic page chrome.

## Related

- [Components hub](../../) — navigation only
- [Theme components](../../) (default theme unit pages)
- [Component resolution](../../../built-in-components/)
- [Use and override components](../../../components-overrides/)

---

## `tag-list`

URL: https://www.arcblock.io/en/docs/web-device/components/tag-list/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/tag-list/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Tag cloud / tag listing with linked pills.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `tags`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Empty tags → empty.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/tag-list/` |
| Manifest | `…/tag-list/manifest.json` |
| Renderer | `…/tag-list/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `tag-list` |

## Notes

List chrome for tags.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `tech-hero`

URL: https://www.arcblock.io/en/docs/web-device/components/tech-hero/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/tech-hero/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Technology page hero with blueprint aesthetic, title, description, and category badge.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup

Common author-facing props (from manifest): `title`, `excerpt`, `category`, `tags`, `slug`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

Missing media → no media block.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/tech-hero/` |
| Manifest | `…/tech-hero/manifest.json` |
| Renderer | `…/tech-hero/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `tech-hero` |

## Notes

Technology landing hero.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## `technology-card`

URL: https://www.arcblock.io/en/docs/web-device/components/technology-card/

**Web Device layout component — not an AUP primitive; not an AUP Web-only widget; not a Markdown directive.**

Default-theme package: `providers/runtime/web-device/themes/default/components/technology-card/` (`manifest.json` + `render.js`). Resolved through the layout component chain (runtime surface → theme → optional site override).

## Purpose

Technology stack cards with dark variant support.

## Boundaries

- Do not call this an AUP primitive or put it under `docs/aup/primitives/`.
- Do not mix multiple layout components' contracts on this page.
- Manifest props are the author-facing contract; invented props are not portable.

## Author entry

layout.aup / list

Common author-facing props (from manifest): `items`, `basePath`

## Surfaces

layout (and narrow where the theme supports it). Not the document Markdown directive surface.

## Public status

`released`

## Fallback

—

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Theme package | `providers/runtime/web-device/themes/default/components/technology-card/` |
| Manifest | `…/technology-card/manifest.json` |
| Renderer | `…/technology-card/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §3 (internal, non-routed) |
| Matrix row concept | layout-component · `technology-card` |

## Notes

Theme list chrome for technology topics.

## Related

- [Components hub](../) — navigation only
- [Surfaces hub](../../surfaces/)
- [Component resolution](../../built-in-components/)
- [Use and override components](../../components-overrides/)

---

## Restrict who can read a page

URL: https://www.arcblock.io/en/docs/web-device/content-access/

Web Device decides who may read a page at serve time, before it replays prerendered HTML. `public` must be written at some policy layer. An unmarked record with no collection, path, or hatch default is a 404, including for site admins.

Connect currently admits four roles: `guest`, `member`, `admin`, and `owner`. `none` is not a role; it is a hard deny.

## Start with a public collection and a tighter record

The usual setup: the collection default is `public`, so unmarked records stay readable. Then mark the few restricted records.

```yaml
# blocklet.yaml
collections:
  articles:
    access: public
```

```yaml
# content/articles/members-only/content.md
---
title: Members-only note
access: member
---
```

This site's articles collection already has that default. `collections.<type>.access` is the default for **details** of that type. It does not set the `/articles/` list page. Zero-config collection list routes are public unless you lock that route. A type-level `member` default therefore does not close the list; it closes unmarked details.

Leave `preview` unset. A signed-out reader gets the first screen of the body, then the gate. The rest of the tree never enters the HTML. Sitemap, `llms.txt`, and MCP omit a **gated** record unless you set `preview: true`. Unmarked records that inherit `public` from the collection stay on those faces (after [arc#4086](https://github.com/ArcBlock/arc/pull/4086)).

`collections.<type>.readRole` is a storage read grant, not this HTML gate.

A signed-out caller is `guest`. A signed-in DID Connect session may include `member`, `admin`, or `owner`. This page does not document how a site grants those roles.

## Choose the record fields

| You write | Unsigned reader | Matching role, or admin/owner |
| --- | --- | --- |
| No `access`, collection `access: public` | Full page | Full page |
| No `access`, and no collection / path / hatch default | 404 | 404 |
| `access: public` | Full page | Full page |
| `access: member` (or `admin` / `owner`), `preview` omitted, record is listable | First-screen teaser + gate | Full page |
| `access: member` and `preview: true` | Teaser + gate. Declared `excerpt` is used only when there is no teaser HTML | Full page |
| `access: member` and `preview: false`, record is listable | Gate only, no teaser | Full page |
| `access: member` and `preview: false`, record is not listable | 404 | Full page |
| `access: none` | 404 | 404 |

A record named role only tightens the scope above it. `access: public` on a record cannot open a locked path or collection. To open one slug under a lock, add a more specific `accessPaths` rule. See [Content access reference](../content-access-reference/).

A record is listable when the **list route** is public (zero-config `/{locale}/{type}/` routes are), or when `blocklet.yaml` sets the hatch `accessDefault: public`. Collection `access` is not what makes the list public. On this site the article list is public, so a gated article without `preview: false` shows a teaser.

Prerender may write the full body into `.web-cache`. The gate runs on serve, before that file is replayed. Do not host `.web-cache` as static files.

## What a denied reader sees

The detail stays in site chrome. Title, author, and date stay in `post-hero`. The cover is cleared. The body slot is a first-screen teaser (unless `preview: false`) and the `access-gate` stop.

![Anonymous reader on an admin-only article: hero stays, first-screen teaser, then a Sign in gate](./visuals/renditions/teaser-gate.png)

*Anonymous GET of a listed admin article on ARC 2.0.0-beta.35, 2026-08-15, `http://arcblock.localhost:4922/`. Live capture, not a mock. That fixture URL is no longer on this site.*

Anonymous GET of a listed `access: admin` article on 2026-08-15, ARC `2.0.0-beta.35`, `http://arcblock.localhost:4922/`:

```bash
curl -sI http://arcblock.localhost:4922/en/articles/access-fixture-team/
```

```text
HTTP/1.1 200 OK
cache-control: private, no-store
x-robots-tag: noindex
```

The HTML includes `access-teaser`, then:

```html
<aside class="access-gate" data-kind="promo-shell" data-required-role="admin">
  <p class="access-gate-message">The rest of this piece is for admins.</p>
  <a class="access-gate-signin"
     href="/.well-known/service/login?return_to=%2Fen%2Farticles%2Faccess-fixture-team%2F&amp;cancel_to=%2Fen%2Farticles%2Faccess-fixture-team%2F">Sign in</a>
</aside>
```

The protected body from that capture is absent. The same URL with a matching test caller returned the body and no gate. Sign-in is DID Connect.

The teaser is an SSR cut of the AUP tree (~480 visual units, at most two top-level blocks, last block always withheld). It is not a CSS fade over the full body.

## Check a live site

Use a runtime that includes [arc#4065](https://github.com/ArcBlock/arc/pull/4065) (`arc --version` on the capture above: `2.0.0-beta.35`). Point the service at **your** blocklet and probe records you declared there. This site does not ship access-gate test articles.

```bash
# Hard deny — a record with access: none
curl -sI http://arcblock.localhost:4900/en/articles/<your-none-record>/
# HTTP/1.1 404 Not Found
# cache-control: private, no-store
# content-length: 0

# Explicit public
curl -sI http://arcblock.localhost:4900/en/articles/<your-public-record>/
# HTTP/1.1 200 OK
# cache-control: no-cache
```

Local services started with `AFS_TEST_ALLOW_CALLER_HEADER=1` accept a test caller. Both headers are required:

```bash
curl -s -H 'x-caller-did: z1admin' -H 'x-caller-role: admin' \
  http://arcblock.localhost:4900/en/articles/<your-admin-record>/ \
  | rg '<a string that exists only in the protected body>'
```

A `member` caller opens a `access: member` record and still sees the gate on an `access: admin` record:

```bash
curl -s -H 'x-caller-did: z1member' -H 'x-caller-role: member' \
  http://arcblock.localhost:4900/en/articles/<your-member-record>/ \
  | rg '<member-only body marker>'

curl -s -H 'x-caller-did: z1member' -H 'x-caller-role: member' \
  http://arcblock.localhost:4900/en/articles/<your-admin-record>/ \
  | rg 'access-gate|<admin-only body marker>'
```

`x-caller-role` alone still returns the gate. Do not send these headers on a public deployment.

## Failures

| What you see | Usual cause |
| --- | --- |
| 404, empty body, `Cache-Control: private, no-store` | No scoped default, or `access: none` |
| Gate, but no first-screen teaser | You set `preview: false` |
| Teaser includes the last section of the article | Unexpected. File an upstream issue; the cut must withhold the last top-level block |
| Record `access: public` still gated or 404 | A stricter `accessPaths` or collection default is the ceiling. If the list route is public you get a teaser/gate, not a 404 |
| Signed-in member still sees an `admin` gate | Admit is AND across every named constraint. `member` does not satisfy `admin` |
| Sitemap / `llms.txt` / MCP lists a gated article | That face only emits a gated record when `preview: true` (shell fields, no body). Omit `preview` to keep it off discovery |

## Limits

- v1 admits `guest` / `member` / `admin` / `owner` from DID Connect. Other role names can be written and are shown in the gate copy; Connect does not currently issue them.
- Verifiable-credential roles are not an admit path. Track [arc#4056](https://github.com/ArcBlock/arc/issues/4056).
- Item-local media and collection RSS use the same admit rule. A teaser never keeps a media block (the file would 404).
- Shared public cache is only allowed for a full anonymous-open page.
- `index.access.json` next to prerendered HTML is not a public URL. A GET of that path is 404.

Resolution order, `accessPaths` syntax, HTTP headers, and discovery rules: [Content access reference](../content-access-reference/). Gate markup: [`access-gate`](../components/access-gate/).

---

## Content access reference

URL: https://www.arcblock.io/en/docs/web-device/content-access-reference/

Lookup page for the serve-time gate. For the authoring sequence, start at [Restrict who can read a page](../content-access/).

Evidence on this page is the merged implementation in [arc#4065](https://github.com/ArcBlock/arc/pull/4065) (`3fa375a41`) plus a local run of this site on ARC `2.0.0-beta.35` at `http://arcblock.localhost:4922/` on 2026-08-15.

## Where to write the policy

| Location | Field | Applies to |
| --- | --- | --- |
| `blocklet.yaml` | `accessDefault: public` | Site-wide hatch: unmarked routes and records inherit public only when this exact sentinel is written. Absent means omit-deny |
| `blocklet.yaml` | `accessPaths[]` | Locale-stripped page path. Longest `match` wins |
| `blocklet.yaml` `collections.<type>` | `access` | Content details of that type. Not the collection list page |
| Route / page | `access` | List and static pages. Not a substitute for a missing record on a detail |
| Content object front matter | `access` | That record only. Tightens the scope; cannot relax it |
| Content object front matter | `preview` | Denied-reader shell. Does not make the body public |

`collections.<type>.readRole` is not this table.

## Resolution

Policy is a ceiling, in this order:

1. Longest matching `accessPaths[].match` (locale prefix already stripped).
2. `collections.<type>.access` on a content detail. Ignored on the list page so a type-level `member` default does not lock `/articles/`.
3. Route `access` on list and static pages. Details do not inherit a public list route as if the record were public.
4. `accessDefault: public`.

Then the record:

| Record `access` | Effect |
| --- | --- |
| omitted | Inherit the scope. If the scope is `public`, the page is public. If there is no scope, undeclared → 404 |
| `public` | No extra role. Does not unlock a locked scope |
| `none` | Hard deny. Admin and owner cannot inherit it |
| any other string | AND-tighten. The caller must satisfy every named role from scope and record |

`admin` and `owner` in the caller’s role list admit any *declared* gated resource. They do not admit an undeclared page or `none`.

Admit is contains-match on `caller.roles`, not a numeric role level. A caller with both `member` and `admin` satisfies an `admin` page. A caller with only `member` does not.

Path match:

| `match` | Hits |
| --- | --- |
| `/docs/internal/**` | `/docs/internal/runbook`, not the list `/docs/internal` |
| `/articles/members-only` | that exact detail, and `/articles/members-only/...` |
| longer prefix | wins over a shorter one |

```yaml
accessPaths:
  - match: /docs/internal/**
    access: admin
  - match: /docs/internal/public-note
    access: public
```

## Decision kinds

`decideWebAccess` returns one of:

| kind | When |
| --- | --- |
| `full` | Caller is admitted |
| `preview-shell` | Denied, and `preview: true` |
| `promo-shell` | Denied, `preview` is not `true`, and the record is listable |
| `not-found` | Undeclared, `none`, or denied and not listable |

On a content detail, `preview-shell` and `promo-shell` live-render through the site layout. Only `not-found` short-circuits as a bare 404. SiteServer then:

- If `preview !== false`, cut a first-screen teaser (`PAYWALL_TEASER_CHARS = 480`, `PAYWALL_TEASER_MAX_BLOCKS = 2`, last top-level block withheld, leading H1/H2 that repeats the hero title dropped).
- If that teaser HTML is non-empty, the visible gate copy uses the preview phrasing even when `kind` is `promo-shell`.
- If `preview: false`, no teaser. Listable → gate only. Unlistable → 404.

CJK characters count as 2 visual units.

## HTTP, cache, and SEO

| Outcome | Status | Cache | Robots |
| --- | --- | --- | --- |
| Full public page | 200 | `no-cache` on this capture | indexable |
| Full gated page (admitted caller) | 200 | `no-cache` on this capture | no forced noindex |
| Teaser / gate | 200 | `private, no-store` | `X-Robots-Tag: noindex` and `<meta name="robots" content="noindex">` |
| 404 | 404 | `private, no-store` | n/a |

Shared public edge cache is legal only when `kind === "full"` and effective access is `public`. Prerender may still write the full body into `.web-cache/<path>/index.html`. The serve gate must run before that file is replayed. Do not publish `.web-cache` as a static host.

Gated HTML may advertise only a declared SEO description or excerpt. A docs summary derived from the protected body does not go into meta, Open Graph, or JSON-LD. `post-hero` `coverImage` is cleared on a shell. `Accept: text/markdown` is refused on a gated detail.

Live capture, anonymous admin fixture:

```text
HTTP/1.1 200 OK
cache-control: private, no-store
x-robots-tag: noindex
```

Live capture, same URL with `x-caller-did` + `x-caller-role: admin` (local seam only):

```text
HTTP/1.1 200 OK
cache-control: no-cache
```

`BODY_MARKER_ADMIN_ONLY` present; no `access-gate`.

## Discovery versus the HTML list

Anonymous sitemap, `llms.txt`, MCP get, and index query force `listedOnPublicList: false`.

| Record | HTML public list | Anonymous discovery |
| --- | --- | --- |
| `public` or inherited public (collection / path / hatch) | Full card | Full fields ([arc#4086](https://github.com/ArcBlock/arc/pull/4086)) |
| gated, `preview: true` | Promo / preview card | Shell fields only; body stripped |
| gated, no `preview: true` | Promo card if listable | Absent: no URL, no body |
| undeclared or `none` | Absent | Absent |

## Media and feeds

Item-local media and collection RSS use the same admit function. Preview and promo shells never grant bytes. A public list card is not a media admit.

## Local caller seam

When the process has `AFS_TEST_ALLOW_CALLER_HEADER=1`:

| Header | Role |
| --- | --- |
| `x-caller-did` | Required. Role headers without it do not admit |
| `x-caller-role` or `x-caller-roles` | Comma-separated role names |

This is a test hook. It is not a public authentication API.

## Related

- [Restrict who can read a page](../content-access/)
- [`access-gate`](../components/access-gate/)
- [SEO, links, and accessibility](../seo-links-accessibility/)
- [Version compatibility](../version-compatibility/)

---

## web-device/content-access/visuals

URL: https://www.arcblock.io/en/docs/web-device/content-access/visuals/

---

## Content objects, metadata, and locales

URL: https://www.arcblock.io/en/docs/web-device/content-and-objects/

Web Device treats an article, document, product, or event as a directory-shaped object, not as a database row that must be moved elsewhere. The object directory is the source of truth; pages and lists read a normalized view from it.

```text
content/
└── articles/
    └── first-post/
        ├── content.md
        ├── content.zh.md
        ├── tags/
        │   └── AFS
        ├── related/
        │   └── docs--web-device-overview
        └── cover.png
```

Here, `articles` is the content type and `first-post` is the object directory. The directory name contributes the default slug, but an author can explicitly provide title, summary, date, author, tags, or related objects in front matter.

## Body and locale variants

The current reader accepts `content.md` and `index.md`. When both exist, `content.md` wins. For a requested locale, it first looks for `content.<locale>.md` or `index.<locale>.md`, then falls back to the default-language file. `content.zh.md` is therefore the normal home for a Chinese body, not a separate object directory.

Do not simply copy the default body and change a title. A locale file should be what a reader actually receives; only when it is absent does the runtime use the default file. Page layouts and SEO can have their own locale variants too; see [Routes, navigation, and locales](/en/docs/web-device/routes-navigation-locales/).

## Metadata read order

The same field can come from three locations. The current read order is:

1. Markdown front matter.
2. Directory-field files in the object directory.
3. `meta` in compatible `.aup/default.json` input.

An earlier source overrides a later source. New Markdown content therefore does not need to duplicate old JSON metadata, but a compatibility consumer must not have its JSON removed without its own check.

Filenames in `tags/` form the tag list. Entries in `related/` use `type--slug` as their filename, for example `docs--web-device-overview`; file content can provide a fallback title. A cover image is an object asset, not part of the body.

## Keep objects movable and re-organizable

An object should say what it is, not which slot it currently occupies on the home page. Keep home-page ordering, filters, and component selection in the page source/binding and layout. The same object can then appear in an article list, a topic page, related reading, or a future UI without rewriting or moving the original file.

Objects can also use grouped directories, but grouping and version layers affect detail paths and collection discovery. Start a new collection with the flat `content/<type>/<slug>/` shape; add nesting only when a specific route requirement calls for it.

## Accept one content object

1. Write `content.md`, with front matter for at least a title and any required summary/date.
2. If Chinese is needed, add `content.zh.md`; do not duplicate the slug directory.
3. Put optional tags, related items, and a cover inside the object directory.
4. Run the site's `arc dsl validate .`, `arc blocklet check .`, and build.
5. Open the detail and list pages in each declared locale and confirm that body, title, and links come from the intended object variant.

To restrict who can read an object, set `collections.<type>.access` and tighten individual records with front-matter `access`. See [Restrict who can read a page](/en/docs/web-device/content-access/).

For querying these objects from a page, see [Bind content to a page](/en/docs/web-device/sources-bindings/). For exact field and compatibility-input boundaries, see [Source-binding reference](/en/docs/web-device/source-binding-reference/).

For a source-and-rendered-result example inside a Markdown body, see [Embed YouTube and X in Markdown](../markdown-embeds/).

---

## Web Device Content Markdown

URL: https://www.arcblock.io/en/docs/web-device/content-markdown/

This section documents Markdown written in a Web Device content item's `content.md`. The content reader turns it into an AUP tree, then the current document target renders it as page content. It is not the complete syntax reference for `format: markdown` in an AUP `text` primitive, and it is not a `.web` component catalog.

Each page places author-written source directly above its real result and says what that result proves and deliberately does not prove. The document itself is read-only. A component may retain an intrinsic limited interaction, such as switching a tab; that does not let a reader edit source, a manifest, a content item, or persistent data.

## Verified Content Markdown structures

| What to write | Start here | Result boundary |
| --- | --- | --- |
| YouTube, X/Twitter, or same-site content embed | [Embed external and internal content](../markdown-embeds/) | Only recognized provider URLs and validated same-site paths are supported; this is not an AUP session or bridge |
| A readable presentation with an inline player | [Markdown slides](../markdown-slides/) | `slides: true` defines page boundaries; a named layout mounts the player. It does not provide a presenter view or free-form canvas |
| GFM tables and callouts | [Tables and callouts](../markdown-gfm-callouts/) | Presents static content; it does not establish editable tables or a data source |
| Navigation and explanatory cards | [Markdown cards](../markdown-cards/) | A link performs ordinary navigation only; there is no `exec`, write, or editor permission |
| Numbered tutorials | [Markdown steps](../markdown-steps/) | Presents a static step body; it does not execute a step's instructions |

## Choose the layer first

For a reusable site layout section, start with `.web/components` and a page `layout.aup`. That path has its own manifest and renderer contract; a Markdown directive cannot replace it.

For a cross-device interactive AUP tree, start with an AUP app, a target renderer, and session semantics. Seeing one HTML result in a static document target does not verify events, patches, data binding, or another device.

For the exact boundary between these three layers, see [Component resolution](../built-in-components/) and [AUP on Web Device](../aup-reference/).

---

## Content site

URL: https://www.arcblock.io/en/docs/web-device/content-site/

This is a reviewable content-site sequence, not a claim that the current CLI has a one-command content-site scaffold. The first board records that gap rather than inventing one.

## Build one complete vertical slice

1. Start with the verified information-site base.
2. Add two objects under `content/articles/<slug>/content.md`, each with real front matter and reader body.
3. Add a page/collection layout that declares an unfiltered `/content/articles/` source.
4. Bind that complete source value to a component with an explicit empty state.
5. Confirm one list result and one detail route in every declared locale.

Only after that slice works should you add sorting, a limit, tags, related objects, or an archive. Each one changes selection or route behavior and deserves its own build/browser observation.

## The core boundary

The content object remains the source of truth. The list page selects objects; it does not own article copy. The detail route presents one object; it does not duplicate its metadata into site configuration. This lets an object appear in a list, related-reading band, topic page, or future surface without moving the original file.

For exact object shape, see [Content objects, metadata, and locales](../content-and-objects/). For the query contract, see [Bind content to a page](../sources-bindings/). The board deliberately does not publish a fake “download this full blog” fixture until a clean-agent vertical slice has been run against the target runtime.

---

## Custom component

URL: https://www.arcblock.io/en/docs/web-device/custom-component/

Use the `hello` component in [Build a first site](../first-site/) as the verified minimal component shape. A new site-owned component has a directory under `.web/components/<name>/` with a manifest and renderer; beta.25’s verified starter also includes a stylesheet.

## Add it as a contract, not an HTML fragment

1. Choose a stable component name based on reader purpose, such as `article-card`.
2. Declare the props that a page may pass in `manifest.json`.
3. Implement `render(ctx)` using `props`, `slots`, `t()`, `locale`, and escaping helpers as appropriate.
4. Add styling at the component level and an explicit empty state for optional values.
5. Reference the component in one page layout with declared props, then run the full local chain.

If a same-named component already comes from the runtime/theme, an overlay can replace only one file and inherit the rest. If the name is new, it needs a complete definition; a lone `style.css` does not create a component.

Do not call `render.js` a sandbox. It is trusted site code. Do not claim hot reload as a correctness guarantee; reload and inspect a rendered page after an edit.

For precedence and rendering context, read [Use and override components](../components-overrides/).

---

## Customize a theme and tokens

URL: https://www.arcblock.io/en/docs/web-device/custom-theme/

Start by changing the visual system that has the smallest, clearest contract: `.web/tokens.json`. Do not begin by assuming that `theme.tone` selects a component overlay.

## A narrow visual change

1. Choose one semantic goal: reading surface, accent role, or content width.
2. Change the corresponding top-level token value in `.web/tokens.json`.
3. Add a `dark` override only when the dark presentation actually differs.
4. Build, then inspect a home page and a content/detail page in both light and dark presentation.
5. Check text contrast, focus visibility, images, and narrow-width wrapping before expanding the token set.

This produces a site-owned visual layer that components can reuse without a new component-selection mechanism.

## Do not guess at theme overlays

In the current runtime, `site.yaml` `theme:` values opt into a shared theme library and set AUP CSS tone/palette; they do not choose `.web/themes/<name>/` as an active component overlay. Local theme trees and library fallback have different precedence. If a design requires a local overlay, first make a small target-version fixture and verify the exact resolver path before treating it as a reusable theme recipe.

The token reader is not a security boundary for untrusted CSS. Keep the file under the same trusted review discipline as component code.

See [Themes and tokens](../themes-tokens/) and [Theme and token reference](../theme-token-reference/).

---

## Diagnose a site

URL: https://www.arcblock.io/en/docs/web-device/diagnose/

Do not begin with a deployment when a page looks wrong. First identify which boundary is actually failing.

| Symptom | Start here | What it tells you |
| --- | --- | --- |
| DSL parse/lint error | `arc dsl lint .` | Static authoring problem; error severity fails, warnings still need review |
| Layout/source validation error | `arc dsl validate .` | AUP/Web layout or declared source contract problem |
| Blocklet/profile error | `arc blocklet check .` | Combined source checks, Content Space when present, or recipe structure problem |
| Package/pre-render error | `arc blocklet build .` | Build/artifact path problem, not yet reader-facing acceptance |
| Browser page is old or different | Check printed URL, registered parent/worktree, reload, then inspect the current source | The local daemon may point at another worktree or its watcher/cache may not have invalidated |
| List is empty | Check source path, scope, filter, locale, then the component empty state | Empty can be a legitimate result or an undeclared/mismatched binding |

## Read the boundaries correctly

`dsl validate` covers AUP sources plus Web layouts under pages, content objects, and `layouts/`. `blocklet check` adds structural and profile-level checks. Neither command proves that the page has useful alt text, keyboard behavior, a good narrow viewport, or a successful external link.

An undeclared `$source.<name>` can be reported when its binding scope is known, rather than silently becoming an empty list. Shared named-layout bindings are not fully covered at initialization, so a rendered browser check remains essential.

## Repair in a stable order

1. Fix the first static error, not the last symptom.
2. Re-run the command that owns that boundary.
3. Build only after lint/validation/check are clean enough to interpret.
4. Run the blocklet directly locally and open the exact printed URL.
5. Record the viewport, locale, route, and observed result for a UI change.

If the page is stale, do not deploy to DID Space. Confirm which blocklet parent directory the local daemon registered; reload once the source and URL are known to match. Local watcher refresh is a convenience, not an unconditional correctness guarantee.

For local run procedure, see [Preview, build, and publish](../preview-build-publish/). For content-query diagnosis, see [Source-binding reference](../source-binding-reference/).

---

## Directory and file conventions reference

URL: https://www.arcblock.io/en/docs/web-device/directory-reference/

Use this reference when you need a precise location. It is a current directory-reading contract, not a claim that every historical site has already migrated to this shape.

## Site root

| Path | Purpose |
| --- | --- |
| `.route/web` | Declares that the blocklet has a Web entry for the local or published runtime |
| `.web/site.yaml` | Site-level scalar configuration: locale, SEO, template/theme values, and related settings |
| `.web/tokens.json` | Light/default design tokens plus optional `dark` overrides |
| `.web/redirects` | Redirect rules in its own line-oriented file form |
| `.web/template/logo.svg` | Site logo asset |
| `.web/components/<name>/` | Reusable site presentation component |
| `.web/themes/` | Local theme material, with separate precedence rules from shared-library fallback |
| `layouts/<name>.aup` | Named object layout, selected by a content record's `layout: <name>` front matter; it does not create a route |

## Pages

| Path | Purpose |
| --- | --- |
| `pages/index/` | Home-page entry point |
| `pages/<name>/layout.aup` | Default page layout source |
| `pages/<name>/layout.<locale>.aup` | Locale-specific layout source when a layout genuinely differs |
| `pages/<name>/seo/title` / `description` | Default page metadata |
| `pages/<name>/seo/title.<locale>` / `description.<locale>` | Locale-specific page metadata |
| `pages/<name>/sources/<source>` | Content source path for that page scope |
| `pages/<name>/sources/<source>.sort|.limit|.filter` | Optional source selection controls |

The layout lookup order is locale AUP, default AUP, locale JSON, default JSON, then convention/default layout. New source should use the AUP form unless a verified compatibility consumer requires JSON.

## Content objects

| Path | Purpose |
| --- | --- |
| `content/<type>/<slug>/content.md` | Default reader-facing body and front matter |
| `content/<type>/<slug>/content.<locale>.md` | Locale-specific body |
| `content/<type>/<slug>/layout.aup` | Object-specific layout when an object needs one |

`content.md` wins over compatible `index.md` naming when both exist. Front matter has higher metadata precedence than sibling field files. A record can select either its own `layout.aup` or a named `layouts/<name>.aup` with `layout: <name>`, not both. Keep body/object identity here rather than copying it into a page layout.

## Locale support files

`.aup/locales/*.json` can provide a compatibility locale fallback. A new multi-locale site should explicitly declare its supported `locale` and `locales` in `.web/site.yaml`, then use locale variants beside the thing they override instead of duplicating the whole tree.

For meaning rather than paths, read [Understand a site directory](../site-directory/). For route effects, read [Routes and locales reference](../routes-locales-reference/).

---

## Build a first site

URL: https://www.arcblock.io/en/docs/web-device/first-site/

Begin with a `basic` blocklet, then add only the files Web Device needs to render a page. The file tree, checks, build, and browser result below were verified together with `arc` `2.0.0-beta.25`.

## 1. Create the blocklet directory

```bash
arc blocklet init ./my-site --recipe basic --name my-site
cd ./my-site
```

The command creates `blocklet.yaml` and prints the generated DID. Keep that file; this local identity does not require you to create, sign in to, or deploy a DID Space.

Confirm the generated `id`:

```bash
grep -E '^id:' blocklet.yaml
```

When this guide created the blocklet with `--name my-site`, the verified result was `id: my-site`. The `site` value in the next step must use the value you see in your own file.

Create the directories used by the remaining files:

```bash
mkdir -p .route .web/components/hello pages/index
```

## 2. Declare the Web route

Use any text editor to create `.route/web`. Use the `id` you just read from `blocklet.yaml` as `site`:

```yaml
site: my-site
path: /
source: .
handler: web
```

This declaration matters. Without it, a direct blocklet URL looks for `.aup/app.aup` or `.aup/app.json`, which is an AUP app entry rather than this static Web Device entry.

## 3. Add site configuration

Use any text editor to create `.web/site.yaml`:

```yaml
domain: my-site.local
locale: en
render-mode: static
seo:
  og-site-name: My Site
  description: A minimal local Web Device site.
```

`domain` is site configuration. This command sequence still uses a local URL; it does not deploy to that domain.

## 4. Add one site component

Use any text editor to create `.web/components/hello/manifest.json`:

```json
{
  "name": "hello",
  "description": "A minimal local component.",
  "props": {
    "title": { "type": "string" },
    "text": { "type": "string" }
  }
}
```

Create `.web/components/hello/render.js`:

```javascript
export function render(ctx) {
  const { props, escapeHtml } = ctx;
  return {
    html: `<main><h1>${escapeHtml(props.title || "")}</h1><p>${escapeHtml(props.text || "")}</p></main>`,
  };
}
```

Create `.web/components/hello/style.css`:

```css
main {
  max-width: 42rem;
  margin: 4rem auto;
  font-family: system-ui, sans-serif;
}
```

For a custom component that does not overlay a theme component, this version's checker requires `manifest.json`, `render.js`, and `style.css` in the same directory. If `style.css` is absent, `arc dsl lint` reports `missing_web_component_file`.

## 5. Add the home-page layout

Create `pages/index/layout.aup`:

```aup
page index {
  hello main title="Hello, Web Device" text="This page is rendered by a local blocklet."
}
```

`hello` is the component you just created. The page contains one component because this guide is only proving the route, AUP layout, and site component work together. It is not a complete content-site or theme template.

Continue to [Run, check, and inspect](../run-check-inspect/) to validate these files and open the rendered page.

---

## Get started

URL: https://www.arcblock.io/en/docs/web-device/getting-started/

This section provides the smallest reproducible path from installing the CLI to a first Web Device site: install and confirm the version, establish scope, create the site, then run and inspect it directly on your machine.

## Read in this order

1. [Install ARC CLI](../install-arc-cli/) to install the CLI, note the local version, and read the platform boundary.
2. [Requirements and scope](../requirements-and-scope/) to decide whether this is a static Web Device site rather than an interactive AUP app.
3. [Build a first site](../first-site/) to create the verified beta.25 file set.
4. [Run, check, and inspect](../run-check-inspect/) to validate the source and open the URL printed by the local run.

## After the first site

Task recipes chain **unit pages** (primitives, widgets, layout components, Markdown, surfaces) without re-documenting their APIs:

- [Recipes hub](../recipes/)
- [Recipe: first site](../recipes/first-site/)
- [Recipe: collection list page](../recipes/collection-list/)
- [Recipe: bind source to layout](../recipes/bind-source/)
- [Showcase mapping](../showcase-mapping/) (local AUP demos → unit pages)

---

## Hero lab · webgl-hero backgrounds

URL: https://www.arcblock.io/en/docs/web-device/hero-lab/

Site `landing-hero` (`blocklets/arcblock/.web/components/landing-hero/`) accepts an optional
`heroVisual` prop that renders a full-bleed `.landing-hero-visual` target div behind the copy. Pair
it with an AUP `widget` child block naming a Web Device widget (here, `webgl-hero` — WebGL 3D
backgrounds, 24 modes, shipped with the runtime) and the hero becomes a real demonstration of what
Web Device's widget layer can render, not decoration bolted onto the page.

This page is a running catalog, not a tutorial: each candidate below is a real render with its exact
config, kept here so a future pass doesn't have to re-derive which modes actually work and which
look right for this site's editorial tone — see "Dead ends" for the ones that don't.

## Gallery

All 24 `webgl-hero` modes, using this site's own `::gallery{folder}` media block (see
[Folder-backed media gallery](../media-gallery/)) rather than a hand-built grid. Each mode's caption
notes what it renders and whether it reads the `colors` config or hardcodes its own palette; full
config and larger screenshots are in the reference section further down the page.

::gallery{folder="gallery" layout="grid" cols="4"}

## How this is wired

```aup
component hero slot=site-introduction component=landing-hero variant=home
    headlineVariant=balanced-statement maxLines=3 heroVisual=webgl
    title=:k0 subtitle=:k1 ... {
  widget hero-bg name=webgl-hero target=".landing-hero-visual" mode=topo
      colors="#008f7a,#fcfdfc" opacity=0.5 speed=0.4 mouse=false
}
```

`heroVisual=webgl` switches the component to single-column copy with a fixed max-width and a
readability scrim. Horizontal coverage is sized off the copy box (not the section — a scrim sized
in vw/% drifts out of sync with the text the wider the browser window gets). Vertical coverage
has to reach the hero edges: the copy sits in a padded, vertically-centered inner, so a scrim
that only extends a few rem around the copy leaves a strip of uncovered canvas under the header.
The trace/geometry aside used elsewhere on this site is suppressed when `heroVisual` is set —
pick one visual per hero, not both.

Below 760px the widget doesn't run at all — a small inline script registers a `DOMContentLoaded`
listener early enough to remove the widget's config `<script>` before the engine's own listener ever
scans for it, so no WebGL context, no Three.js, no render loop gets created on a phone. Matches this
site's rule that mobile layouts don't run WebGL/canvas effects; a plain hero (headline, subtitle,
actions) renders instead.

Live comparison pages (internal, not in nav): `/en/hero-lab-topo/`, `/en/hero-lab-aurora/`,
`/en/hero-lab-cubegrid/` — same copy as the homepage hero, different `heroVisual` config, useful for
side-by-side judgment in a real browser before anything ships to the homepage itself.

**These render correctly only against a locally-built `arc`.** The CSS-override and opacity bugs
below are fixed upstream in [ArcBlock/arc#4402](https://github.com/ArcBlock/arc/pull/4402) (merged),
and the topo coverage/aspect fix is in
[ArcBlock/arc#4490](https://github.com/ArcBlock/arc/pull/4490) — until whichever of those hasn't
shipped in a release lands on the `arc` binary actually serving this blocklet, the live pages above
can still show the un-fixed behavior (widget mounts but collapses to `height:0`, or `topo` stretched
on wide screens). The screenshots in each candidate section are the honest record of what this looks
like on a fixed build; the live links are for local verification, not a guarantee of what the
deployed site currently shows.

## Candidates

### topo — dense contour fill

![ArcBlock hero with a topographic contour-line pattern in teal, fading to white behind the "Own the software you need." headline](./media/hero-lab-topo.png)

```
mode=topo colors="#008f7a,#fcfdfc" colorsDark="#2ec8ae,#061211" opacity=0.5 speed=0.4 mouse=false
```

Verdict: strongest candidate so far. Reads as a real technical texture (elevation lines), not a
generic AI-tech gradient, and holds up at both narrow and ultra-wide viewports once the plane-sizing
fix below landed. Full opacity control works (this mode respects `opacity`).

Known gaps fixed while building this:

- `TopoEngine` used a fixed-size `PlaneGeometry(30, 20)`, which only covers hero aspect ratios up to
  about 2.4:1 — any wider browser window ran past the plane's edge and showed bare fill color down
  both sides. Fixed upstream to size the plane from the camera's actual visible frustum at render time
  (see "Upstream fixes" below).
- That coverage fix exposed a second bug: the noise shader samples `vUv * 6.0` on both axes, and vUv
  is 0-1 per axis regardless of the plane's physical aspect ratio — on a wide plane each noise cycle
  covers more physical width than height, so contours read as horizontally stretched streaks instead
  of round elevation-line blobs. Fixed upstream by scaling only the x sample by the plane's aspect
  ratio, keeping a noise cycle the same physical size on both axes.
- The widget's `colors` config is static and theme-unaware — a light-mode config rendered as a bright
  rectangle in dark mode. `landing-hero`'s render.js now accepts a matching `colorsDark`/`bgDark` pair
  and swaps them in client-side before the widget parses its config, if the page loads with dark mode
  already active. **Known remaining gap**: switching the theme toggle live (no reload) does not
  retroactively recolor the already-rendered canvas — the swap only applies at load time.

### aurora — atmospheric gradient

![ArcBlock hero with a dark aurora/starfield gradient behind the headline, fading from white on the left to near-black on the right](./media/hero-lab-aurora.png)

```
mode=aurora colors="#008f7a,#2ec8ae,#0f3d38" opacity=0.5 speed=0.4 mouse=false
```

Verdict: visually striking but reads closer to a generic "AI product" demo than this site's
restrained editorial tone. Still needs either a lower-contrast color set or a narrower subtitle
measure before it's a real candidate, not just a working one.

Bug found while building this: a dark, hard-edged band ran across the top of the hero, right
below the header. An earlier pass measured the section, the `.landing-hero-visual` target, and
the canvas as pixel-identical via `getBoundingClientRect()`, concluded it wasn't CSS, and spent
three attempts tuning `camera.lookAt()` on `aurora` / `ocean` / `retrowave`. That diagnosis was
wrong. The canvas *does* fill the section; the missing coverage is the readability scrim on
`.landing-hero-copy::before`. The copy sits in a padded, vertically-centered inner, and the
scrim only extended ±8rem around that box — about 45px of uncovered canvas under the header at
1440px, more at other widths. Dark modes make that strip obvious; light modes like `topo` hide
it. The published "fixed" `retrowave` screenshot still showed the band.

The actual fix is in `landing-hero` CSS: keep the scrim's horizontal sizing tied to the copy,
and stretch it vertically past the section (`top`/`bottom: -100vmax`, clipped by
`.landing-hero { overflow: hidden }`). Verified at 600/868/1221/1440/1920px. Camera tilt can
still leave empty sky in the 3D scene itself; that is a different, remaining widget issue, not
the header gap.

### cubegrid — geometric wireframe grid

![ArcBlock hero with a grid of small rotating teal wireframe cubes behind the headline, echoing the ArcBlock cube/pyramid mark](./media/hero-lab-cubegrid.png)

```
mode=cubegrid colors="#008f7a" opacity=0.6 speed=0.5 mouse=false
```

Verdict: the strongest thematic fit — the rotating wireframe cubes echo the actual ArcBlock
cube/pyramid mark instead of being an unrelated texture, and a single accent color keeps it quiet.
Worth testing against `positioning.md`'s "would this still make sense on a generic AI site" question
before committing — the geometry argument is specific to us, but the effect alone is a common
pattern.

## Dead ends

Rendered and screenshotted, not just described from reading the source — a mode that "should" work on
paper can still fail on screen, and the reverse (see rings below, corrected after actually looking).
Also live (internal, not in nav) for the same local-build caveat as above: `/en/hero-lab-network/`,
`/en/hero-lab-wave/`, `/en/hero-lab-rings/`.

### network — dead, ignores brand color entirely

![ArcBlock hero with a dark starfield/network-node background of thin white lines and glowing points, ignoring the configured teal color entirely](./media/hero-lab-network.png)

```
mode=network colors="#008f7a,#0f3d38" opacity=0.5 speed=0.4 mouse=false
```

Verdict: dead end, not a style judgment — `NetworkEngine` hardcodes its palette directly in the GLSL
fragment shader and never reads `cfg.colors`, so the teal config above has zero effect; what renders
is a generic blue-white constellation look with no connection to this site's palette. Not usable until
that color-hardcoding gap is fixed upstream (tracked in the issue, not fixed in this PR — bigger
change than the mechanical opacity fix).

### wave — dead, too sparse to read as a background

![ArcBlock hero with a sparse starburst of thin teal lines radiating from a point behind the headline, mostly empty canvas around it](./media/hero-lab-wave.png)

```
mode=wave colors="#008f7a,#1f7a6e" bg="#fcfdfc" opacity=0.85 speed=0.4 mouse=false
```

Verdict: dead end. Technically the best-behaved mode (respects both `opacity` and `colors`, no
upstream bugs), but the wireframe sphere is small and sparse relative to a 1440×600+ full-bleed
canvas — it reads as a tiny starburst floating in mostly-empty space, not a background.

### rings — not chosen, but wrongly assumed sparse before actually rendering it

![ArcBlock hero with a large wireframe sphere made of many overlapping teal orbital rings behind the headline](./media/hero-lab-rings.png)

```
mode=rings colors="#008f7a" bg="#fcfdfc" opacity=0.85 speed=0.4 mouse=false
```

Verdict: **correction** — an earlier draft of this page grouped rings with wave as "too sparse" based
on reading the engine's source, without actually rendering it. It isn't sparse at all: 18 overlapping
rings read as a bold, cohesive wireframe globe. Not chosen for a different reason, checked against
`positioning.md`'s self-test ("would this still make sense on any generic AI site?") — a wireframe
globe/orbit is a common tech-marketing cliché with no connection to this site's own content, unlike
cubegrid's actual cube/pyramid mark. Left out on that basis, not because it doesn't render well.

## Also surveyed

`webgl-hero` ships 24 modes total. The six above are the ones worth a real decision; the rest were
rendered and screenshotted for completeness, not left as an assumption from reading the source. Same
config shape throughout unless noted: teal-family `colors`, `bg="#fcfdfc"`, `opacity=0.6`,
`speed=0.4`, `mouse=false`. Every mode covered on this page has a matching live page (internal, not
in nav) at `/en/hero-lab-<mode>/`, same local-build caveat as above.

### Ignores the color config entirely (confirmed via source, not just the render)

`crystal`, `phantom`, `lightcube`, `reflect`, `gyroid`, `tunnel`, and `abstract` never read
`cfg.colors` — each hardcodes its own palette in-shader, the same class of bug as `network`. None are
usable without that fix landing upstream (not attempted here — bigger surface than the mechanical
`opacity` fix).

| Mode | Screenshot | Note |
| --- | --- | --- |
| crystal | ![crystal: purple/blue glass shards flying, ignoring the teal config](./media/hero-lab-crystal.png) | Off-brand purple/blue glass shards. |
| phantom | ![phantom: white glowing bokeh shapes on a dark background](./media/hero-lab-phantom.png) | Off-brand white bokeh glow. |
| lightcube | ![lightcube: muddy orange and blue blurred cube grid](./media/hero-lab-lightcube.png) | Muddy, off-brand, part of the frame renders flat black. |
| reflect | ![reflect: stacked colorful boxes resembling cardboard cartons](./media/hero-lab-reflect.png) | Reads as stacked cardboard boxes, not abstract. |
| gyroid | ![gyroid: psychedelic red and blue fractal surface](./media/hero-lab-gyroid.png) | Psychedelic, jarring, wrong tone entirely. |
| tunnel | ![tunnel: dark abstract tunnel with magenta and gold edges](./media/hero-lab-tunnel.png) | Off-brand magenta/gold, mostly a black void. |
| abstract | ![abstract: iridescent oil-slick magenta and gold gradient](./media/hero-lab-abstract.png) | Off-brand iridescent oil-slick look. |

### Too sparse or too small to read as a background

![blob: a small pale faceted rock shape floating off to the side](./media/hero-lab-blob.png)
![collapse: a sparse scatter of falling dots, mostly empty canvas](./media/hero-lab-collapse.png)
![meshline: scattered short diagonal line fragments, mostly empty canvas](./media/hero-lab-meshline.png)

`blob`, `collapse`, `meshline` — same failure mode as `wave`: technically fine, geometrically too
thin against a full-bleed 1440×600+ canvas to register as a background at a glance.

### Renders fine but reads as a generic tech-marketing cliché

![galaxy: a dense gray and teal particle network sphere](./media/hero-lab-galaxy.png)

`galaxy` — a bold, dense network-globe. Same call as `rings`: common "blockchain network" stock
imagery, not specific to this site.

![landscape: a stock photo–style mountain range and road at sunset, colors ignored](./media/hero-lab-landscape.png)

`landscape` — full-bleed mountain/road/sunset scene. Reads as generic stock photography; also
ignored the teal config (rendered in neutral grays/tans regardless). Still not a candidate for
the stock-photo reason.

![retrowave: an 80s-style synthwave sunset over hills, with the grid floor still in view](./media/hero-lab-retrowave.png)

`retrowave` — the textbook synthwave sunset. The most generic "AI demo site" cliché in the whole
set; also overlaps the subtitle enough to hurt readability. The header-gap on this mode is the
CSS scrim bug described under `aurora` (screenshot above is after that fix; the grid floor is
still in the scene). Still not a candidate for the cliché reason.

### Chaotic / visually noisy

![cube: a large distorted, glitchy-looking wireframe cube](./media/hero-lab-cube.png)

`cube` — a wireframe box with heavy vertex jitter. Reads as a rendering glitch rather than an
intentional effect, and its right edge sits under the subtitle text.

### On-brand color, decent render, not chosen for content reasons

![ocean: a teal ocean horizon with a sunset sky](./media/hero-lab-ocean.png)

`ocean` — actually picks up the teal config correctly (the "water" fill is on-brand) and looks calm.
Not chosen because the content itself — a literal ocean/sunset scene — has no connection to software
or this site's subject matter.

![metaball: soft glowing teal blobs floating on a dark background](./media/hero-lab-metaball.png)

`metaball` — also correctly on-brand (soft teal glow blobs), the best-looking of this group. Reads as
a generic "lava lamp" ambient effect; kept as a fallback option worth reconsidering if none of the
three main candidates survive further design review.

![marble: a single large glossy mint-colored sphere](./media/hero-lab-marble.png)

`marble` — originally rendered nothing at all: two texture files it `loader.load()`s
(`marble-noise.jpg`, `marble-noise3d.jpg`) 404'd in every environment, never shipped anywhere in the
widget package. Filed as [ArcBlock/arc#4417](https://github.com/ArcBlock/arc/issues/4417) and fixed
upstream in [ArcBlock/arc#4440](https://github.com/ArcBlock/arc/pull/4440) (merged) by replacing the
missing textures with procedural noise. Now renders — a single large glossy sphere, on-brand color,
but no visible marble veining came through from the procedural swap; reads as a generic glass/chrome
orb rather than anything specific to this site. Not chosen for the same reason as `metaball`: a
correct, on-brand render of a generic effect.

### Broken

![clouds: a flat teal gradient with no visible cloud detail](./media/hero-lab-clouds.png)

`clouds` — rendered as a flat gradient wash with no visible volumetric detail. `CloudsEngine` has GPU
tier detection that drops march-step quality on a detected low-end/software renderer; this ran under
headless Chromium (SwiftShader), which may explain it — inconclusive without a real-GPU comparison,
noted here rather than guessed at.

## Upstream fixes behind this

Four `webgl-hero` bugs surfaced while building the above, all now fixed upstream:

- [ArcBlock/arc#4392](https://github.com/ArcBlock/arc/issues/4392) — the widget's own injected CSS
  (`.wh{position:relative}`) silently overrode this site's `position:absolute;inset:0` on the target
  element (equal specificity, later in the cascade), collapsing it to `height:0` in every mode
  regardless of config. Also: 17 of ~24 modes discarded the `opacity` config via a duplicate
  `setClearColor(x, 1)` call.
  Fix: [ArcBlock/arc#4402](https://github.com/ArcBlock/arc/pull/4402) (merged) — applies `cfg.opacity`
  via canvas CSS opacity instead of WebGL clear alpha, since three.js's `WebGLBackground` hardcodes
  clear alpha to 1 for any `scene.background` Color regardless of `setClearColor`'s alpha argument.
  An earlier attempt at this same fix ([#4403](https://github.com/ArcBlock/arc/pull/4403), closed as
  a duplicate) took the per-engine route of nulling `scene.background` on all 17 modes — #4402's
  single shared-function fix is the one that actually shipped.
- `topo`'s plane was a fixed `PlaneGeometry(30, 20)`, covering only ~2.4:1 aspect ratio — any wider
  hero ran past the plane's edge and showed bare clear color as a margin down both sides. Once fixed
  to size from the camera's actual frustum, this exposed a second bug: the noise shader sampled both
  axes at the same rate, stretching contours horizontally on any wide hero.
  Fix: [ArcBlock/arc#4490](https://github.com/ArcBlock/arc/pull/4490).
- `marble` loaded two texture files that don't exist anywhere in the widget package, rendering
  nothing. Filed as [ArcBlock/arc#4417](https://github.com/ArcBlock/arc/issues/4417), fixed in
  [ArcBlock/arc#4440](https://github.com/ArcBlock/arc/pull/4440) (merged) — see its entry above.

The header-band artifact investigated under `aurora` above was in `arcblock-site`'s own readability
scrim, not this widget — `webgl-hero`'s camera behavior was never the cause. See that section for
the fix.

Until the fixes above ship in a release, the candidates on this page only render correctly on a
locally-built `arc` — see the site's `arc-upstream` skill for what "upstream closed" vs. "we can
actually use it" means in practice.

## Related

- [`landing-hero` component reference](../components/site/landing-hero/)
- [Widget integration cookbook](https://github.com/ArcBlock/arc/blob/main/providers/runtime/web-device/COOKBOOK.md#widget-integration)

---

## In-page review mode

URL: https://www.arcblock.io/en/docs/web-device/in-page-review/

In-page review mode lets you leave feedback on the **rendered page**, not on the source tree. Feedback lands next to the content item as `.review/` files, so agents and people can process it without a separate comment system.

This page is an operations guide. Overlay chrome below was verified on 2026-08-21 against the glass-island HUD that landed in [arc#4525](https://github.com/ArcBlock/arc/pull/4525). The feature itself landed in `2.0.0-beta.19` / `2.0.0-beta.20` via arc#2870. It is not a design essay; for motivation see the [feature article](/en/articles/web-device-in-page-review/).

## When to use it

Use review mode when:

- lint, validate, check, and build are green, but the **rendered** copy still needs human judgment;
- you want feedback tied to the exact string a reader sees, including multi-locale renders;
- an agent should later apply mechanical edits (`delete` / `replace` / `insert-after`) or free-form instructions.

Do **not** use it as:

- a public visitor feedback widget on production;
- a multi-user conflict resolver (opposite opinions stay side by side);
- a substitute for `arc dsl lint` / `validate` / `blocklet check` (those still own structural defects).

## Enable review mode

1. Run the blocklet the usual way (see [Preview, build, and publish](../preview-build-publish/)):

   ```bash
   arc blocklet run blocklets/arcblock
   ```

2. Open the printed URL for the page you care about, then append **exactly** `?review=1`:

   ```text
   http://<host>:<port>/en/docs/web-device/overview/?review=1
   ```

   Only the value `1` enables the overlay. `?review=true`, `?review=0`, or a bare `?review` do not.

3. Confirm the page injects the review UI. A frosted-glass island sits at the **bottom right** with three icons:

   | Icon | Control | What it does |
   | --- | --- | --- |
   | Pointer | **Point** | Opt-in. Click an element with `data-aup-id`, or drag a box. Ordinary clicks still work while Point is off. |
   | Bubble | **Page note** | Unanchored whole-page feedback. There is no bottom-left Page note button. |
   | Pause | **Freeze** | Pause CSS animations, transitions, and `<video>`. The island stays live. |

   Selecting body text opens a light composer near the selection (**Add** / **Cancel**). The status strip (`Review: open · N planned / N done`, **Approve page**, **Run checks**) stays **hidden while empty**. It fills after a signed-in session loads `.review/.actions/state`. Anonymous `?review=1` still shows the island and composers.

![Rendered page with the review island at bottom right: Point, Page note, Freeze](media/review-idle--0-0-0-.png)

*Glass-island HUD · this site's in-page-review article at `?review=1` · 1440×900 · 2026-08-21. Capture used a local Web Device handler after arc#4525, not a published CLI tag.*

Review mode works on draft and already-published pages. Injection is **per request** and opt-in; static HTML in a publish snapshot does not auto-enable it.

## Leave feedback

| Action | How |
| --- | --- |
| Anchored note | Select text on the page (Point does not need to be on). Choose a type, optionally write an instruction, click **Add**. |
| Pointed note | Arm **Point**, then click a node with `data-aup-id`. Shift/meta-click adds another node; dragging a box can cover several nodes or an empty region. |
| Whole-page note | Click the bubble (**Page note**) in the island. No selection is stored. |
| Freeze a frame | Click **Freeze**. Click again to unfreeze. Does not edit CSS. |
| Dismiss panel | **Cancel**, or press Escape. Clearing the text selection also closes a selection-driven panel. |

![Light composer after selecting body text: instruction pill, Add / Cancel, island still visible](media/review-selection-panel--0-0-0-.png)

*Text selection on a markdown article body. Point was off. Types are `instruction` / `delete` / `replace` / `insert-after`.*

![Page note composer: preview says page note not anchored to a selection](media/review-page-note-panel--0-0-0-.png)

*Page note from the island bubble. Composer parks above the island.*

Point only targets elements that carry `data-aup-id` (AUP-rendered nodes). A 2026-08-21 capture of this site's markdown article body found **zero** such nodes; text selection still worked. Do not document Point as "click anywhere."

### Feedback types

| `type` | Anchored? | Meaning |
| --- | --- | --- |
| `instruction` | yes | Free-form instruction about the selection ("make this longer") |
| `delete` | yes | Remove the selected content |
| `replace` | yes | Replace the selection (body carries the replacement text) |
| `insert-after` | yes | Insert content after the selection |
| `page-note` | no | Page-level note with no text anchor |

These are **executable instructions**, not a discussion thread. Conflicting notes on the same span are all kept; nothing is auto-merged.

### What is captured

For anchored types the overlay records:

- `anchor`: the selected string as the reader sees it;
- `context`: about 50 characters before and after, with `{selected}` marking the span (DOM Range offsets, not the first `indexOf` match);
- `locale`: the locale segment of the URL at submit time (server-injected; empty means "not tagged");
- `instruction`: free text for every type except `delete`.

Script, style, noscript, and the review UI itself are excluded from context capture.

## Two-level status

| Level | File | Values | Unit of |
| --- | --- | --- | --- |
| Page | `.review/.status.md` | `open` · `approved` | Approval of the whole page |
| Item | `.review/<id>.md` field `status` | `open` · `done` | Processing of one note |

The status strip stays hidden while empty. After a signed-in session loads `.review/.actions/state`:

- **Approve page** / **Reopen page** toggles page-level status;
- **Done** / **Reopen** on a row toggles that item.

Anonymous overlay sessions still compose notes; they do not paint item rows until session context is present.

Submitting a new item demotes an `approved` page back to `open`. Page approval and item processing are independent: a page can be `approved` while some items remain `open` only if you re-approve after new work, or if you never demote (new submits always re-open).

## Where feedback is stored

Feedback follows the **content item**, not a site-wide comment store.

```text
content/articles/<slug>/
  content.md
  content.zh.md
  .review/
    <id>.md          # one feedback item
    .status.md       # page-level status (optional until set)
```

Pages under `pages/<slug>/` use the same relative structure next to `layout.aup`.

Example item file shape:

```markdown
---
status: open
type: instruction
anchor: selected text on the page
context: …before…{selected}…after…
locale: en
author: anonymous
created: 2026-08-02T03:33:00.000Z
---
make this longer
```

Page status file:

```markdown
---
status: approved
updated: 2026-08-02T04:00:00.000Z
---
```

Ids are **server-generated** (8 hex characters). Clients cannot choose an id to overwrite an existing item.

## Read and drive status through AFS

Virtual paths live under the web-device mount (default `/web`):

```text
/web/content-sites/<site>/collections/<collection>/<slug>/.review
/web/content-sites/<site>/pages/<slug>/.review
```

Actions (same item path + `/.review/.actions/<action>`):

| Action | Purpose | Typical args |
| --- | --- | --- |
| `submit` | Create one item | `type`, optional `anchor` / `context` / `instruction` / `locale` / `author` |
| `set-item-status` | Mark item `open` or `done` | `id`, `status` |
| `set-page-status` | Mark page `open` or `approved` | `status` |
| `state` | Read page status + all items + locale presence | (none) |

List and read:

```bash
# List structured items for one content record (path is site-specific)
arc afs ls /web/content-sites/<site>/collections/articles/<slug>/.review

# Read one item
arc afs read /web/content-sites/<site>/collections/articles/<slug>/.review/<id>

# Snapshot used by the overlay status bar
arc afs exec /web/content-sites/<site>/collections/articles/<slug>/.review/.actions/state
```

Replace `<site>` and the collection path with the content site you actually mounted. Paths that do not resolve to a real content item return `NOT_FOUND` rather than creating a stray `.review/` directory.

## Locale and automated checks

Multi-locale items share one `.review/` directory (variants are sibling files such as `content.md` / `content.zh.md`). The status bar can show which declared locales have a file present (`✓` / `✗`). That is "other renders worth opening", not a separate review state per locale.

Each submission can carry the **locale of the page you were looking at**. Use that field when the same string appears in more than one language version.

**Run checks** on the status bar runs site-level `lint` and `check-seo` for **this page only** through the declared-site actions namespace, and shows findings next to human feedback. A failed check surfaces as an error row; an empty result means no findings for this page, not "checks never ran".

## Publish does not ship `.review/`

Publish snapshots **exclude** any directory named `.review` from both the physical copy and the published tree metadata (arc#2870 Phase 3). Review data stays with the authoring tree; it must not appear in public deploy artifacts.

That is separate from the `?review=1` query flag. Even if someone appends the flag on a public host, there is no `.review/` payload in the published snapshot for them to write into unless the host still exposes a writable content-space surface (local/dev only by design of this workflow).

## Limits and failure modes

| Boundary | Behavior |
| --- | --- |
| Enable flag | Only `?review=1` injects the overlay |
| Point target | Only elements with `data-aup-id`. Markdown body text still uses text selection |
| Empty status strip | Hidden (`:empty { display: none }`) until state loads |
| Freeze | Pauses CSS animation, transition, and video; HUD itself is excluded |
| Free-text size | `anchor` / `context` / `instruction` capped at 64 KiB each; oversize → `VALIDATION` |
| Invalid type or status | `VALIDATION`; values are never coerced |
| Missing content item | `NOT_FOUND`; no write under a guessed path |
| Read-only AFS | `READONLY` |
| Invalid `locale` string | Dropped (submission still succeeds without locale) |
| Concurrent submits | Distinct server ids; no multi-user merge |
| Broken / stale anchor after rewrite | Item is kept; use `context` for fuzzy re-location; do not auto-delete |
| Domain-router vs portal URL | Overlay derives the content-site path from the server; wrong site name fails the action loudly |

## Related pages

- [Preview, build, and publish](../preview-build-publish/): local run vs build vs formal publish
- [Run, check, and inspect](../run-check-inspect/): first local verification chain
- [Diagnose a site](../diagnose/): narrow structural failures before review
- [Content objects, metadata, and locales](../content-and-objects/): where content items live on disk
- Feature article: [Review the rendered page, keep feedback with the content](/en/articles/web-device-in-page-review/)
- [Bookmark and note (save capability)](../save-capability/): reader save chrome, not this overlay

---

## web-device/in-page-review/media

URL: https://www.arcblock.io/en/docs/web-device/in-page-review/media/

---

## web-device/in-page-review/visuals

URL: https://www.arcblock.io/en/docs/web-device/in-page-review/visuals/

---

## Install ARC CLI

URL: https://www.arcblock.io/en/docs/web-device/install-arc-cli/

Install `arc` before continuing to the site steps. The installer resolves the current published release on its own, so there is no version number to copy off this page.

## Install

On macOS, run the official installer:

```bash
curl -fsSL https://arc.arcblock.io/install.sh | bash
```

The command downloads ARC CLI, verifies the downloaded archive against a checksum published from a second, independent origin, and installs the executable under `~/.arc`. When verifiable release-signing metadata is available, the installer checks it too; the current unsigned fallback warns and continues. The installer tells you which PATH configuration it writes. If the current shell does not find `arc` yet, open a new terminal before continuing.

## Confirm the version

```bash
arc --version
```

Every build prints its version:

```text
<version>
```

Newer builds add the short commit they were built from and its build date, as `<version> (<commit>) <build date>`. Both forms are correct.

Note down the version you get. Most pages in this section carry the ARC version their evidence was captured on. Where that is older than what you just installed, read [Version compatibility](../version-compatibility/) and repeat that page's checks against your own version instead of assuming the output matches. To reproduce a page's captured output exactly, install its version instead by appending `-s -- --version <v>` to the command above.

Installing the CLI does not deploy a blocklet or create or sign in to a DID Space. Continue with [Requirements and scope](../requirements-and-scope/).

---

## Markdown directives & structures

URL: https://www.arcblock.io/en/docs/web-device/markdown/

This hub lists every **Markdown directive** and **Markdown structure** unit documented for the Web Device content reader.

**These are MD authoring units — not AUP primitives; not layout components.**

## MD directives (8)

- [`::embed`](./embed/)
- [`::::steps`](./steps/)
- [`:::step`](./step/)
- [`::link-card`](./link-card/)
- [`:::action-card`](./action-card/)
- [`:::info-card`](./info-card/)
- [`::::card-group`](./card-group/)
- [Generic MD directive (incl. `::input`)](./generic-directive/)

## MD structures (10)

- [GFM admonition](./gfm-admonition/)
- [GFM table](./gfm-table/)
- [heading](./heading/)
- [paragraph](./paragraph/)
- [fenced code](./fenced-code/)
- [list](./list/)
- [thematicBreak / HR](./thematic-break/)
- [raw HTML](./raw-html/)
- [image (inline)](./image/)
- [`slides: true` front matter](./slides-front-matter/)

## Counts

| Layer | Count |
| --- | ---: |
| md-directive | 8 |
| md-structure | 10 |
| Unit pages under `markdown/` | 18 |

Historical multi-unit authoring pages (now thin hubs that only link out): [cards](../markdown-cards/), [steps](../markdown-steps/), [embeds](../markdown-embeds/), [GFM callouts/tables](../markdown-gfm-callouts/), [slides](../markdown-slides/).

Also see [Layout components](../components/) and [Surfaces](../surfaces/).

---

## Use cards in Markdown

URL: https://www.arcblock.io/en/docs/web-device/markdown-cards/

Cards are Markdown directives in a Web Device content item. They organize an author-provided title, description, optional icon, and link as page content. A card does not create an AUP session or gain permission to run `exec`, write data, or edit the document.

This page is a **live feature guide** (source + rendered cards on the same page). Atomic unit pages: [link-card](../markdown/link-card/), [info-card](../markdown/info-card/), [action-card](../markdown/action-card/), [card-group](../markdown/card-group/).

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Navigation and static info cards in content Markdown |
| Boundaries | Navigation only for links; no `exec`, AFS write, or session; not a `.web` component API |
| Author entry | `::link-card` · `:::info-card` · `:::action-card` · `::::card-group` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | No safe `href` → non-link card; `info-card` ignores `href`; fence depth errors drop structure |
| Verification | Routes below · `arc --version` = `2.0.0-beta.32` |

## link-card

Source:

```markdown
::link-card{title="Web Device overview" description="Review the site structure and its boundary" href="/en/docs/web-device/overview/" icon="book"}
```

Rendered:

::link-card{title="Web Device overview" description="Review the site structure and its boundary" href="/en/docs/web-device/overview/" icon="book"}

A `link-card` becomes a link only when it has a safe `href`. Clicking it performs ordinary page navigation only; it does not write content.

Source without `href` (not a navigation target):

```markdown
::link-card{title="Not a link" description="Missing href stays non-interactive chrome"}
```

Rendered:

::link-card{title="Not a link" description="Missing href stays non-interactive chrome"}

## info-card

Source:

````markdown
:::info-card{title="A read-only example" description="Content and layout are maintained separately"}
The body can contain paragraphs, lists, and code.

- A content item owns the reader-facing text
- `layout.aup` decides how a page organizes those items
:::
````

Rendered:

:::info-card{title="A read-only example" description="Content and layout are maintained separately"}
The body can contain paragraphs, lists, and code.

- A content item owns the reader-facing text
- `layout.aup` decides how a page organizes those items
:::

An `info-card` is not a link. Even if an author supplies an `href`, the current content reader does not promote it to a clickable card.

## action-card

An `action-card` places explicit `action` nodes in a card body. This example contains only an ordinary navigation `href`, with no event, `exec`, or data write.

Source:

````markdown
:::action-card{title="Continue reading" description="Place several navigation choices in one card" icon="book"}
::action{label="Read the AUP layout boundary" href="/en/docs/web-device/aup-reference/" variant="primary"}
:::
````

Rendered:

:::action-card{title="Continue reading" description="Place several navigation choices in one card" icon="book"}
::action{label="Read the AUP layout boundary" href="/en/docs/web-device/aup-reference/" variant="primary"}
:::

In Content Markdown, this `action` proves link navigation only. It is not evidence that a document can run a background action or has AFS or session permission.

## Put several entry points in a card-group

The outer fence needs one more colon than the nested container directive. This `card-group` contains two leaf cards, so four colons are sufficient:

Source:

```markdown
::::card-group
::link-card{title="Content objects" description="Review content and metadata" href="/en/docs/web-device/content-and-objects/" icon="book"}
::link-card{title="AUP boundary" description="See the difference between page layout and an AUP tree" href="/en/docs/web-device/aup-reference/" icon="layout"}
::::
```

Rendered:

::::card-group
::link-card{title="Content objects" description="Review content and metadata" href="/en/docs/web-device/content-and-objects/" icon="book"}
::link-card{title="AUP boundary" description="See the difference between page layout and an AUP tree" href="/en/docs/web-device/aup-reference/" icon="layout"}
::::

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `link-card` without `href` | Non-link presentation |
| `href` on `info-card` | Ignored for navigation |
| Outer fence too shallow | Parser misreads children; group/cards may collapse |
| Expecting `exec` or form submit | Out of contract |

Card syntax belongs to the Web Device content-reading path. It is not a general input format for a `.web` component. To override or author a layout component, see [Use and override components](../components-overrides/).

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-12` · `arc --version` → `2.0.0-beta.32` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `::link-card` · `:::action-card` · `:::info-card` · `::::card-group` |
| Implementation | `providers/runtime/web-device/src/content-reader.ts` (`contentCardToAup`, card-group) |
| Unit pages | [link-card](../markdown/link-card/) · [info-card](../markdown/info-card/) · [action-card](../markdown/action-card/) · [card-group](../markdown/card-group/) |
| Public routes | `/en/docs/web-device/markdown-cards/` · `/zh/docs/web-device/markdown-cards/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · click link-cards → ordinary navigation only |
| Accept | Source matches cards; missing `href` is not a link; no write/`exec` |

---

## Embed external and internal content in Markdown

URL: https://www.arcblock.io/en/docs/web-device/markdown-embeds/

Web Device recognizes a narrow set of standalone Markdown links as content embeds. This is not a general permission to frame arbitrary sites. The current content reader recognizes YouTube video URLs, X/Twitter status URLs, and validated same-site absolute paths. Other URLs remain visible links.

This page is a **live feature guide**. Atomic directive contract: [embed unit](../markdown/embed/). Use that page for the single-unit matrix row; use this page for how-to plus working frames.

Use an explicit `embed` directive when the source itself is part of the documentation. It makes the authoring intent unambiguous and puts the source directly above the result.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Supported third-party and same-site embeds in content Markdown |
| Boundaries | Not a general iframe capability; document stays read-only for site content/AUP state |
| Author entry | `::embed{url=…}` or standalone recognized URL |
| Surface | Web Device **document** → frame/media with provider-specific sandbox |
| Public status | `released` for YouTube, X status, validated internal paths |
| Fallback / failure | Unrecognized or refused URL → ordinary link / no embed descriptor |
| Verification | Routes below · `arc --version` = `2.0.0-beta.32` · same-site host only for internal paths |

## A YouTube embed

Source:

```markdown
::embed{url="https://youtu.be/jNQXAC9IVRw"}
```

Rendered:

::embed{url="https://youtu.be/jNQXAC9IVRw"}

The current renderer turns this supported URL into a responsive, lazy-loaded, sandboxed third-party iframe. The document stays read-only: the frame is not an editor for this Markdown item or an AUP session owned by the document. Read-only refers to this site's content and AUP state, not to network behavior inside the third-party frame.

## An X post

Source:

```markdown
::embed{url="https://x.com/arcblock_io/status/1955367769672950142"}
```

Rendered:

::embed{url="https://x.com/arcblock_io/status/1955367769672950142"}

The renderer keeps the original status URL as the frame fallback target. The availability and appearance of the embedded post remain controlled by X; do not treat a third-party frame as evidence that a document has persisted state or granted a capability.

## A same-site page or deck

Use one site-absolute path, beginning with a single `/`, to embed a page from the same site. After the client-side slides widget initializes, a slides record uses this form as a 16:9 player surface; before then, its server-rendered transcript remains part of the frame. Opening the source route directly keeps the normal readable transcript.

Source:

```markdown
::embed{url="/en/docs/web-device/slides-demo/"}
```

Rendered:

::embed{url="/en/docs/web-device/slides-demo/"}

The path must remain on this site. Protocol-relative paths, traversal segments, backslashes, and control characters are refused; this directive does not grant a general external iframe capability. A query and fragment can select the target page's supported state, such as a deck's `?full#slide-…` link. See [Markdown slides](../markdown-slides/) for the deck contract.

Same-site embeds load the target page inside an iframe. ARC’s default `frame-ancestors 'none'` blocks that framing. Sites that embed their own pages must set `.web/security`:

```yaml
frame-ancestors: "'self'"
```

Without it, the iframe is blank while the target URL still works when opened alone. Deck and other internal embeds on this site depend on that override.

## Refusal and ordinary-link fallback

`resolveContentEmbed` returns no descriptor when the URL is empty, not a recognized provider, fails URL parsing, uses a non-http(s) scheme, or fails the internal-path checks. In content Markdown those cases stay ordinary links (or bare text), not frames.

| Input | Expected result |
| --- | --- |
| Supported YouTube / X status HTTPS URL | Provider embed frame |
| Site path `/en/docs/…/` without `..`, `\`, or control chars | Same-site internal embed |
| `//evil.example/` (protocol-relative) | Refused as internal path → no embed |
| `/../secret` or path segments containing `..` | Refused (`traversal`) |
| Path with control characters or `\` | Refused |
| `https://example.com/not-a-provider` | No resolver match → ordinary link |
| Inline link inside a sentence | Always stays a normal link |

Do not paste a rejected path into a live `::embed` on this page just to “prove” failure: the failure mode is “no embed,” not a special error chrome. Keep refusal cases in the source fence above, not as live frames.

## Keep surrounding prose as a link

Only a standalone supported URL or an explicit directive becomes an embed. A link inside a sentence remains a normal link:

```markdown
Read [the original post](https://x.com/arcblock_io/status/1955367769672950142) before continuing.
```

Rendered:

Read [the original post](https://x.com/arcblock_io/status/1955367769672950142) before continuing.

For the exact content-item and locale structure, see [Content objects, metadata, and locales](../content-and-objects/). This page documents recognized external providers and validated same-site paths; verify the security and trust boundary of a general `frame` against its target renderer before using one.

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-12` · `arc --version` → `2.0.0-beta.32` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `::embed` |
| Implementation | `providers/runtime/web-device/src/content-embed.ts` (`resolveContentEmbed`, `checkInternalEmbedPath`); `content-reader.ts` embed case |
| Site framing | `.web/security` → `frame-ancestors: "'self'"` for same-site iframes |
| Unit page | [embed](../markdown/embed/) |
| Public routes | `/en/docs/web-device/markdown-embeds/` · `/zh/docs/web-device/markdown-embeds/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · confirm YouTube + same-site frames; X may depend on third-party availability |
| Accept | Supported URLs frame (not blank); unsupported stay links; internal path stays same-site only |

---

## Write tables and callouts in Markdown

URL: https://www.arcblock.io/en/docs/web-device/markdown-gfm-callouts/

The Web Device content reader turns GFM tables and GitHub-style callouts in Markdown into document content. The source and result below use the same document-reading path. They are not a general AUP `table` or `text` primitive contract, and they do not imply that `format: markdown` inside an AUP page has the same result.

This page is a **live feature guide**. Unit pages: [gfm-table](../markdown/gfm-table/), [gfm-admonition](../markdown/gfm-admonition/).

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Author static GFM tables and admonition callouts in content Markdown |
| Boundaries | Not an editable grid; not AUP `table` node; not a chart fallback table; no write path |
| Author entry | Pipe tables · `> [!NOTE]`-style blockquotes in `content.md` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | Unknown admonition marker → ordinary blockquote; bare marker uses locale default title |
| Verification | Routes below · `arc --version` = `2.0.0-beta.32` |

## A GFM table

Source:

```markdown
| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |
```

Rendered:

| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |

This is a Markdown table handled by the content reader (often as HTML text in the document tree). It does not turn the table into editable data, establish an AFS data source, or prove the AUP primitive `table` path. Do not confuse an empty **chart** degradation table (`No data` / reshape) with this author-written GFM table.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Malformed pipes | Ordinary Markdown / broken table, not a runtime error surface |
| Empty body rows | Author content only — no automatic “No data” chrome from the chart chain |
| Assuming AUP `table` props | Wrong surface; write AUP JSON/DSL when you need that node |

## A GitHub-style callout

Source (custom title on the marker line):

```markdown
> [!IMPORTANT] This is a content-file capability
> Write this kind of callout in `content.md`. The page presents what the author wrote; it does not execute an action or modify data.
```

Rendered:

> [!IMPORTANT] This is a content-file capability
> Write this kind of callout in `content.md`. The page presents what the author wrote; it does not execute an action or modify data.

Bare markers (no same-line title) use the reader’s default label for the content locale. English keeps the English defaults from the text renderer; **zh** defaults are applied at read time:

| Marker | zh default title |
| --- | --- |
| `NOTE` | 说明 |
| `TIP` | 提示 |
| `IMPORTANT` | 重要 |
| `WARNING` | 警告 |
| `CAUTION` | 注意 |

An explicit same-line title always wins over the locale default, in any locale.

Source (bare marker — label comes from locale defaults):

```markdown
> [!TIP]
> Prefer a same-line custom title when the English word is not the label you want.
```

Rendered:

> [!TIP]
> Prefer a same-line custom title when the English word is not the label you want.

The current reader recognizes five markers: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION` (case-insensitive). An unknown marker remains an ordinary blockquote instead of becoming a different callout.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `[!FIXME]` or other unknown marker | Plain blockquote, not a callout chrome |
| Marker not on the first line of the quote | Not recognized as admonition |
| Expecting an editor or dismiss control | Static document content only |

GFM tables and callouts in content items are static document content. To author a runtime AUP tree, keep this document-reading path separate from the target-specific primitive support that its renderer defines. For the site-facing boundary, see [AUP layout boundary](../aup-reference/).

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-12` · `arc --version` → `2.0.0-beta.32` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · GFM admonition · GFM table |
| Implementation | `providers/runtime/web-device/src/content-reader.ts` (`ADMONITION_MARKER_RE`, `ADMONITION_LOCALIZED_LABELS`); text admonition renderer |
| Unit pages | [gfm-table](../markdown/gfm-table/) · [gfm-admonition](../markdown/gfm-admonition/) |
| Public routes | `/en/docs/web-device/markdown-gfm-callouts/` · `/zh/docs/web-device/markdown-gfm-callouts/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; on zh locale, bare markers show Chinese default titles |
| Accept | Source and rendered table/callout match; unknown marker stays a quote; no edit controls |

---

## Write and embed Markdown slides

URL: https://www.arcblock.io/en/docs/web-device/markdown-slides/

Use Slides when one explanation should work both as a document and as a short presentation. Each page remains ordinary Markdown content rendered by Web Device. Slides only paginate that content at explicit boundaries and add a player to the page; they do not introduce a separate canvas, component set, or content type.

This page is a **live feature guide** (how to author, mount, and embed a deck, with working samples below). Atomic structure contracts live under the Markdown unit pages: [`slides: true` front matter](../markdown/slides-front-matter/), [thematic break / HR](../markdown/thematic-break/), and [`::embed`](../markdown/embed/). Those unit pages are reference; this page is the runnable how-to.

This feature requires an ARC build that contains the Web Device `slides` widget. The segment reading form on this page — slide cards with narration, divider section titles, and `slidesLayout` — additionally requires a build that includes the article-segment transcript; on an older build those decks still render as the earlier linear transcript. The target runtime is the ARC service that will serve your site. Do not infer support from version labels on older documentation pages; verify that runtime before publishing a deck. See [Version compatibility](../version-compatibility/) for the evidence boundary.

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | One Markdown record as readable transcript + optional 16:9 player |
| Boundaries | No presenter view, PDF export skill, free-form canvas, or bundled slide theme; no document write from player controls |
| Author entry | Front matter `slides: true` + `layout: slides` (+ optional `slidesLayout`) · named `layouts/slides.aup` · same-site `::embed` |
| Surface | **slides** / document transcript; embed player on document pages |
| Public status | `released` when the serving ARC includes the slides widget |
| Fallback / failure | Without widget: server-rendered transcript only; without `slides: true`: ordinary article; bad `---` underlining fails build; unknown `slidesLayout` fails build |
| Verification | Demo routes below · authoring CLI `arc --version` = `2.0.0-beta.32`; **serving** runtime must still include the slides widget |

## Write a deck record

In the YAML front matter at the start of the Markdown content file you want to turn into a deck, set `slides: true`. That field makes top-level thematic breaks into slide boundaries. Set `layout: slides` separately to choose the named layout that mounts the player.

Source:

```markdown
---
title: A short technical explanation
slides: true
layout: slides
---

## Start with one idea

The first slide is an ordinary Markdown body.

---

## Continue on a new slide

- A list
- a table
- a code block
```

`slides: true` and `layout: slides` answer different questions. The first turns the body into a deck. The second selects `layouts/slides.aup`. A deck without the widget remains server-rendered, readable transcript content; it does not gain player controls. If the record has its own `layout.aup`, do not also set `layout: slides`: one record must choose one object layout.

## Mount the player once

Add the named layout at the site root. It supplies the player to any record that selects `layout: slides`.

Source: `layouts/slides.aup`

```aup
page slides {
  view root {
    detail-content body slot=content
    widget deck name=slides target=".aup-deck"
  }
}
```

`detail-content` keeps the transcript inside the normal readable content area. The `slides` widget inserts a 16:9 player above that transcript. It uses the site's existing visual tokens — such as colors, type, and spacing — rather than a bundled slide theme, so you do not add separate deck styling to this record.

## Allow same-site embeds (required for in-page players)

ARC’s default security headers set `Content-Security-Policy: frame-ancestors 'none'`. That blocks **every** iframe, including same-origin deck embeds. A site that uses `::embed` for decks must override framing for itself.

Source: `.web/security`

```yaml
# Allow this site to frame its own pages (Markdown Slides embeds, internal frames).
frame-ancestors: "'self'"
```

Without this file, top-level deck pages still work, but article/doc embeds render as a blank frame. This site ships the override; copy the same shape when you enable Slides on another site.

## Inspect a live deck

In the Markdown file for a page that should show a deck, add this directive and replace its `url` with the site-absolute path of your published deck. The following same-site record is this guide's demo source.

Source:

```markdown
::embed{url="/en/docs/web-device/slides-demo/"}
```

Rendered:

::embed{url="/en/docs/web-device/slides-demo/"}

Before the Slides widget initializes, the server-rendered transcript remains part of the frame. After initialization, the fixed 16:9 frame presents the player as its visible surface. Open [the demo as its own page](../slides-demo/) to inspect the default player plus readable transcript. The document and its source remain read-only; player controls only change browser-local presentation state and never write the document or its source.

## Put two decks on one page

A page is not limited to one embedded deck. Add one directive for each same-site route. This guide uses a short interaction demo and a separate overview deck, so the two players have different content and different slide counts.

Source:

```markdown
::embed{url="/en/docs/web-device/slides-demo/"}

::embed{url="/en/docs/web-device/slides-overview/"}
```

Rendered:

::embed{url="/en/docs/web-device/slides-demo/"}

::embed{url="/en/docs/web-device/slides-overview/"}

Each directive creates its own same-site frame. Moving the first player does not move the second one. Its slide fragment and `?full` presentation mode belong to that deck's frame, so either player can be used or opened fullscreen without advancing or opening the other player. The directive has no one-deck-per-page limit. Keep every route intentional, because every embedded player still loads a real page.

## Add speaker notes and page breaks

An HTML comment that occupies its own Markdown block becomes a speaker note. In the reading form the notes are the article: each slide renders as a scaled slide card, and its notes render beside or below that card as narration prose. Blank lines inside a note become paragraph breaks. Notes never appear on the projected slide. Write them as the sentences you would say over that slide, and the transcript reads the way a talk write-up reads.

Source:

```markdown
## Explain the boundary

<!--
Pause before the example.

A second paragraph, split on the blank line.
-->

---

## Show the example
```

You can use `---`, `***`, `___`, or `- - -` as a slide boundary. A deck cannot use these top-level thematic breaks as decorative horizontal rules. Put a blank line before `---`: without it, Markdown can read the dashes as a heading underline and the build rejects the deck. A ruler inside a fenced code block remains code, not a boundary.

## Break a long deck into sections

A page whose content is exactly one `#` (level-1) heading is a divider. In the player it is a normal title page; in the reading form it renders as a section title between segments instead of a slide card. Use `#` only for dividers and `##` for ordinary slide titles, and a long deck stops reading as one uniform list. A `#` heading with anything else on the page — a subtitle paragraph, an image — remains an ordinary slide. A divider may still carry a speaker note; that note renders full-width under the section title.

Source:

```markdown
# Part one: why

---

## The problem
```

## Choose a reading-form layout

`slidesLayout` front matter picks how each segment arranges the slide card and its notes. One value per deck. Every card is the same size whether or not its slide has notes, so the page stays even.

| `slidesLayout` | Arrangement |
| --- | --- |
| `side` *(default)* | card left · notes right |
| `side-reverse` | notes left · card right |
| `stacked` | full-width card · notes under it |
| `stacked-reverse` | notes first · full-width card under them |

Source:

```markdown
---
title: A short technical explanation
slides: true
layout: slides
slidesLayout: stacked
---
```

On a narrow screen both `side` modes collapse to the vertical arrangement and keep the author's order: `side` shows the card first, `side-reverse` shows the notes first. An unknown `slidesLayout` value fails the build and lists the valid values; it never falls back silently.

## Read, present, and share

The default page keeps an inline player above the transcript. Use the previous and next controls to move the player without changing the page mode. Each transcript card is a control: click it — or the **Play from here** button revealed when the pointer is over the card, or when the button has keyboard focus — to move the player to that slide and scroll it into view without switching the page to presentation mode. In inline reading mode, the player accepts arrow keys, PageUp/PageDown, Space, Home, and End only while it has focus; reading the transcript does not hijack those keys. In presentation mode, the deck owns those keys until you leave that mode. On a touch device, swipe the stage to move between slides.

Use the fullscreen control, `f` while the player has focus, or `?full` in the URL to enter presentation mode. A slide fragment uses its first heading when there is one; a heading-less slide falls back to its one-based page number, and repeated headings receive a stable numeric suffix. For example, the heading `## Keep the player in the page` in the demo becomes `#slide-keep-the-player-in-the-page`, so `/en/docs/web-device/slides-demo/?full#slide-keep-the-player-in-the-page` opens that page in presentation mode. You can also navigate to a slide and copy the browser address. On an initial page load, an unknown fragment starts at the first slide; changing an already-open player to an unknown fragment leaves its current slide in place.

This guide documents the current player and transcript contract. It does not provide a presenter view, PDF export workflow, authoring skill, free-form positioned canvas, or a bundled presentation theme.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `slides: true` without slides widget in serving ARC | Readable transcript; no player chrome |
| `layout: slides` missing while `slides: true` | Deck semantics may exist without the named player mount |
| `slidesLayout` with an unknown value | Build rejects the deck, listing the valid values |
| `---` without a blank line after a heading | Treated as setext underline; build rejects the deck |
| Thematic break inside a fenced code block | Remains code, not a slide boundary |
| External `::embed` URL | Not a same-site deck player; follow [embeds](../markdown-embeds/) refusal rules |
| Same-site embed with default `frame-ancestors 'none'` | Blank iframe; set `.web/security` `frame-ancestors: "'self'"` |

## Unit contracts (reference)

| Topic | Unit page |
| --- | --- |
| `slides: true` | [slides front matter](../markdown/slides-front-matter/) |
| Page breaks (`---`) | [thematic break / HR](../markdown/thematic-break/) |
| `::embed` directive | [embed](../markdown/embed/) |
| Full Markdown index | [Markdown units hub](../markdown/) |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline (authoring CLI) | `2026-08-12` · `arc --version` → `2.0.0-beta.32` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `slides: true` · `deck` widget |
| Implementation | `providers/runtime/web-device/src/slides.ts`; `widgets/slides/`; site `layouts/slides.aup` |
| Site framing | `.web/security` → `frame-ancestors: "'self'"` (required for embeds) |
| Guide routes | `/en/docs/web-device/markdown-slides/` · `/zh/docs/web-device/markdown-slides/` |
| Live deck routes | `/en/docs/web-device/slides-demo/` · `/en/docs/web-device/slides-overview/` · [AUP capability tour](/en/docs/aup/capability-tour-slides/) (and zh counterparts) |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open guide embeds + demo page; try narrow width and `?full` |
| Accept | Embed shows player when widget loads (not a blank frame); controls stay browser-local; no document write |

For a full document-surface AUP walk that uses this slides host (18 primitives, Markdown surface, deck media host): [AUP capability tour](/en/docs/aup/capability-tour-slides/). For the exact boundary on the embed directive, see [Embed external and internal content](../markdown-embeds/). For the named-layout convention beyond Slides, see [Compose pages and layouts](../pages-layouts/) and the [directory reference](../directory-reference/).

---

## Write step-by-step guides in Markdown

URL: https://www.arcblock.io/en/docs/web-device/markdown-steps/

`steps` and `step` organize Markdown as a numbered tutorial. They present static content written by the author. A step has no action, data binding, or write behavior of its own.

This page is a **live feature guide**. Unit pages: [steps](../markdown/steps/), [step](../markdown/step/).

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static numbered tutorial structure in content Markdown |
| Boundaries | Static-only: no run-button, no bind, no write; not a cross-device primitive promise |
| Author entry | `::::steps` wrapping `:::step{title=…}` containers |
| Surface | Web Device **document** → `view` with `mode=steps` |
| Public status | `released` |
| Fallback / failure | Wrong fence depth drops or misparses body; `::step` leaf cannot hold content |
| Verification | Routes below · `arc --version` = `2.0.0-beta.32` |

## Start with the fence rule

A `step` needs a body, so it must be a container directive with at least three colons. The wrapping `steps` directive uses one more. A two-colon `::step` is a leaf directive with no body and cannot hold step content.

Source:

`````markdown
::::steps
:::step{title="Define the content boundary"}
Say what the page presents, and what it does not execute.
:::

:::step{title="Place source above the result"}
Let the reader see both the Markdown and its actual output.
:::

:::step{title="Inspect it in a browser"}
Confirm that the numbering, text, and narrow-screen layout all render normally.
:::
::::
`````

Rendered:

::::steps
:::step{title="Define the content boundary"}
Say what the page presents, and what it does not execute.
:::

:::step{title="Place source above the result"}
Let the reader see both the Markdown and its actual output.
:::

:::step{title="Inspect it in a browser"}
Confirm that the numbering, text, and narrow-screen layout all render normally.
:::
::::

A step body can include ordinary Markdown blocks such as paragraphs, lists, code blocks, or GitHub-style callouts. The outer `steps` fence must have more colons than the deepest nested container, otherwise the parser reads the fence as a different directive structure.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `::step{title="…"}` leaf (two colons) | No body; not a usable step |
| Outer `:::steps` with nested `:::step` (same depth) | Misparsed structure; body may be lost |
| Expecting a “Run this step” control | Out of contract — steps are static presentation |
| Narrow viewport | Numbering and text remain readable as document content |

`steps` is a Web Device document structure produced by the content reader. It is not a separate cross-device AUP primitive promise. For the Web layout boundary in this site, see [AUP layout boundary](../aup-reference/).

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-12` · `arc --version` → `2.0.0-beta.32` |
| Capability row | `docs/aup/capability-matrix.md` (internal, non-routed) · `::::steps` / `:::step` |
| Implementation | `providers/runtime/web-device/src/content-reader.ts` (`stepsDirectiveToAup`); `renderer/primitives/view.ts` (`mode=steps`) |
| Unit pages | [steps](../markdown/steps/) · [step](../markdown/step/) |
| Public routes | `/en/docs/web-device/markdown-steps/` · `/zh/docs/web-device/markdown-steps/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · desktop + ~390px |
| Accept | Numbered steps match source titles/bodies; no action/write chrome |

---

## `:::action-card`

URL: https://www.arcblock.io/en/docs/web-device/markdown/action-card/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Card that nests navigation-only `::action` nodes |
| Boundaries | Nested `::action` is not general `exec` permission; document stays read-only for site content |
| Author entry | `:::action-card{…}` with nested `::action` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | Unsafe action `href` rejected; fence depth errors drop nested actions |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Sample

Source:

````markdown
:::action-card{title="Continue reading" description="Place several navigation choices in one card" icon="book"}
::action{label="Read the AUP layout boundary" href="/en/docs/web-device/aup-reference/" variant="primary"}
::action{label="Browse components hub" href="/en/docs/web-device/components/" variant="secondary"}
:::
````

Rendered:

:::action-card{title="Continue reading" description="Place several navigation choices in one card" icon="book"}
::action{label="Read the AUP layout boundary" href="/en/docs/web-device/aup-reference/" variant="primary"}
::action{label="Browse components hub" href="/en/docs/web-device/components/" variant="secondary"}
:::

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Expecting `exec` or form submit | Out of contract |
| Nested `::action` without `href` | Non-link action chrome |
| Outer fence too shallow | Nested actions may drop |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `:::action-card` |
| Implementation | `content-reader.ts` · nested generic `::action` |
| Public routes | `/en/docs/web-device/markdown/action-card/` · `/zh/docs/web-device/markdown/action-card/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · clicks navigate only |
| Accept | Actions navigate; no write/`exec`; source matches card |

## Related

- [Markdown hub](../) — navigation only
- [AUP `action` primitive](../../../aup/primitives/action/)
- Historical multi-unit hub: [markdown-cards](../../markdown-cards/)

---

## `::::card-group`

URL: https://www.arcblock.io/en/docs/web-device/markdown/card-group/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Lay out nested cards in a document grid |
| Boundaries | Outer fence must be deeper than nested containers; not a layout-component API |
| Author entry | `::::card-group` wrapping card directives |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | Without group, cards render individually; fence depth errors collapse structure |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Sample

The outer fence needs one more colon than nested containers. With leaf `::link-card` children, four colons are sufficient:

Source:

```markdown
::::card-group
::link-card{title="Content objects" description="Review content and metadata" href="/en/docs/web-device/content-and-objects/" icon="book"}
::link-card{title="AUP boundary" description="See the difference between page layout and an AUP tree" href="/en/docs/web-device/aup-reference/" icon="layout"}
::::
```

Rendered:

::::card-group
::link-card{title="Content objects" description="Review content and metadata" href="/en/docs/web-device/content-and-objects/" icon="book"}
::link-card{title="AUP boundary" description="See the difference between page layout and an AUP tree" href="/en/docs/web-device/aup-reference/" icon="layout"}
::::

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Outer fence too shallow | Parser misreads children; group/cards may collapse |
| Empty group | Empty grid chrome / no cards |
| Expecting layout `.web` component props | Wrong surface |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `::::card-group` |
| Implementation | `content-reader.ts` · arc#2454 · docs-page CSS |
| Public routes | `/en/docs/web-device/markdown/card-group/` · `/zh/docs/web-device/markdown/card-group/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes |
| Accept | Group lays out nested cards; clicks navigate only |

## Related

- [Markdown hub](../) — navigation only
- Sibling cards: [link-card](../link-card/) · [info-card](../info-card/) · [action-card](../action-card/)
- Historical multi-unit hub: [markdown-cards](../../markdown-cards/)

---

## `::embed`

URL: https://www.arcblock.io/en/docs/web-device/markdown/embed/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Embed a supported external or same-site URL in content Markdown |
| Boundaries | Providers limited (YouTube, X/Twitter status, validated same-site); not a general iframe API |
| Author entry | `::embed{url=…}` or standalone recognized URL |
| Surface | Web Device **document** (partial frame path) |
| Public status | `released` |
| Fallback / failure | Unrecognized or refused URL → ordinary link / no embed descriptor |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Sample

Source:

```markdown
::embed{url="https://youtu.be/jNQXAC9IVRw"}
```

Rendered:

::embed{url="https://youtu.be/jNQXAC9IVRw"}

The current renderer turns this supported URL into a responsive, lazy-loaded, sandboxed third-party iframe. Unrecognized URLs stay ordinary links.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Unrecognized host / URL shape | Ordinary link; no embed chrome |
| Expecting arbitrary iframe with full privileges | Out of contract (`allowSameOrigin` / whitelist rules apply elsewhere) |
| Same-site path not validated | Refused or link fallback |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `::embed` · widget `frame` |
| Implementation | `content-reader.ts` · `content-embed.ts` (youtube / twitter / internal) · `renderer/primitives/frame.ts` |
| Public routes | `/en/docs/web-device/markdown/embed/` · `/zh/docs/web-device/markdown/embed/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; refuse path stays link |
| Accept | Supported URL embeds; unsupported stays link; no general iframe claim |

## Related

- [Markdown hub](../) — navigation only
- Historical multi-unit hub: [markdown-embeds](../../markdown-embeds/)

---

## fenced code

URL: https://www.arcblock.io/en/docs/web-device/markdown/fenced-code/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

Fenced code blocks as document text/code nodes.

## Boundaries

- One unit per page: this page documents **only** `fenced-code`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

triple-backtick fences

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`released`

## Fallback

—

## Sample

````markdown
```bash
arc --version
```
````

Static presentation only — the fence does not execute commands.

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-structure` · `fenced-code` |

## Notes

Static code presentation only.

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../content-markdown/

---

## Generic MD directive (incl. `::input`)

URL: https://www.arcblock.io/en/docs/web-device/markdown/generic-directive/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

Any `::name` / `:::name` maps to a document node with `type=name`. Known released subset includes unbound `::input`.

## Boundaries

- One unit per page: this page documents **only** `generic-directive`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

arbitrary `::name` / `:::name` · released path: `::input{…}`

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`experimental (generic); `::input` released subset`

## Fallback

Unknown type → `renderUnknown`.

## Sample

Released subset — unbound `::input` is covered under the AUP live-example contract:

- [Live examples: scope and contract](../../../aup/live-example-contract/)

Other generic directive names are experimental until a docs-safe sample and matrix row say otherwise. `::chart` is **not** defined.

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` generic path · arc#2598 · live-example-contract (input) |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-directive` · `generic-directive` |

## Notes

Do not publish unverified generic names as product capabilities. MD `::chart` is **not** defined (unsupported).

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../../aup/live-example-contract/

---

## GFM admonition

URL: https://www.arcblock.io/en/docs/web-device/markdown/gfm-admonition/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Author static GFM admonition callouts in content Markdown |
| Boundaries | Not editable; not AUP `text` full props; no write path |
| Author entry | `> [!NOTE]`-style blockquotes in `content.md` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | Unknown marker → ordinary blockquote; bare marker uses locale default title |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Purpose

GitHub-style callouts from `> [!NOTE]` (and TIP/IMPORTANT/WARNING/CAUTION) blockquotes.

## Sample

Source (custom title on the marker line):

```markdown
> [!IMPORTANT] This is a content-file capability
> Write this kind of callout in `content.md`. The page presents what the author wrote; it does not execute an action or modify data.
```

Rendered:

> [!IMPORTANT] This is a content-file capability
> Write this kind of callout in `content.md`. The page presents what the author wrote; it does not execute an action or modify data.

Bare markers (no same-line title) use the reader’s default label for the content locale. English keeps English defaults; **zh** defaults are applied at read time:

| Marker | zh default title |
| --- | --- |
| `NOTE` | 说明 |
| `TIP` | 提示 |
| `IMPORTANT` | 重要 |
| `WARNING` | 警告 |
| `CAUTION` | 注意 |

Source (bare marker):

```markdown
> [!TIP]
> Prefer a same-line custom title when the English word is not the label you want.
```

Rendered:

> [!TIP]
> Prefer a same-line custom title when the English word is not the label you want.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `[!FIXME]` or other unknown marker | Plain blockquote, not a callout chrome |
| Marker not on the first line of the quote | Not recognized as admonition |
| Expecting an editor or dismiss control | Static document content only |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · GFM admonition |
| Implementation | `content-reader.ts` (`ADMONITION_MARKER_RE`, `ADMONITION_LOCALIZED_LABELS`); text admonition renderer |
| Public routes | `/en/docs/web-device/markdown/gfm-admonition/` · `/zh/docs/web-device/markdown/gfm-admonition/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes; on zh locale bare markers show Chinese defaults |
| Accept | Source and rendered callout match; unknown marker stays a quote; no edit controls |

## Related

- [Markdown hub](../) — navigation only
- [AUP `text` primitive](../../../aup/primitives/text/)
- Historical multi-unit hub: [markdown-gfm-callouts](../../markdown-gfm-callouts/)

---

## GFM table

URL: https://www.arcblock.io/en/docs/web-device/markdown/gfm-table/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Author static GFM tables in content Markdown |
| Boundaries | Not an editable grid; not AUP `table` node; not a chart fallback table; no write path |
| Author entry | Pipe tables in `content.md` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | Malformed pipes → ordinary Markdown / broken table |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Purpose

Pipe tables in content Markdown rendered on the document path.

## Sample

Source:

```markdown
| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |
```

Rendered:

| File | Purpose | Writes data |
| --- | --- | --- |
| `content.md` | Content item | No |
| `layout.aup` | Page layout | No |

This is a Markdown table handled by the content reader. It does not turn the table into editable data, establish an AFS data source, or prove the AUP primitive `table` path. Do not confuse an empty **chart** degradation table with this author-written GFM table.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Malformed pipes | Ordinary Markdown / broken table, not a runtime error surface |
| Empty body rows | Author content only — no automatic “No data” chrome from the chart chain |
| Assuming AUP `table` props | Wrong surface; write AUP JSON/DSL when you need that node |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · GFM table |
| Implementation | `content-reader.ts` (table case) |
| Public routes | `/en/docs/web-device/markdown/gfm-table/` · `/zh/docs/web-device/markdown/gfm-table/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes |
| Accept | Source and rendered table match; no edit controls; no chart claim |

## Related

- [Markdown hub](../) — navigation only
- [AUP `table` primitive](../../../aup/primitives/table/)
- Historical multi-unit hub: [markdown-gfm-callouts](../../markdown-gfm-callouts/)

---

## heading

URL: https://www.arcblock.io/en/docs/web-device/markdown/heading/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

ATX/setext headings become document text nodes with level props.

## Boundaries

- One unit per page: this page documents **only** `heading`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

`#` / setext headings

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`released`

## Fallback

—

## Sample

```markdown
## Section title
```

Headings also feed the [in-page-toc](../../surfaces/in-page-toc/) surface when the docs shell mounts it.

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-structure` · `heading` |

## Notes

Also feeds in-page TOC surfaces.

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../content-markdown/

---

## image (inline)

URL: https://www.arcblock.io/en/docs/web-device/markdown/image/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

Inline images `![alt](src)` become document img nodes.

## Boundaries

- One unit per page: this page documents **only** `image`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

`![alt](src)`

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`released`

## Fallback

—

## Sample

```markdown
![Alt text](/path/to/image.png)
```

Inline images are not the AUP `media` node path.

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` (inline → img) |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-structure` · `image` |

## Notes

Different path from AUP `media` node.

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../content-markdown/

---

## `:::info-card`

URL: https://www.arcblock.io/en/docs/web-device/markdown/info-card/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static info card with optional body |
| Boundaries | Not a link; `href` ignored; no `exec` or write |
| Author entry | `:::info-card{title=… description=…}` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | `href` ignored for navigation |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Sample

Source:

````markdown
:::info-card{title="A read-only example" description="Content and layout are maintained separately"}
The body can contain paragraphs, lists, and code.

- A content item owns the reader-facing text
- `layout.aup` decides how a page organizes those items
:::
````

Rendered:

:::info-card{title="A read-only example" description="Content and layout are maintained separately"}
The body can contain paragraphs, lists, and code.

- A content item owns the reader-facing text
- `layout.aup` decides how a page organizes those items
:::

An `info-card` is not a link. Even if an author supplies an `href`, the current content reader does not promote it to a clickable card.

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `href` on `info-card` | Ignored for navigation |
| Expecting click-through card | Use `link-card` instead |
| Outer fence too shallow for body | Body may drop / misparse |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `:::info-card` |
| Implementation | `content-reader.ts` · arc#2546 |
| Public routes | `/en/docs/web-device/markdown/info-card/` · `/zh/docs/web-device/markdown/info-card/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes |
| Accept | Body renders; card is not a link; no write path |

## Related

- [Markdown hub](../) — navigation only
- Sibling cards: [link-card](../link-card/) · [action-card](../action-card/) · [card-group](../card-group/)
- Historical multi-unit hub: [markdown-cards](../../markdown-cards/)

---

## `::link-card`

URL: https://www.arcblock.io/en/docs/web-device/markdown/link-card/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Navigation card in content Markdown |
| Boundaries | Navigation only; no `exec`, AFS write, or session; not a `.web` component API |
| Author entry | `::link-card{title=… description=… href=… icon=…}` |
| Surface | Web Device **document** (static) |
| Public status | `released` |
| Fallback / failure | No safe `href` → non-link card chrome |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Sample

Source:

```markdown
::link-card{title="Web Device overview" description="Review the site structure and its boundary" href="/en/docs/web-device/overview/" icon="book"}
```

Rendered:

::link-card{title="Web Device overview" description="Review the site structure and its boundary" href="/en/docs/web-device/overview/" icon="book"}

Source without `href` (not a navigation target):

```markdown
::link-card{title="Not a link" description="Missing href stays non-interactive chrome"}
```

Rendered:

::link-card{title="Not a link" description="Missing href stays non-interactive chrome"}

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Missing `href` | Non-link presentation |
| Unsafe `href` scheme | Not promoted as a safe navigation target |
| Expecting `exec` or form submit | Out of contract |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `::link-card` |
| Implementation | `content-reader.ts` · `contentCardToAup` |
| Public routes | `/en/docs/web-device/markdown/link-card/` · `/zh/docs/web-device/markdown/link-card/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · click link-card → ordinary navigation only |
| Accept | Source matches card; missing `href` is not a link; no write/`exec` |

## Related

- [Markdown hub](../) — navigation only
- Sibling cards: [info-card](../info-card/) · [action-card](../action-card/) · [card-group](../card-group/)
- Historical multi-unit hub: [markdown-cards](../../markdown-cards/)

---

## list

URL: https://www.arcblock.io/en/docs/web-device/markdown/list/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

Unordered and ordered lists on the document path.

## Boundaries

- One unit per page: this page documents **only** `list`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

ul / ol Markdown lists

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`released`

## Fallback

—

## Sample

```markdown
- Item one
- Item two

1. First
2. Second
```

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-structure` · `list` |

## Notes

Core list path.

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../content-markdown/

---

## paragraph

URL: https://www.arcblock.io/en/docs/web-device/markdown/paragraph/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

Markdown paragraphs as document text; standalone recognized links may promote to embeds.

## Boundaries

- One unit per page: this page documents **only** `paragraph`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

ordinary paragraphs

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`released`

## Fallback

Standalone link may promote via `resolveStandaloneLinkEmbed`.

## Sample

Ordinary paragraphs are the default prose path. A standalone recognized URL line may promote to an [embed](../embed/) via `resolveStandaloneLinkEmbed`.

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-structure` · `paragraph` |

## Notes

Core prose path.

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../content-markdown/

---

## raw HTML

URL: https://www.arcblock.io/en/docs/web-device/markdown/raw-html/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

Implementation path: content-reader / slides / embed modules under `providers/runtime/web-device/src/`.

## Purpose

HTML blocks in content Markdown under a restricted document path.

## Boundaries

- One unit per page: this page documents **only** `raw-html`.
- Do not treat MD structures as AUP primitive contracts (`table`, `media`, …).
- Experimental or unverified names must not be published as full product capability.

## Author entry

HTML block in Markdown

## Surfaces

Web Device **document** (and slides path where noted).

## Public status

`experimental`

## Fallback

Unsafe paths stripped or ignored.

## Sample

No docs-safe live sample. Unsafe HTML paths are stripped or ignored. Do not treat raw HTML as a product-ready host for arbitrary scripts.

## Evidence

| Item | Path |
| --- | --- |
| Reader / impl | `content-reader.ts` |
| Internal matrix | `docs/aup/capability-matrix.md` §6 (internal, non-routed) |
| Matrix row concept | `md-structure` · `raw-html` |

## Notes

Do not treat as a general HTML host promise. Experimental; no docs-safe sample.

## Related

- [Markdown hub](../) — navigation only
- [Content Markdown guide](../../content-markdown/)
- Historical multi-unit page (thin hub): ../content-markdown/

---

## `slides: true` front matter

URL: https://www.arcblock.io/en/docs/web-device/markdown/slides-front-matter/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | YAML flag that turns top-level HR breaks into slide boundaries and mounts the slides player path |
| Boundaries | Without flag → ordinary article; without widget → server transcript only; not a free-form canvas |
| Author entry | `slides: true` (+ often `layout: slides`) + HR boundaries |
| Surface | Web Device **slides** / document embed player |
| Public status | `released` |
| Fallback / failure | No flag → ordinary prose separators; no widget → transcript only |
| Verification | Routes below · demo page · `arc --version` = `2.0.0-beta.28` |

## Sample

Author front matter on a content record:

```markdown
---
title: A short technical explanation
slides: true
layout: slides
---

## Start with one idea

The first slide is an ordinary Markdown body.

---

## Continue on a new slide

- A list
- a table
```

This documentation page **does not** flip itself into a deck (the page is a reference, not the slides record). Live player (when the serving runtime includes the slides widget): [Slides demo](../../slides-demo/).

A deck may add the sibling key `slidesLayout` (`side` · `side-reverse` · `stacked` · `stacked-reverse`) to pick how the reading form arranges each slide card and its notes; the default is `side`. On a serving runtime that includes the segment reading form, an unknown value fails the build. The full layout contract, including the narrow-screen fallback and divider pages, lives in the [markdown-slides guide](../../markdown-slides/).

Pair structure: [thematic-break / HR](../thematic-break/).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Missing `slides: true` | Ordinary article; HR is a separator only |
| Slides flag without widget mount | Server-side transcript / incomplete player chrome |
| `slidesLayout` with an unknown value | Build rejects the deck, listing the valid values |
| Expecting free canvas editing | Out of contract |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `slides: true` front matter · widget `deck` |
| Implementation | `slides.ts` · `SLIDES_FRONT_MATTER_FIELD` · `widgets/slides` · `renderer/primitives/deck.ts` |
| Public routes | `/en/docs/web-device/markdown/slides-front-matter/` · `/zh/docs/web-device/markdown/slides-front-matter/` · demo `/en/docs/web-device/slides-demo/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open reference + demo |
| Accept | Source shows flag+HR contract; demo (if widget present) plays slides; no canvas claim |

## Related

- [Markdown hub](../) — navigation only
- [thematic-break](../thematic-break/)
- Historical multi-unit hub: [markdown-slides](../../markdown-slides/)

---

## `:::step`

URL: https://www.arcblock.io/en/docs/web-device/markdown/step/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Single step container inside `::::steps` |
| Boundaries | Must nest under `::::steps`; leaf `::step` cannot hold a body |
| Author entry | `:::step{title=…}` nested under `::::steps` |
| Surface | Web Device **document** (child view of steps) |
| Public status | `released` |
| Fallback / failure | Outside steps → no full steps chrome; wrong fence → empty body |
| Verification | Pair page [steps](../steps/) · `arc --version` = `2.0.0-beta.28` |

## Sample

`:::step` only has meaning inside `::::steps`. Full fence rule and live render:

Source (must be nested):

`````markdown
::::steps
:::step{title="One unit, one body"}
This body is a step item. It is not a free-standing tutorial primitive.
:::
::::
`````

Rendered:

::::steps
:::step{title="One unit, one body"}
This body is a step item. It is not a free-standing tutorial primitive.
:::
::::

See also the fuller multi-step sample on [steps](../steps/).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| `:::step` without outer `::::steps` | No complete steps contract |
| Leaf `::step` | Cannot hold a body |
| Missing `title` | Step still may render; title chrome omitted |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `:::step` |
| Implementation | `content-reader.ts` (child name `step`) · `stepsDirectiveToAup` |
| Public routes | `/en/docs/web-device/markdown/step/` · `/zh/docs/web-device/markdown/step/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open this page and [steps](../steps/) |
| Accept | Nested step body renders inside steps chrome |

## Related

- [Markdown hub](../) — navigation only
- Container unit: [steps](../steps/)
- Historical multi-unit hub: [markdown-steps](../../markdown-steps/)

---

## `::::steps`

URL: https://www.arcblock.io/en/docs/web-device/markdown/steps/

**Web Device Markdown directive — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Static numbered tutorial container on document |
| Boundaries | Static only — no run button, bind, or write; outer fence deeper than nested `step` |
| Author entry | `::::steps` wrapping `:::step` children |
| Surface | Web Device **document** (renders as `view` mode `steps`) |
| Public status | `released` |
| Fallback / failure | Wrong fence depth drops or misparses body; non-`step` children skipped |
| Verification | Routes below · `arc --version` = `2.0.0-beta.28` |

## Sample

Outer fence needs more colons than nested containers.

Source:

`````markdown
::::steps
:::step{title="Define the content boundary"}
Say what the page presents, and what it does not execute.
:::

:::step{title="Place source above the result"}
Let the reader see both the Markdown and its actual output.
:::
::::
`````

Rendered:

::::steps
:::step{title="Define the content boundary"}
Say what the page presents, and what it does not execute.
:::

:::step{title="Place source above the result"}
Let the reader see both the Markdown and its actual output.
:::
::::

### Failure and limits

| Situation | Expected result |
| --- | --- |
| Outer fence too shallow | Structure misread; steps may drop |
| `:::step` outside `::::steps` | No full steps chrome contract on this page |
| Expecting executable run buttons | Out of contract |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · `::::steps` |
| Implementation | `content-reader.ts` · `stepsDirectiveToAup` · `renderer/primitives/view.ts` |
| Public routes | `/en/docs/web-device/markdown/steps/` · `/zh/docs/web-device/markdown/steps/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open routes |
| Accept | Numbered static steps render; no execution controls |

## Related

- [Markdown hub](../) — navigation only
- Pair unit: [step](../step/)
- [AUP `view` primitive](../../../aup/primitives/view/)
- Historical multi-unit hub: [markdown-steps](../../markdown-steps/)

---

## thematicBreak / HR

URL: https://www.arcblock.io/en/docs/web-device/markdown/thematic-break/

**Web Device Markdown structure — not an AUP primitive; not a theme/site layout component.**

## Sample contract

| Field | Value |
| --- | --- |
| Purpose | Horizontal rules as ordinary separators; under `slides: true`, top-level breaks become slide boundaries |
| Boundaries | Without `slides: true` → ordinary separator only |
| Author entry | `---` |
| Surface | Web Device **document** · slides when flagged |
| Public status | `released` |
| Fallback / failure | No slides flag → prose separator |
| Verification | This page + [slides-front-matter](../slides-front-matter/) · `arc --version` = `2.0.0-beta.28` |

## Sample

In ordinary content, a thematic break is a horizontal rule:

Source:

```markdown
Above the break.

---

Below the break.
```

Rendered:

Above the break.

---

Below the break.

With `slides: true` in front matter, top-level `---` becomes a slide boundary. See [slides front matter](../slides-front-matter/) and the [slides demo](../../slides-demo/).

### Failure and limits

| Situation | Expected result |
| --- | --- |
| HR without slides flag | Ordinary separator |
| Nested/context HR inside containers | Not a top-level slide boundary |
| Expecting free-form page breaks for layout components | Wrong surface |

## Verification evidence

| Item | Value |
| --- | --- |
| Baseline | `2026-08-09` · `arc --version` → `2.0.0-beta.28` |
| Capability row | `docs/aup/capability-matrix.md` §6 · thematicBreak / HR |
| Implementation | `content-reader.ts` · `slides.ts` |
| Public routes | `/en/docs/web-device/markdown/thematic-break/` · `/zh/docs/web-device/markdown/thematic-break/` |
| Local run | `arc service start --blocklet blocklets/arcblock --port 4900` · open this page and slides demo |
| Accept | Ordinary HR renders; slides path documented honestly |

## Related

- [Markdown hub](../) — navigation only
- [slides-front-matter](../slides-front-matter/)
- Historical multi-unit hub: [markdown-slides](../../markdown-slides/)

---

## Folder-backed media gallery (`::gallery`)

URL: https://www.arcblock.io/en/docs/web-device/media-gallery/

Put image (and video) files in a folder under the content item, then declare a gallery in Markdown. The runtime expands `::gallery` into a static media block. Media stays with the item; you do not publish a separate CDN catalog for the set.

Requires a Web Device runtime that includes gallery folder expand (arc#3676 / `::gallery{folder}`). If the directive does not expand, upgrade the serving ARC build before treating samples as broken.

## Minimal example

```markdown
::gallery{folder="media" layout="grid" cols="3"}
```

1. Create `media/` next to this content object's `content.md` (or another relative folder under the item).
2. Drop image files into that folder (`jpg`, `jpeg`, `png`, `webp`, `gif`, `avif`, `svg`; video: `mp4`, `webm`).
3. Name files so lexicographic order matches the intended sequence (`01-…`, `02-…`).
4. Render the content object; the directive expands to a media-gallery block.

This page keeps its samples in `./media/` so the images ship with the repo (no external URLs).

## Parameters

| Attribute | Values | Default | Notes |
| --- | --- | --- | --- |
| `folder` | item-relative path | — (required) | Resolved under the content item directory. `..` and absolute URLs are rejected. |
| `layout` | see table below | `large` | Presentation mode for the same folder. |
| `cols` / `columns` | `2`–`6` | `3` when layout is `grid` | Only applied to `layout=grid`. |
| `lightbox` | `true` / `false` | **on** for browse layouts; **off** for `large`, `stage`, `story` | Click opens a fullscreen dialog; ←/→ stay inside **this** gallery. |
| `intro` / `lede` | `true` / `false` | **off** for browse layouts; **on** for `large` / `stage` / `story` | Optional folder `content.md` title + body as a lede. |
| `ratio` | `1:1`, `16/9`, `4x3`, `square`, … | — | CSS `aspect-ratio` for sized plates. Aliases: `aspect`, `aspectRatio`. |
| `width` / `w` | CSS length (`24rem`, `100%`, `min(100%,36rem)`, bare number → px) | with only `ratio`: `min(100%,36rem)` | Plate width. Rejects injection-like strings. |
| `height` / `h` | CSS length (`50vh`, `400px`, …) | — | Plate height. Use alone or with `ratio` / `width`. |

Layout aliases: `expose` / `slideshow` → `stage`; `magazine` → `story`; `diptych` / `two` → `pair`; `bento` / `hero-grid` → `mosaic`; `contact` / `sheet` / `thumb` → `film`.

### Sized plates (`ratio` · `width` · `height`)

`stage` / `expose` / `story` (and `large`) default to full-viewport or full-width plate height. For an **in-article** demo — square Live Photo feel, fixed hero height, or a reading-column box — set any combination of `ratio`, `width`, and `height`. The runtime emits `data-sized="true"` and CSS variables; media uses `object-fit: cover` inside the box.

| Form | Example | Result |
| --- | --- | --- |
| Ratio only | `ratio="1:1"` | Square box; width defaults to `min(100%, 36rem)` |
| Ratio + width | `ratio="16:9" width="100%"` | Widescreen, full content width |
| Height only | `height="50vh"` | Fixed plate height, width 100% of content column unless `width` set |
| Width + height | `width="32rem" height="18rem"` | Explicit box; `ratio` optional |

```markdown
::gallery{folder="media" layout="stage" ratio="1:1"}
::gallery{folder="media" layout="stage" ratio="16:9" width="100%"}
::gallery{folder="media" layout="stage" height="40vh"}
::gallery{folder="media" layout="large" width="24rem" height="16rem"}
```

**Scope:** sized-plate CSS applies to `stage` / `expose` / `story` / `large`. Browse layouts (`grid`, `mosaic`, …) ignore these props for tile geometry. Invalid ratio or size strings are dropped (unsized gallery remains valid).

Requires a Web Device runtime that includes sized-plate CSS (gallery `ratio` / `width` / `height`). Older builds expand the gallery but keep full-viewport stage.

## Layout reference

| Layout | Role | Typical use |
| --- | --- | --- |
| `mosaic` | Bento: first image 2×2, rest fill | Hero + companions |
| `pair` | Two-up diptych (4:5 on desktop; stacks on phone) | Before/after, call-and-response |
| `grid` | Equal tiles; density via `cols` | Editorial sets |
| `masonry` | Column flow, natural heights | Mixed aspect ratios |
| `film` | Tight contact sheet | Scan a whole set |
| `large` | Full-width stack | One image per breath |
| `stage` | Full-viewport plates + **on-image** overlay caption | Immersive plate sequence |
| `expose` | Alias of `stage` | Same as stage (Expose-style name) |
| `story` | Full-bleed scroll plates + on-image caption | Magazine-style scroll |

Cover + short video pairs (same stem or sidecar `video:` / `poster:`) turn stage/expose/story plates into muted looping immersion when the runtime includes arc#3764. Dedicated authoring notes and a live sample: [Immersive video gallery (Expose-style)](../media-gallery-immersive/).

## Live samples (same folder)

All samples below use `folder="media"` on this document.

### Mosaic

```markdown
::gallery{folder="media" layout="mosaic"}
```

::gallery{folder="media" layout="mosaic"}

### Pair

```markdown
::gallery{folder="media" layout="pair"}
```

::gallery{folder="media" layout="pair"}

### Grid (`cols="3"`)

```markdown
::gallery{folder="media" layout="grid" cols="3"}
```

::gallery{folder="media" layout="grid" cols="3"}

### Grid denser (`cols="4"`)

```markdown
::gallery{folder="media" layout="grid" cols="4"}
```

::gallery{folder="media" layout="grid" cols="4"}

### Masonry

```markdown
::gallery{folder="media" layout="masonry"}
```

::gallery{folder="media" layout="masonry"}

### Film

```markdown
::gallery{folder="media" layout="film"}
```

::gallery{folder="media" layout="film"}

### Large (lightbox off by default)

```markdown
::gallery{folder="media" layout="large"}
```

::gallery{folder="media" layout="large"}

### Large with lightbox forced

```markdown
::gallery{folder="media" layout="large" lightbox="true"}
```

::gallery{folder="media" layout="large" lightbox="true"}

### Stage (immersive plates)

Full-viewport plates. Caption text is drawn **on the image** (not under it), from per-file sidecars (`title`, body, `overlay`, `tone`). Lightbox defaults off — the plate already owns the viewport.

```markdown
::gallery{folder="media" layout="stage"}
```

::gallery{folder="media" layout="stage"}

### Stage sized (`ratio="1:1"`)

Same folder and overlay captions, constrained to a square reading-column plate (no full-viewport scroll tax):

```markdown
::gallery{folder="media" layout="stage" ratio="1:1"}
```

::gallery{folder="media" layout="stage" ratio="1:1"}

### Story (full-bleed scroll)

Tall plates in a continuous scroll. Same on-image overlay captions as stage.

```markdown
::gallery{folder="media" layout="story"}
```

::gallery{folder="media" layout="story"}

## Lightbox

- **Browse layouts** (`mosaic`, `pair`, `grid`, `masonry`, `film`): lightbox **on** unless `lightbox=false`.
- **`large` / `stage` / `story`**: lightbox **off** unless `lightbox=true`.
- Open: click a tile. Close: `Esc`, backdrop, or ×.
- Navigate: `←` / `→` (or on-screen controls) within the **same** gallery only.
- Progressive enhancement via the site SSR runtime bundle; tiles keep their layout CSS (no DOM rewrite of the grid).

```markdown
::gallery{folder="media" layout="grid" lightbox="false"}
```

## Folder `content.md` and sidecars

Optional `media/content.md` (and locale variants such as `content.zh.md`) can supply a short lede for immersive modes:

```markdown
---
title: Coastal walk
---

A short coastal walk at dusk.
```

Per-file sidecars (e.g. `01-ridge.md` or `01-ridge.jpg.md`) set the plate label. For `stage` / `story`, front matter also places the caption **on** the image:

```markdown
---
title: Ridge at dusk
overlay: bottom-left   # top-left | top | top-right | center | bottom-left | bottom | bottom-right
tone: dark             # dark | light
---

Optional second line on the plate.
```

Browse layouts (`grid`, `mosaic`, …) still show the caption under the tile when present.
Sidecars and `content.md` are never treated as media members. Names starting with `_` or `.` are skipped.

## Self-contained media

- Keep files under the content item. Relative `src` values stay item-local after expand.
- Prefer shipping demo images **in the repo** next to the content (this page does). External hotlinks break when the host changes.
- Pre-render copies item-local media into the web cache so relative paths resolve on the built site.

## Responsive behavior (summary)

| Breakpoint | Browse adjustments |
| --- | --- |
| ≤900px | grid → 2 columns; mosaic → 2 columns; film → 4-up |
| ≤640px | pair → stack; masonry → 2 columns; film → 3-up; story drops `100vw` breakout |
| ≤380px | film → 2-up; masonry → 1 column |

Stage captions respect safe-area insets on notched phones. Details and screenshots: site issue #349 / design pack under `reference/design/gallery-responsive-evidence/`.

## Errors and empty states

| Situation | Result |
| --- | --- |
| Missing or unreadable `folder` | Empty gallery wrapper (`data-empty`), no broken `<img src="">` |
| Path traversal (`../…`) or URL `folder` | Rejected (`invalid-folder`) |
| Empty folder | Valid empty gallery, no images |
| Unknown `layout` | Falls back to `large` |
| Invalid `ratio` / `width` / `height` | Prop ignored; gallery still renders unsized |
| Runtime without gallery expand | Directive may appear unexpanded — upgrade ARC |
| Runtime without sized-plate CSS | Stage stays full-viewport; `ratio` / `width` / `height` have no visual effect |

## Boundaries

- Gallery is a **content-item media block**, not a site-wide media library UI and not the AUP `photo-story` widget.
- `stage` / `story` are presentation modes of the same folder model; they are not separate content types.
- Do not document price, token value, or unimplemented overlay products as part of this block.

## Related

- Immersive cover+video plates: [Immersive video gallery (Expose-style)](../media-gallery-immersive/)
- Introduction article: [One folder of photos, several ways to look](/en/articles/folder-backed-media-gallery/)
- Markdown image (inline single image): [image](../markdown/image/)
- Markdown slides (different feature): [Write and embed Markdown slides](../markdown-slides/)
- AUP `photo-story` widget (separate layer): [photo-story](../../aup/widgets/photo-story/)

---

## Immersive video gallery (Expose-style)

URL: https://www.arcblock.io/en/docs/web-device/media-gallery-immersive/

Use immersive video when a plate should feel like a Live Photo: a cover still first, then a muted looping clip once the video is ready. This is still the same folder-backed [`::gallery`](../media-gallery/) model — not a new content type, and not Expose polygon / spatial overlay scope.

Requires a Web Device runtime that includes cover+video immersion (arc#3764). Older builds still expand `::gallery{folder}` and show covers; they may not crossfade into video. Upgrade the serving ARC build before treating a still-only plate as a broken sample.

Sized plates (`ratio` / `width` / `height`) need a runtime that includes sized-plate CSS; older builds keep full-viewport stage. Parameter details: [Folder-backed media gallery](../media-gallery/#sized-plates-ratio--width--height).

## When to use

| Use immersive video when… | Prefer something else when… |
| --- | --- |
| You want full-viewport plates with subtle motion | Readers only need a scannable grid → browse layouts on [Folder-backed media gallery](../media-gallery/) |
| You want an **in-article** square / fixed-height motion plate | Use `ratio` / `width` / `height` on stage — not a second media system |
| Each plate has a short, loopable clip | You need a free-positioned motion deck or heavy interactive video UI |
| Cover must paint immediately (slow networks / first paint) | A single inline clip belongs in ordinary Markdown / embed, not a gallery set |

## Minimal example

```markdown
::gallery{folder="plates" layout="expose"}
```

In-article square plate (reading column, no full-viewport scroll tax):

```markdown
::gallery{folder="plates" layout="expose" ratio="1:1"}
```

1. Create a folder next to this content object's `content.md` (this page uses `plates/`).
2. Add a same-stem pair: `bay.jpg` + `bay.mp4` (or `.webm` / `.mov`).
3. Optional: a per-file sidecar for on-image caption (`title`, body, `overlay`, `tone`).
4. Render with `layout="expose"` (alias of `stage`), or `layout="stage"` / `layout="story"`.
5. Optional: size the plate with `ratio`, `width`, and/or `height` (see below).

This page keeps samples in `./plates/` so covers and videos ship in the repo (no hotlinks). License notes: [`plates/_ATTRIBUTION.md`](./plates/_ATTRIBUTION.md).

## Authoring: layouts

Immersion comes from **cover+video pairing in the folder**, not from a separate layout engine.

| `layout` | Role for immersive pairs |
| --- | --- |
| `expose` | Alias of `stage` (Expose-style naming) |
| `stage` | Full-viewport plates + on-image overlay caption (or sized via props below) |
| `story` | Full-bleed scroll plates; same overlay rules |

Browse layouts (`grid`, `mosaic`, `pair`, `masonry`, `film`) and still-only `large` / `stage` plates without a video sibling stay as documented on [Folder-backed media gallery](../media-gallery/). Pairing rules below still apply if a browse layout encounters video files; immersion UX is designed for `stage` / `expose` / `story`.

## Authoring: plate size

Stage defaults to full viewport. For demos that should sit in the reading column (square Live Photo, 16:9 hero, fixed height), pass any combination of:

| Prop | Aliases | Example | Role |
| --- | --- | --- | --- |
| `ratio` | `aspect`, `aspectRatio` | `1:1` · `16/9` · `square` | CSS `aspect-ratio` |
| `width` | `w` | `24rem` · `100%` · `min(100%,36rem)` | Plate width |
| `height` | `h` | `50vh` · `400px` | Plate height |

With only `ratio`, width defaults to `min(100%, 36rem)`. Full parameter contract and error cases: [Folder-backed media gallery — sized plates](../media-gallery/#sized-plates-ratio--width--height).

## Cover + video pairing

### Same-stem (Live Photo–like)

Put a still and a video that share the **filename stem**:

```text
plates/
  01-bay.jpg
  01-bay.mp4
  01-bay.md          # optional sidecar
```

Accepted video extensions include `mp4`, `webm`, and `mov` (same stem as the cover image). Image extensions follow the gallery still set (`jpg`, `jpeg`, `png`, `webp`, …).

The cover is the plate member the gallery orders and captions; the matching video is the immersive motion layer for that plate.

### Sidecar `video:` / `poster:`

When stems cannot match (or you rename assets), declare the pair in the plate sidecar:

```markdown
---
title: Bay
overlay: bottom-left
tone: dark
video: clips/bay-loop.mp4
poster: covers/bay.jpg
---

Optional second line on the plate.
```

Paths in `video:` / `poster:` are resolved under the gallery folder (item-local), same as other gallery media — not site-level `content/media/`.

Use **either** same-stem **or** explicit sidecar fields for a plate; keep one clear pairing so authors and reviewers can see the contract in the folder.

## Expected runtime behavior

| Phase | Behavior |
| --- | --- |
| First paint | Show the **cover** still (fast fallback). |
| When video is ready | Crossfade / swap into a **seamless muted loop**. |
| Audio | Playback starts **muted**. If the clip has an audio track, offer **Unmute** (user gesture). |
| Still-only plate | No video sibling → plate stays a still image (same stage/story chrome). |
| Lightbox | Defaults **off** for `stage` / `expose` / `story` (plate already owns the viewport). |

Demos on this page strip audio so the muted loop is the whole story; shipping a clip with audio is allowed — expect Unmute, not autoplay with sound.

## How this differs from other gallery modes

| Concern | Browse layouts | Still-only stage/story | Immersive cover+video |
| --- | --- | --- | --- |
| Job | Scan a set; optional lightbox | Full-viewport still plates | Full-viewport plates that can move |
| Media | Images (video may appear as members depending on runtime) | Cover / image only | Cover + paired short loop |
| Caption | Usually under the tile | On-image overlay via sidecar | Same on-image overlay as stage/story |
| Motion | None by default | None | Muted loop after cover |

Do not invent Expose polygon masks, multi-layer spatial overlays, or a separate “expose content type” — those are out of scope for `::gallery`.

## Live sample

Same folder for every sample below: `folder="plates"` on this document.

Folder members:

| File | Role |
| --- | --- |
| `01-bay.jpg` + `01-bay.mp4` | Same-stem immersive pair |
| `02-sky.jpg` + `02-sky.mp4` | Same-stem immersive pair |
| `03-bloom.jpg` + `03-bloom.mp4` | Same-stem immersive pair |
| `04-still.jpg` | Still-only plate (contrast) |

### Expose sized square (`ratio="1:1"`)

In-article demo: same pairing, constrained plate.

```markdown
::gallery{folder="plates" layout="expose" ratio="1:1"}
```

::gallery{folder="plates" layout="expose" ratio="1:1"}

### Expose full viewport (`layout="expose"`)

```markdown
::gallery{folder="plates" layout="expose"}
```

::gallery{folder="plates" layout="expose"}

### Stage (same immersion; `expose` is an alias)

```markdown
::gallery{folder="plates" layout="stage"}
```

::gallery{folder="plates" layout="stage"}

### Story (scroll plates; same pairing)

```markdown
::gallery{folder="plates" layout="story"}
```

::gallery{folder="plates" layout="story"}

**What you should see (with arc#3764+):** plates `01`–`03` show cover, then muted looping video; plate `04` stays still. Overlay titles come from sidecars. The sized square sample keeps that immersion inside a reading-column box. On older ARC, covers and stills still render; motion or sizing may be absent until the runtime is upgraded.

## Errors and empty states

| Situation | Result |
| --- | --- |
| Cover without video | Still plate (valid) |
| Video without cover / poster | Depends on runtime pairing rules — prefer always shipping a cover |
| Broken or unreadable video | Cover remains; do not leave a broken empty `<video>` as the only paint |
| Missing `folder` / path traversal | Same rejection rules as [Folder-backed media gallery](../media-gallery/) |
| Runtime without immersion | Covers and gallery expand may work; treat missing motion as a version gap, not a bad folder |
| Runtime without sized-plate CSS | Stage stays full-viewport; `ratio` / `width` / `height` have no visual effect |
| Invalid size props | Props ignored; immersive expand still applies |

## Boundaries

- Same `::gallery` directive and item-local folder model — **no new contentType**.
- `expose` aliases `stage`; immersion is pairing, not a parallel product.
- Not AUP `photo-story`, not a site-wide media library, not Expose polygon / spatial overlay.
- Do not document price, token value, or unimplemented overlay products here.

## Related

- Parameter tables and browse layouts: [Folder-backed media gallery (`::gallery`)](../media-gallery/)
- Introduction article: [One folder of photos, several ways to look](/en/articles/folder-backed-media-gallery/)
- Runtime authoring (cover+video immersion): [ArcBlock/arc#3764](https://github.com/ArcBlock/arc/pull/3764)

---

## Immersive plates

URL: https://www.arcblock.io/en/docs/web-device/media-gallery-immersive/plates/

Cover stills first. When a plate has a paired video, the runtime crossfades into a muted loop.

---

## web-device/media-gallery-immersive/visuals

URL: https://www.arcblock.io/en/docs/web-device/media-gallery-immersive/visuals/

---

## web-device/media-gallery/media

URL: https://www.arcblock.io/en/docs/web-device/media-gallery/media/

One folder. One set of plates. Choose the layout in the directive.

---

## Minimal information site

URL: https://www.arcblock.io/en/docs/web-device/minimal-information-site/

This recipe deliberately starts from the first locally verified Web Device path. It is a small information site, not a generic blog starter and not a deployment procedure.

## Establish the verified base

Follow [Build a first site](../first-site/) to create:

```text
.route/web
.web/site.yaml
.web/components/hello/{manifest.json,render.js,style.css}
pages/index/layout.aup
```

Then add one named page directory, for example `pages/about/`, with its own `layout.aup` and an existing site component. Keep the navigation choice explicit: creating `pages/about/` makes a route possible, but does not automatically put it in every header/menu.

## Keep the first acceptance narrow

1. Run lint, validation, blocklet check, and build.
2. Directly run the local blocklet, not a DID Space deployment.
3. Open home and the named page at the exact printed URL.
4. Check a narrow viewport and one internal navigation path.
5. Only then extract a shared header/footer component if two pages genuinely need it.

The verified base is intentionally component-driven. Do not turn this recipe into a content-site claim by pasting article bodies into the layouts; add content objects and source bindings when the site actually needs collections.

Next: [Content site](../content-site/) or [Custom component](../custom-component/).

---

## Web Device

URL: https://www.arcblock.io/en/docs/web-device/overview/

ARC is the runtime and command-line tooling behind the site. AFS is its path-based filesystem abstraction. Web Device is ARC's AFS provider for static websites: a runtime module that reads a class of AFS paths. It reads a site's pages, content records, and Web configuration, then renders static HTML. It is not a separate website framework: the files in the AFS-backed site remain the source of truth.

## Three parts of a site

Most sites divide their work across these locations:

| Location | Purpose |
|---|---|
| `pages/` | Routable pages, routes, and layouts. Use `layout.aup` for Web pages; `layout.json` remains a compatibility fallback. |
| `content/` | Directory-based content records. A record normally stores its body in `content.md` or `index.md`, and can add locale variants such as `content.zh.md` with YAML front matter, the YAML metadata block at the start of a document. |
| `.web/` | Site-wide configuration, components, themes, templates, and static assets. `.web/site.yaml` is the recommended configuration entry point. |

AUP is ARC's declarative language for describing UI and layouts. Use it to compose Web components into a page layout. Do not expect arbitrary AUP-native nodes to render as Web content on their own: a Web layout must refer to components supplied by the site's `.web/components/` directory or a theme library. See [AUP layout boundary](../aup-reference/) for the current boundary.

## Choose a path

Read by task rather than trying to learn the whole system at once:

| Goal | Start here |
|---|---|
| Start from an empty directory | [Get started](../getting-started/); establish scope, create a first site, then run it directly on your machine. |
| Understand an existing site | [Understand a site](../understand/); begin with the directory, pages, content, and routes. |
| Start authoring or changing a site | [Author a site](../author/); begin with site configuration, page layouts, and content binding. |
| Look up the exact contract | [Reference](../reference/); this will cover directories, AUP, source bindings, components, and version boundaries. |
| Follow a complete path | [Recipes](../recipes/); grow from a minimal information site to a content site and a custom component. |

The complete shape is fixed before each page is filled in. Every draft page says which question it will answer; a page with commands becomes operational reference only after those commands have been run against the current runtime.

## Articles explain context; documentation states the contract

[Web Device: Declare a Website, Then Pick the Right Path](/en/articles/arc-web-device/) explains the design context. [The Web Content System on ARC](/en/articles/arc-web-content-system/) explains why a content object does not need to begin as an article, product, or event.

Those articles are useful background, not the operational reference. This board follows current code, tests, and observed runtime behavior. Historical language in an article does not automatically become a product commitment.

## Version boundary

The facts in this initial page were checked against `arc` `2.0.0-beta.25`. Any page that includes commands must name the version used for verification and show actual output. When using another release, check its command reference and compatibility guidance first.

---

## Page variants

URL: https://www.arcblock.io/en/docs/web-device/page-variants/

A page directory can carry sibling versions next to its default layout. Same canonical URL. Each version is a fully server-rendered HTML document, built at `arc blocklet build` / prerender time.

This page is the operations contract, verified 2026-08-21 against Web Device after [arc#4548](https://github.com/ArcBlock/arc/pull/4548) (token delta) and [arc#4557](https://github.com/ArcBlock/arc/pull/4557) (Split + Select reason). It is not a design essay; for motivation see the [feature article](/en/articles/web-device-page-variants/).

In-page review is a **different** capability that happens to share the HUD. Do not treat this page as a rewrite of [In-page review mode](../in-page-review/). Review writes feedback next to content (`.review/`). Variants choose among finished renders (`.experiment/selection.json` plus the `variants/` tree).

## When to use it

Use page variants when:

- an agent (or a person) can produce more than one finished version of the **same route** in one pass;
- you need to look at those versions on the rendered page, including side by side, before visitors see any of them;
- you later want a cookie-assigned traffic split on that same tree.

Do **not** use them as:

- a second review overlay, a `?experiment=1` mode, or a client-side theme switcher;
- per-article / per-doc alternatives (collection item URLs are not variant pages);
- slot-level or sentence-level experiments (not this wave);
- a metrics or significance product (out of scope).

## Declare the versions

Only `pages/<name>/` pages grow variants. The control layout must exist.

```text
pages/index/layout.aup                 # default / control (required)
pages/index/variants/aurora/layout.aup # kind 2: full layout tree
pages/index/variants/quiet/tokens.json # kind 1: values only, inherit default layout
pages/index/variants/_config           # optional: split= / seed=
```

| Kind | What differs | What to put in `variants/<name>/` | What is inherited |
| --- | --- | --- | --- |
| 1 Values | tokens / concrete CSS variables | `tokens.json` only | default layout tree |
| 2 Structure | hero, block order, widgets | full `layout.aup` or `layout.json` | nothing from the control layout |

A declared directory with neither a layout nor a valid `tokens.json` is a **build failure**. Kind 2 ignores a `tokens.json` sitting next to a layout in this wave; do not mix both in one name and expect the tokens to apply.

`_config` uses one `key=value` per line. A malformed line is a build failure, not a skip:

```text
split=100,0,0
seed=homepage-choose-2026
```

`split` weights are parallel to `[default, ...directory names in listing order]` and must sum to 100. Omitting `_config` (or omitting `split`) distributes evenly across every declared version.

To keep every visitor on default while the extra versions exist for authoring, set the first weight to 100 and the others to 0. Changing `seed` reshuffles every visitor.

## Agent recipe: one pass, several versions

This is the shape an agent should produce. Do not invent a second API.

1. Read the existing `pages/<name>/layout.aup` (and i18n / sources it already binds).
2. Decide which alternatives are **values** and which are **structure**. Values → `tokens.json` only. Structure → a complete layout file. Do not copy the whole layout to change `--accent`.
3. Write each alternative under `pages/<name>/variants/<name>/` in the **same turn** as the control, so a human can open review once.
4. Add `_config`. If visitors must not enter the experiment yet: `split=100,0,0` (pad zeros to the number of non-default names).
5. Run `arc dsl lint` / `validate` / `blocklet check` on the site. A bad `split` or an empty variant directory fails here, not at request time.
6. Open the rendered page with `?review=1`. Use Split to compare, Select to record the winner.

Directory names must be ordinary (`aurora`, `b`, `quiet`). `.`, `..`, and names containing `/` are rejected.

Collection routes such as `/en/articles/<slug>/` do not grow a switcher. Put the experiment on `pages/index/` (or another `pages/<name>/` route), not next to a markdown item.

## Compare and select on the review HUD

Injection is still only `?review=1` (value exactly `1`). There is no `?experiment=1`. Inner iframes use `?embed=1` so they do not grow a nested HUD.

On a page that listed at least two names including `default`:

| Control | What it does |
| --- | --- |
| Version buttons | `location.assign` the same path with `review=1` and `variant=<name>` |
| **Split** | `review=1&split=1`. Builds at most four iframes, declaration order |
| Pane title / chrome | Leaves split: `review=1&variant=<that name>`, no `split` |
| **Select** | `POST` to `<page>/.experiment/.actions/select` with `{ selected, reason }` |

`reason` is the current Page note text from the same HUD. Empty or omitted still succeeds and **omits** the key. Max stored length 8192.

`?variant=` wins over the visitor cookie, does not write a cookie, and forces `noindex`. Unknown names fall back to default rather than 404.

![Homepage review HUD with the version bar](media/homepage-review-hud.png)

*This site's `/en/?review=1` · 2026-08-21. Capture is a local Web Device handler after arc#4557, not a published CLI tag.*

![Homepage split grid](media/homepage-split.png)

*`?review=1&split=1` on the same route. Inner frames have no HUD. Each pane layouts at 1280px and scales to the cell, so desktop-only visuals (WebGL heroes) still run.*

Anonymous `cms-write` on Select is still 401 with a reason. Layout source is never rewritten by Select; the record is `.experiment/selection.json` next to the page.

## Visitor assignment, crawlers, SEO

Production HTML is static per version. The assigned visitor receives that version's pre-rendered document. No experiment-switching JavaScript ships in the output.

| Actor | What they get |
| --- | --- |
| First-time browser visitor | hashed into a bucket from `(seed, visitorId)`; `arc_variant_id` cookie is minted |
| Same visitor later | the same bucket, until `seed` changes |
| Recognized crawler UA | **always default**, never a cookie |
| `?variant=` (review/QA) | that name, `noindex`, no cookie write |

Canonical, sitemap, and `hreflang` stay on the one URL. Serving a crawler a non-default version would be cloaking.

Changing `variants/` or `_config` requires a rebuild. There is no runtime reconfiguration, no geo/device targeting, and no significance dashboard.

## Limits

| Topic | Current contract |
| --- | --- |
| Enable flag | only `?review=1` injects the HUD; `?split=1` alone does nothing |
| Second overlay | none; no `data-arc-experiment` script |
| Kind 3 (one slot / one sentence) | not implemented; use whole-page split |
| Kind 2 + tokens in the same directory | tokens ignored this wave |
| Split capacity | at most four iframes, first names in declaration order |
| Split pane viewport | each iframe layouts at 1280×800 CSS px and scales to the cell (so in-frame `matchMedia(max-width: 760px)` is false) |
| Collection items | not variant pages |
| Metrics | out of scope |
| Published snapshot | `.experiment/` is authoring-time; do not teach it as a public widget |

## Check

```bash
arc --version
arc dsl lint blocklets/arcblock
arc dsl validate blocklets/arcblock
arc blocklet check blocklets/arcblock
```

Then open the printed local URL:

```text
http://<host>:<port>/en/?review=1
http://<host>:<port>/en/?review=1&split=1
http://<host>:<port>/en/?review=1&variant=aurora
```

Confirm: version bar present on the homepage; Split shows distinct finished heroes; inner iframes have no HUD; a page without `variants/` still has the review HUD and no version bar.

---

## web-device/page-variants/media

URL: https://www.arcblock.io/en/docs/web-device/page-variants/media/

---

## web-device/page-variants/visuals

URL: https://www.arcblock.io/en/docs/web-device/page-variants/visuals/

---

## Build a page with AUP

URL: https://www.arcblock.io/en/docs/web-device/pages-and-aup/

In Web Device, AUP has two related but distinct paths. The static renderer can render a supported native AUP tree directly to HTML. A page `layout.aup`, by contrast, uses the Web layout and component contract; its reusable presentation belongs in site or theme components, which own richer browser HTML, CSS, and interaction. The current Web renderer defines both support boundaries; an AUP primitive existing does not mean it is a valid layout section or that it must render on the Web.

## How a page gets a layout

For `pages/<name>/`, the current runtime looks for a layout in this order:

1. The locale-specific `layout.<locale>.aup`, then `layout.aup`.
2. The locale-specific `layout.<locale>.json`, then `layout.json`.
3. A compatibility convention layout inferred from the page directory and site component names.
4. The default page layout.

The first two are explicit author-provided layouts. Prefer `layout.aup` for a new page; `layout.json` is compatible input, not the default form for a new tutorial. A missing layout does not prove that a page renders as you intended; it only makes the runtime attempt the next fallback. Local acceptance must therefore include the rendered page, not just the directory.

## Components and native nodes in a Web layout

The Web renderer validates page layouts against the Web component-and-props contract. Its separate static-tree renderer can render supported native AUP trees, but that does not make arbitrary native primitives valid `.web` layout sections. A page can reference a component in `.web/components/` or one supplied by the selected theme. Components are the stable site layer for reusable Web HTML, styling, slots, and page data.

Conceptually, a page should look like this:

```text
pages/index/layout.aup
        │
        ▼
.web/components/site-home/
        │
        ▼
HTML, CSS, theme tokens, and content bindings
```

This does not mean that all UI belongs in one component. It preserves a stable boundary: the page arranges the semantic structure, and site components provide reusable Web presentation.

## Start with the page directory

1. Create `pages/index/` or another explicit `pages/<name>/` directory.
2. Add `layout.aup`, using Web components that actually exist in the site or selected theme. Use the direct static-tree path only when that separate renderer and its node support have been verified for the target.
3. If the page needs content data, declare it in the page's source/binding layer; do not copy article body text into a layout. See [Bind content to a page](/en/docs/web-device/sources-bindings/).
4. Use `arc dsl validate .` for DSL, then `arc blocklet build .` and a browser check for the final presentation.

A page can have locale variants, but a locale file is not a second page model. Keep the same page and component structure first, then add `layout.<locale>.aup` or locale-specific content. Split the layout only when the structure itself needs to differ.

## Common misunderstandings

| Misunderstanding | Current boundary |
| --- | --- |
| “Any native AUP node can be a section in `layout.aup`.” | No. Static-tree rendering is a separate path; Web layouts use actual Web components and their props. |
| “`layout.json` is the recommended format for new projects.” | It is compatible input; new pages should prefer DSL source. |
| “No layout means the page must fail.” | The runtime has convention and default fallbacks; neither verifies product intent. |
| “A content object should carry every page's UI.” | An object can have content or an inline-layout boundary; keep shared presentation in pages and components. |

Read [Compose pages and layouts](/en/docs/web-device/pages-layouts/) next. The general AUP language contract is intentionally outside this Web Device board.

---

## Compose pages and layouts

URL: https://www.arcblock.io/en/docs/web-device/pages-layouts/

A page layout determines how one Web route assembles presentation, not where an article, product, or document body lives. Start with the route and reader task; then use components for repeated presentation and sources for content selection.

## Choose the layout level

| Need | Place it in |
| --- | --- |
| A page’s default presentation | `pages/<name>/layout.aup` |
| A layout that truly differs by locale | `pages/<name>/layout.<locale>.aup` |
| A content object’s exceptional presentation | `content/<type>/<slug>/layout.aup` |
| One named presentation shared by several content objects | `layouts/<name>.aup`, selected by `layout: <name>` in front matter |
| Shared card/header/section presentation | `.web/components/<name>/` |
| The body and identity of a reader-facing object | `content/<type>/<slug>/content.md` |

The current lookup prefers locale AUP, default AUP, locale JSON, default JSON, then a convention/default layout. That makes an AUP layout the normal source-first choice for a new page; JSON remains a compatibility form, not a reason to duplicate both by default.

## Compose in the right direction

1. Declare the page or collection route first.
2. Declare any content source in the matching page/collection scope.
3. Use a complete `$source.<name>` value only where the layout/component contract expects it.
4. Compose a reusable Web component with explicit props rather than copying a repeated tree into every page.
5. Keep a one-off detail layout next to the object only when the object really needs a different reader task.

Web Device page layouts use a Web-component-and-props model. A supported AUP tree can also be statically rendered through the Web renderer, but that does not make arbitrary native primitives valid as layout sections. Use components for reusable site presentation and use the direct-tree path only where the target’s support has been verified.

A content object chooses either an item-local `layout.aup` or one named layout through `layout: <name>`. Do not declare both. A named layout can attach a verified widget to content it renders; [Markdown slides](../markdown-slides/) shows the complete content-plus-widget pattern.

Run layout validation and inspect the resulting route in the browser. A syntactically valid layout can still have an empty source, a wrong locale variant, or an unreadable narrow-width hierarchy.

For layout mechanics, see [Build a page with AUP](../pages-and-aup/); for components, see [Use and override components](../components-overrides/).

---

## Preview, build, and publish

URL: https://www.arcblock.io/en/docs/web-device/preview-build-publish/

These stages answer different questions. Treating one as evidence for another is a common way to ship an uninspected page.

| Stage | Command or action | What it proves | What it does not prove |
| --- | --- | --- | --- |
| Local acceptance | `arc blocklet run .` and a browser | The selected local blocklet can be served and inspected on this machine | That it is formally published or available to a DID Space user |
| Build | `arc blocklet build .` | ARC can assemble a distributable artifact from the current directory | That readers saw the intended page or that a production deployment succeeded |
| Formal publish | Follow the project’s approved release path | A separately authorized production delivery occurred | That local direct-run testing was unnecessary |

## Run locally first

`arc blocklet run <path>` validates the target directory, reuses or starts a local daemon, registers the blocklet’s parent directory for this process, and prints both a subdomain URL and a universal query URL. Use the printed URL for your browser; the host and port are machine-specific. To keep the source on a named instance across restarts, use `arc service start --instance <name> --blocklet <path>`.

This is the normal Web Device acceptance path. It is not a DID Space deployment. Open the page at a wide and narrow viewport, follow at least one internal link, and reload after an edit if the local result looks stale.

## Build deliberately

`arc blocklet build [dir]` creates the packaged build material under `<dir>/dist`, including the AFS manifest and blocklet distribution metadata. The build command manages that output directory, so do not put hand-maintained source there or commit it unless your repository’s release process explicitly requires the generated artifact.

Static pre-rendering is normally enabled when the blocklet exposes a Web route. Its page cache/output behavior is separate from packaging `dist`; do not use a successful package build as a substitute for opening the rendered page.

## Publish only as a separate, authorized path

Production publishing has its own identity, authorization, and release concerns. It may be appropriate after local acceptance and artifact verification, but it must not be used merely to discover whether a local layout works. For everyday documentation and site work, direct local run is the first test.

The local watcher can invalidate cache for registered parent directories and normally ignores generated/build directories. If a watcher cannot start, it can degrade without automatic refresh. A stale preview therefore calls for an explicit reload and source/path check, not an automatic deployment.

Use [Run, check, and inspect](../run-check-inspect/) for the first local chain, [In-page review mode](../in-page-review/) when the gates are green but the rendered page still needs human feedback, and [Diagnose a site](../diagnose/) when the stages disagree.

---

## Publish and maintain

URL: https://www.arcblock.io/en/docs/web-device/publish-maintain/

This section explains a site's path through local preview, build, formal publishing, ongoing checks, and diagnosis when something fails. Local direct runs are the default acceptance path; formal deployment is a separate, explicitly requested surface.

## Read in this order

1. [Preview, build, and publish](../preview-build-publish/) to distinguish a direct local run, a build artifact, and formal deployment.
2. [In-page review mode](../in-page-review/) to leave text-anchored feedback on the rendered page next to the content item.
3. [Bookmark and note (save capability)](../save-capability/) for reader bookmark/note chrome (not review). Declaration lives on `blocklet.yaml`.
4. [SEO, links, and accessibility](../seo-links-accessibility/) to separate static checks from reader-facing acceptance.
5. [Diagnose a site](../diagnose/) to narrow a failure before changing source or deploying anything.

---

## Recipes

URL: https://www.arcblock.io/en/docs/web-device/recipes/

Use a **task recipe** when you know the outcome (first site, list page, docs board, slides, source binding) and need the correct **chain of unit pages**. Recipes do **not** restate props, caps, or sample contracts — those live on:

- `/docs/aup/primitives/<name>/`
- `/docs/aup/widgets/<name>/`
- `/docs/web-device/components/...`
- `/docs/web-device/markdown/...`
- `/docs/web-device/surfaces/...`

## Task recipes (#299 wave 4)

1. [First site](./first-site/) — minimal static site from verified getting-started + layout units.
2. [Collection list page](./collection-list/) — content objects + list layout components.
3. [Docs board](./docs-board/) — `docs-page` surface and related chrome.
4. [Slides in an article](./slides-in-article/) — MD slides structures + `deck` widget.
5. [Bind source to layout](./bind-source/) — `$source.<name>` into a layout section.

## Showcase evidence map

- [Showcase mapping](../showcase-mapping/) — showcase-dsl / showcase page ids → primitive/widget unit pages, plus **local** run instructions (not full hosting on this site).

## Legacy narrative recipes

These pages keep longer narrative slices with evidence boundaries. Prefer the task recipes above when you only need the unit-page chain.

1. [Minimal information site](../minimal-information-site/) — verified route/layout/component foundation narrative.
2. [Content site](../content-site/) — collection vertical-slice narrative and current evidence boundary.
3. [Custom component](../custom-component/) — when a second real page needs the same presentation.
4. [Customize a theme and tokens](../custom-theme/) — narrow token-first visual path.

## Getting started (before any recipe)

1. [Install ARC CLI](../install-arc-cli/)
2. [Requirements and scope](../requirements-and-scope/)
3. [Build a first site](../first-site/)
4. [Run, check, and inspect](../run-check-inspect/)

## Layer reminder

| Task needs… | Open unit under |
| --- | --- |
| Portable AUP tree node | `/docs/aup/primitives/` |
| Web-only AUP widget | `/docs/aup/widgets/` |
| Theme / site layout component | `/docs/web-device/components/` |
| MD directive / structure | `/docs/web-device/markdown/` |
| Board shell (docs/search/…) | `/docs/web-device/surfaces/` |

---

## Recipe: bind source to layout

URL: https://www.arcblock.io/en/docs/web-device/recipes/bind-source/

**Task:** declare a named content source under a page, then pass it into a layout section as a complete `$source.<name>` value. Field-level contracts live on reference and unit pages.

## Outcome

- `pages/<page>/sources/<name>` (+ optional `.sort` / `.limit` / `.filter`)
- A `layout.aup` section whose top-level prop is the full `$source.<name>` binding
- Undeclared bindings and empty results are diagnosable

## Steps (link out only)

1. Know what a content object is: [Content objects, metadata, and locales](../../content-and-objects/).
2. Authoring guide for `path` / `sort` / `limit` / `filter` and empty states: [Bind content to a page](../../sources-bindings/).
3. Field and diagnostic reference: [Source-binding reference](../../source-binding-reference/).
4. Where the section sits in a page: [Compose pages and layouts](../../pages-layouts/) · [AUP layout boundary](../../aup-reference/).

## Canonical units that commonly receive `$source`

| Consumer role | Unit page |
| --- | --- |
| Card list | [`content-card`](../../components/content-card/) |
| Related reading | [`related-content`](../../components/related-content/) |
| Event cards | [`event-card`](../../components/event-card/) |
| Tag chips | [`tag-list`](../../components/tag-list/) |
| Site editorial feed (site package) | [site `editorial-feed`](../../components/site/editorial-feed/) |
| Site period index (site package) | [site `period-index`](../../components/site/period-index/) |

Open the unit page for props such as `items`, `emptyText`, and variants. This recipe does not copy those tables.

## Binding rules (pointers only)

| Rule | Where it is specified |
| --- | --- |
| Complete `$source.<name>` as a section top-level prop value | [Bind content to a page](../../sources-bindings/) |
| Source path stays under `/content/<type>/` | [Source-binding reference](../../source-binding-reference/) |
| Undeclared name → `source-binding-undeclared` (when checks run) | same reference + [Diagnose a site](../../diagnose/) |
| Component empty state for legitimate zero results | the layout component unit you chose |

## AUP data lists (different path)

Interactive AUP apps often list AFS data with the **`afs-list` primitive**, not with Web Device `$source` files:

- Primitive contract: [`afs-list`](../../../aup/primitives/afs-list/)
- Showcase demos for list variants: [Showcase mapping](../../showcase-mapping/) (`list-basic`, `list-pagination`, …)

Do not conflate `$source` (Web Device content query) with `afs-list` (AUP tree / session data).

## Related recipes

- [Collection list page](../collection-list/) — end-to-end list slice
- [Docs board](../docs-board/) — surface-mounted docs rather than freeform `$source` lists

---

## Recipe: collection list page

URL: https://www.arcblock.io/en/docs/web-device/recipes/collection-list/

**Task:** one collection list page that selects objects under `content/<type>/` and presents them with a list layout component. Contracts live on unit pages; this recipe only sequences them.

## Outcome

- At least two real content objects with front matter + body
- A page (or collection layout) that declares an unfiltered source for that type
- A list component bound to `$source.<name>` with an empty state
- List + one detail route checked in every declared locale

## Steps (link out only)

1. Start from a working first site: [Recipe: first site](../first-site/).
2. Object shape and locales: [Content objects, metadata, and locales](../../content-and-objects/).
3. Declare `path` / optional `sort` / `limit` / `filter` and bind `$source.<name>`: [Bind content to a page](../../sources-bindings/) · [Source-binding reference](../../source-binding-reference/).
4. Bind the source into the layout (task order only): [Recipe: bind source to layout](../bind-source/).
5. Full vertical-slice narrative and evidence boundary: [Content site](../../content-site/).

## Canonical units for the list surface

| Role | Unit page |
| --- | --- |
| Card list for posts / news | [`content-card`](../../components/content-card/) |
| Related band | [`related-content`](../../components/related-content/) |
| Tags on a card or index | [`tag-list`](../../components/tag-list/) |
| Optional editorial home mix | [`site-home`](../../components/site-home/) · site override [site `content-card`](../../components/site/content-card/) if the site shadows the theme |

Do **not** restate manifest props on this page — open the unit page for the component you chose.

## Markdown on list/detail bodies (optional)

If list items open Markdown detail pages, structure and cards come from MD unit pages, not from inventing HTML in the layout:

- [heading](../../markdown/heading/) · [paragraph](../../markdown/paragraph/) · [list](../../markdown/list/)
- Cards: [`::link-card`](../../markdown/link-card/) · [`:::info-card`](../../markdown/info-card/) · [`::::card-group`](../../markdown/card-group/)
- Callouts / tables: [GFM admonition](../../markdown/gfm-admonition/) · [GFM table](../../markdown/gfm-table/)

## Acceptance order

1. Unfiltered `/content/<type>/` source → list shows items.
2. Add `sort`, then `limit`, then `filter` — rebuild and re-check after each layer.
3. Open one detail route; confirm locale variants if you declared more than one locale.
4. Force an empty source and confirm the component empty state (see the unit page).

## Next

- [Docs board](../docs-board/) for documentation shells instead of blog lists
- [Slides in an article](../slides-in-article/) when a single Markdown object is a deck

---

## Recipe: docs board

URL: https://www.arcblock.io/en/docs/web-device/recipes/docs-board/

**Task:** a documentation board: left nav, prose body, breadcrumb, previous/next, optional in-page TOC. This recipe only points at surface and component unit pages.

## Outcome

- A docs board (or collection) served through the docs page surface
- Board `_nav.yaml` (or equivalent nav tree) drives the left rail
- One doc object renders as prose with working prev/next when the tree has neighbors

## Steps (link out only)

1. Have a working Web Device site: [Recipe: first site](../first-site/).
2. Understand content objects under `content/docs/`: [Content objects, metadata, and locales](../../content-and-objects/).
3. Board navigation conventions: [Routes, navigation, and locales](../../routes-navigation-locales/) · [Routes and locales reference](../../routes-locales-reference/).
4. Mount the documentation shell — read the surface unit for author entry and props: [`docs-page` surface](../../surfaces/docs-page/).

## Canonical units for a docs board

| Role | Unit page |
| --- | --- |
| Board shell (nav + prose + chrome) | [`docs-page`](../../surfaces/docs-page/) |
| In-page TOC (when enabled) | [`in-page-toc`](../../surfaces/in-page-toc/) |
| Search entry (if the board exposes search) | [`search-page`](../../surfaces/search-page/) |
| List/pagination helpers (indexes) | [`pagination` surface](../../surfaces/pagination/) |
| Optional comments attachment | [`comments-surface` surface](../../surfaces/comments-surface/) — different layer from the AUP widget [`comments-surface`](../../../aup/widgets/comments-surface/) |

## Prose and structure inside a doc

Doc bodies are Markdown. Use unit pages for structure and directives; do not treat layout components as MD:

- Structure: [heading](../../markdown/heading/) · [paragraph](../../markdown/paragraph/) · [fenced code](../../markdown/fenced-code/) · [list](../../markdown/list/) · [thematicBreak](../../markdown/thematic-break/)
- Directives: [`::::steps`](../../markdown/steps/) · [`:::step`](../../markdown/step/) · [`::embed`](../../markdown/embed/) · cards under [Markdown hub](../../markdown/)
- Portable AUP in document target (tabs etc.): [`view`](../../../aup/primitives/view/) · [`input`](../../../aup/primitives/input/) — sample contract: [Live examples: scope and contract](../../../aup/live-example-contract/)

## Layer discipline

| Need | Layer | Where the unit lives |
| --- | --- | --- |
| Docs chrome / left nav | Web Device **surface** | `/docs/web-device/surfaces/docs-page/` |
| Card list on a landing | Web Device **layout component** | `/docs/web-device/components/...` |
| Portable tree node | AUP **primitive** | `/docs/aup/primitives/...` |
| Web-only AUP chrome widget | AUP **widget** | `/docs/aup/widgets/...` |

Do not document multiple surfaces or components on this recipe page.

## Related

- [Collection list page](../collection-list/) when the board needs a non-docs collection landing
- [Showcase mapping](../../showcase-mapping/) for AUP interactive demos (not the docs surface)

---

## Recipe: first site

URL: https://www.arcblock.io/en/docs/web-device/recipes/first-site/

**Task:** ship a local static site with one home route and one named page. This page only **orders existing unit and guide pages**. It does not redefine component, primitive, or Markdown contracts.

## Outcome

- `.route/web` + `.web/site.yaml` + at least one `pages/<name>/layout.aup`
- One theme or site layout component on the page
- Local check + browser open of the printed URL

## Steps (link out only)

1. Install and confirm CLI version: [Install ARC CLI](../../install-arc-cli/).
2. Confirm this is a **static Web Device** site (not an interactive AUP app): [Requirements and scope](../../requirements-and-scope/).
3. Create the verified minimal file set: [Build a first site](../../first-site/).
4. Run lint / validate / check / build, then open the URL the CLI prints: [Run, check, and inspect](../../run-check-inspect/).

## Canonical units you will touch

| Role on this path | Unit page (contract lives there) |
| --- | --- |
| Page shell / sections | [`page-stack`](../../components/page-stack/) · [`page-sections`](../../components/page-sections/) |
| Site chrome (optional later) | [`portal-header`](../../components/portal-header/) · [`portal-footer`](../../components/portal-footer/) |
| AUP container (if you put a document tree on the page) | [`view`](../../../aup/primitives/view/) · [`text`](../../../aup/primitives/text/) · [`action`](../../../aup/primitives/action/) |

Layout composition rules (not unit APIs): [Compose pages and layouts](../../pages-layouts/) · [AUP layout boundary](../../aup-reference/).

## Do not do here

- Do not invent props for layout components — read the unit page for that name.
- Do not paste article bodies into `layout.aup` and call it a content site — use [Recipe: collection list page](../collection-list/) next.
- Do not deploy to DID Space for first acceptance.

## Next recipes

- [Collection list page](../collection-list/)
- [Bind source to layout](../bind-source/)
- Legacy narrative path: [Minimal information site](../../minimal-information-site/)

---

## Recipe: slides in an article

URL: https://www.arcblock.io/en/docs/web-device/recipes/slides-in-article/

**Task:** one content object (article or doc) that presents as slides in the browser when the slides path is available. This page only links unit contracts.

## Outcome

- Front matter enables the slides path
- Top-level HR / thematic breaks become slide boundaries
- Browser shows slide chrome when the serving runtime includes the slides player; otherwise you get the honest server transcript fallback described on the unit pages

## Steps (link out only)

1. Author a normal Markdown object under `content/articles/` or `content/docs/` — object rules: [Content objects, metadata, and locales](../../content-and-objects/).
2. Enable slides and understand HR boundaries:
   - [`slides: true` front matter](../../markdown/slides-front-matter/)
   - [thematicBreak / HR](../../markdown/thematic-break/)
3. Thin hub (navigation only): [Write and embed Markdown slides](../../markdown-slides/).
4. Live demo page when the runtime mounts the player: [Slides demo](../../slides-demo/).

## Canonical units (do not restate props here)

| Role | Unit page | Layer |
| --- | --- | --- |
| Enable slides path | [`slides-front-matter`](../../markdown/slides-front-matter/) | MD structure |
| Slide boundaries | [`thematic-break`](../../markdown/thematic-break/) | MD structure |
| AUP deck / slides player (Web-only widget) | [`deck`](../../../aup/widgets/deck/) | AUP widget — **not** a layout component |
| Optional rich media inside a slide | [`media`](../../../aup/primitives/media/) · [image (inline)](../../markdown/image/) | primitive / MD |

## Layer discipline

- **MD structures** (`slides: true`, HR) live under `/docs/web-device/markdown/…`.
- **`deck` is an AUP widget**, not a Web Device theme component and not a cross-device primitive. Contract: [deck widget](../../../aup/widgets/deck/).
- Do not treat layout components such as [`product-showcase`](../../components/product-showcase/) as slide APIs.

## Fallback honesty

Without `slides: true` → ordinary article. Without the slides widget in the runtime → server transcript only. Those statements are owned by the unit pages above; this recipe does not invent a third fallback story.

## Related

- [First site](../first-site/) if you still need a host site
- [Docs board](../docs-board/) if the slides object is a doc on a board
- [Showcase mapping](../../showcase-mapping/) for interactive AUP demos (separate from Markdown slides)

---

## Reference

URL: https://www.arcblock.io/en/docs/web-device/reference/

This section collects precise, version-bounded Web Device contracts. It is for lookup, not a replacement for task-oriented guides. A page that records a limitation or an unresolved public contract is intentionally not a promise of a hidden API.

## Read by question

- [Directory and file conventions](../directory-reference/) for file locations and compatibility inputs.
- [AUP layout boundary](../aup-reference/) for what a Web layout can accept.
- [Source-binding reference](../source-binding-reference/) for declared data-source boundaries.
- [Site configuration reference](../site-configuration-reference/) and [routes and locales reference](../routes-locales-reference/) for the currently verified configuration and URL surface.
- [Content access reference](../content-access-reference/) for `access`, `preview`, path rules, and the serve-time gate.
- [Bookmark and note (save capability)](../save-capability/) for `blocklet.yaml` `save:`, HTML attributes, and `/.actions/bookmark` / `/.actions/annotate`.
- [Component resolution](../built-in-components/) and [theme and token reference](../theme-token-reference/) for provider/resolver boundaries.
- **Unit pages (one capability per page):**
  - [Layout components](../components/) — default theme + site `.web/components`
  - [Surfaces](../surfaces/)
  - [Markdown directives & structures](../markdown/)
- [Version compatibility](../version-compatibility/) before carrying an example to another ARC release.

---

## Requirements and scope

URL: https://www.arcblock.io/en/docs/web-device/requirements-and-scope/

Start by treating Web Device as the web route of a local blocklet. It reads `.web/`, `pages/`, and, when you add it later, `content/`, then renders those source files as a static site. You do not need DID Space or a deployment to prove the first page works.

This path deliberately proves only one thing: from an empty directory, you can create, check, directly run, and inspect a static page in a browser. It does not yet prove a content collection, a theme library, CMS integration, publishing, or a production domain.

## Runtime used here

Every command on these first pages was run with `arc` `2.0.0-beta.25`:

```text
$ arc --version
2.0.0-beta.25
```

Check your version first:

```bash
arc --version
```

If it differs, do not assume the component-file shape or CLI output will match exactly. Read [Version compatibility](../version-compatibility/) and repeat the checks against your target version.

## Smallest useful boundary

Use an empty writable directory and make sure your shell can already find `arc`. If the command is unavailable, complete [Install ARC CLI](../install-arc-cli/) first. `arc blocklet run` chooses or reuses a local service and prints the actual URL, so this guide does not require you to choose a port in advance. The first site needs these files:

```text
my-site/
├── blocklet.yaml
├── .route/web
├── .web/
│   ├── site.yaml
│   └── components/hello/
│       ├── manifest.json
│       ├── render.js
│       └── style.css
└── pages/
    └── index/
        └── layout.aup
```

`blocklet.yaml` gives the runtime a blocklet identity. It includes a local DID, but that does not require you to create, sign in to, or deploy a DID Space. `.route/web` gives the root URL to Web Device. `.web/` contains site configuration and components, while `pages/` contains renderable page definitions. The next page creates each one.

## Keep local validation local

Use `arc blocklet run <directory>` and open the localhost URL it prints. That command runs the selected blocklet on your machine.

`arc deploy` and DID Space belong to a separate formal-publishing path. They do not replace the local validation in this guide, and you should not use them just to inspect a page.

## Known boundary

The current CLI has no narrow recipe that creates only a Web Device content site: `basic` creates blocklet metadata, while `minimal-app` also creates an AUP app, an agent, and settings. This guide begins with `basic` and writes the smallest explicit Web file tree.

The first example uses the compatibility component shape that actually passed in `2.0.0-beta.25`: `manifest.json`, `render.js`, and `style.css`. The source/generated relationship for component DSL belongs in a version-specific reference page. Do not infer from this first example that every version accepts only this shape.

---

## Routes and locales reference

URL: https://www.arcblock.io/en/docs/web-device/routes-locales-reference/

This table is the current route-family reference. It describes a route shape, not permission to claim every future slug is collision-free.

| Declaration | Route family |
| --- | --- |
| `pages/index/` | Home page `/` |
| `pages/about/` | Named page `/about/` |
| `content/articles/first-post/` | Collection and detail family such as `articles/first-post/` |
| Tagged content collection | `articles/tags/<tag>/` and pagination form |
| Archive-enabled collection | Year/month archive family |

`search` is a built-in path. Within a collection, `tags`, `page`, and `feed.xml` have dedicated meanings. Archive, pagination, tag, and feed rules can therefore shadow names that would otherwise look like ordinary slugs. Pick collection type names and common slugs before a large content migration, then build and inspect the relevant route family.

## Locale variants

Declare the default and supported locale set in `.web/site.yaml`:

```yaml
locale: en
locales:
  - en
  - zh
```

Then use sibling locale variants only where content changes:

| Default | Locale variant |
| --- | --- |
| `content.md` | `content.zh.md` |
| `layout.aup` | `layout.zh.aup` |
| `seo/title` | `seo/title.zh` |
| `seo/description` | `seo/description.zh` |

The runtime can derive a compatibility locale set from `.aup/locales/*.json` when `locales` is absent. A new site should declare the actual supported set in `site.yaml`; it gives authors, build, and review one explicit contract. Do not add `en/` and `zh/` directories under every page/object to create translations of the same thing.

Navigation is not routing. A menu link does not create a page, and a page directory does not decide which menu should expose it. Resolve the route first, then make a separate information-architecture choice for navigation.

For a walkthrough, read [Routes, navigation, and locales](../routes-navigation-locales/).

---

## Routes, navigation, and locales

URL: https://www.arcblock.io/en/docs/web-device/routes-navigation-locales/

Web Device paths begin with declared site structure, not strings scattered through components. `pages/` contributes named pages, `content/<type>/` contributes collections and detail objects, and a multi-locale site renders those paths in a locale view.

## The basic path model

The current runtime uses these foundational rules:

| Declaration | Typical serviceable path |
| --- | --- |
| `pages/index/` | The home page `/` |
| `pages/about/` | A named page `/about/` |
| `content/articles/first-post/` | Collection and detail paths such as `articles/first-post/` |
| A tagged content collection | `articles/tags/<tag>/` and its paginated form |
| A collection with archive enabled | Year and month archive paths |

Build and multi-locale preview put the site paths into a locale context. A site with `en` and `zh`, for example, can render `/en/about/` and `/zh/about/`. Do not create another `en/` or `zh/` directory beneath every content object to express a translation of the same item.

## Declare locales

The default locale and available locales belong in `.web/site.yaml`:

```yaml
locale: en
locales:
  - en
  - zh
```

When `locales` is absent, the current runtime can also derive a locale set from filenames under `.aup/locales/*.json`. That fallback suits an existing compatible app; a new site should explicitly state the languages it supports in `site.yaml`, so authors, builds, and reviewers operate against the same boundary.

Content bodies use locale files such as `content.zh.md`; page layouts use files such as `layout.zh.aup`; page SEO uses files such as `seo/title.zh` and `seo/description.zh`. Each overrides the default version in the same directory. Do not duplicate the whole site tree.

## The boundary between navigation and URLs

Navigation describes how readers discover pages. Routing describes whether the runtime can serve a URL. They often relate, but neither replaces the other:

- Adding a navigation link does not create a page or content object. First ensure the target path has a real page or content declaration.
- A page directory does not automatically mean it belongs in every navigation menu. Treat public information architecture as an explicit navigation decision.
- Hard-coding `/zh/`, `/en/`, or a content slug inside a component makes new locales, renames, and local preview more fragile. Prefer the current page locale and an already resolved object route.

## Watch reserved names and collection collisions

Web Device has declared built-in and collection route shapes. `search` is a built-in search path; `tags`, `page`, and `feed.xml` carry dedicated semantics inside a collection. Once archive, pagination, or tag pages are enabled, some paths that could otherwise be slugs are shadowed by route rules.

Choose collection type names and common slugs before creating a collection. After enabling archive, feed, or pagination, rebuild and run link checks. A directory being creatable does not mean every URL derived from it is collision-free.

## Local acceptance

1. Put the default locale and explicit locale list in `.web/site.yaml`.
2. Add one default content body and one `content.<locale>.md` body.
3. Give at least one page a locale title/description, and add a layout variant only when necessary.
4. Run `arc blocklet build .`; inspect generated pages and the sitemap for each language.
5. With the blocklet running directly locally, open each language page, one detail page, and one navigation link.

For content-variant reading, see [Content objects, metadata, and locales](/en/docs/web-device/content-and-objects/). For site configuration fields, see [Site-wide configuration](/en/docs/web-device/site-configuration/).

---

## Run, check, and inspect

URL: https://www.arcblock.io/en/docs/web-device/run-check-inspect/

From the `my-site/` directory created on the previous page, run:

```bash
arc dsl lint .
arc dsl validate .
arc blocklet check .
arc blocklet build .
```

On `2.0.0-beta.25`, the minimal site produced `Passed DSL lint`, `Passed DSL validation`, `Passed blocklet check (basic)`, and build output in `dist/`. That output is local build material. Do not commit it unless your project’s publishing process explicitly requires it.

## Run the current blocklet directly

```bash
arc blocklet run .
```

ARC reuses or starts a local daemon and prints the actual URL for this blocklet. The port and host depend on your machine, so copy the reported URL rather than constructing one by hand.

Open the primary URL printed by your command. Do not substitute a host or port from another machine, an example, or an earlier run. You should see:

- `Hello, Web Device` as the heading;
- `This page is rendered by a local blocklet.` as the body text;
- no horizontal overflow or browser console errors.

This browser check is the page acceptance step. DSL validation and build prove that the inputs can be processed; the browser proves what a reader will actually receive.

## Start with the first failure

| Symptom | Check first |
|---|---|
| `missing_web_component_file` | Confirm that `manifest.json`, `render.js`, and `style.css` live in the same custom-component directory. |
| The page says it has no direct app entry | Confirm `.route/web` exists and that `handler: web`, `source: .`, and `site` are correct. |
| `arc blocklet build` fails | Fix the first error from `arc dsl lint` or `arc dsl validate`, then build again. |
| The URL does not open | Do not deploy to DID Space. Check the exact host and port printed by the command, then check whether another local service already uses that port. |

You have now verified a minimal static site. Add content next through [Content objects, metadata, and locales](../content-and-objects/), or use [Reference](../reference/) when you need a particular field or syntax rule.

---

## Bookmark and note (save capability)

URL: https://www.arcblock.io/en/docs/web-device/save-capability/

Page bookmark and selection notes are a **blocklet-level capability**. Omit `save:` and it is on. Chrome stays hidden until the visitor is authenticated. This is not in-page review (`?review=1`), not comments, and not connect-service User Center.

Evidence for this page is the parser and runtime on Arc `feat/save-capability` ([arc#6715](https://github.com/ArcBlock/arc/issues/6715), [PR #6716](https://github.com/ArcBlock/arc/pull/6716)): `packages/core/src/blocklet/save-capability.ts`, `parse-manifest.ts` `save:`, `packages/aup/src/save-surface.ts`, `packages/aos/src/session/bookmark.ts`, `annotate.ts`. It is **not** a released `arc --version` tag. Do not treat this contract as present on an older host.

Motivation: [Bookmarking is a runtime capability, not a site plugin](/en/articles/save-as-runtime-capability/).

## Declare it

Write `save:` on the **blocklet** `blocklet.yaml`, not on `.web/site.yaml` and not on a single page.

| Input | Normalized `{ enabled, chrome }` | HTML `data-arc-save-capability` |
| --- | --- | --- |
| omitted / `null` / `true` | `{ enabled: true, chrome: "floating" }` | `floating` |
| `false` | `{ enabled: false, chrome: "floating" }` | `off` |
| `{ enabled: false }` | `{ enabled: false, chrome: "floating" }` | `off` |
| `{ chrome: "buttons" }` | `{ enabled: true, chrome: "buttons" }` | `buttons` |
| `{ enabled: true, chrome: "floating" }` | same | `floating` |

```yaml
# default: omit the field

save: false

save:
  enabled: false

save:
  chrome: buttons
```

### Field reference

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| `save` | `boolean` or object | omitted = on | Top-level `blocklet.yaml` key. Spec v1 and v2. |
| `save.enabled` | boolean | `true` unless the value is exactly `false` | Only `false` opts out. Missing key in the object still enables. |
| `save.chrome` | `"floating"` \| `"buttons"` | `"floating"` | Any other string is treated as `floating` at normalize time. The **parser** rejects unknown enum values. |
| object extra keys | n/a | n/a | Rejected (`.strict()`). `save: { chrome: floating, extra: 1 }` fails parse. |

Boolean `save: true` is accepted and equals the default.

## Auth gate

| Signal | Effect |
| --- | --- |
| `save` off (`data-arc-save-capability="off"`) | No chrome. Page `[data-arc-save]` controls stay hidden (`html:not([data-arc-save-ready]) [data-arc-save] { display: none }`). |
| Session missing or `authenticated: false` | Same as off for chrome. Capability declaration is unchanged. |
| Session `authenticated: true` and capability on | Sets `data-arc-save-ready` to `floating` or `buttons` and mounts that mode. |

Unauthenticated clicks on a save control that somehow remains visible open the header Login control, or `/login?redirect=<current path+query>`.

Web Device publishes session through `window.__arcSessionCtx` / `__arcSessionWaiters`. AUP also sends `msg.save` (`off` \| `floating` \| `buttons`) on render/stage frames when the blocklet module set `save`. Client copies that onto `window.__arcSave` and the HTML attribute before draining waiters.

Override order in the shared IIFE: `window.__arcSave` (string or `{ enabled, chrome }`) wins over the HTML attribute. Missing both → `floating`.

## Display modes

### `floating` (default)

After login, a side bar (`.arc-save-bar`, `data-arc-save="bar"`) with:

| Control | `data-arc-save` | Action |
| --- | --- | --- |
| Bookmark | `bookmark` | `exec("/.actions/bookmark", { url, title })` |
| My saves | `library` | navigate to `/{locale}/my/` |
| Selection | (mouseup) | if selected text length ≥ 2, open note popover → `/.actions/annotate` |

`url` is `window.location.href`. `title` is `document.title` when non-empty.

Locale for My saves: if `location.pathname` matches `^/([a-z]{2}(?:-[A-Za-z0-9]+)?)/`, use `/{that}/my/`. Otherwise `/my/`.

### `buttons`

No side bar. No automatic selection popover. Bind page-authored controls:

| `data-arc-save` | Required | Behavior when authed |
| --- | --- | --- |
| `bookmark` | yes for this mode | same bookmark exec; sets `aria-pressed` |
| `annotate` | optional | open note popover (uses current selection if any) |
| `library` | optional | go to `/{locale}/my/` |
| `bar` | runtime-only | ignored as a click target |

```html
<button type="button" data-arc-save="bookmark">Bookmark</button>
<button type="button" data-arc-save="annotate">Annotate</button>
<a data-arc-save="library">My saves</a>
```

Clicks bubble: the handler walks from the event target up until it finds a `data-arc-save` other than `bar`.

## HTML attributes

| Attribute | On | Values | Who writes it |
| --- | --- | --- | --- |
| `data-arc-save-capability` | `<html>` | `off` \| `floating` \| `buttons` | Web Device `finalizePageHtml` / `stampSaveCapabilityHtml`. AUP `handleAup` when `msg.save` is one of those three. |
| `data-arc-save-ready` | `<html>` | `floating` \| `buttons` | Client, only after authenticated + capability on. Removed when off or anonymous. |
| `data-arc-save` | controls | `bar` \| `bookmark` \| `annotate` \| `library` | Floating bar (runtime) or page author (buttons mode). |

Stamp is idempotent: if `data-arc-save-capability` is already on `<html>`, it is not rewritten. The attribute is appended **before** the tag closer so `lang` / `data-tone` stay in place.

## Actions

Both actions write into **this session's** caller DID Space. Wire `path` / `target` / `collection` are ignored. Workbench-private fields (`tagIds`, `status`, `collectionIds`, `dataVersion`, `version`) are rejected.

### `/.actions/bookmark`

| Arg | Required | Notes |
| --- | --- | --- |
| `url` | yes | Absolute `http:` or `https:` URL. Becomes `objectId`. |
| `title` | no | Record `name`. Untitled pages derive a label from the URL (last path segment or hostname). Label is not provenance. |
| `ctype` / `contentType` / `schemaType` | no | ABOUT types only: `link` (default), `place`, `product`. Unknown claimed types are refused, not coerced to `link`. |
| `notes` / `text` / `description` | no | Optional body fields on the L1 record. Floating chrome does not send them. |

Write path: `/user/bookmarks/{id}` with `id = b_` + first 16 bytes of SHA-256(`url`) as hex.

Success: `{ ok: true, id, path, copied }`. Duplicate URL: `copied: false` (same id).

| `error.code` | When |
| --- | --- |
| `unauthorized` | No `callerDid`, or write forbidden / not found on `/user` |
| `invalid-url` | Missing or not absolute http(s) |
| `unknown-type` | Claimed type is not `link` / `place` / `product` |
| `invalid-record` | Builtin schema validation failed |
| `workbench-private-field` | Payload still has a private Aside field |

### `/.actions/annotate`

| Arg | Required | Notes |
| --- | --- | --- |
| `url` | yes | Absolute http(s) page URL → `isBasedOn` |
| `quote` | yes unless `text` | Selected text → record `text` |
| `text` | alias of `quote` | Used if `quote` is empty |
| `note` | no | Optional; stored as record `name` |

Write path: `/user/notes/{id}` with `id = n_` + first 16 bytes of SHA-256(`url + "\n" + quote + "\n" + note`) as hex. `contentType: note`.

| `error.code` | When |
| --- | --- |
| `unauthorized` | No caller, or `/user` write denied |
| `invalid-url` | Missing or not absolute http(s) |
| `invalid-quote` | Both `quote` and `text` empty |
| `invalid-record` | Schema validation failed |
| `workbench-private-field` | Private Aside field present |

Floating chrome only opens the note popover when the current selection length is ≥ 2.

## `/my/` compositor

Built-in route: `/{locale}/my/` (same locale rule as My saves). Not `/.well-known/service/user`.

When save is on, sections always start with:

| id | label | path |
| --- | --- | --- |
| `bookmarks` | Bookmarks | `/user/bookmarks` |
| `notes` | Notes | `/user/notes` |

Then collections that set `faces.my: true` **and** live under `/user`. Duplicate `id` or `path` is skipped. Pass `{ save: false }` into `composeMyPageSections` (runtime does this when `save.enabled` is false): builtin bookmark/note sections disappear; extra `faces.my` collections remain.

## Failure and limits

| Boundary | Behavior |
| --- | --- |
| Parse unknown `save.chrome` | Manifest parse throws (enum) |
| Parse unknown object key | Manifest parse throws (strict) |
| Normalize garbage (array, random object) | Runtime treats as default on / floating, except `enabled: false` |
| Anonymous visitor | No chrome; `[data-arc-save]` hidden |
| `save: false` | Attribute `off`; `/my/` drops builtin sections |
| Action without login | `unauthorized` |
| Non-http(s) `url` | `invalid-url` |
| Selection length 0 or 1 in floating mode | No popover |
| Cross-site reading list | Not this capability. Records are this site's `/user/**` for this caller |
| In-page review | Different overlay. See [In-page review mode](../in-page-review/) |

## Related pages

- [Restrict who can read a page](../content-access/): public HTML vs logged-in writes
- [In-page review mode](../in-page-review/): authoring-time overlay, not reader save
- [Manifest and capabilities](/en/docs/blocklets/manifest-and-capabilities/): `save:` on the package
- Feature article: [Bookmarking is a runtime capability, not a site plugin](/en/articles/save-as-runtime-capability/)

---

## SEO, links, and accessibility

URL: https://www.arcblock.io/en/docs/web-device/seo-links-accessibility/

Web Device can assemble canonical and multi-locale `hreflang` links, Open Graph/Twitter metadata, and JSON-LD from site/page/content configuration. That automation makes the right structure available; it does not make the resulting page discoverable or accessible by itself.

## Give each level its own metadata

| Scope | Put it here |
| --- | --- |
| Site-wide title template, description, site identity, sharing defaults | `.web/site.yaml` `seo:` block |
| Page title/description and locale-specific variant | `pages/<name>/seo/` such as `title.zh` and `description.zh` |
| Content-object title, summary, date, and relationships | the object’s own content/front matter |

A page can also choose an `seo/og-type`. Do not compensate for missing page or object metadata by putting every title in the site-level configuration.

A denied access shell (`preview-shell` or `promo-shell`) always sends `X-Robots-Tag: noindex` and a robots meta tag. Its description may only use a declared SEO description or excerpt, never a summary derived from the protected body. See [Content access reference](../content-access-reference/).

## Know what automated checks cover

The static publishing doctor can block a static build with a missing build index, sitemap, robots file, or recognizable internal page dead link. Missing title is currently advisory rather than a block. The page-level SEO check is intentionally lightweight: it looks for title, description, H1 count, an `alt` attribute on `img`, and basic Open Graph fields.

That does **not** mean an image alt is meaningful, keyboard paths work, focus is visible, color contrast is adequate, external links work, or an embedded service endpoint is reachable. Those are author and reviewer responsibilities.

## A practical acceptance pass

1. Build the site and open the default locale plus every declared locale.
2. Inspect title, description, canonical, `hreflang`, and a sharing preview on representative pages.
3. Follow primary navigation and a content detail/list path; distinguish a known internal page from an external URL that cannot be statically verified.
4. At wide and narrow widths, use keyboard navigation, inspect focus, read image alternatives, and look for overflow or clipped text.
5. Review the page’s actual content hierarchy; one literal `H1` is not the same as a coherent reader-facing heading structure.

These checks are intentionally small enough to repeat. For route formation, see [Routes, navigation, and locales](../routes-navigation-locales/); for runtime/build failure categories, see [Diagnose a site](../diagnose/).

---

## Showcase mapping

URL: https://www.arcblock.io/en/docs/web-device/showcase-mapping/

**What this page is:** a public **mapping** from local Showcase routes to on-site **unit reference pages**.  
**What it is not:** production hosting of all Showcase pages, a multi-capability sample contract, or a second API manual.

Showcase proves that a named ARC checkout **can demonstrate** a type. It does **not** automatically make a docs-safe product sample. Unit contracts and sample honesty live on:

- `/docs/aup/primitives/<name>/`
- `/docs/aup/widgets/<name>/`

Internal full inventory (non-routed): `content/docs/aup/capability-matrix.md` §7.

## Two Showcase blocklets (ARC repo)

| Blocklet | Role | Canonical sources |
| --- | --- | --- |
| `blocklets/showcase-dsl` | DSL-authored companion (prefer for reading page sources) | `.aup/pages/*.aup`, `.aup/app.aup` |
| `blocklets/showcase` | JSON-tree companion (largely isomorphic page set; heavy test fixture) | `.aup/pages/*.json`, `.aup/app.json` |

Both live in the **ARC** repository (`ArcBlock/arc`), not in this site blocklet. This site only **links** unit docs and tells you how to run Showcase **locally**.

### Registration note (showcase-dsl)

`app.aup` loads `pages from "pages/*.aup" except [afs-list-searchable, degradation-demo, errors, globe]`, plus recipe pages `blocklet-settings`, `scaffold-app`, `afs-workspace`. Physical page files can exist without being registered.

## Run Showcase locally

Use a local ARC checkout that contains `blocklets/showcase-dsl` (and optionally `blocklets/showcase`). Commands below match the same direct-run pattern as [Run, check, and inspect](../run-check-inspect/) and [Validate, run, and inspect](../../aup/validate-run-inspect/): **do not** deploy to DID Space for this evidence path.

From the **ARC repository root**:

```bash
arc --version
# Expect a version you intend to map (docs matrix baseline: 2.0.0-beta.28).

# Preferred: serve the single showcase-dsl blocklet and use the printed URL
arc service start --blocklet blocklets/showcase-dsl --port 4901
```

Or, from the blocklet directory:

```bash
cd blocklets/showcase-dsl
arc blocklet run .
```

Open the **host and path the CLI prints** (often a `*.localhost` URL). Prefer that over inventing a host/port from another machine.

JSON companion (when you need the checked-in JSON tree or existing test fixtures):

```bash
# from ARC repo root
arc service start --blocklet blocklets/showcase --port 4902
```

Regenerate DSL → JSON only inside the ARC repo when you edit DSL sources (Showcase maintainers):

```bash
pnpm dsl:regen blocklets/showcase-dsl
```

This site does **not** publish that generation workflow as a product feature of www.arcblock.io.

### Stop when finished

```bash
arc service stop
# or stop only the daemon you started for this check — do not disrupt other local services you still need
```

## Primary primitive demos → unit pages

These Showcase **page ids** are the usual first stop for each **cross-device primitive**. Open the unit page for status, document caps, degradation, and sample honesty.

| Showcase page id | Primary primitive(s) | Unit page(s) | Notes |
| --- | --- | --- | --- |
| `chart` | `chart` | [`chart`](../../aup/primitives/chart/) | web-full demo; document target often unsupported — read unit |
| `map` | `map` (+ `globe` widget) | [`map`](../../aup/primitives/map/) · [`globe`](../../aup/widgets/globe/) | `globe` page file may exist but be **except**ed from app registration |
| `calendar` | `calendar` | [`calendar`](../../aup/primitives/calendar/) | |
| `time` | `time` | [`time`](../../aup/primitives/time/) | |
| `overlays` | `overlay` | [`overlay`](../../aup/primitives/overlay/) | interactive / experimental on document — read unit |
| `chat` | `chat` | [`chat`](../../aup/primitives/chat/) | often composed with `afs-list` |
| `device` | `surface` | [`surface`](../../aup/primitives/surface/) | not the Web Device **docs-page** surface |
| `subsystems` | `editor`, `canvas` | [`editor`](../../aup/primitives/editor/) · [`canvas`](../../aup/primitives/canvas/) | |
| `explorer` | `explorer` (+ AFS widgets) | [`explorer`](../../aup/primitives/explorer/) · [`afs-list`](../../aup/primitives/afs-list/) · [`afs-stat`](../../aup/widgets/afs-stat/) · [`afs-preview`](../../aup/widgets/afs-preview/) | |
| `list-basic` | `afs-list` | [`afs-list`](../../aup/primitives/afs-list/) · [`pagination` widget](../../aup/widgets/pagination/) | also see `list-*` rows below |
| `markdown` | `text` / `view` / `editor` | [`text`](../../aup/primitives/text/) · [`view`](../../aup/primitives/view/) · [`editor`](../../aup/primitives/editor/) | MD rendering contrast, not MD unit docs |
| `dashboard` | `view`, `input`, `table`, `action`, `media`, `time` | [`view`](../../aup/primitives/view/) · [`input`](../../aup/primitives/input/) · [`table`](../../aup/primitives/table/) · [`action`](../../aup/primitives/action/) · [`media`](../../aup/primitives/media/) · [`time`](../../aup/primitives/time/) | composition page |
| `form-contact` / `form-wizard` | `input`, `action`, `view` | [`input`](../../aup/primitives/input/) · [`action`](../../aup/primitives/action/) · [`view`](../../aup/primitives/view/) | form demos |
| `rtc` | *(no dedicated page id in the §7 scan)* | [`rtc`](../../aup/primitives/rtc/) | use unit + matrix; do not invent a Showcase row |

Hub indexes: [All primitives](../../aup/primitives/) · [Primitive taxonomy](../../aup/primitive-support-matrix/).

## Primary widget demos → unit pages

| Showcase page id | Primary widget(s) | Unit page(s) |
| --- | --- | --- |
| `prim-app-header` | `app-header` | [`app-header`](../../aup/widgets/app-header/) |
| `prim-app-footer` | `app-footer` | [`app-footer`](../../aup/widgets/app-footer/) |
| `prim-key-value-list` | `key-value-list`, `tooltip` | [`key-value-list`](../../aup/widgets/key-value-list/) · [`tooltip`](../../aup/widgets/tooltip/) |
| `finance` | `finance-chart` | [`finance-chart`](../../aup/widgets/finance-chart/) · [`chart` primitive](../../aup/primitives/chart/) |
| `moonphase` | `moonphase` | [`moonphase`](../../aup/widgets/moonphase/) |
| `natal` | `natal-chart` | [`natal-chart`](../../aup/widgets/natal-chart/) |
| `comments` | `comments-surface` (widget) | [`comments-surface` widget](../../aup/widgets/comments-surface/) — distinct from [Web Device `comments-surface` surface](../surfaces/comments-surface/) |
| `auto-surface` | `auto-surface` | [`auto-surface`](../../aup/widgets/auto-surface/) |
| `wm-desktop` | `wm` (+ `wm-surface`) | [`wm`](../../aup/widgets/wm/) · [`wm-surface`](../../aup/widgets/wm-surface/) |
| `tx-detail` | `entity-overview`, `key-value-list`, `tooltip` | [`entity-overview`](../../aup/widgets/entity-overview/) · [`key-value-list`](../../aup/widgets/key-value-list/) · [`tooltip`](../../aup/widgets/tooltip/) |
| `openai-home` | `agent` (among others) | [`agent`](../../aup/widgets/agent/) |

Hub: [All widgets](../../aup/widgets/).

## `afs-list` variant pages

| Showcase page id | Focus | Unit pages |
| --- | --- | --- |
| `list-basic` | base list | [`afs-list`](../../aup/primitives/afs-list/) · [`pagination`](../../aup/widgets/pagination/) |
| `list-pagination` | pagination | same |
| `list-template` | template | [`afs-list`](../../aup/primitives/afs-list/) · [`text`](../../aup/primitives/text/) · [`media`](../../aup/primitives/media/) |
| `list-grid` / `list-virtual` | layout modes | [`afs-list`](../../aup/primitives/afs-list/) |
| `list-fields-row` / `card` / `compact` / `media` / `hero` | field presentations | [`afs-list`](../../aup/primitives/afs-list/) · [`media`](../../aup/primitives/media/) · [`action`](../../aup/primitives/action/) |
| `afs-list-searchable` | searchable variants | **except**ed from app registration — physical page only; still map evidence to [`afs-list`](../../aup/primitives/afs-list/) |

## Composition / replica pages (map, do not treat as single-type samples)

These pages combine many primitives for product-shaped demos. Use them for **navigation and interaction** evidence, then open **one unit page per type** you care about.

| Showcase page id | Typical hits (non-exhaustive) | Start unit pages |
| --- | --- | --- |
| `index` | hub | [`view`](../../aup/primitives/view/) |
| `content` / `portal` / `report` / `workspace` | multi-primitive | [`view`](../../aup/primitives/view/) · [`table`](../../aup/primitives/table/) · [`afs-list`](../../aup/primitives/afs-list/) |
| `google` / `openai-home` / `openai-help` / `once` / `myvibe` / `unsplash` / `exposure` | layout replicas | [`view`](../../aup/primitives/view/) · [`media`](../../aup/primitives/media/) · [`input`](../../aup/primitives/input/) |
| `sh-climate` … `sh-living` | smart-home series | [`view`](../../aup/primitives/view/) · [`table`](../../aup/primitives/table/) · [`input`](../../aup/primitives/input/) |
| `session` / `session-chrome` | app chrome | [`app-header`](../../aup/widgets/app-header/) |
| `live-updates` | live list / terminal | [`afs-list`](../../aup/primitives/afs-list/) · [`explorer`](../../aup/primitives/explorer/) · [`terminal`](../../aup/widgets/terminal/) |
| `universal` / `supplementary` / `sharing` | multi | [`surface`](../../aup/primitives/surface/) · [`view`](../../aup/primitives/view/) |
| `set-sugar` | DSL sugar | [`afs-list`](../../aup/primitives/afs-list/) · [`text`](../../aup/primitives/text/) · [DSL language reference](../../aup/dsl-language-reference/) |
| `blocklet-settings` / `scaffold-app` / `afs-workspace` | **recipe** pages (not `pages/*.aup`) | see ARC scaffold / settings shells — not layout-component unit pages |

## Unregistered physical pages

| Page id | Registration | Use |
| --- | --- | --- |
| `degradation-demo` | **except** | degradation chains — [Device capabilities and degradation](../../aup/device-capabilities-degradation/) + primitive units |
| `errors` | **except** | error surfaces — [`surface`](../../aup/primitives/surface/) |
| `globe` | **except** | [`globe`](../../aup/widgets/globe/) (file may still exist under `pages/`) |
| `afs-list-searchable` | **except** | searchable `afs-list` variants |

## Widgets without a dedicated Showcase page name

Do **not** invent Showcase rows for widgets that only appear composed or not at all. Examples recorded in the matrix appendix include `deck`, `frame`, `ticker`, `hero-widget`, `breadcrumb`, `chip`, and others. Evidence for those types is on their [widget unit pages](../../aup/widgets/) and the internal matrix — not on this map as fake page ids.

Markdown slides on **this site** use MD units + `deck`, not a Showcase page: [Recipe: slides in an article](../recipes/slides-in-article/).

## How to use this map with unit docs

1. Pick a Showcase **page id** above and open it in your local Showcase run.
2. Open the linked **unit page** for each type you assert.
3. If you need a docs-safe sample on www.arcblock.io, that is a separate bar (`released` + sample contract on the unit page / #304) — Showcase alone is not enough.

## Related

- [Recipes hub](../recipes/)
- [AUP primitives hub](../../aup/primitives/)
- [AUP widgets hub](../../aup/widgets/)
- [Web Device components hub](../components/) (layout components — different layer from Showcase AUP trees)

---

## Site-wide configuration

URL: https://www.arcblock.io/en/docs/web-device/site-configuration/

`.web/site.yaml` is the current Web Device entry point for site-level configuration. It gathers scalar settings that were previously scattered across many `.web/` files, but it does not force every kind of file into YAML: tokens, redirects, and the logo retain their own suitable forms.

A conservative starting point is:

```yaml
locale: en
locales:
  - en
  - zh

seo:
  title: Example site
  description: A small site built with Web Device.
```

Write only keys you need and have verified against the target ARC version. The config document allows author comments, but the reader currently ignores unknown keys. That prevents a new key from making a site unreadable, and it also means a spelling mistake does not automatically become the behavior you intended.

## Configuration responsibilities

| What you configure | Location |
| --- | --- |
| Default locale, locale set, render mode, color scheme, comment switches, and detail sections | Top-level keys in `.web/site.yaml` |
| Site SEO and template-level values | The `seo:` and `template:` blocks in `site.yaml` |
| Shared-theme-library opt-in and AUP CSS tone/palette | The `theme:` block in `site.yaml` |
| Design tokens | `.web/tokens.json`, or the compatible `.web/tokens/` directory |
| Redirect rules | `.web/redirects` |
| Site logo asset | `.web/template/logo.svg` |

`site.yaml` and the older split-file layout can be read during the compatibility window. For the same configuration value, the YAML expression overrides the corresponding flat-file value. Prefer `site.yaml` for a new site, but do not bulk-delete historical files until the target consumer has been run.

The `theme:` block does **not** currently select a component-overlay directory below `.web/themes/<name>/`. In the current runtime, an active overlay is not a normal `site.yaml` authoring switch. Do not treat a tone or palette name as a component-theme directory name.

## Do not lift page settings into site settings

A site title, default locale, or theme selection belongs in `.web/`. A page's SEO title/description belongs in `pages/<name>/seo/`; an item's title, summary, date, and tags belong to its `content/<type>/<slug>/` object. Putting all of them into `site.yaml` erases the boundaries needed for page reuse, locale overrides, and content indexing.

## Accept a configuration change

1. Start with a minimal `site.yaml`, keeping existing token, redirect, and logo files.
2. Run `arc dsl validate .` and `arc blocklet check .`, then build the site.
3. In every declared locale, inspect the home-page title/description, links, and theme presentation.
4. When migrating from flat files, compare the rendered build item by item; do not only confirm that YAML parses.

Read [Routes, navigation, and locales](/en/docs/web-device/routes-navigation-locales/) for locale behavior, and [Themes and tokens](/en/docs/web-device/themes-tokens/) for the next visual layer.

---

## Site configuration reference

URL: https://www.arcblock.io/en/docs/web-device/site-configuration-reference/

`.web/site.yaml` is the current single-file form for site-level scalar configuration. It does not absorb every file in `.web/`.

| Responsibility | Location |
| --- | --- |
| Default `locale` and supported `locales` | Top-level YAML keys |
| Render mode, color scheme, comment switches, detail sections | Top-level YAML keys when needed |
| Site SEO and template-level values | `seo:` and `template:` blocks |
| Shared-theme-library opt-in and AUP CSS tone/palette | `theme:` block |
| Design tokens | `.web/tokens.json` or compatible `.web/tokens/` tree |
| Redirects | `.web/redirects` |
| Logo | `.web/template/logo.svg` |

`site.yaml` overrides corresponding legacy flat-file scalar values. Unknown YAML keys are ignored; malformed YAML falls back to legacy files rather than making the entire site unreadable. Neither behavior makes a typo safe; always inspect the rendered result.

The `theme:` block does not currently choose a `.web/themes/<name>/` component overlay. Keep component overlay selection out of a `tone` or `palette` assumption.

Page title/description belongs in `pages/<name>/seo/`; content-object metadata belongs beside its content. See [Site-wide configuration](../site-configuration/) for an authoring workflow and [Theme and token reference](../theme-token-reference/) for visual boundaries.

---

## Understand a site directory

URL: https://www.arcblock.io/en/docs/web-device/site-directory/

A Web Device site is not one large page configuration. It keeps three different responsibilities separate: page declarations in `pages/`, reader-facing content objects in `content/`, and site configuration, components, and visual system in `.web/`.

| Location | Owns | Does not own |
| --- | --- | --- |
| `pages/` | Page entry points, layouts, page SEO, and presentation rules for lists or details | Article or product body copy |
| `content/` | Identified content objects and their body, front matter, tags, and relationships | Site-wide component implementation |
| `.web/` | Site configuration, site components, tokens, themes, and template assets | The body of every content item |
| `.route/` | Declaring the blocklet's Web entry to a local or published runtime | Page implementation or content data |

A minimal directory can look like this:

```text
my-site/
├── .route/
│   └── web
├── .web/
│   ├── site.yaml
│   └── components/
│       └── site-home/
├── pages/
│   └── index/
│       └── layout.aup
└── content/
    └── articles/
        └── first-post/
            └── content.md
```

## Choose the directory by responsibility

Use this order to decide where a file belongs:

1. Does it define the presentation of a site URL? Put it in `pages/<name>/`.
2. Is it an identified object with a title, slug, body, or relationships that lists and detail pages will consume? Put it in `content/<type>/<slug>/`.
3. Does it affect components, configuration, templates, or visual behavior across pages? Put it in `.web/`.
4. Does it only hand the current directory to the Web runtime? Put it in `.route/`, not in a layout or content item.

The practical result is that one content object can be used by several pages or components without duplicating its body into a layout, and one component can serve several pages without making every object carry UI.

## Pages and content are not the same thing

`pages/index/` normally supplies the home-page entry point. An ordinary `pages/about/` directory supplies the `/about/` page entry point. The runtime also discovers collection types from `content/<type>/`, so a content collection can supply list and detail routes; that does not turn every content directory into a hand-authored page.

The page structure under `pages/` and the object structure under `content/` can evolve independently. For example, articles can remain under `content/articles/` while the site later gains a different home-page or list layout. Do not move original content just to change how it is displayed.

## `.web/` is the site layer, not a second content store

The current runtime treats `.web/site.yaml` as the single-file form of site-level configuration. Locale, `locales`, render mode, color scheme, comment switches, plus SEO, template, and theme settings each have an explicit site-layer home. `tokens.json`, `redirects`, and `template/logo.svg` remain independent files because they represent design tokens, line-oriented redirect rules, and an asset respectively.

Site components live in `.web/components/`. A page AUP layout composes those components. The runtime also has a separate static-tree path for supported native AUP nodes; that does not make arbitrary native nodes valid page-layout sections. Components remain the site layer for reusable Web HTML, styling, and interaction. See [Build a page with AUP](/en/docs/web-device/pages-and-aup/).

## Read next

- To make a page render, continue with [Build a page with AUP](/en/docs/web-device/pages-and-aup/).
- To create article, documentation, or product objects for pages to consume, continue with [Content objects, metadata, and locales](/en/docs/web-device/content-and-objects/).
- To check paths, locale prefixes, and reserved routes, continue with [Routes, navigation, and locales](/en/docs/web-device/routes-navigation-locales/).

This page describes the directory-reading boundary in ARC `2.0.0-beta.25`. Older Cookbook material or historical sites can use compatibility layouts; run the local checks before using an older convention as a new-site template.

---

## Slide lab · ceiling

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-ceiling/

<!-- @slide board=cover tone=hero mark=01 kicker="Ceiling" -->

# Not a document player

One decoration layer. Type, color, paper with rules. Same Markdown source.

<!--
Open with ?full. Decoration are AIGC plates + shells, not free CSS.
-->

---

<!-- @slide board=quote tone=dark mark=02 kicker="Thesis" -->

> The floor was low. The ceiling is not a free canvas.

---

<!-- @slide board=statement tone=paper mark=03 kicker="Model" -->

## Three layers. Stop there.

- **Paper** — `deckTheme`: type, color, gradient, pattern
- **Frame** — `@slide` board / tone / mark / kicker
- **Decoration** — one painted surface: AIGC plate or shell

---

<!-- @slide board=kpi tone=dark mark=04 kicker="Type" -->

## Display scale

**140**

px KPI — drama from type, not from more chrome

---

<!-- @slide board=media tone=dark mark=05 kicker="Ornament" -->

## AIGC is the decoration layer

::media{type="image" src="plates/01-paper-atmosphere.jpg" alt="Warm paper atmosphere, abstract editorial field"}

---

<!-- @slide board=media tone=dark mark=06 kicker="Dark" -->

## Mood without a second theme

::media{type="image" src="plates/02-dark-stage.jpg" alt="Dark charcoal stage with soft warm accent glow"}

---

<!-- @slide board=media tone=dark mark=07 kicker="Field" -->

## Pattern as field

::media{type="image" src="plates/03-ink-wash.jpg" alt="Sage ink wash abstract on warm paper"}

---

<!-- @slide board=media tone=dark mark=08 kicker="Set" -->

## Ornament set

::gallery{folder="plates" layout="mosaic"}

---

<!-- @slide board=statement tone=paper mark=09 kicker="Shell" -->

## Shells stay data

A chart is still decoration-with-data. Author names the series; runtime paints. No fake screenshot.

---

<!-- @slide tone=paper mark=10 kicker="Live" -->

## Series on stage

::chart{id="lab-ceiling-chart" variant="bar" labels='["Paper","Frame","Ornament"]' data='[3,5,7]' label="Weight" height="380px" title="Where the look comes from"}

---

<!-- @slide board=compare tone=dark mark=11 kicker="Bounds" -->

## Enough vs excess

| | enough | excess |
| --- | --- | --- |
| Paper | One theme stack | Per-page free hex |
| Frame | board + mark | Custom HTML layout |
| Decoration | One plate or shell | Stacked chrome |

---

<!-- @slide board=quote tone=paper mark=12 kicker="Honest" -->

> Free HTML is freer. This is still a keynote stage.

---

<!-- @slide board=close tone=dark mark=13 kicker="Next" -->

## Keep climbing

- Lock paper first (`deckTheme`)
- Frame every page (`@slide`)
- Add **one** decoration when the page needs atmosphere — AIGC plate or shell

::action{label="Editorial lab" href="/en/docs/web-device/slide-lab-editorial/?full" variant="primary"}

::action{label="Markdown slides guide" href="/en/docs/web-device/markdown-slides/" variant="secondary"}

---

## Slide lab · coolbackgrounds

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-coolbg/

<!-- @slide board=cover tone=hero -->

# Cool backgrounds

Signature looks — curated names, token dyes, no WebGL.

---

<!-- @slide board=statement tone=paper -->

## This deck

- Paper: `porcelain`
- Surface: `topo-soft` (whole deck)
- Switch in front matter to try `facet-soft` / `horizon-band`

---

<!-- @slide board=compare tone=paper -->

## The three

| id | coolbackgrounds echo |
| --- | --- |
| topo-soft | Gradient Topography rings |
| facet-soft | Trianglify facets |
| horizon-band | Hero horizon bands |

---

<!-- @slide board=quote tone=paper -->

> Atmosphere only. Type stays readable. One family per deck.

---

<!-- @slide board=close tone=paper -->

## Packs

::action{label="Kraft" href="/en/docs/web-device/slide-lab-kraft/?full" variant="primary"}

::action{label="Dune" href="/en/docs/web-device/slide-lab-dune/?full" variant="secondary"}

---

## Slide lab · dune

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-dune/

<!-- @slide board=cover tone=hero -->

# Dune sand

Charcoal on warm sand — still token-curated.

---

<!-- @slide board=quote tone=paper -->

> Cormorant display. Source Sans body. Contour rings under the type.

---

<!-- @slide board=statement tone=paper -->

## Defaults

- `deckTheme: dune`
- Default surface: `topo-soft`
- Fonts: Cormorant Garamond · Source Sans 3

---

<!-- @slide board=kpi tone=paper -->

## Contours

**topo-soft**

coolbackgrounds topography — static CSS only

---

<!-- @slide board=close tone=paper -->

## Next

::action{label="Kraft lab" href="/en/docs/web-device/slide-lab-kraft/?full" variant="primary"}

::action{label="Coolbg surfaces" href="/en/docs/web-device/slide-lab-coolbg/?full" variant="secondary"}

---

## Slide lab · editorial

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-editorial/

<!-- @slide board=cover tone=hero -->

# Editorial rhythm

One idea per page. Argument first. Atmosphere from CSS surface.

<!--
Lab deck for slide-write skill. Not a product launch narrative.
-->

---

<!-- @slide board=statement tone=paper -->

## One record, two surfaces

A Markdown content item can stay a readable transcript and mount a 16 by 9 player.

- Same source of truth
- Player is presentation chrome
- Transcript is still the article

---

<!-- @slide board=kpi tone=dark -->

## Primitives on deck

**18**

cross-device surfaces — not a valuation claim

---

<!-- @slide board=compare tone=paper -->

## Document path vs deck path

| | document | deck |
| --- | --- | --- |
| Goal | Scan and deep-read | One claim at a glance |
| Density | Prose ok | Overflow is a bug |
| Shells | Often degrade | Live when ARC supports |

---

<!-- @slide board=statement tone=paper -->

## What this lab proves

- Recipes + boards beat free-form MD
- Tone changes page mood without a second theme
- Gaps go to issues — not silence

---

<!-- @slide board=close tone=paper -->

## Keep exploring

::action{label="Markdown slides guide" href="/en/docs/web-device/markdown-slides/" variant="primary"}

::action{label="Visual lab" href="/en/docs/web-device/slide-lab-visual/" variant="secondary"}

---

## Slide lab · grid-dense

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-grid/

# Dense without clutter

More information per deck — not more noise per page.

<!--
grid-dense style: short tables and filled grids; still one idea per slide.
-->

---

## Plate grid

::gallery{folder="plates" layout="grid" cols="3"}

---

## Compact compare

| Signal | Prefer | Avoid |
| --- | --- | --- |
| Bullets | ≤5 | Walls of text |
| Table | ≤6 rows | Full matrices |
| Media | One host | Caption essays |

---

## Three rules

- Density is a **deck** property, not a slide dump
- Every page still fits 1280 by 720
- If a claim needs ten bullets, split pages

---

## What this lab proves

- grid-dense is still recipe-driven
- Compact tables beat prose lists for scan
- Overflow remains a hard fail

---

## Keep exploring

::action{label="Editorial lab" href="/en/docs/web-device/slide-lab-editorial/" variant="primary"}

::action{label="slide-write skill" href="https://github.com/ArcBlock/arcblock-site/tree/main/.claude/skills/slide-write" variant="secondary"}

---

## Slide lab · kraft

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-kraft/

<!-- @slide board=cover tone=hero -->

# Kraft paper

guizang warmth as a curated pack — not free hex.

---

<!-- @slide board=quote tone=paper -->

> Editorial stock. Baskerville titles. Grain you feel, not wallpaper you fight.

---

<!-- @slide board=statement tone=paper -->

## Defaults

- `deckTheme: kraft`
- Default surface: `paper-grain`
- Fonts: Libre Baskerville · Source Serif 4 · Noto Serif SC

---

<!-- @slide board=compare tone=paper -->

## Pairings

| surface | use |
| --- | --- |
| paper-grain | default kraft |
| warm-mesh | softer glow |
| topo-soft | coolbackgrounds contour |

---

<!-- @slide board=close tone=paper -->

## Next

::action{label="Dune lab" href="/en/docs/web-device/slide-lab-dune/?full" variant="primary"}

::action{label="Coolbg surfaces" href="/en/docs/web-device/slide-lab-coolbg/?full" variant="secondary"}

---

## Slide lab · shell-demo

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-shell/

# Shell demos

One primitive per page. Title plus shell. Boundaries live on a statement page.

<!--
Requires ARC with DEVICE_CAPS_DECK chart/map/calendar shells. Older ARC may degrade.
-->

---

## chart — bar

::chart{id="lab-shell-chart" variant="bar" labels='["Alpha","Beta","Gamma","Delta"]' data='[4,7,5,9]' label="Series" height="360px" title="Lab series"}

---

## map — harbor city

::map{id="lab-shell-map" tileStyle="carto-voyager" center='[37.7749,-122.4194]' zoom="11" height="380px" markers='[{"lat":37.8199,"lng":-122.4783,"label":"Bridge"},{"lat":37.7599,"lng":-122.4148,"label":"Mission"}]'}

---

## calendar — lab month

::calendar{id="lab-shell-cal" year="2026" month="8" title="August 2026" events='[{"date":"2026-08-14","label":"Lab ship","intent":"success"},{"date":"2026-08-28","label":"Review","intent":"info"}]'}

---

## Boundaries (read this once)

- Deck path can host readonly shells when ARC includes them
- Ordinary document pages may still degrade chart → table and map → media
- No write path, session bus, or product claim beyond the shell

---

## What this lab proves

- Shell pages stay visual-first
- Boundary text is a separate slide
- Missing shell on old ARC is a version gap, not a silent delete

---

## Keep exploring

::action{label="AUP capability tour" href="/en/docs/aup/capability-tour-slides/" variant="primary"}

::action{label="Device caps" href="/en/docs/aup/device-capabilities-degradation/" variant="secondary"}

---

## Slide lab · surface

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-surface/

<!-- @slide board=cover tone=hero -->

# Abstract paper

Cool often means the **background**. CSS surfaces — not free HTML.

<!--
Open with ?full. Requires ARC with deckSurface (#4085 / #4074).
-->

---

<!-- @slide board=quote tone=dark -->

> Zero images. Token-tied gradients. One family per deck.

---

<!-- @slide board=statement tone=paper -->

## How to apply

Front matter only — same idea as a PPT theme.

- `deckTheme` — paper, type, colors
- `deckSurface` — named abstract backdrop
- Omit surface → theme default (ink → warm-mesh)

---

<!-- @slide board=kpi tone=dark -->

## Weight

**0**

HTTP requests for the backdrop

---

<!-- @slide board=compare tone=paper -->

## Curated set

| id | feel |
| --- | --- |
| warm-mesh | soft dual radial (this deck) |
| cool-mesh | porcelain tech wash |
| radial-glow | dark corner light |
| grid-swiss | large Swiss grid |
| ink-wash | soft blot |

---

<!-- @slide board=statement tone=dark -->

## Discipline

- Low contrast — atmosphere, not wallpaper
- One surface family for the whole deck
- media-fill pages drop the pattern
- No free hex; no purple SaaS gradients

---

<!-- @slide board=close tone=paper -->

## Keep exploring

::action{label="Editorial lab (ink default)" href="/en/docs/web-device/slide-lab-editorial/?full" variant="primary"}

::action{label="Markdown slides guide" href="/en/docs/web-device/markdown-slides/" variant="secondary"}

---

## Slide lab · visual-first

URL: https://www.arcblock.io/en/docs/web-device/slide-lab-visual/

<!-- @slide board=cover tone=hero -->

# Visual first

Title plus one media surface. No essay under the photo.

<!--
Media is item-local under plates/. Runtime media-fill should own the stage.
-->

---

<!-- @slide board=media tone=dark -->

## Single plate

::media{type="image" src="plates/01-bridge.jpg" alt="Bridge spanning water"}

---

<!-- @slide board=media tone=dark -->

## Mosaic fill

::gallery{folder="plates" layout="mosaic"}

---

<!-- @slide board=media tone=dark -->

## Grid fill

::gallery{folder="plates" layout="grid" cols="3"}

---

<!-- @slide board=media tone=dark -->

## Sized stage

::gallery{folder="plates" layout="stage" ratio="16:9" width="100%"}

---

<!-- @slide board=statement tone=paper -->

## What this lab proves

- One media host per page keeps the frame clean
- mosaic / grid / stage are layout modes, not new content types
- If fill or immersion fails, record a gap — do not fake screenshots

---

<!-- @slide board=close tone=paper -->

## Keep exploring

::action{label="Folder-backed gallery" href="/en/docs/web-device/media-gallery/" variant="primary"}

::action{label="Capability tour media" href="/en/docs/aup/capability-tour-slides/" variant="secondary"}

---

## Web Device Slides demo

URL: https://www.arcblock.io/en/docs/web-device/slides-demo/

## One Markdown record, two reading modes

The same content can play in place and remain readable as a document.

<!--
This is a speaker note. In the transcript it becomes the narration beside this slide's card; it never appears in the player.
-->

---

## Keep the player in the page

Use the controls to move through the deck. Enter presentation mode with the fullscreen control, `f` while the player has focus, or a URL containing `?full`.

---

# The transcript is an article

---

## Keep the transcript in the document

Below the player, each slide renders as a card with its notes as narration. Click a card to play from that slide.

<!--
The page above this one contains only a level-1 heading, so it renders as the section title you just passed.
-->

---

## A slide with no note

A card without narration keeps the same size as every other card.

---

## Web Device Markdown Slides at a Glance

URL: https://www.arcblock.io/en/docs/web-device/slides-overview/

## One Markdown record, not two artifacts

Markdown Slides lets one piece of content remain a readable page and play inside that page.

<!--
The point is not to shrink an article into cards. It is to keep speaking and reading in one content record.
-->

---

## A page first, a presentation when needed

On the deck's own page, the player stays above the complete transcript. When it is embedded in an article, readers see the player itself.

---

## An author only declares and divides

Set `slides: true` and divide pages with top-level breaks. Once the site has the named layout, set `layout: slides` to mount the player.

---

## It can be truly embedded on the same site

Point `::embed` at the deck's site-absolute path. The result is a usable 16-by-9 player, not a static screenshot.

---

## Markdown is not the right home for every deck

Use another tool when a presentation needs a free-positioned canvas, an independent visual system, or extensive custom animation.

---

## Write something worth reading first

If a talk should still be read after it ends, Slides lets that page be presented when needed.

---

## Source-binding reference

URL: https://www.arcblock.io/en/docs/web-device/source-binding-reference/

A page- or collection-scope source is a four-field selection contract:

| File | Meaning | Required? |
| --- | --- | --- |
| `<name>` | A path under `/content/<type>/` | Yes |
| `<name>.sort` | Sort expression | No |
| `<name>.limit` | Maximum number of results | No |
| `<name>.filter` | One filter condition per line | No |

For example, `pages/topic/sources/related` is a source named `related` in the `topic` page scope.

## Filter behavior

One filter line is a field/value condition. Multiple lines are ANDed. Comma-separated values on one line are ORed. Current matching is exact and case-sensitive; an object without the named field does not match.

```text
tags=AFS,Web Device
category=Research
```

means “tag contains AFS or Web Device, and category exactly equals Research.” Start with an unfiltered collection before adding a sort, then a limit, then a filter; that makes an empty result diagnosable.

## Binding behavior

Use a source as a complete top-level layout prop value, for example:

```text
items=$source.related
```

The name resolves within the relevant page or collection scope. It is not a site-wide variable, and it should not be interpolated into arbitrary prose or assumed to resolve in a nested object. The current source-binding checks can identify an undeclared `$source.<name>` when the binding scope is knowable; some shared named-layout cases remain outside complete init-time coverage.

An invalid source path returns an empty result rather than reading outside the content root. An empty list can therefore mean a bad path, a filter/locale mismatch, or legitimately no matching objects; inspect the generated page rather than treating all emptiness as one error.

For an authoring walkthrough, see [Bind content to a page](../sources-bindings/).

---

## Bind content to a page

URL: https://www.arcblock.io/en/docs/web-device/sources-bindings/

A page should not hard-code the result of “find the six newest articles” into its layout. Declare a content source first, then reference it in a layout's top-level props. A source is a small four-field contract: `path`, optional `sort`, optional `limit`, and optional `filter`.

## Declare a source in page scope

A page can declare sources beneath `pages/<page>/sources/`. These files together define a source named `related`:

```text
pages/topic/sources/
├── related          # /content/articles/
├── related.sort     # -date
├── related.limit    # 6
└── related.filter   # tags=AFS,Web Device
                   # category=Research
```

The content of `related` is a source path such as `/content/articles/`. `.sort` and `.limit` are optional. `.filter` has one condition per line: lines are ANDed together; comma-separated values on one line are ORed. The example means “tag contains AFS or Web Device, and category exactly equals Research.” Field matching is currently exact and case-sensitive; an item without the field does not match.

A source path must live below `/content/<type>/`. It can point to a subpath inside a collection to narrow the scope. Do not write `..` or treat arbitrary filesystem paths as content sources. An invalid source path resolves to an empty result rather than reading outside the content root.

## Bind it in a layout

A source name resolves within its page or collection scope. A layout references it as a complete placeholder value, for example:

```text
items=$source.related
```

or reads an available path from it when needed. Do not mix `$source.related` into ordinary prose, and do not assume it will resolve in an arbitrary nested object: current source-binding checks treat complete `$source.<name>` values in a section's own top-level props as declarative bindings.

The same source name can mean a different query on a different page; it is not a site-wide global variable. `$source.related` on the `topic` page should be answered by `pages/topic/sources/related` (or a source declaration on that collection record), not by an identically named file on another page.

## Make empty results diagnosable

An undeclared `$source.<name>` used to make a page silently display an empty list. The current runtime can check whether a layout's required source is declared in the same scope and labels a problem `source-binding-undeclared`, including the names that scope did declare. Still inspect the browser result: a real source can also return an empty collection because of its path, filter, locale, or content.

Use this acceptance order:

1. Start with an unfiltered `/content/<type>/` source and verify that list and detail objects appear.
2. Add `sort`, then `limit`, and add a filter last.
3. After each layer, run the DSL/site checks and a build, then inspect the real page.
4. Give a component an explicit empty state for a legitimate zero-result case instead of hiding missing data.

For tags and relationships on content objects, see [Content objects, metadata, and locales](/en/docs/web-device/content-and-objects/). For complete field boundaries, see [Source-binding reference](/en/docs/web-device/source-binding-reference/).

---

## Surfaces

URL: https://www.arcblock.io/en/docs/web-device/surfaces/

This hub lists every **Web Device surface** package under `providers/runtime/web-device/surfaces/` (directories only; README excluded).

**Surfaces are not AUP primitives (`surface`), not `wm-surface` widgets, and not theme layout components.**

## All surfaces (5)

- [`comments-surface`](./comments-surface/)
- [`docs-page`](./docs-page/)
- [`in-page-toc`](./in-page-toc/)
- [`pagination`](./pagination/)
- [`search-page`](./search-page/)

## Counts

| Layer | Count |
| --- | ---: |
| Surfaces | 5 |

Also see [Layout components](../components/) and [Markdown](../markdown/).

---

## `comments-surface` surface

URL: https://www.arcblock.io/en/docs/web-device/surfaces/comments-surface/

**Web Device surface — not an AUP primitive (`surface`); not an AUP widget (`wm-surface` / same-named widgets); not a theme layout component.**

Package: `providers/runtime/web-device/surfaces/comments-surface/` (`manifest.json` + `render.js`).

## Purpose

Comment thread for the AFS path this page renders. Server output is a skeleton; the thread hydrates on the interactive path.

## Boundaries

- Surface packages are mounted by boards/routes/layout shells — they are not Markdown directives.
- Same type name as a widget does not merge layers; this page is the surface contract only.
- Do not document multiple surfaces on this page.

## Author entry

surface mount / AUP

Common author-facing props (from manifest): `target`, `title`, `composer`, `reactions`, `collect`, `requireAuth`, `emptyText`, `loginPromptText`, `composerText`, `errorText`, `retryText`, `messages`

## Surfaces

As implemented by this package (document shell, layout list, interactive site, etc. — see notes).

## Public status

`experimental`

## Fallback

Login empty state / empty thread prompts.

## Sample

No docs-safe live sample on this site yet. Use the evidence paths as source-only reference. Experimental units must not be described as released product capability.

## Evidence

| Item | Path |
| --- | --- |
| Surface package | `providers/runtime/web-device/surfaces/comments-surface/` |
| Manifest | `…/comments-surface/manifest.json` |
| Renderer | `…/comments-surface/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §4 (internal, non-routed) |
| Matrix row concept | surface · `comments-surface` |

## Notes

Same type name as the AUP widget `comments-surface`, but this page documents the Web Device **surface** package. Auth/identity prerequisites apply. Experimental.

## Related

- [Surfaces hub](../) — navigation only
- [Components hub](../../components/)
- [Markdown hub](../../markdown/)

---

## `docs-page` surface

URL: https://www.arcblock.io/en/docs/web-device/surfaces/docs-page/

**Web Device surface — not an AUP primitive (`surface`); not an AUP widget (`wm-surface` / same-named widgets); not a theme layout component.**

Package: `providers/runtime/web-device/surfaces/docs-page/` (`manifest.json` + `render.js`).

## Purpose

Documentation board shell: left nav, prose content, breadcrumb, previous/next, optional in-page TOC.

## Boundaries

- Surface packages are mounted by boards/routes/layout shells — they are not Markdown directives.
- Same type name as a widget does not merge layers; this page is the surface contract only.
- Do not document multiple surfaces on this page.

## Author entry

docs board / routes

Common author-facing props (from manifest): `siteName`, `current`, `basePath`, `sections`, `navTree`, `title`, `summary`, `eyebrow`, `docsRootPath`, `docsRootLabel`, `collectionLabel`, `collectionHref`, `toc`, `actionsHtml`, `collectionLanding`

## Surfaces

As implemented by this package (document shell, layout list, interactive site, etc. — see notes).

## Public status

`released`

## Fallback

—

## Sample

Live surface: the docs board shell that renders this documentation set. There is no separate fake HTML mock inside this page body — the shell *is* the evidence surface.

## Evidence

| Item | Path |
| --- | --- |
| Surface package | `providers/runtime/web-device/surfaces/docs-page/` |
| Manifest | `…/docs-page/manifest.json` |
| Renderer | `…/docs-page/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §4 (internal, non-routed) |
| Matrix row concept | surface · `docs-page` |

## Notes

Includes card-group CSS and related docs chrome. This is a surface shell, not a content Markdown sample.

## Related

- [Surfaces hub](../) — navigation only
- [Components hub](../../components/)
- [Markdown hub](../../markdown/)

---

## `in-page-toc` surface

URL: https://www.arcblock.io/en/docs/web-device/surfaces/in-page-toc/

**Web Device surface — not an AUP primitive (`surface`); not an AUP widget (`wm-surface` / same-named widgets); not a theme layout component.**

Package: `providers/runtime/web-device/surfaces/in-page-toc/` (`manifest.json` + `render.js`).

## Purpose

Shared in-page reading navigation built from headings on long-form content.

## Boundaries

- Surface packages are mounted by boards/routes/layout shells — they are not Markdown directives.
- Same type name as a widget does not merge layers; this page is the surface contract only.
- Do not document multiple surfaces on this page.

## Author entry

docs/page shell

Common author-facing props (from manifest): `entries`, `label`

## Surfaces

As implemented by this package (document shell, layout list, interactive site, etc. — see notes).

## Public status

`released`

## Fallback

No headings → empty TOC.

## Sample

Live surface: the docs board shell that renders this documentation set. There is no separate fake HTML mock inside this page body — the shell *is* the evidence surface.

## Evidence

| Item | Path |
| --- | --- |
| Surface package | `providers/runtime/web-device/surfaces/in-page-toc/` |
| Manifest | `…/in-page-toc/manifest.json` |
| Renderer | `…/in-page-toc/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §4 (internal, non-routed) |
| Matrix row concept | surface · `in-page-toc` |

## Notes

Mounted by docs-page and similar shells.

## Related

- [Surfaces hub](../) — navigation only
- [Components hub](../../components/)
- [Markdown hub](../../markdown/)

---

## `pagination` surface

URL: https://www.arcblock.io/en/docs/web-device/surfaces/pagination/

**Web Device surface — not an AUP primitive (`surface`); not an AUP widget (`wm-surface` / same-named widgets); not a theme layout component.**

Package: `providers/runtime/web-device/surfaces/pagination/` (`manifest.json` + `render.js`).

## Purpose

Prev/next and numbered pager for a statically paginated collection list page.

## Boundaries

- Surface packages are mounted by boards/routes/layout shells — they are not Markdown directives.
- Same type name as a widget does not merge layers; this page is the surface contract only.
- Do not document multiple surfaces on this page.

## Author entry

collection list layout

Common author-facing props (from manifest): `basePath`, `currentPage`, `totalPages`

## Surfaces

As implemented by this package (document shell, layout list, interactive site, etc. — see notes).

## Public status

`released`

## Fallback

Empty page → empty pager chrome.

## Sample

No isolated docs-safe live mock on this page. The contract is proven by site pages that mount this unit in `layout.aup` (or the docs shell). Copy author source from the evidence paths; do not invent props beyond the target `manifest.json`.

## Evidence

| Item | Path |
| --- | --- |
| Surface package | `providers/runtime/web-device/surfaces/pagination/` |
| Manifest | `…/pagination/manifest.json` |
| Renderer | `…/pagination/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §4 (internal, non-routed) |
| Matrix row concept | surface · `pagination` |

## Notes

Same type name as the AUP widget `pagination`, different layer. This page is the Web Device surface package.

## Related

- [Surfaces hub](../) — navigation only
- [Components hub](../../components/)
- [Markdown hub](../../markdown/)

---

## `search-page` surface

URL: https://www.arcblock.io/en/docs/web-device/surfaces/search-page/

**Web Device surface — not an AUP primitive (`surface`); not an AUP widget (`wm-surface` / same-named widgets); not a theme layout component.**

Package: `providers/runtime/web-device/surfaces/search-page/` (`manifest.json` + `render.js`).

## Purpose

Site-wide search page: input box plus client-side results driven by the standard AFS search op.

## Boundaries

- Surface packages are mounted by boards/routes/layout shells — they are not Markdown directives.
- Same type name as a widget does not merge layers; this page is the surface contract only.
- Do not document multiple surfaces on this page.

## Author entry

search route

Common author-facing props (from manifest): `basePath`, `title`, `placeholder`, `searchRoot`, `localeFilter`, `collections`

## Surfaces

As implemented by this package (document shell, layout list, interactive site, etc. — see notes).

## Public status

`released`

## Fallback

No results → empty results region.

## Sample

No docs-safe live sample on this site yet. Use the evidence paths as source-only reference. Experimental units must not be described as released product capability.

## Evidence

| Item | Path |
| --- | --- |
| Surface package | `providers/runtime/web-device/surfaces/search-page/` |
| Manifest | `…/search-page/manifest.json` |
| Renderer | `…/search-page/render.js` |
| Internal matrix | `docs/aup/capability-matrix.md` §4 (internal, non-routed) |
| Matrix row concept | surface · `search-page` |

## Notes

No separate docs-safe reference sample yet; live site search route is the evidence surface.

## Related

- [Surfaces hub](../) — navigation only
- [Components hub](../../components/)
- [Markdown hub](../../markdown/)

---

## Theme and token reference

URL: https://www.arcblock.io/en/docs/web-device/theme-token-reference/

## Token file

`.web/tokens.json` is independent of `.web/site.yaml`.

| Shape | Role |
| --- | --- |
| Top-level CSS custom-property values | Light/default token layer |
| `dark` object | Dark-mode override layer |
| Runtime default `--ds-*` values | Baseline design system tokens a site may override |

Treat it as trusted configuration. The reader filters some obvious style/script-injection patterns but is not an untrusted-CSS sandbox.

## Theme configuration

`site.yaml` can carry a `theme:` block for shared theme-library opt-in and AUP CSS tone/palette values. It does **not** currently make a `.web/themes/<name>/` directory active as a component overlay. A named local theme tree and a shared-library fallback also have different precedence behavior; new sites should avoid mixing them before a concrete target setup is tested.

At a high level, a local `.web/themes/` tree can affect token/SEO inheritance differently from a shared library fallback, while template structure remains site-layer-first. Do not rely on that subtle cascade for a first site; keep tokens in one explicit site-owned file and review the rendered result.

For the authoring guide, read [Themes and tokens](../themes-tokens/). If this reference does not settle a design question, verify the target setup before presenting a guessed theme contract.

---

## Themes and tokens

URL: https://www.arcblock.io/en/docs/web-device/themes-tokens/

Tokens make a visual decision reusable without forcing every page to carry its own color, type, and spacing rules. In a new site, put the common visual vocabulary in `.web/tokens.json` before inventing page-specific CSS exceptions.

## Declare light and dark token values

`tokens.json` is independent of `site.yaml`. Its top-level properties become the light/default CSS custom-property layer; its `dark` object supplies the dark-mode overrides. The runtime also provides default `--ds-*` design tokens and AUP palette/tone defaults. A site can override those values deliberately.

Keep a token semantic rather than local to a page. For example, name a token for a surface, reading width, or accent role, not for “the blue on the third card.” The second name makes a future redesign unnecessarily expensive.

## What `theme:` does and does not do

The `.web/site.yaml` `theme:` block can opt into the shared theme library and declare AUP CSS tone/palette values. It does not currently select a component overlay directory from `.web/themes/<name>/`. Do not write a tone name expecting it to replace a header or card component.

If a local `.web/themes/` tree is present, it is a distinct source with its own precedence behavior. In particular, local-theme token/SEO behavior and shared-library fallback do not have the same cascade. Until a concrete target setup has been tested, avoid mixing both systems in one new site.

## Review a visual-system change

1. Change the smallest set of semantic token values.
2. Build and open a representative content page plus the home page in light and dark presentation.
3. Check text contrast, focus visibility, images, and narrow-width wrapping manually.
4. If a page needs a structural change, make it in a component; do not encode layout behavior into a color token.

The current token reader filters some obvious style/script injection patterns. That is not a guarantee that arbitrary untrusted CSS is safe to accept. Treat the token file as trusted site configuration.

See [Theme and token reference](../theme-token-reference/) for compatibility notes and [Use and override components](../components-overrides/) for component-layer overrides.

---

## Understand a site

URL: https://www.arcblock.io/en/docs/web-device/understand/

This section explains the shape of an existing Web Device site: where files live, how pages form, how content is read, and how directories become routes and locale variants.

## Read in this order

1. [Site directory](../site-directory/) to separate the site layer, pages, and content objects.
2. [Build a page with AUP](../pages-and-aup/) to distinguish a Web layout from the separate static-tree renderer.
3. [Content objects, metadata, and locales](../content-and-objects/) to see what a reader object owns.
4. [Routes, navigation, and locales](../routes-navigation-locales/) to inspect the current URL and locale boundaries.

---

## Version compatibility

URL: https://www.arcblock.io/en/docs/web-device/version-compatibility/

Web Device compatibility has more than one moving part: the installed ARC CLI/runtime, the source checkout that may be ahead of it, a site’s source conventions, and generated compatibility material. Similar version names do not make those things interchangeable.

## Evidence used by this first board

| Claim type | Current evidence boundary |
| --- | --- |
| Serve-time content access gate, first-screen teaser, `access-gate` | `arc 2.0.0-beta.35` after [arc#4065](https://github.com/ArcBlock/arc/pull/4065); local capture on `http://arcblock.localhost:4922/` 2026-08-15 |
| Local command paths and minimal-site acceptance | `arc 2.0.0-beta.25` in an isolated local environment |
| Markdown Slides | A local ARC source build that contains the Web Device `slides` widget; no released version boundary is recorded on this board yet |
| Runtime implementation semantics | Current ARC source inspected while writing this board |
| Historical Cookbook/articles/issues | Context and design history only; not the default current contract |

When this page says a command was “run,” it means that command was exercised on beta.25 unless the page records another target. Markdown Slides is a newer source-level contract: verify that the target build contains the `slides` widget before relying on it. When this page says the runtime “currently reads” a directory or chooses a layout, it is sourced from the inspected implementation and should be rechecked if the installed version differs.

## Check before copying a pattern

```bash
arc --version
arc dsl validate .
arc blocklet check .
arc blocklet build .
arc blocklet run .
```

Use the installed version and the actual local output as the compatibility decision. If a historical site or article uses a different pattern, preserve it until the target version has been run; do not bulk-convert it just because a newer documentation page uses a newer source-first form.

## Keep compatibility artifacts in their own lane

JSON layouts/configuration and split `.web` files can remain supported compatibility forms. A new site should prefer the current documented AUP and `site.yaml` forms, but generated or historical files must only be removed after the concrete consumer has passed. A build that succeeds on one runtime does not prove an older deployment/runtime accepts the same source.

Record the CLI/runtime version, route, locale, browser/device target, and observed result with any UI acceptance evidence. That is more useful than claiming unqualified “latest” support.

---

## Web3 Kit

URL: https://www.arcblock.io/en/docs/web3-kit/

---

## How to install Point Up

URL: https://www.arcblock.io/en/docs/web3-kit/0oriCiUdAnTCJraiAnn2HrCP/

Point Up does not contain any practical business logic; it merely offers the most basic and purely points-related capabilities. As a result, its use case is more about being integrated into existing business logic.

For example, ArcBlock's [Aistro](https://www.aistro.io/) service is used in this way.

![UAVrRjxqARQywp1G.png](https://media.arcblock.io/lib/25/2588b36bdfca6f4bd3979609451ebb54.w1600.webp)

Next, we will install the Point Up combination step by step into an existing service (the version of Point Up is continuously being upgraded, and the version number is based on the latest version available in the Store):

### Step one, access the Blocklet Service Management Console

Enter blocklets

![截屏2024-12-09 19.46.09.png](https://media.arcblock.io/lib/5e/5edfd1eb8ebe20c0e7925d9b6d35803d.w1600.webp)

### Step two, click the "Add Blocklet" button and locate Point Up

Search for Point Up in the official ArcBlock Store

![截屏2024-12-09 19.49.15.png](https://media.arcblock.io/lib/58/58459c5df6a1d84a8b14882eff26d798.w1600.webp)

### Step three, click "Select" to begin the installation

Follow the guided steps to complete the final installation, and wait for the installation to finish.

![截屏2024-12-09 20.00.28.png](https://media.arcblock.io/lib/4f/4fc6e3462baf3631cca7ac5595c98b66.w1600.webp)

### Step four, launch Point Up and access its management page

Launch Point Up Blocklet

![截屏2024-12-09 20.03.03.png](https://media.arcblock.io/lib/97/975e3a8835ac399fba6b0900644649b6.w1600.webp)

成功启动后，进入其管理页面

![截屏2024-12-09 20.04.55.png](https://media.arcblock.io/lib/47/47d63dccbfbc10f9c7db27404d358d10.w1600.webp)

> When first launching the service, there will be a DID Connect process, which can be completed using a DID Wallet.

When you see the page below, the installation is complete.

![截屏2024-12-09 22.13.38.png](https://media.arcblock.io/lib/b0/b034912968e876df2911c81418a24630.w1600.webp)

---

## Rules for customizing badges

URL: https://www.arcblock.io/en/docs/web3-kit/2HSf8kiCdO4hrvqWpCwzcj0e/

Point Up also supports the configuration of customized badge rules. The context for these badge rules is that when we want users to perform certain specific actions within our business logic, we can reward them with personalized badges, allowing users to gain an additional sense of achievement while using the application.

Now, let's follow the steps to configure a set of our badge rules.

In this example, we will create the following action badges:

- First Post Badge
- First Comment Badge
- First Like Badge
- First-time Liked Badge

### Step one: locate the entry point to add badge rules

![UypeJGZOxbaXSnN7.png](https://media.arcblock.io/lib/2c/2c5b8983951ec41cabf38d6969325458.w1600.webp)

### ### Step two: Fill in the creation rules as required

![截屏2024-12-10 17.50.51.png](https://media.arcblock.io/lib/39/391608cb016f3ab5462241909af86a5a.w1600.webp)

After all maintenance is complete, we obtained this list

![截屏2024-12-10 17.54.54.png](https://media.arcblock.io/lib/bb/bba934780a08ada7df67e8002b76bfb1.w1600.webp)

At this point, we opened our badge wall page and found that all the badges were gray, in an unlit state.

![截屏2024-12-10 17.55.43.png](https://media.arcblock.io/lib/55/55fbe085a27d6d8f2b98ab9f93fa3777.w1600.webp)

Next, we will test the ability of the badge to be lit. Firstly, we return to the Admin Console and click through to test claiming the badge.

![Y8br9Ejx9gFglaGf.png](https://media.arcblock.io/lib/bb/bba934780a08ada7df67e8002b76bfb1.w1600.webp)

Then, returning to the current page, you will see that the badge wall has been illuminated.

![截屏2024-12-10 17.59.39.png](https://media.arcblock.io/lib/ad/ad2defaa9481e8897ac2d61b53506ad4.w1600.webp)

---

## In the Virtual Gift Card

URL: https://www.arcblock.io/en/docs/web3-kit/3zlXbJHWNJ6yK-3-vW5PBIWH/

If you have Virtual Gift Card installed in your service

[Virtual Gift Card](https://store.blocklet.dev/blocklets/z8iZscGk6ohCejHEiX16C7apdFC7JrPYD1J4Z)

We can create a new loyalty gift card and use this card to organize some promotional activities.

Next, we will attempt to create a points gift card.

First, we head to the Point Up management console to create a points rule for gift cards.

![截屏2024-12-10 20.23.12.png](https://media.arcblock.io/lib/76/76103ce6429953773dd4ff04133f2bbc.w1600.webp)

Next, we will go to the management console of Virtual Gift Card to create a reward gift card using this point rule.

![截屏2024-12-10 20.26.29.png](https://media.arcblock.io/lib/80/8008274d877860b07cf0d366f3e08d5c.w1600.webp)

Once the gift card creation is complete, you can share the gift card link for users to claim it:

![截屏2024-12-10 20.30.08.png](https://media.arcblock.io/lib/5b/5bd684b9d5e52bd548fdf529112fca5d.w1600.webp)

---

## In the DiscussKit

URL: https://www.arcblock.io/en/docs/web3-kit/499FakA8Y4zd6wVI5uPygaDz/

If DiscussKit is installed in your service

[Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu)

Then you can use the points rules in Point Up in a configurable way, just by opening the DiscussKit configuration page

![截屏2024-12-10 19.44.16.png](https://media.arcblock.io/lib/0f/0fc460e70b678903e19a71093ba09949.w1600.webp)

Next, we will go to the Point Up management console to create a points rule for "New Discussion," and then configure it to test the final effect.

![截屏2024-12-10 19.56.34.png](https://media.arcblock.io/lib/9c/9c1e8da64ff8ec1aebfc3b5eaafa96a1.w1600.webp)

![截屏2024-12-10 19.57.53.png](https://media.arcblock.io/lib/83/83f750836ac0802e5c2bb5a5bdf77290.w1600.webp)

We copy the ID into the configuration of DiscussKit

![截屏2024-12-10 20.02.51.png](https://media.arcblock.io/lib/e4/e4f723099c562438674cef4f02cb6a6a.w1600.webp)

and open the Notification of Discuss Kit

![截屏2024-12-10 20.09.40.png](https://media.arcblock.io/lib/9e/9ef3c1ab54edac10b618464a057ff983.w1600.webp)

Next, let's try creating a new post to see if the points can be successfully claimed.

<video src="https://media.arcblock.io/lib/bc/bc70d61ce2a28641e43e7e70c75e9ab5.qt" controls></video>

There are other configuration options that you can try following the steps above.

---

## How to use components from Store?

URL: https://www.arcblock.io/en/docs/web3-kit/5YYM961H0KXgQCb-bZEyXau4/

Pages Kit is designed with extensibility in mind. You can use custom components from [Blocklet Store](https://store.blocklet.dev/) to extend its capabilities.

Check out the following video tutorial on how to do that.

<video src="https://media.arcblock.io/lib/9e/9eb4b8cb246038451050dcd95a8fb1bb.mp4" controls></video>

---

## By calling through code

URL: https://www.arcblock.io/en/docs/web3-kit/6bnit3SxeP525kPix8X7E0Hc/

To use Point Up through configuration as mentioned above, the corresponding Blocklet must support the capability of Point Up. Implementing this capability is straightforward; it only requires specific API calls using the Blocklet SDK. If you are developing your own Blocklet and wish to integrate Point Up’s rewards functionality into your Blocklet's business logic, the following documentation will be of great help.

Next, we will list the APIs that can be called by other Blocklet combinations in Point Up.

### 1. Add points for the specified user DID based on the specified rules.

Example code for request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: '/api/add-point-cc',
    data: { ruleId: 'Add Point Rule ID', userDID: 'User DID' },
});
```

Successful return example:

```javascript
{

id: 'xxxx',

type: 0,

points: x,

userDID: 'User DID',

ruleId: 'Add Point Rule ID',

preRecordId: '',

isUndone: false
}
```

You can use your logic to properly store the id along with other valuable information for later use.

### 2 Revoke a Points Redemption Based on Points Earning Records

Example code for the request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: '/api/undo-add-point-cc',
    data: { ruleId: 'Add Point Rule ID', userDID: 'User DID', addPointRecordId: 'Add Point Record ID' }, // This addPointRecordId is saved from add-point-cc call
});
```

Example of successful return:

```javascript
{

id: 'xxxx',

type: 2,

points: -x,

userDID: 'User DID',

ruleId: 'Add Point Rule ID',

preRecordId: 'xxxx',

isUndone: false
}
```

You can combine your logic to store the ID and other useful information for future use.

### 3 Consume points for the designated user DID based on specified rules

Example code for requests:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: '/api/consume-point-cc',
    data: { ruleId: 'Consume Point Rule ID', userDID: 'User DID' },
});
```

Successful return example:

```javascript
{

id: 'xxxx',

type: 1,

points: x,

userDID: 'User DID',

ruleId: 'Consume Point Rule ID',

preRecordId: '',

isUndone: false
}
```

You can organize the ID along with other useful information for future reference.

### 4 Inquire about the details of a new points rule

Example code for request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: `/api/get-add-point-rule-info-cc/${id}`,
    method: 'GET',
    data: { },
});
```

Successful return example:

```javascript
{

id: 'xxxx',

points: x,

isLimited: x,

periodicType: x,

maxTimes: x,

desc: 'desc',

title: 'title',

isDisabled: x,

addedBy: 'Creator DID',

tTranslation: 'Title translation',
}
```

### 5 Query the details of a points-based rule

Sample code for request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: `/api/get-consume-point-rule-info-cc/${id}`,
    method: 'GET',
    data: { },
});
```

Successful return example:

```javascript
{

id: 'xxxx',

points: x,

desc: 'desc',

title: 'title',

isDisabled: x,

addedBy: 'Creator DID',

tTranslation: 'Title translation',
}
```

### 6 Query a Batch of Users' Points Overview

Example code for request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: '/api/batch-get-user-points-info-cc',
    params: { userDID: 'xxx,xxx,xxx' },
    method: 'GET',
});
```

Successful return example:

```javascript
[

{

did: 'xxxx',

maxPoints: x,

unUsedPoints: x,

},

{

did: 'xxxx',

maxPoints: x,

unUsedPoints: x,

},

//...
]
```

### 7 Query the points profile of a user

Example code for request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: `/api/get-user-points-info-cc/${userDID}`,
    data: { },
    method: 'GET',
});
```

Successful Return Example:

```javascript
{

did: 'xxxx',

maxPoints: x,

unUsedPoints: x,
}
```

### 8 Claim badges for the specified user DID

Example code for request:

```javascript
const component = require('@blocklet/sdk/lib/component');

// ...

const { data } = await component.call({
    name: 'z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA',
    path: '/api/add-badge-cc',
    data: { ruleId: 'Badge Rule ID', userDID: 'User DID'},
    method: 'POST',
});
```

Successful return example:

```javascript
{

id: 'xxxx',

userDID: 'User DID',

ruleId: 'Badge Rule ID',
}
```

---

## By configuring way

URL: https://www.arcblock.io/en/docs/web3-kit/7snlzmYzubTKYZ3z51jQhy68/

Some Blocklets now support the integration of Point Up's point system through configuration. Below are several common types of Blocklets.

- [In the DiscussKit](/en/docs/web3-kit/499FakA8Y4zd6wVI5uPygaDz/)

- [In the Virtual Gift Card](/en/docs/web3-kit/3zlXbJHWNJ6yK-3-vW5PBIWH/)

- [In the Lucky Draw](/en/docs/web3-kit/qYF6LHP7w2tSWTc2fnT3KcJU/)

---

## AD Kit (Beta)

URL: https://www.arcblock.io/en/docs/web3-kit/ad-kit-beta/

> * This blocklet is in beta and is not recommended for production use

## Overview

<strong>AD Kit</strong> is a kit that supports configuring advertisement space within a page

[AD Kit](https://test.store.blocklet.dev/blocklets/z8iZrdP3XNxaqzcHqTRewE3BdJiCfeMfNLzTc)

---

## AI Kit

URL: https://www.arcblock.io/en/docs/web3-kit/ai-kit/

## Overview

<strong>AI Kit</strong> is a AI-powered tools to help you and your team increase productivity by 10x!

Create content, SEO, analyze data, automate processes, design, and code faster and smarter....

<video src="https://media.arcblock.io/lib/b1/b15d9a00e3f946d2c10b40d273d6406a.mp4" controls></video>
* For more information, please visit the official website:  [https://www.web3kit.rocks/ai-kit](https://www.web3kit.rocks/ai-kit)

[AI Kit](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ)

---

## Daily Attendance

URL: https://www.arcblock.io/en/docs/web3-kit/daily-attendance/

## Overview

<strong>Daily Attendance</strong> is a kit to publish punch card activities

[Daily Attendance](https://dev.store.blocklet.dev/blocklets/z8iZma8NBMdASCpRd3Bj3JpfNYd1ySa7rtCSV)

---

## Discuss Kit

URL: https://www.arcblock.io/en/docs/web3-kit/discuss-kit/

## Overview

<strong>Discuss Kit</strong> is a kit offers highly customizable and combinable components for everything you need to decentralize communication.

Create a safe, free space for your group to share, discuss and discover new things with each other.

<video src="https://media.arcblock.io/lib/94/94d8114cefd1aa1472de46dcfa2db20e.mp4" controls></video>
* For more information, please visit the official website: [https://www.web3kit.rocks/discuss-kit](https://www.web3kit.rocks/discuss-kit)

[Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu)

---

## How to bookmark a website

URL: https://www.arcblock.io/en/docs/web3-kit/discuss-kit-how-to-bookmark-a-website/

If you come across a website and content that you like, and want to bookmark it, Discuss Kit's Bookmark module can help you complete this task more efficiently!

## How to bookmark a website

To bookmark a website, you can do it in two ways:

1. Through remote URL
2. Through bookmarklet

### Through remote URL

First, you can fill in the URL address that needs to be bookmarked at the URL field and click the "Pick" button.

![image.png](https://media.arcblock.io/lib/d6/d63a647d940d39e8e15e61cd4805ae32.w1600.webp)

Please wait a moment, the search content will appear shortly. At this time, you can modify the options in the form to match your needs.

The most important thing is to support inputting your own comments and thoughts about this website.

![image.png](https://media.arcblock.io/lib/21/21a70f832cd92326456c0c352b3af3b9.w1600.webp)

Click the Pick button to complete the bookmark, and you will be redirected to the details page, where you can perform more operations.

![image.png](https://media.arcblock.io/lib/dc/dc8c91a69975f7d829cb64ed2b6bc8a3.w1600.webp)

Return to the list page, you can see that there is one more record.

![image.png](https://media.arcblock.io/lib/ed/edc6b4ba2d938c56a7d569c4889db0a9.w1600.webp)

### Through bookmarklet

First, by clicking the Pick button, you can open the Pick Dialog and drag the bookmark widget to the favorites bar.

![image.png](https://media.arcblock.io/lib/9a/9ace2f06c5ab13c8572fe88e586054ac.w1600.webp)

When browsing a website normally, if you come across a website you like, feel free to click on the bookmark widget, which will pop up a new window for bookmark information where you can add comments and further details.

![image.png](https://media.arcblock.io/lib/1f/1f2cc08fb8eefebf549f00802319f34b.w1600.webp)

If encountered with a situation where data cannot be bookmarked properly, a dialog box will pop up.

At this point, clicking on Add To Bookmark will continue the above process.

![image.png](https://media.arcblock.io/lib/cb/cbdfe4d0a158fd12c23a840ad507fa55.w1600.webp)

---

## Discuss Kit

URL: https://www.arcblock.io/en/docs/web3-kit/discuss-kit-how-to-use/

- [How to use the Blog Module](/en/docs/web3-kit/discuss-kit-how-to-use-blog-module/)

- [How to use the Doc Module](/en/docs/web3-kit/knTFBHMMfx_nWfLU2S2-_6KB/)

- [How to bookmark a website](/en/docs/web3-kit/discuss-kit-how-to-bookmark-a-website/)

- [Preference Setting](/en/docs/web3-kit/discuss-kit-preference-setting/)

---

## How to use the Blog Module

URL: https://www.arcblock.io/en/docs/web3-kit/discuss-kit-how-to-use-blog-module/

If you encounter something happy and want to record it, then the Blog Module of Discuss Kit can help you accomplish this!

## How to use

First, we open the Blog Module, click on the Post button, and it will take you to an immersive page where you can focus on writing your blog.

![image.png](https://media.arcblock.io/lib/7e/7e22d7dfd80025d2bbc4a36a10ec47d9.w1600.webp)

In the webpage, we refine the content of the Blog and set a Title. During the writing process, the system will automatically save.

It is worth noting the "Draft" status in the top left corner, indicating that the current modifications have not been published. At the moment, only administrators and yourself can see this blog. If you need to publish it, please click the "Publish" button in the top right corner.

![image.png](https://media.arcblock.io/lib/3b/3bc0ae8543ce7dcad8578a93d2e1b480.w1600.webp)

Of course we can also determine whether the Blog is in Draft status through the icon on the list page and details page.

![image.png](https://media.arcblock.io/lib/8b/8bd6d1bd138c61a227d8377376961be2.w1600.webp)

![image.png](https://media.arcblock.io/lib/7f/7fc0d0b71bda7782678cfccdc5541095.w1600.webp)

At the same time, on the editing page, you can also click on this icon to do more settings, including: scheduled publishing, setting slug, viewing history, and other functions.

![image.png](https://media.arcblock.io/lib/c3/c3d72b174fe90ade30c56af3aa249dc3.w1600.webp)

You can also set up different language versions for people in different countries to watch

![image.png](https://media.arcblock.io/lib/40/403c35c2ef9b5c5b1b9f9bc09bfc5555.w1600.webp)

More content awaits your further exploration!

---

## Preference Setting

URL: https://www.arcblock.io/en/docs/web3-kit/discuss-kit-preference-setting/

I hope this document can help everyone understand how to set preferences for Discuss Kit.

Currently, the Discuss Kit includes the following modules:

- Manage Module
-
  - Board Manager
  - Label Manager
  - Collection Manager (WIP)
- Post Module
-
  - Discussion
  - Blog
  - Doc
  - Bookmark
  - Chat
- User Profile

These modules are all related in Discuss Kit, with some of our preference configurations placed in Discuss Kit, and the rest in Blocklet's Configuration. Please don't worry, the documents below will detail where the preference configuration entry for each module is.

Side note: If Luci wants to view a Discussion written by Jack, they may go through the following process.

Label Manager
Important
Useless
Board Manager
Discussion
Boards
Blog
Doc
Bookmark
I need a new post
what is the post type?
Yes!
Select board from
Discussion Boards
I can add to a board
Select any labels
I can add to any labels
Done
Notice
Post Module
User Profile
Feeds
Comments
Following
...
go to luci user Profile
Jack
Luci
I want to see Jack Discussion
go to jack user Profile
go to discussion list

## Manager Module

### Board Manager

First of all, it needs to be clear that: each Post Module has a Board Manager entry, and the Boards of different Post Modules are independent of each other. For example, Docs cannot be mounted on Discussion Boards.

Taking Discussion as an example, you can enter Board Manager by clicking on Manage Boards.

![image.png](https://media.arcblock.io/lib/98/98e1c8fa877f8c52feb1bac4f3c03d83.w1600.webp)

In the Board Manager, you can filter by Post Module, and you can also perform a series of operations on the Board.

![image.png](https://media.arcblock.io/lib/c7/c7e9cc3e225faeeec081e8601c8a2705.w1600.webp)

It is worth mentioning that, due to the fact that the permission mechanism of Discuss Kit is implemented through Passport, in the configuration of Board, Passports can be configured to be visible to some users.

![image.png](https://media.arcblock.io/lib/98/98d5356ba2469da68c1f4f13cd83537f.w1600.webp)

### Label Manager

Label Manager is similar to Board Manager, but it is not associated with any Post Module. For example, there is a label called Important, which can be used to mark both documents and discussions.

Taking Discussion as an example, you can enter the Label Manager by clicking on the Label Icon - Edit Labels.

![image.png](https://media.arcblock.io/lib/ac/ac50ab84091704b844ee9abcebb174cc.w1600.webp)

In Label Manager, you can perform a series of operations on labels.

![image.png](https://media.arcblock.io/lib/d9/d9e71b11ae5ed98a472b4848b9fca3dc.w1600.webp)

It is worth mentioning that Labels also support specifying Passports, which allows users holding specific Passports to use Labels to mark Posts.

![image.png](https://media.arcblock.io/lib/e2/e2249bb10cebed4ab9843724a7f863bc.w1600.webp)

### Collection Manager

The feature is still under development, please stay tuned for updates.

## Post Module

The configuration of the Post Module is generally found in Dashboard - Configuration - Preferences - Discuss Kit. Administrators can access it through the profile menu in the upper right corner.

![image.png](https://media.arcblock.io/lib/54/54b37580e235525f417ffe7e6e7808db.w1600.webp)

After entering the settings page, you can perform some basic site settings in Configuration.

![image.png](https://media.arcblock.io/lib/39/3928f18b2bb679c99b4a378282bdb26a.w1600.webp)

Also can add some new navigation to the site.

![image.png](https://media.arcblock.io/lib/51/51af8478f65173b2435f6f40377d8712.w1600.webp)

In the preference settings, many tabs are also divided, corresponding to different post modules. The vast majority of settings do not require restarting the blocklet. Of course, if you find that the saved settings are not taking effect, you can try restarting.

![image.png](https://media.arcblock.io/lib/63/63f1a826a6a56f0fd337d15a99575852.w1600.webp)

### Discussion

Module configuration for Discussion, by selecting the Common Tab and Discussions Tab, the functional configuration remains consistent with the text description, and administrators can choose as needed.

If you need to modify the Title and Description of the Banner, you can go to the Common Tab to define the Banner.

![image.png](https://media.arcblock.io/lib/d0/d0cc296fdbf803ee9ba3e5d37a7ee560.w1600.webp)

It is worth mentioning that, if you need BBS/Forum functionality, it is recommended to go to the Discussions Tab and adjust these two options to the ones in the image below, for a better reading experience.

![image.png](https://media.arcblock.io/lib/8f/8f91ff42a08994e3c9c5e1d923b0b8b1.w1600.webp)

### Blog

Module configuration of Blog, configured through selecting the Blog Tab.

It is worth noting that the options for the Blog Template support both the Standard template and the Corp template. If you need to publish a more stylish business blog, then Corp is an option.

![image.png](https://media.arcblock.io/lib/14/14212acd8fac56978226a1cc12982fb0.w1600.webp)

### Doc

Doc's module configuration is mainly within the Discuss Kit application.

When creating a Board of type Doc, if you choose to upload a Cover, then the Cover will be displayed on the cover.

![image.png](https://media.arcblock.io/lib/6b/6b147416ba096c5588f0013c9eefe0d9.w1600.webp)

Its corresponding position is here.

![image.png](https://media.arcblock.io/lib/e2/e2722328e4afafd023b2ab27a7ee924b.w1600.webp)

### Bookmark

The module configuration of Bookmark is configured by selecting the Bookmarks Tab.

Support configuration allows regular users to collect bookmarks.

![image.png](https://media.arcblock.io/lib/5d/5d327a63e8e89577775083af68f33c57.w1600.webp)

### Chat

There is currently no module configuration for Chat, please stay tuned.

## User Profile

User Profile can be accessed through the avatar in the upper right corner. It will redirect to a new page.

![image.png](https://media.arcblock.io/lib/ef/ef3bbcd679157f5f63a3e92fd973ccf5.w1600.webp)

By clicking on the icon, you can set preferences for individual notifications, personal privacy, and login status.

![image.png](https://media.arcblock.io/lib/7f/7fe9e7bc9b11fef659edb24986a05041.w1600.webp)

---

## Rules for using points

URL: https://www.arcblock.io/en/docs/web3-kit/dXYPPMrwE8AWY3wsee8HTklN/

Access the Point Up management console, navigate to the "Usage Points Rules" tab, and click the add button on the page to begin creating your first usage points rule.

![截屏2024-12-09 22.36.26.png](https://media.arcblock.io/lib/ba/ba8a1304b0dad65774fd16bc580e7b5b.w1600.webp)

Maintain the rules according to usage requirements and confirm the additions.

![截屏2024-12-09 22.50.19.png](https://media.arcblock.io/lib/ee/ee37b58262981032937710083f028f9e.w1600.webp)

After adding is complete, the rule list will refresh automatically:

![截屏2024-12-09 22.53.22.png](https://media.arcblock.io/lib/93/9359f6e665d9a9a19977e30ea8bf02e6.w1600.webp)

At this point, we can click the test button to check if the points usage feature is functioning properly.

<video src="https://media.arcblock.io/lib/e5/e5e90e704c216182122d2be87a8d8e40.qt" controls></video>

---

## Pages Kit

URL: https://www.arcblock.io/en/docs/web3-kit/H0Ao1YnQMDzt0ful7jZTCKvT/

- [Custom Component](/en/docs/web3-kit/pages-kit-custom-component/)

- [How to use components from Store?](/en/docs/web3-kit/5YYM961H0KXgQCb-bZEyXau4/)

---

## How to use the Doc Module

URL: https://www.arcblock.io/en/docs/web3-kit/knTFBHMMfx_nWfLU2S2-_6KB/

If you encounter a scenario where you need to provide documents to other users, then the Doc Module of Discuss Kit can help you accomplish this task!

## How to use

First we open the Doc Module, where we can see a list page with Boards management attached above. Clicking on it will take us to the Doc Boards settings page.

In the list page, it categorizes each document and lists them out like a booklet, and each booklet belongs to a Board.

![image.png](https://media.arcblock.io/lib/ae/ae1ac4e537cb1c57f024c91b30ca4afc.w1600.webp)

In the Doc Board configuration, additional configurations for Cover and Description are supported, and they will apply to the booklet.

![image.png](https://media.arcblock.io/lib/b7/b7309a2d8bf7ae3a5ffbcd1dc6877abe.w1600.webp)![image.png](https://media.arcblock.io/lib/18/18d926dfd15f60c2b29a4b77fa86bdd0.w1600.webp)

Click on one of the small booklets to enter the Doc details page, where you can see some common operations inside.

![image.png](https://media.arcblock.io/lib/4c/4c6947f32b2408fe8865dc3294ae63a9.w1600.webp)

Modify document content to support generating a sub-document directory using  `/Subpage Listing` (only supported in the Doc Module)

![image.png](https://media.arcblock.io/lib/13/1310622d670d9427c7152c63534d87e6.w1600.webp)

Support clicking on the current document's +, add a sub-document to the document ![image.png](https://media.arcblock.io/lib/6f/6fe1c278a6a4b8fe69fb9cac9cff5dbf.w1600.webp).

After saving, you can view the parent document to see the newly created sub-document.

![image.png](https://media.arcblock.io/lib/71/716cdd141edb1aae554b121a58198459.w1600.webp)

For multiple documents, support sorting by long-pressing the document, and you can also drag the sub-document out to detach it from the parent document.

![image.png](https://media.arcblock.io/lib/10/102d13b3d66bbe58266cde898d6c6f98.w1600.webp)

In the Doc module, the Doc menu is automatically generated based on the contents of H1, H2, H3, etc.

Please refer to this page
[偏好设置](/en/docs/web3-kit/discuss-kit-preference-setting/)


![image.png](https://media.arcblock.io/lib/4d/4d1b216e5b42fcd4d5531fd1ebe6a0da.w1600.webp)

Supporting different language versions for documents, allowing people from different countries to view them.

![image.png](https://media.arcblock.io/lib/e3/e378f25f85b09a830a32dd5f8e369af4.w1600.webp)

More content awaits your further exploration!

---

## Lucky Draw

URL: https://www.arcblock.io/en/docs/web3-kit/lucky-draw/

## Overview

<strong>Lucky Draw</strong> is a kit that allows you to publish sweepstakes

[Lucky Draw](https://dev.store.blocklet.dev/blocklets/z2qaDrNKHv1PeXuSd9Er2kF9uLRPgJ2gxtcfA?tab=info)

---

## How to configure point rules

URL: https://www.arcblock.io/en/docs/web3-kit/Njj-D5qbcpeEIv_P5WC68QKp/

Point Up supports various types of points rules, which can be configured as per the documentation below.

- [Rules for earning points](/en/docs/web3-kit/OdUMkQ8InF47_n-ZLWGO1Fe5/)

- [Rules for using points](/en/docs/web3-kit/dXYPPMrwE8AWY3wsee8HTklN/)

- [Rules of the points level](/en/docs/web3-kit/TWoYzA66FxfDsNHUo1z-eLvT/)

- [Rules for customizing badges](/en/docs/web3-kit/2HSf8kiCdO4hrvqWpCwzcj0e/)

---

## Rules for earning points

URL: https://www.arcblock.io/en/docs/web3-kit/OdUMkQ8InF47_n-ZLWGO1Fe5/

Open the management console of Point Up, switch to the "Earning Points Rules" tab, and then click the add button on the page to start adding your first earning points rule.

![截屏2024-12-09 22.17.28.png](https://media.arcblock.io/lib/db/db5c7661714c4e08acf3624454e45b7e.w1600.webp)

Maintain the rules per the requirements for adding rules, and confirm the addition.

The rules for earning points can be set to include a limit on the number of times points can be earned. When the limit is enabled, you can add restrictions:

- Each user can have a maximum of N times per day
- Each user can access a maximum of N times per week
- Each user can have a maximum of N times per month
- Each user can have a maximum of N times per year

For example, in the following scenario, I have set a limit that each user can trigger this rule to earn points a maximum of two times per day.

![截屏2024-12-09 22.20.13.png](https://media.arcblock.io/lib/e7/e75e578e8f1b597720950c093f0f5591.w1600.webp)

After adding is complete, the rule list will refresh automatically:

![g0p3L7IqPlLZZDh1.png](https://media.arcblock.io/lib/ed/edddf6a4d516daf750bd5802798f7c82.w1600.webp)

At this stage, we can click the test button to verify that the points functionality works correctly.

<video src="https://media.arcblock.io/lib/b2/b2f1cc87ca5f8ee54a17b3c39f5f8d48.qt" controls></video>

---

## Pages Kit

URL: https://www.arcblock.io/en/docs/web3-kit/pages-kit/

## Overview

<strong>Pages Kit</strong> is a powerful tool that helps you and your team easily and quickly build beautiful websites.

It is a new generation of no-code WYSIWYG AI-supported content management system that integrates simplicity, AI, and decentralization into web design Blocklet.

<video src="https://media.arcblock.io/lib/99/99bda744c1d165979ab1f837d9ac0d93.mp4" controls></video>
* For more information, please visit the official website: [https://www.web3kit.rocks/pages-kit](https://www.web3kit.rocks/pages-kit)

[Pages Kit](https://store.blocklet.dev/blocklets/z8iZiDFg3vkkrPwsiba1TLXy3H9XHzFERsP8o)

---

## Built-in Package List

URL: https://www.arcblock.io/en/docs/web3-kit/pages-kit-builtin-packages/

## React

Supports all exports in the official react

```javascript
import React, { lazy, forwardRef, ... } from '@blocklet/pages-kit/builtin/react'
```

## React Router DOM

Support all exports from the official react-router-dom

```javascript
import { useNavigate, ... } from '@blocklet/pages-kit/builtin/react-router-dom';
```

## MUI

<strong>MaterialUI</strong>

[Material UI components - Material UI](https://mui.com/material-ui/all-components/)

```javascript
import {
  Alert,
  AlertTitle,
  Autocomplete,
  Avatar,
  Box,
  Button,
  ButtonGroup,
  Card,
  CardActionArea,
  CardActions,
  CardContent,
  CardHeader,
  CardMedia,
  CircularProgress,
  ClickAwayListener,
  Collapse,
  Container,
  Dialog,
  DialogActions,
  DialogContent,
  DialogTitle,
  Divider,
  Fade,
  GlobalStyles,
  Grid,
  Grow,
  LinearProgress,
  Link,
  List,
  ListItem,
  ListItemAvatar,
  ListItemButton,
  ListItemIcon,
  ListItemSecondaryAction,
  ListSubheader,
  Menu,
  MenuItem,
  MenuList,
  Paper,
  Popper,
  Select,
  Slide,
  Stack,
  Switch,
  TextField,
  ThemeProvider,
  Tooltip,
  Typography,
  Zoom,
  alpha,
  createTheme,
  styled,
  useMediaQuery,
  useTheme,
} from '@blocklet/pages-kit/builtin/mui/material';
```

<strong>Lab</strong>

```javascript
import { LoadingButton } from '@blocklet/pages-kit/builtin/mui/lab';
```

### styled

⚠️ Note: `styled.div` is currently not supported. Please use `styled('div')`

```javascript
import { styled } from '@blocklet/pages-kit/builtin/mui/material'

const Div = styled('div')`
  width: 100px;
  height: 100px;
  background-color: red;
`
```

## Emotion

<strong>css</strong>

```ts
import { css } from '@blocklet/pages-kit/builtin/emotion/css';
```

## Iconify

[@iconify/react](https://www.npmjs.com/package/@iconify/react)

```javascript
import { Icon } from '@blocklet/pages-kit/builtin/iconify/react';
```

## React Hook Form

Supports all exports from the official react-hook-form

[React Hook Form - performant, flexible and extensible form library](https://react-hook-form.com)

```javascript
import { useForm, ... } from '@blocklet/pages-kit/builtin/react-hook-form';
```

## React Wrap Balancer

[GitHub - shuding/react-wrap-balancer: Simple React Component That Makes Titles More Readable](https://github.com/shuding/react-wrap-balancer)


```javascript
import Balancer, { Provider } from '@blocklet/pages-kit/builtin/react-wrap-balancer';
```

## Zustand

<strong>zustand</strong> [GitHub - pmndrs/zustand: 🐻 Bear necessities for state management in React](https://github.com/pmndrs/zustand)

```javascript
import { create, ... } from '@blocklet/pages-kit/builtin/zustand';
```

<strong>immer middleware</strong>

```javascript
import { immer } from '@blocklet/pages-kit/builtin/zustand/middleware/immer';
```

## Stream

```javascript
import { EventSourceParserStream } from '@blocklet/pages-kit/builtin/stream';
```

## Session

```javascript
import { useSessionContext } from '@blocklet/pages-kit/builtin/session';
```

## Locale

```javascript
import { useLocaleContext } from '@blocklet/pages-kit/builtin/locale';
```

## Call

```javascript
import { call } from '@blocklet/pages-kit/builtin/call';
```

## Utils

```javascript
import { joinURL, withQuery, getQuery, getComponentMountPoint } from '@blocklet/pages-kit/builtin/utils';
```

## React Scroll To Bottom

⚠️: This is an asynchronous export, and components need to be referenced using `React.lazy`.

```ts
import ScrollToBottomAsync from '@blocklet/pages-kit/builtin/async/react-scroll-to-bottom';

const ScrollToBottom = React.lazy(() => ScrollToBottomAsync);
```

## ArcBlock UX

```ts
import { RelativeTime, DID } from '@blocklet/pages-kit/builtin/arcblock/ux';

```

## Built-in

```javascript
import { LanguageField } from '@blocklet/pages-kit/builtin/components';
```

---

## Custom Component

URL: https://www.arcblock.io/en/docs/web3-kit/pages-kit-custom-component/

- [How to use third-party dependencies (CDN)](/en/docs/web3-kit/pages-kit-how-to-use-cdn-deps/)

- [Built-in Package List](/en/docs/web3-kit/pages-kit-builtin-packages/)

---

## How to use third-party dependencies (CDN)

URL: https://www.arcblock.io/en/docs/web3-kit/pages-kit-how-to-use-cdn-deps/

## Introduction

Although we have implemented handling of the built-in packages for security reasons, we still cannot cover all scenarios.

At this point, developers can introduce third-party dependencies.

## How to use third-party dependencies (CDN)

> ⚠️ Third-party dependencies must be loaded asynchronously, and it is important to load <strong>esm</strong> format JS!

React component, taking ReactTweetEmbed as an example:

```javascript
import React from '@blocklet/pages-kit/builtin/react';

const T = React.lazy(() => import('https://cdn.jsdelivr.net/npm/react-tweet-embed@2/+esm'));

export default function () {
  return (
    <T tweetId="1811849042001035287" />
  );
}
```

Non-React components, taking Lottie as an example, are shown in the following code:

```javascript
import React from '@blocklet/pages-kit/builtin/react';
import { Box } from '@blocklet/pages-kit/builtin/mui/material';

export default function () {
  React.useEffect(() => {
    import('https://cdn.jsdelivr.net/npm/@lottiefiles/lottie-player@2.0.3/+esm')
  }, [])

  return (
    <Box>
      Hello World

      <lottie-player
        autoplay
        loop
        mode="normal"
        src="https://www.aikit.rocks/.blocklet/proxy/z8iZvMrKPa7qy2nxfrKremuSm8bE9Wb9Tu2NA/assets/lottie-welcome-W07w6pFE.json"
      />
    </Box>
  );
}
```

The effect is as follows

![](https://team.arcblock.io/comment/uploads/36e96757751b29148a6e177f3588eacb.png)

## FAQ

#### How to find the ESM version of an npm library

Visit the following site and enter the name of the npm lib you want to use:

[jsDelivr - A free, fast, and reliable CDN for JS and Open Source](https://www.jsdelivr.com/)

Then check if there is an esm version and find the corresponding esm link, taking the html-to-image lib as an example.

[html-to-image CDN by jsDelivr - A CDN for npm and GitHub](https://www.jsdelivr.com/package/npm/html-to-image)

In the end, we obtained

![image.png](https://media.arcblock.io/lib/af/af7559ab217823d361869f14a13a6217.w1600.webp)

---

## Point Up

URL: https://www.arcblock.io/en/docs/web3-kit/point-up/

## Overview

<strong>Point Up</strong> is a blocklet that provides common point capabilities and can be installed to quickly give your service a complete set of point system capabilities. You can also combine other blocklets to make Points Up available to more services.

[Point Up](https://store.blocklet.dev/blocklets/z2qa2ZST7Frp8w1XGqyw9v85u12R3mBbB2oaA)

- [How to install Point Up](/en/docs/web3-kit/0oriCiUdAnTCJraiAnn2HrCP/)

- [How to configure point rules](/en/docs/web3-kit/Njj-D5qbcpeEIv_P5WC68QKp/)

- [How to use the point rules](/en/docs/web3-kit/RxqcPCVhfPqVP3SvS1vf0-ab/)

---

## Promotion Kits

URL: https://www.arcblock.io/en/docs/web3-kit/promotion-kits/

## Overview

<strong>Promotion Kits</strong> is a series of promotional and operational tools

- [Tweet Token (Share 2 Win)](/en/docs/web3-kit/tweet-token-share-2-win/)

- [Lucky Draw](/en/docs/web3-kit/lucky-draw/)

- [Token Prize Pool](/en/docs/web3-kit/token-prize-pool/)

- [Virtual Gift Card](/en/docs/web3-kit/virtual-gift-card/)

- [AD Kit (Beta)](/en/docs/web3-kit/ad-kit-beta/)

- [Waiting List](/en/docs/web3-kit/waiting-list/)

- [Daily Attendance](/en/docs/web3-kit/daily-attendance/)

- [Point Up](/en/docs/web3-kit/point-up/)

---

## In the Lucky Draw

URL: https://www.arcblock.io/en/docs/web3-kit/qYF6LHP7w2tSWTc2fnT3KcJU/

In the previous section, we introduced two ways to configure the use of Point Up, both allowing users to earn points within our services. The introduction of this Lucky Draw Blocklet is intended to enable users to utilize their points for engaging activities, such as participating in an exciting lucky draw.

在 ArcBlock's AI astrology app Aistro, we used this Blocklet to host several events for points and drawing NFT on the chain.

[Integral draw astrological constellation NFT](https://www.aistro.io/lucky/lucky/ZSOnJue1f0aKNEIa)

[Starry Christmas: Aistro Astrology Points Raffle](https://www.aistro.io/lucky/lucky/NpfuMKhrVd3MpZLm)

If you're interested in adding engaging points-based lottery activities to your service, consider integrating Lucky Draw into it.

> Note: Currently, the Lucky Draw still requires switching the Store to Dev Store during installation in the Dev Store.

[Lucky Draw](https://dev.store.blocklet.dev/blocklets/z2qaDrNKHv1PeXuSd9Er2kF9uLRPgJ2gxtcfA)

![截屏2024-12-10 23.03.18.png](https://media.arcblock.io/lib/53/5341e22be1f6c1f5221d0db9121fc0a1.w1600.webp)

---

## How to use the point rules

URL: https://www.arcblock.io/en/docs/web3-kit/RxqcPCVhfPqVP3SvS1vf0-ab/

On the ArcBlock platform, a complex service is always composed of several smaller Blocklets, and Point Up is no exception. A service based on the Blocklet platform can quickly gain points capability by integrating with Point Up.

There are two ways to use Point Up:

- [By configuring way](/en/docs/web3-kit/7snlzmYzubTKYZ3z51jQhy68/)

- [By calling through code](/en/docs/web3-kit/6bnit3SxeP525kPix8X7E0Hc/)

---

## Token Prize Pool

URL: https://www.arcblock.io/en/docs/web3-kit/token-prize-pool/

## Overview

<strong>Token Prize Pool</strong> is a kit to publish a prize pool event

[Token Prize Pool](https://store.blocklet.dev/blocklets/z8ia5gwZog5Ut4TfUJP4k82fXKQN8iWZp2bfG)

---

## Tweet Token (Share 2 Win)

URL: https://www.arcblock.io/en/docs/web3-kit/tweet-token-share-2-win/

## Overview

<strong>Tweet Token (Share 2 Win)</strong> is a kit that allows you to post shares and win rewards

[Tweet Token](https://store.blocklet.dev/blocklets/z8iZoLRKRXHzqdJ2vFZEi4H5UXT9ADsurxZRK)

---

## Rules of the points level

URL: https://www.arcblock.io/en/docs/web3-kit/TWoYzA66FxfDsNHUo1z-eLvT/

Point Up also supports configuring different level rules. When users accumulate points that meet these level criteria, they will receive a corresponding level display.

Next, I will demonstrate how to configure our level rules. In the following example, I will set it up according to the rules outlined below:

1. >= 100 Free Member
2. >= 300 Premium Member
3. >= 1000 Elite Member

### Step 1: Find the portal to add a point-level rule

Once you have found the portal, click the Add button on the page to start adding.

![截屏2024-12-10 10.02.19.png](https://media.arcblock.io/lib/71/713f83c7dfdae058d5e868e71c2275dd.w1600.webp)

### Step 2: Refine the Points Level Rules

Based on the established rules, configure different rules for Points requirements. Below is an example configuration for Free Member.

![截屏2024-12-10 10.33.15.png](https://media.arcblock.io/lib/1e/1efb83e58af37cfe9f6c2a21fbc71ea1.w1600.webp)

Once all settings are complete, the result is as follows:

![zR9FUfXOnbREiTMN.png](https://media.arcblock.io/lib/01/01fcd08860c34f00b8d530d72476bf7f.w1600.webp)

Next, after accumulating a certain number of points and accessing our personal points page, we can observe that the points level has already taken effect.

![截屏2024-12-10 17.04.29.png](https://media.arcblock.io/lib/6f/6ff78d5f49e76ba2cf8f78e55a6e03bd.w1600.webp)

---

## Virtual Gift Card

URL: https://www.arcblock.io/en/docs/web3-kit/virtual-gift-card/

## Overview

<strong>Virtual Gift Card</strong> is a kit to publish on-chain bonuses

[Virtual Gift Card](https://store.blocklet.dev/blocklets/z8iZscGk6ohCejHEiX16C7apdFC7JrPYD1J4Z)

---

## Vote Kit

URL: https://www.arcblock.io/en/docs/web3-kit/vote-kit/

## Overview

<strong>Vote Kit</strong> is a tool to make vote great again, decentralized voting results are stored on the blockchain, making voting records tamper-evident and traceable

[Vote](https://store.blocklet.dev/blocklets/z8iZqTiD6tFwEub6t685e3dj18Ekbo8xvqBSV)

---

## Waiting List

URL: https://www.arcblock.io/en/docs/web3-kit/waiting-list/

## Overview

<strong>Waiting List</strong> is a kit to publish embedded waiting list activities on the page

[Waiting List](https://store.blocklet.dev/blocklets/z8ia5nxBkFetpK1BzaumvDStQiKyAuHdymnoh)

---

## FAQs

URL: https://www.arcblock.io/en/docs/web3-kit/web3-kit-faqs/

## Overview

Here's a quick Q&A of Creator Studio's frequently asked questions.

## Q&A

### What is Blocklet Launcher?

Blocklet Launcher is a fully decentralized app launcher! With just a few clicks, you can quickly install decentralized applications in your digital world and immediately enable and run the applications smoothly.

### Why we need to have this Web3 Kit?

We have noticed that many large projects have a lot of basic modules that they need for operations, promotions, payments and other functions.

So we abstracted most of the logic and formed these kits to reduce the duplication of workload for developers. Anyone can develop a blocklet with just a simple docking introduction.

---

## Getting Started

URL: https://www.arcblock.io/en/docs/web3-kit/web3-kit-getting-started/

## Overview

Click on the subpage listing below to quickly go to the corresponding module

- [Pages Kit](/en/docs/web3-kit/pages-kit/)

- [Discuss Kit](/en/docs/web3-kit/discuss-kit/)

- [AI Kit](/en/docs/web3-kit/ai-kit/)

- [Vote Kit](/en/docs/web3-kit/vote-kit/)

- [Promotion Kits](/en/docs/web3-kit/promotion-kits/)

---

## How To Guides

URL: https://www.arcblock.io/en/docs/web3-kit/web3-kit-how-to-guides/

WIP

---

## Reference Guide

URL: https://www.arcblock.io/en/docs/web3-kit/web3-kit-reference-guide/

WIP

---

## Sample Projects

URL: https://www.arcblock.io/en/docs/web3-kit/web3-kit-sample-projects/

WIP

---

## Welcome

URL: https://www.arcblock.io/en/docs/web3-kit/welcome-8Zka_/

## Overview

<strong>Web3 Kit</strong> is a series of components about basic blocklets, which currently consists of the following blocklets

- <strong>Pages Kit</strong> is a powerful tool that helps you and your team easily and quickly build beautiful websites
- <strong>Discuss Kit</strong> offers highly customizable and combinable components for everything you need to decentralize communication
- <strong>AI Kit</strong> is a AI-powered tools to help you and your team increase productivity by 10x
- <strong>Vote Kit</strong> is a tool to make vote great again
- <strong>Promotion Kits</strong> is a series of promotional and operational tools
-
  - <strong>Tweet Token (Share 2 Win)</strong> is a kit that allows you to post shares and win rewards
  - <strong>Lucky Draw</strong> is a kit that allows you to publish sweepstakes
  - <strong>Token Prize Pool</strong> is a kit to publish a prize pool event
  - <strong>Virtual Gift Card</strong> is a kit to publish on-chain bonuses
  - <strong>AD Kit</strong> is a kit that supports configuring advertisement space within a page
  - <strong>Waiting List</strong> is a kit to publish embedded waiting list activities on the page
  - <strong>Daily Attendance</strong> is a kit to publish punch card activities
  - <strong>Point Up</strong> is a kit that allows you to customize and publish point rules
- <strong>Payment Kit</strong> a kit to make your payments easy

* For more information, please visit the official website: [https://www.web3kit.rocks](https://www.web3kit.rocks)

---

## ArcBlock White Paper V1

URL: https://www.arcblock.io/en/docs/white-paper/

---

## ArcBlock Technical White Paper

URL: https://www.arcblock.io/en/docs/white-paper/arcblock-technical-white-paper/

Version 1.0 (2017.12)

# Introduction

## Purpose

The purpose of this document is to provide a high-level technical overview of the ArcBlock platform. It assumes that the reader has a basic understanding of cloud computing, decentralized applications, and blockchain technology. A list of resources is provided for those who would like to develop a foundational understanding of blockchain technology.

## Scope

This document provides a technical overview of ArcBlock, a blockchain ecosystem for building and deploying decentralized applications. It describes core elements of the service and provides details about the architectural design of critical components.

The information in this document is intended for informational purposes only. ArcBlock may make improvements or changes to the products, architectural design, or programs described in this document at any time without notice.

## Related Documents

- ArcBlock Official Website: [https://arcblock.io](https://arcblock.io/)
- ICO Version Whitepaper: [https://www.arcblock.io/whitepaper/](https://old.arcblock.io/files/whitepaper/en_v2.pdf)

# Overview

## Problems with Today’s Blockchains

Blockchain technology is still in its infancy. There are many issues preventing developers and businesses from creating widespread, decentralized blockchain applications.

### Poor Performance

Performance is one of the main challenges facing current blockchain technology. The blockchain that Bitcoin uses is designed to handle seven transactions per second, and Ethereum can only handle a few more. As of December 2017, a simple CryptoKitties application can slow Ethereum and increase transaction fees dramatically.

Today’s consumer applications must be able to handle tens of millions of active users on a daily basis. In addition, some applications will only become meaningful when critical mass is reached. The platform itself must be able to handle a large number of concurrent users.

A good user experience demands reliable feedback with only sub second delays. Longer delays frustrate users and make applications built on a blockchain less competitive with existing non-blockchain alternatives.

### Not Consumer Friendly

Today’s blockchain applications are built for the few tech whizzes who know how to use them, rather than mainstream consumers. Nearly all blockchain applications require users to either run a blockchain node or install a “light node." The learning curve and effort involved has delayed adoption among the general public.

For example, while the Ethereum-based game CryptoKitties is probably the most user-friendly decentralized app ever built, it still requires the user to install the Metamask light wallet browser extension. Users also need to know how to buy ethers securely and use them with Metamask.

To attract large numbers of people, blockchain applications need to be as simple as today’s web and mobile apps. Blockchain technology should be completely transparent to the consumer.

### Cost

The extremely high cost of using blockchain technology is a major barrier to mainstream adoption. It also limits developers who need the flexibility to build free services. Just like today’s web and mobile apps, users shouldn’t have to pay for every minor action. Similar to the Internet, blockchain technology should be able to support free applications.

Making blockchain free to use is key to widespread adoption. A free platform will also empower developers and businesses to create valuable new services they can monetize, rather than having users pay fees to use the blockchain network.

### Platform Lock-In

As with the early days of any computing technology, blockchains have critical “platform lock-in” problems. Developers have to decide which blockchain to support, then implement platform-specific code that makes it very difficult to switch an application to a different blockchain later on.

Developers don’t want to be locked into working with a certain blockchain technology. They need the freedom to evaluate, use, and switch between options. Some applications may even need to run on multiple platforms to provide the best user experience.

### Lack of Features

People have high expectations for blockchain—the news media, evangelists, and journalists paint a bright future for decentralized applications for the public, especially with the increasingly high prices of cryptocurrencies. In reality, however, blockchain technology is still in its infancy. Most blockchain services lack rich features and don’t have a mechanism to encourage the community to contribute to the feature stacks.

Blockchain protocols make them very easy to fork, and there's been a recent spike in forks created for various purposes. Unfortunately, forks typically only improve on the forked branch, splitting the community and computing resources. The incentive mechanisms for blockchains just aren't designed to encourage contributions to the blockchain tech stack yet.

## The ArcBlock Platform

ArcBlock solves these problems through its revolutionary new design. Unlike its predecessors, ArcBlock is a <strong>platform service</strong>, rather than a standalone software package or set of APIs. ArcBlock is a comprehensive solution that combines blockchain technology with Cloud Computing.

ArcBlock is an <strong>incentive-driven marketplace</strong> for reusable services, components, and even applications. <strong>“Miners”</strong> in ArcBlock platform not only bring computing resources, more over they help to build the platform together by providing reusable components, new services, and even ready to deploy applications. People who contributed resources or services will be rewarded with tokens to form a positive, self-growing platform that continues to evolve on its own. The ArcBlock platform service isn’t our creation alone. It’s developed by the entire ArcBlock community—we’re just kick-starting a new blockchain revolution.

ArcBlock’s introduction of the <strong>Open Chain Access Protocol</strong> enabled open connectivity over multiple blockchain protocols. Developers now have the freedom to evaluate blockchain protocols, and even switch back and forth between them. The Open Chain Access Protocol makes it easy to implement new blockchains as the technology evolves. It eliminates the platform lock-in issue and enables applications to run on multiple blockchain fabrics, vastly improving the developer and user experiences.

<strong>Blocklet</strong> is another revolutionary component that takes advantage of the latest microservice architecture and serverless computing technology. Blocklet is a high-level application protocol that can be implemented with any platform or language. It leverages the full capacity of the native platform and offers the same level of performance, rather than running on a low-performing virtual machine.

Blocklet does more than access blockchains. It connects to any existing data source, and performs both on-chain and off-chain computing.

Our unique design aims to provide a high-performance, user-friendly, cost efficient, and protocol-agnostic platform. We believe that ArcBlock represents a major technological advance that will usher in the 3.0 generation of blockchain applications.

![image.png](https://media.arcblock.io/lib/be/bee35f695e48e156691cb06d737eca9f.w1600.webp)

### <em>Fig: Road map toward Blockchain 3.0</em>

## ArcBlock’s Advantages

In addition to solving the common problems outlined above, building and deploying decentralized blockchain applications with ArcBlock has significant advantages over the vendor-specific frameworks available in today’s market.

### Built for the New Token Economy

ArcBlock is a self-evolving ecosystem—not just a software platform built by one centralized organization. We at ArcBlock, Inc. and the ArcBlock Foundation are only jump starting the project; the platform will continue to develop and grow on its own.

The entire ArcBlock service is driven by the token economy. Rather than a basic service platform, ArcBlock is an economy driven by incentives that encourage the blockchain community to work together to build a better ecosystem.

### Optimized for the Best Experience

We built the ArcBlock platform using a “top-down” strategy that centers on the user experience. In contrast, many existing solutions focus on the blockchain technology itself at the expense of user friendliness. Applications built with ArcBlock offer reactive, real-time experiences. Users can simply access them from a web browser (no additional plugins required), or download a mobile app directly from an app store. Either way, the process is familiar.

ArcBlock also dramatically improves the developer experience. There’s no need to deal with low-level blockchain protocols. With our mock blockchain adapters, engineers don’t even have to run local blockchain test nodes to start developing and testing their applications.

### Built for the Cloud

ArcBlock is designed to run natively in the cloud. It can also run on a single computer for testing and development.

This design principle makes ArcBlock fundamentally different from many other platforms in the blockchain world. In ArcBlock, a node can be a “logical computer” comprised of one or more virtual machines, or a group of cloud services working together as a computing environment. This approach marks a significant step forward that will help elevate blockchain and decentralized applications to the next level, including our patent pending technologies.

ArcBlock will initially build on top of AWS and Windows Azure, then expand to support Google Compute Engine, major cloud computing players in China, and other platforms.

### Built with an Open Standard

ArcBlock is built with an open standard. We’re trying our best not to reinvent the wheel and to build for the application developer’s wants and needs. In addition to open sourcing our core components, we will also actively contribute to a variety of blockchain technology communities.

Our team members are actively involved with a range of standards organizations, non-profit foundations, and committees. These currently include the W3C Blockchain Community Group Community Group, IEEE Standard Association’s Blockchain Community, Enterprise Ethereum Alliance, Linux Foundation, and Hyperledger Foundation. This list will expand over time.

# Architecture

ArcBlock aims to build a <strong>scalable, extensible,</strong> and <strong>easy-to-use</strong> platform for building and deploying decentralized blockchain applications.

## Design Principles

ArcBlock’s design is based on following core principles:

- The user experience comes first.
- Performance matters.
- The system will be built on an open standard.
- The system will build upon an Incentive-driven economy.

## System Architecture

The ArcBlock platform introduces a suite of revolutionary technologies designed to mainstream blockchain applications by making them easy for the average consumer to use.

![image.png](https://media.arcblock.io/lib/c3/c3697bb4383b1d1ba5cbb092ba9c0dd3.w1600.webp)

### <em>Fig: High-level Overview of ArcBlock</em>

### Open Chain Access Protocol

Our open source protocol provides an abstract layer for accessing underlying blockchains. Similar to an ODBC or JDBC interface to a set of databases, our Open Chain Access Protocol enables your application to work on different blockchains. There’s no need to alter your business logic or work with multiple chain technologies.

Chain Adapters can be built by the community and encouraged by the incentive mechanism. This will enable ArcBlock to support many blockchain protocols and continue to improve.

### Blocklet

Blocklet is a serverless computing architecture component for running various types of applications. Use Blocklet for smart contracts, oracle, resource and asset handling, and off-chain business logic. Blocklet communicates with blockchains through ArcBlock’s Open Chain Access Protocol, and can be orchestrated with our Algorand-based consensus algorithm.

Anyone can use Blocklet to build services and components and contribute them under the incentive system. Community members will receive tokens when others use their contributions.

### Blocklet Components

Blocklet Components are pre-built blocklets that form the foundation of the ArcBlock platform. Most of ArcBlock’s features (such as its token services, user identity services, etc.) are implemented with them. Blocklet Components are highly reusable and customizable.

Incorporate our pre-built Blocklet Components into your applications to get up and running fast. We provide components for user identity management, utility tokens, wallets, messaging, notification services, and more. Use them out-of-the-box, or as customizable starting points for your own creations.

Blocklet Components can also be built and contributed by the community. They are managed through the ArcBlock Marketplace app.

### Decentralized Pub/Sub Gateway

A distributed messaging system supports pub/sub and acts as an API gateway for Blocklets. ArcBlock's gateway uses a decentralized design and secure communication channels. Your applications will run in both web browsers and mobile apps, giving users reactive, real-time experiences.

The gateway supports various network protocols by default, including WebSocket, DDP, HTTPS, and MQTT. Advanced developers can extend the gateway with new network protocols to fit their needs.

### Marketplace and Token Economy

ArcBlock comes with a fully customizable token economy manager for apps built on the platform. Applications can even build unique utility tokens that inherit all ArcBlock features.

The ArcBlock Marketplace is a native application built on ArcBlock to allow the community contribute and exchange reusable components (e.g. Chain Adapters, Blocklets, or even applications) .

The diagram below shows a high-level view of the platform architecture. Detailed descriptions of some of the core components appear in the next section.

## Cloud Nodes

While using a group of cloud services as a node may seem like an unusual approach, a physical computer is simply a group of hardware components that work together (CPU, memory, external storage, bus, network interfaces) in one box. Aside from how the components are distributed and communicate with each other, they're essentially the same. ArcBlock is the first blockchain platform to treat cloud services as nodes, achieving a much higher level of abstraction, enhanced performance, and even better security. We believe this approach will likely become the de facto standard for future blockchain platform design, and we as a pioneer will lead the trend as technology evolves.

Although ArcBlock’s preferred node is a cloud node, you can still run ArcBlock in a single traditional node like a server box. In a test or private environment, developers likely run the node locally, or in their test server boxes.

Using a cloud node won’t compromise the decentralization and security of the system. In fact, it takes decentralization and security to the next level.

The cloud platform’s own security is enforced by cloud service providers. Most likely, the servers and services from a cloud service provider will be more secure and reliable than self-hosting servers, and far more secure and reliable than peer-to-peer connected nodes from homes or mining farms.

The decentralization aspect of using a cloud node is even more interesting, since a cloud node is likely a distributed service that runs on multiple servers from multiple availability zones, or even different regions. In the future, cloud nodes could be offered by various providers and cloud computing vendors. Some may even be self-hosted mining service providers. This makes the system much more decentralized indeed.

# Core Components

The following sections offer more detailed descriptions of our key components and core algorithm. This section assume that you have an advanced understanding of blockchain technology and computer science. If you’re not interested in detailed information about the components and would rather learn more about using the platform, feel free to skip this section.

## Open Chain Access Protocol

ArcBlock’s Open Chain Access Protocol enables your application to adapt to a variety of blockchain protocols including Bitcoin, Ethereum, Hyperledger, and more. The Open Chain Access Protocol will be open sourced with an MIT license so that everyone in the blockchain community will be able to contribute, create extensions, and make improvements. We will develop the protocol in private mode, then open source it once we reach the release candidate milestone.

![image.png](https://media.arcblock.io/lib/5d/5d49be14de14ec85738276ee690e3b3e.w1600.webp)

### Open Chain Access Layer

The Open Chain Access Layer defines high-level, generic APIs that enable open connectivity and access to a range of blockchain protocols. The Layer is supported by a Chain Adapter under layer. Each Chain Adapter is implemented for a specific blockchain protocol.

The Open Chain Access Layer has three levels of APIs:

| Level  | Description  |
|---|---|
| Level 1: Common Chain APIs  | This set of APIs provides the foundation for the Open Chain Access APIs. Any Chain Adapters must support all of the APIs included in this level.  |
| Level 2: Common Chain Data APIs  | This set of APIs enables fundamental access to blockchain data, and treats each blockchain under layer as a finite state machine. Chain Adapters may either support the APIs at this level, or alternate capabilities. The set includes APIs that allow applications to query the supported capabilities. A Chain Adapter must support all of the APIs included in this level. However, they may implement a different capacity set.  |
| Level 3: Native Chain APIs  | This advanced API set exposes the native features of underlying blockchain protocols. While supporting this set is optional, it will maximize your application's ability to use native blockchain features. Supporting the API set at this level is optional for Chain Adapters.  |

### Chain Adapters

ArcBlock’s Open Chain Access Layer enables the platform to support multiple blockchain protocols. Application developers can choose from several different blockchains, node types, and deployment types. ArcBlock’s Chain Adaptors are the implementations that make the Open Chain Access Layer possible.

Chain Adapters work like device drivers to translate blockchain under layer protocols into the unified APIs defined in the Open Chain Access Layer. Some of the Chain Adapter implementations require you to combine on-chain and off-chain implementation works together. The Chain Adapter is also assigned one of three categories, based on the Open Chain Access Layer API set it has implemented.

We plan to implement Chain Adapters for Bitcoin Blockchain, Ethereum, and Hyperledger first. After we open source the code, anyone will be able to contribute, improve the protocol, or implement their own code. We also plan to support additional blockchain protocols.

### Chain Adapters Marketplace

Chain Adapters that have been developed or improved by the community will be made available in the ArcBlock marketplace so that everyone can use them. The people who contributed to the adapter will receive rewards when others use it. The incentive model will encourage the community to develop more and better Chain Adapters. In time, ArcBlock will be able to offer a line of high-performance, high-quality Chain Adapters for various blockchains.

### Relationship with Blockchain as a Service

In the past 12 months, several leading cloud platform providers began offering a new type of platform called Blockchain as a Service (BaaS). BaaS platforms typically offer users a permissioned or public chain, and they’re usually optimized for a specific deployment or node type. IBM Cloud (aka Bluemix) BaaS , which offers a Hyperledger Fabric service, was one of the earliest providers. While Microsoft Windows Azure also offers a BaaS platform , it mainly targets the test environment and fast spin-up for developers. Amazon AWS hasn’t officially offered a BaaS yet, but there are third-party VM images that help users quickly deploy blockchain nodes with AWS EC2 instances.

Existing BaaS platforms work perfectly with ArcBlock. While they simplify the process of deploying blockchain for users, ArcBlock simplifies the process of developing and deploying blockchain apps for software engineers. The first phase of ArcBlock’s implementation will include integrating with cloud computing platforms (through the AWS SDK, for example), so that users can manage BaaS services from directly within ArcBlock applications.

### Design Principles and Inspiration

To design the Open Chain Access Protocol, we investigated many existing customer solutions, talked to real developers, and learned from the evolution of computers and database systems. For example, the structure for the Open Chain Access Layer was inspired by the open connectivity design seen in databases.

A look back at the development of database systems and applications reveals many similarities with the evolution of blockchain technology . The position of the blockchain in a typical system is very much the same as the database in a database application system. In many scenarios, it’s fair to say that a blockchain is actually acting as a distributed database. Most of the blockchain itself is built on top of a database, including Bitcoin and Ethereum. That said, we can find inspiration in how database systems evolved.

## Blocklet

Blocklet is the core of ArcBlock. More than an application protocol, it’s also a software architect that lays the foundational building blocks of ArcBlock itself. The ArcBlock platform is built on a series of Blocklets. The Open Chain Access Protocol allows Blocklet to communicate with under layer blockchains. The Distributed pub/sub gateway allows Blocklets to communicate with the client-side code live in the user’s browser or mobiles apps. In short, Blocklets are at the center of the entire system.

![image.png](https://media.arcblock.io/lib/12/12e12c0da2111db35e2ec9f8cd41effb.w1600.webp)

### Microservice Architecture

Microservice architecture is a perfect match for blockchain applications. A variant of the service-oriented architecture (SOA) style, microservice architecture structures an application as a collection of loosely coupled services. The services should be fine-grained and the protocols lightweight. Deconstructing an application into a variety of smaller services improves modularity and makes the application easier to understand, develop, and test.

ArcBlock is designed as an event-driven microservice that uses Blocklet technology to overcome the inherent limitations of the blockchain. Blocklet communicates with the blockchain under layer through the Open Chain Access Protocol, allowing the application to access external data securely while also maintaining data integrity.

### Serverless Computing

Serverless computing is a cloud computing execution model in which the cloud provider dynamically manages the allocation of machine resources. Most serverless vendors offer compute runtimes or function as a service (FaaS) platforms, which execute application logic but do not store data.

Serverless computing models also work well with blockchains. Most of the Blocklets can be implemented as a serverless program. Manage Blocklets through AWS Lambda, Windows Azure Functions, or another serverless execution environment.

Note that microservice architecture and serverless computing involve different levels of abstraction. Serverless computing can be used to implement a microservice that fits perfectly within a microservice architecture. However, developers can also use serverless computing for other purposes, and it’s not always necessary to use serverless computing to implement microservices.

### Blocklet Types

Blocklet is inherently flexible and can be used to develop various kinds of applications. This section describes some common types of blocklets. Bear in mind, however, that a Blocklet could consist of one or more of the following units of business logic packaged together.

#### <em>Off-Chain Logic</em>

Because Blocklet is a native microservice, it can access data sources other than the blockchain. For example, it can connect to a database, external restful API, or any other data source. Blocklet can be used to develop any application logic—even logic that's not related to blockchain. Using Blocklet for standard application development has no overhead.

Real-life, decentralized applications often run quite a few logical components off-chain. Blocklet provides a total solution for application development so that engineers won’t need to use different frameworks to handle different parts of their applications.

#### <em>Off-Chain and On-Chain Logic</em>

It’s very common for an application’s business logic to need both on-chain and off-chain handling, and to require the respective data to be connected. For example, on-chain code can't access external data and events, such as time or market. Calling code or data outside of an on-chain smart contract or blockchain breaks the general trust barrier and reduces confidence in the authenticity of transactions. In these cases, an off-chain Blocklet acts as a bridge that connects on-chain and off-chain logic to bring the full business logic together.

#### <em>Asset and Resource Handling</em>

Applications usually need to handle resources and assets like photos, videos, music, and documents. Because blockchain isn’t designed to handle large amounts of data, a typical blockchain application handles those resources and assets with off-chain solutions. While there are different ways to accomplish this, the traditional solution involves using a service like AWS S3, or a more decentralized solution like IPFS.

Regardless of the approach you take, Blocklet will be able to communicate with your assets and resource storage system. Sometimes assets may need to be mapped with their on-chain token or identifiers, or verified through the records on the blockchain. Blocklet is the perfect location for these kinds of logic.

#### <em>Smart Contracts</em>

By communicating with on-chain code securely through the Open Chain Access Protocol, Blocklet enables you to implement high-performance smart contracts while maintaining the trust barrier and verifying the authenticity of transactions.

It’s up to the engineer to decide how much logic should run on-chain vs. off-chain. At one extreme, the engineer could simply treat the blockchain as a state machine and put most of the business logic inside the Blocklet. At the other extreme, the engineer might develop a complex, fully on-chain contract where the Blocklet merely serves as a stub for triggering or monitoring activity from the on-chain execution.

#### <em>Oracle</em>

In Blocklet design, Oracle is simply a type of smart contract that takes external data sources as event triggers. Blocklet makes it easy to implement Oracle by design.

Blocklet-based design also compels engineers to consider the division between on-chain and off-chain logic during the design and development phases. This improves the efficiency of these phases without compromising security and trust.

### Blocklet Implementation

In the first phase of ArcBlock development, we will implement Blocklets with a local test environment and AWS. The local implementation is for test purposes only. Production will be based on AWS so that we can take advantage of the many advanced design features AWS offers.

In the future, we will support Windows Azure, Google Compute Engine, IBM Bluemix, and other computing platforms. We also plan to support Docker and open source FasS solutions for Blocklet so that users can easily build and deploy their own Blocklets without using any cloud services.

Because Blocklet itself is a type of application protocol and architecture, it’s possible to implement it with different languages and frameworks. Our initial implementation will be based on Node.js and GO.

### Blocklet Components

Blocklet Building Blocks are pre-built blocklets that lay the foundation for the ArcBlock platform and most of its features, such as token and user identity services. Blocklet Building Blocks are highly reusable and customizable components.

## Decentralized Pub/Sub API Gateway

A distributed messaging system supports pub/sub and acts as an API gateway for Blocklets. ArcBlock's gateway uses a decentralized design and secure communication channels. Your applications will run in both web browsers and mobile apps, giving users reactive, real-time experiences.

![image.png](https://media.arcblock.io/lib/3e/3ec2feee63d1b229bfd85845f1b8e951.w1600.webp)

### API Gateway

An API gateway is essential in microservice architecture. An API gateway is a façade that provides a simple API interface to a complex subsystem. It essentially decouples the interface that clients see (in our case API consumers, which could be mobile apps, web clients, or thin clients) from the underlying implementations. In ArcBlock, all features are implemented with Blocklets. Rather than communicating directly with clients, Blocklets communicate through the API Gateway.

The gateway supports various network protocols by default, including WebSocket, DDP, HTTPS, and MQTT. Advanced developers can extend the gateway with new network protocols to fit their needs.

![image.png](https://media.arcblock.io/lib/21/21deca074e64cc3561e7227f54beafba.w1600.webp)

### <em>Fig: A Simple Reference Implementation in Node.js(as of Dec 2017)</em>

### Pub/Sub

Publish–subscribe is a messaging pattern where message senders (publishers) categorize published messages into classes without knowing which subscribers will receive them, if any. Similarly, subscribers only receive messages assigned to the classes they've expressed interest in, without knowing which publishers there are, if any.

The publish–subscribe pattern is a sibling of the message queue paradigm. It’s typically a single piece in a larger message-oriented middleware system. Most messaging systems support both the pub/sub and message queue models in their APIs. This pattern provides greater network scalability and a more dynamic network topology, resulting in decreased flexibility in terms of modifying the publisher and the structure of the published data (This is not a disadvantage for blockchain applications).

### Decentralized and Secured

We use a completely decentralized design to implement and simplify cloud services. ArcBlock’s API Gateway can be used out-of-the-box with zero configuration—just start it up and it will do its magic. It also features name-based addressing, clusters (i.e. automatic load balancing), and perfect secrecy (all network traffic is encrypted).

![image.png](https://media.arcblock.io/lib/32/325a86d00878e2508c12ec16e6b8d442.w1600.webp)

### <em>Fig: How decentrailized messaging and pub/sub works</em>

## Decentralized Media and Assets

While ArcBlock’s core components weren’t designed to handle media and assets, Blocklet can be used to handle them with support from other systems. Blocklet can also help you create off-chain data, or verify off-chain data with the on-chain data. . Today, most decentralized applications handle media and assets with off-chain logic. They either use a cloud-based centralized solution like AWS S3 or Microsoft Windows Azure’s storage service, or a decentralized solution like IPFS or Swarm .

Rather than reinventing the wheel, we encourage application developers to adopt the best-fit solution for handling their media and assets. We predict that most application developers will use centralized solutions, which are the simplest and most mature. In addition, media and resources don't necessarily have any relationship with blockchain data in most applications. Other developers might consider using IPFS or a hybrid solution. ArcBlock allows you to decide which solution is best for your application—it works with either technological approach.

While the ArcBlock platform uses AWS to handle its own media and assets, we may consider moving toward a decentralized system in the future.

## Client Library/Framework

ArcBlock provides libraries and frameworks for client application development. These libraries support web, iOS, and Android platforms. With the Electron Framework , the web version can be easily encapsulated and packaged as a desktop application for Windows and Mac OS.

The version for the web is a simple communication library that works with HTTPS and WebSocket to provide a real-time and reactive user experience. It works with nearly all other web frameworks, allowing you to pick the framework you’d like to work with, such as Meteor, VUE, or React.

This is an important advantage for application development. Engineers can spend most of their time handling the client side and user experiences, and write most of the code in this layer. Thanks to ArcBlock, however, now they can develop client applications the same way they build traditional, non-blockchain applications. Our design enables developers to work with their favorite frameworks and tools so they can draw upon community resources and support.

![image.png](https://media.arcblock.io/lib/27/274c5a5c685b7928bf275137e7bc74bc.w1600.webp)

### <em>Fig: Client communication model of our reference implementation on AWS (as of Dec 2017)</em>

## Algorand

ArcBlock is among the first blockchain startups to adopt Algorand in production.

Algorand was founded by Silvio Micali, winner of the 2012 ACM Turing Award. Micali is a pioneer in cryptocurrency and blockchain technology. He was instrumental in the development of many of the building blocks of cryptography, published works on game theory and Byzantine Agreements, and even launched a micropayments startup. When Micali saw Bitcoin, he thought it could be improved; Algorand is the result of that quest.

![image.png](https://media.arcblock.io/lib/de/de0e141149b09f52f5741b5af20683f2.w1600.webp)

### <em>Fig: An overview of transaction flow in Algorand</em>

Algorand involves suddenly and randomly selecting a small group of nodes to be in charge of the next block, then receiving a reward in the form of a percentage of the block transaction. This must be done in a way that can’t be manipulated by an adversary. No one selects the group; it’s selected by hash instead. Micali suggests taking a pseudo-random generator which is pre-specified and elongating as much as you need to select the committee. The group decides the next block via a redesigned Byzantine agreement in which a leader is picked randomly from the group.

ArcBlock uses Algorand and its variant in a number of places. For example, we use Algorand to pick where the smart contract Blocklet will execute from, as well as for the high-performance blockchain that powers our native tokens. We will disclose more details on implementing Algorand in the ArcBlock in the future when we reach release candidate milestone.

# The Token Economy and the Service

What makes ArcBlock unique is that it’s not just a set of APIs or libraries—it’s a robust platform with a full set of features. In addition, the service runs on top of its own native token system, which is driven by latest blockchain technology.

## The ArcBlock Token (ABT)

The ArcBlock Token (ABT) is native to the ArcBlock platform. To achieve high-performance transactions, we built an optimized blockchain dedicated to ArcBlock’s own token services and the public ledger. The design goal is to achieve >100,000 Tx/s, which is more than adequate for a wide range of applications. In the future this blockchain could be improved for broader purposes.

The ABT is designed as a general purpose token that can be used in different scenarios. Within ArcBlock, the ABT’s basic utility value is to pay for the cost of using the ArcBlock system. Like a cloud computing service, the ABT is a utility token for paying the cost associated with using the service.

![image.png](https://media.arcblock.io/lib/ed/ed98fa114429ad8d04fc0ab7d91a13af.w1600.webp)

Unlike Ethereum or Bitcoin, where users typically pay a fee for each transaction they make, ArcBlock is designed to let application providers pay the transaction fees for their end users. This approach vastly improves the user experience. Developers pay on a monthly basis, enabling them to add up small units and save money. ArcBlock also request developers to lock in a number of ABT token as a stake when they need to provide mission critical services.

ArcBlock tokens map to ERC20 tokens 1:1. This simplifies token exchanges and allows developers to tie into the Ethereum community. Application developers can take advantage of the existing ecosystem built on the ERC20 token while also leveraging a high-performance and full-featured token service. While this mapping is necessary today, we anticipate that it may become obsolete as the ABT matures and the ArcBlock community grows.

## The Miners

ArcBlock allow contributors (“miners”) to run ArcBlock platform services and join the overall service network. The role of miners within the ArcBlock community is significantly different from that of Bitcoin and Ethereum contributors, however.

### Resource Miners

Resource Miners contribute computing resources to the system. They might provide cloud computing resources and run as a cloud node, or contribute self-hosted computing resources.

In ArcBlock’s design, Miners may provide the computing resources for their own use only, share them across multiple parties, or share them with anyone. The choice of model is entirely up to the miner, and can be changed as they need to.

### Component Miners

Component Miners contribute software components to the system, such as new Chain Adapters, Blocklet Components, or ready-to-deploy applications. The component might be packaged code that can be reused and deployed by another application, or a set of services that's merely exposed through the Blocklet interface. For example, a deep learning-based image recognition service may have its own services running elsewhere, but offer the services as Blocklets so that other ArcBlock applications can use them.

A smart contract defines how the miner’s fee will be distributed if the component is developed by multiple parties. It will also define the rules for how the code for the component is forked.

## The ArcBlock Marketplace

The ArcBlock Marketplace is a decentralized blockchain application built on ArcBlock platform itself. The app serves as a marketplace for listing, searching, evaluating, using, and ranking reusable components, such as Chain Adapters, Blocklets Components, and applications.

The marketplace is also responsible for maintaining public feedback about the quality of components and the reputation of their developers, as well as other information. This information will help users evaluate reusable components. All the marketplace information are recorded in the public ledger powered by ArcBlock’s blockchain technology to ensure transparency and the trust.

## Token Foundation Services

The platform’s token foundation services consist of a set of Blocklet components that lay the groundwork for ArcBlock’s token services.

The ArcBlock token is implemented entirely with Blocklet. The token foundation service is also powered by Blocklets, and the Token Economy Service consists of a group of Blocklet Building Blocks. Application developers can use Blocklet to easily handle events triggered by tokens and accomplish complex business logic. The distributed ledger in ArcBlock ensures that your tokens are secure, high performing, and reliable.

Just like any other Blocklet components, the Blocklets for the token foundation service can also be improved and extended by the blockchain community .

## Application Tokens

With ArcBlock, developers can also create their own custom tokens that inherit all of the features of our native token.

ArcBlock makes it easy to build your own economy. Tokens aren’t just for cryptocurrencies, however. They can represent many different things, from user identities, certifications, and documents to real-world entities. ArcBlock enables you to tokenize everything in your application.

In the near future, you'll be able to make initial coin offers (ICOs) with ArcBlock’s application token once you've built and deployed your applications with ArcBlock.

# Acknowledgements

This work is the cumulative effort of multiple individuals with the ArcBlock team, and would not have been possible without the help, comments and review from our partners, advisors, community collaborators and valuable customers.

This technical whitepaper was written by Robert Mao, the Chief-Architect of ArcBlock and reviewed by Flavien Charlon, the Chief-Scientist of ArcBlock. During the authoring process we received valuable helps and comments from the rest of ArcBlock engineering and marketing team, our partners, we also received lots of valuable feedback from the emails, WeChat groups, Telegram groups, conferences and forums.

We would like to thank all our advisors and collaborators for valuable conversations, in particular Ximen LiuShang, Justin Tomboulian, Vilion Wang, Frank Lee, Richard Liu and Jonathan Lu. We woulds also like to thanks to Kate Dougherty and Jean Chen for the help on the proof reading and document structure.

## The End

Copyright © 2017 ArcBlock, Inc. All rights reserved. Draft for community review. Subject to change.

---

## Versions

URL: https://www.arcblock.io/en/docs/white-paper/versions/

### Versions

### Changes

---

## ABT

URL: https://www.arcblock.io/en/glossary/abt/

---

## ABT Settlement

URL: https://www.arcblock.io/en/glossary/abt-settlement/

An obligation may be calculated in another unit. Project rights say who is entitled. ABT is the settlement asset that can move when that obligation is executed.

Settlement asset is not an ownership token. The existing `abt` entry still holds: ABT is the unit the protocol meters and settles in.

---

## AFS

URL: https://www.arcblock.io/en/glossary/afs/

---

## AFS UI

URL: https://www.arcblock.io/en/glossary/afs-ui/

---

## Agent

URL: https://www.arcblock.io/en/glossary/agent/

---

## Agentic

URL: https://www.arcblock.io/en/glossary/agentic/

---

## AOS

URL: https://www.arcblock.io/en/glossary/aos/

---

## ARC

URL: https://www.arcblock.io/en/glossary/arc/

The product sentence above stays: ARC is the Blocklet runtime. In the Realm Computing vocabulary, that same runtime is where a Realm acts. An Arc may operate as a Worker. This does not rename ARC, and it does not say that every Arc is already joined to DARC.

---

## AUP

URL: https://www.arcblock.io/en/glossary/aup/

---

## Bitcoin

URL: https://www.arcblock.io/en/glossary/bitcoin/

---

## Block Explorer

URL: https://www.arcblock.io/en/glossary/block-explorer/

---

## Blockchain

URL: https://www.arcblock.io/en/glossary/blockchain/

---

## Blocklet

URL: https://www.arcblock.io/en/glossary/blocklet/

The product sentence above stays: a Blocklet is ARC's deployable unit. In this vocabulary it can also be an economic software unit — software that can have its own DID, owner, and settlement policy. That is the word. It is not a claim that every Blocklet already settles on a chain.

---

## Claim

URL: https://www.arcblock.io/en/glossary/claim/

---

## CLI

URL: https://www.arcblock.io/en/glossary/cli/

---

## Component Miner

URL: https://www.arcblock.io/en/glossary/component-miner/

The older reading was a developer who manually built reusable components. The AI-era reading is human intent and judgment, with Workers producing the component.

This is a role name in the vocabulary. It is not a claim that a miner marketplace is the current shipping product.

---

## Consensus

URL: https://www.arcblock.io/en/glossary/consensus/

---

## Context

URL: https://www.arcblock.io/en/glossary/context/

---

## Contribution

URL: https://www.arcblock.io/en/glossary/contribution/

Effort or spend is not enough. The chain this vocabulary uses is: resource, work, accepted output, then contribution.

Compute consumed is not contribution. Accepted useful output is.

---

## Crowd Building

URL: https://www.arcblock.io/en/glossary/crowd-building/

Crowdfunding asks people to fund something. Crowd Building lets people and Workers help make it.

This entry names the model. It is not a claim that a Crowd Building marketplace is the current shipping product.

---

## DAO

URL: https://www.arcblock.io/en/glossary/dao/

---

## Dapp

URL: https://www.arcblock.io/en/glossary/dapp/

---

## Darc Factory

URL: https://www.arcblock.io/en/glossary/darc-factory/

DARC is the protocol. Darc Factory is the production system on that protocol. The name also alludes to a dark factory: highly automated production with little direct human labor on the line.

This is a vocabulary term for a designed production system. It is not a claim that such a factory is the current shipping product.

---

## DARC Protocol

URL: https://www.arcblock.io/en/glossary/darc-protocol/

The working expansion is Decentralized Autonomous Resource Coordination. Decentralized Autonomous Realm Coordination is an accepted reading of the same name.

This entry names the protocol. It is not a claim that a public DARC implementation is the current shipping runtime.

Arc works. DARC is the word for Arcs working together.

---

## Decentralization

URL: https://www.arcblock.io/en/glossary/decentralization/

---

## Decentralized Identity

URL: https://www.arcblock.io/en/glossary/decentralized-identity/

---

## Delegation

URL: https://www.arcblock.io/en/glossary/delegation/

---

## Demand Contribution

URL: https://www.arcblock.io/en/glossary/demand-contribution/

Examples include naming a real problem, validating a use case, committing to buy, giving domain requirements, or testing product-market assumptions.

A purchase can make someone a credible demand-side participant. The purchase itself is not automatically a Contribution.

---

## Device

URL: https://www.arcblock.io/en/glossary/device/

---

## DID

URL: https://www.arcblock.io/en/glossary/did/

---

## did:abt

URL: https://www.arcblock.io/en/glossary/did-abt/

The `did:` prefix identifies the URI scheme; `abt` selects ArcBlock’s method; the final part is the method-specific identifier. ArcBlock’s format includes role, key and hash type information. An object’s DID identifies that object; it does not mean the object owns a private key or grants permissions by itself.

The method’s encoding and supported role types are documented in [Understanding DIDs](/en/docs/blockchain/understanding-dids/). See [DID at ArcBlock](/en/did/) for the products and architecture that use it.

## Implementation guides

- [Encoding and role types](/en/docs/blockchain/understanding-dids/)
- [Create and inspect a DID with the SDK](/en/docs/blockchain/working-with-dids/)
- [Accounts and wallets](/en/docs/blockchain/understanding-wallets-and-accounts/)
- [Token identifiers](/en/docs/blockchain/understanding-tokens/)
- [NFT](/en/docs/blockchain/understanding-nfts/)

---

## DID Document

URL: https://www.arcblock.io/en/glossary/did-document/

---

## DID Motif

URL: https://www.arcblock.io/en/glossary/did-motif/

---

## Docker

URL: https://www.arcblock.io/en/glossary/docker/

---

## Economic Composition

URL: https://www.arcblock.io/en/glossary/economic-composition/

Ordinary composition answers how function flows. This word adds how settlement and ownership follow the same composition.

If software can compose, ownership and settlement must compose too. This is the vocabulary. On-chain settlement of that graph is not the current shipping runtime.

---

## Ethereum

URL: https://www.arcblock.io/en/glossary/ethereum/

---

## FT

URL: https://www.arcblock.io/en/glossary/ft/

---

## Gas

URL: https://www.arcblock.io/en/glossary/gas/

---

## Governance

URL: https://www.arcblock.io/en/glossary/governance/

---

## GraphQL

URL: https://www.arcblock.io/en/glossary/graphql/

---

## gRPC

URL: https://www.arcblock.io/en/glossary/grpc/

---

## Ledger

URL: https://www.arcblock.io/en/glossary/ledger/

---

## LLM

URL: https://www.arcblock.io/en/glossary/llm/

---

## MCP

URL: https://www.arcblock.io/en/glossary/mcp/

---

## Multi-Agent

URL: https://www.arcblock.io/en/glossary/multi-agent/

---

## NFT

URL: https://www.arcblock.io/en/glossary/nft/

---

## OAuth

URL: https://www.arcblock.io/en/glossary/oauth/

---

## Operation Miner

URL: https://www.arcblock.io/en/glossary/operation-miner/

The older reading was a participant who helped operate, market, or sell ecosystem products. The AI-era reading includes work before the product exists: validating demand, shaping requirements, committing customers, or arranging distribution.

Building supply makes the product. Operation makes the market. This is a role name, not a shipping marketplace.

---

## Proof of Stake

URL: https://www.arcblock.io/en/glossary/pos/

---

## Proof of Work

URL: https://www.arcblock.io/en/glossary/pow/

---

## Realm

URL: https://www.arcblock.io/en/glossary/realm/

A Realm is identified and controlled through a DID. It does not have to represent a person. It may represent a person, an organization, a project, a software system, an AI agent, a device, or another Realm.

A Realm is not a user account. A user account exists inside somebody else's system. A Realm is controlled by its own subject.

---

## Realm Computing

URL: https://www.arcblock.io/en/glossary/realm-computing/

Instead of applications, data, agents, and resources being owned mainly by a centralized platform, they can belong to independent Realms and interact through open protocols.

This entry names the model. It is not a claim that every listed protocol in that model is already the shipping runtime.

---

## Recursive Settlement

URL: https://www.arcblock.io/en/glossary/recursive-settlement/

A product may settle to a component. That component may settle further to its own components and contributors, until the graph reaches terminal recipients.

This names the process. It is not a claim that recursive on-chain settlement is the current shipping runtime.

---

## Resource Miner

URL: https://www.arcblock.io/en/glossary/resource-miner/

The older reading was a participant supplying infrastructure such as cloud compute. The AI-era reading standardizes external AI resources into Workers, instead of recreating commodity cloud.

This is a role name in the vocabulary. It is not a claim that a miner marketplace is the current shipping product.

---

## Rollup

URL: https://www.arcblock.io/en/glossary/rollup/

---

## Runtime

URL: https://www.arcblock.io/en/glossary/runtime/

---

## SDK

URL: https://www.arcblock.io/en/glossary/sdk/

---

## Self-Sovereign Identity

URL: https://www.arcblock.io/en/glossary/self-sovereign-identity/

---

## Slashing

URL: https://www.arcblock.io/en/glossary/slashing/

---

## Small World

URL: https://www.arcblock.io/en/glossary/small-world/

---

## Smart Contract

URL: https://www.arcblock.io/en/glossary/smart-contract/

---

## Staking

URL: https://www.arcblock.io/en/glossary/staking/

---

## Token

URL: https://www.arcblock.io/en/glossary/token-blockchain/

---

## Token

URL: https://www.arcblock.io/en/glossary/token-llm/

---

## Transaction

URL: https://www.arcblock.io/en/glossary/transaction/

---

## UI Device

URL: https://www.arcblock.io/en/glossary/ui-device/

---

## Verifiable Credential

URL: https://www.arcblock.io/en/glossary/vc/

---

## Verifiable Contribution Token

URL: https://www.arcblock.io/en/glossary/vct/

VCT is the name of the record. VC is what it carries. The payload is the signed statement defined by the `vc` entry on this site — issuer, subject, and claims — not a second meaning of the word VC.

The project decides the policy around the VCT: transferable or not, vested or not, what the claims stand for. That policy sits on the envelope. The payload remains a VC.

DID identifies the subject. A VCT records what a project has recognized, using a VC as payload. ABT is the settlement asset.

---

## Verifiable Presentation

URL: https://www.arcblock.io/en/glossary/verifiable-presentation/

---

## Wallet

URL: https://www.arcblock.io/en/glossary/wallet/

---

## Web Device

URL: https://www.arcblock.io/en/glossary/web-device/

---

## Worker

URL: https://www.arcblock.io/en/glossary/worker/

A Worker may write code, research, test, design, write, sell, support, localize, or operate. It does not have to use one AI provider.

This is the concept. The `arc worker` CLI command is a different object: a command for attaching compute, not this glossary role.

---

## Worker Pool

URL: https://www.arcblock.io/en/glossary/worker-pool/

The pool can include subscriptions, local models, GPUs, cloud compute, specialized agents, and APIs. The interface is what a project sees, not the brand of model behind it.

A principle of this vocabulary: money can buy productive capacity. It does not buy contribution.

---

## AIGNE

URL: https://www.arcblock.io/en/products/aigne/

A framework for developers building agents. Start from the command line to create and run a project; use the framework documentation for the parts that need detail.

---

## AIGNE Hub

URL: https://www.arcblock.io/en/products/aigne-hub/

---

## AIGNE Studio

URL: https://www.arcblock.io/en/products/aigne-studio/

---

## Aistro

URL: https://www.arcblock.io/en/products/aistro/

---

## ARC

URL: https://www.arcblock.io/en/products/arc/

---

## ARC Space

URL: https://www.arcblock.io/en/products/arc-space/

A data space associated with a DID. Create a personal space, or connect an application with the permissions and data model its task requires.

---

## ArcBlock Chain

URL: https://www.arcblock.io/en/products/arcblock-chain/

---

## ArcBridge

URL: https://www.arcblock.io/en/products/arcbridge/

---

## ArcSphere

URL: https://www.arcblock.io/en/products/arcsphere/

ARC's mobile application surface. It gives supported ARC Blocklet experiences a coherent, app-like way to be used on a phone.

---

## ArcWallet

URL: https://www.arcblock.io/en/products/arcwallet/

The app for working with a DID and related credentials.

---

## Aside

URL: https://www.arcblock.io/en/products/aside/

---

## Block Explorer

URL: https://www.arcblock.io/en/products/block-explorer/

Look up transactions and DIDs on ArcBlock Main. Open the explorer to inspect a record or browse recent activity.

---

## Blocklet Launcher

URL: https://www.arcblock.io/en/products/blocklet-launcher/

---

## Blocklet Server

URL: https://www.arcblock.io/en/products/blocklet-server/

The server that hosted blocklets as subprocesses. ARC is where that work continues; the subprocess hosting model is not being carried forward.

---

## Blocklet Store

URL: https://www.arcblock.io/en/products/blocklet-store/

---

## Creator Studio

URL: https://www.arcblock.io/en/products/creator-studio/

---

## DID Connect

URL: https://www.arcblock.io/en/products/did-connect/

---

## DID Names

URL: https://www.arcblock.io/en/products/did-names/

---

## DID Spaces

URL: https://www.arcblock.io/en/products/did-spaces/

A data space associated with a DID. Create a personal space, or connect an application with the permissions and data model its task requires.

---

## DID Wallet

URL: https://www.arcblock.io/en/products/did-wallet/

The app for working with a DID and related credentials.

---

## DiscussKit

URL: https://www.arcblock.io/en/products/discuss-kit/

---

## DocSmith

URL: https://www.arcblock.io/en/products/docsmith/

---

## Forge

URL: https://www.arcblock.io/en/products/forge/

---

## Media Kit

URL: https://www.arcblock.io/en/products/media-kit/

---

## NFT Marketplace

URL: https://www.arcblock.io/en/products/nft-marketplace/

---

## NFT Studio

URL: https://www.arcblock.io/en/products/nft-studio/

---

## OCAP

URL: https://www.arcblock.io/en/products/ocap/

---

## Pages Kit

URL: https://www.arcblock.io/en/products/pages-kit/

---

## Payment Kit

URL: https://www.arcblock.io/en/products/payment-kit/

---

## Web3 Kit

URL: https://www.arcblock.io/en/products/web3-kit/

---

## WebSmith

URL: https://www.arcblock.io/en/products/websmith/

---

## ArcBlock Stack

URL: https://www.arcblock.io/en/technologies/arcblock-stack/

The layers applications, components, compute, storage, chain, and identity sit on. Products hang on these layers; this record is the stack, not any one product.