@aigne/afs-ocap 1.12.0-beta.5

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,144 @@
+# @aigne/afs-ocap
+
+AFS provider for the Arcblock OCAP verifiable ledger — read-only GraphQL-over-HTTPS view of transactions, accounts, tokens, factories, bridges, etc.
+
+## Installation
+
+```bash
+pnpm add @aigne/afs-ocap
+```
+
+## Usage
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSOCAP } from "@aigne/afs-ocap";
+
+const afs = new AFS();
+afs.mount(
+  new AFSOCAP({
+    endpoint: "https://main.abtnetwork.io/api",
+    name: "main-chain",
+  }),
+  "/dev/chain/main",
+);
+
+// Browse on-chain data
+const blocks = await afs.list("/dev/chain/main/blocks");
+const tx = await afs.read("/dev/chain/main/transactions/<hash>");
+```
+
+The `BUILTIN_CHAIN_NETWORKS` constant from `@aigne/aos` covers `main` + `beta` so most setups don't need to mount manually — `arc service start` (Node) and `createAfsFromEnv` (Cloudflare Worker) auto-mount these chains under `/dev/chain/<network>` when `AFS_MOUNTS` doesn't already declare them.
+
+## Companion AUP recipes
+
+The `aup/` directory ships AUP recipes (e.g. `default.json`, `accounts/item.json`, `transactions/default.json`) that AFS projects as hidden supplements at `/dev/chain/<network>/.aup/<view>` so blocklets like `chain-explorer` can render rich UI without bundling chain-specific layout code.
+
+Two delivery paths exist, transparent to consumers:
+
+| Runtime | Path | Mechanism |
+|---|---|---|
+| Node | local filesystem | `loadPackageDirAsResources` reads `<package>/aup/` directly |
+| Cloudflare Worker | `https://afsd-blocklets.pages.dev/_providers/ocap@<version>/` | `AFSHttpMount` fetches `.afs/manifest.json` + `.afs/bundle.json` |
+
+The Worker can't read `node_modules` at runtime, so recipes are published to a CF Pages namespace alongside blocklets. URL embeds the package version so old workers always fetch their old recipes — no skew.
+
+## Releasing
+
+When publishing a new OCAP version:
+
+1. **Bump `package.json` version** and merge to `main` (release-please handles version + changelog).
+2. **Publish recipes to CF Pages** so the new Worker bundle (which inlines this version into URLs) finds them:
+
+   ```bash
+   arc provider publish-resources @aigne/afs-ocap \
+     --cloud cf \
+     --project afsd-blocklets \
+     --cf-account-id "$CF_ACCOUNT_ID" \
+     --cf-api-token "$CF_API_TOKEN"
+   ```
+
+   This pushes `aup/**/*.json` to `/_providers/ocap@<version>/` on CF Pages (with `.afs/manifest.json` + `.afs/bundle.json` wrappers). CI should run this after release-please merges to `main`.
+
+3. **Deploy the Worker** (any subsequent `arc worker deploy` cycle picks up the new `__OCAP_VERSION__` from `build.mjs`).
+
+The order matters: if the Worker deploys before recipes are published, it will fail to fetch the new version's manifest and chain device AUP supplements will be silently absent (graceful-degrade — the data tree is still readable, just no AUP-styled UI). The publish step is idempotent, so re-running is safe.
+
+For the local dev workflow (`arc worker dev`), recipes are served from `blocklets-dev-server` at `http://127.0.0.1:8788/_providers/ocap@<workspace-version>/` — no publish needed.
+
+## Subscribe Capability
+
+This provider opts into the AFS `subscribe` operation when the supplied
+`OcapDataSource` exposes a working `subscribe(topic, callback)` primitive
+(typically wrapping `@ocap/client.subscribe` over phoenix WS). The
+capability manifest at `/<mount>/.meta/.capabilities` reports:
+
+```json
+{
+  "operations": {
+    "subscribe": {
+      "supported": true,
+      "features": {
+        "live": true,
+        "eventTypes": "append,write",
+        "maxRateHz": 100,
+        "scope": "global"
+      }
+    }
+  }
+}
+```
+
+The `live` flag reflects runtime reality: if the underlying source has no
+`subscribe()` method, or if the install throws (e.g. the worker bundle
+fails to import `@arcblock/ws`), the provider degrades to `live: false`
+and continues serving reads. The mount itself never fails because of a
+missing subscribe path.
+
+When live is on, each upstream `tx.create` payload becomes an AFS
+`afs:append` event at `<mount>/transactions/<hash>` carrying
+`{ hash, type, time, sender, receiver }`. Consumers subscribe via
+`afs.subscribe({ path: "/<mount>/transactions" }, callback)`. The
+per-connection event broker (providers/runtime/ui) coalesces bursts and
+paces by `maxRateHz`, so high-traffic chains don't flood the WS link.
+
+Runtime behavior:
+- **Node**: source dynamically imports `@ocap/client/subscribe`; the WS
+  client is whatever ships in the Node export condition.
+- **Worker (Cloudflare)**: subscribe support is adapter-dependent — see
+  `planning/afs-ui/afs-live-updates/worker-research.md`. Workers that
+  cannot install the WS client report `live: false` and chain UIs fall
+  back to user-initiated refresh.
+
+See `planning/afs-ui/afs-live-updates/` for the broader event vocabulary,
+broker design, and the framework-level `_aupListBind` consumer.
+
+## Typed where（`whereToOcapOptions` 适配器）
+
+list 选项接受 typed `where`（afs-collection-query T5.3）——chain-explorer 的
+tx filter Apply 即此形态。`listOpts()` 是唯一注入点：`options.where` 存在时，
+`whereToOcapOptions()` 把 typed where 翻译成 7 个 `extract*Filters` 入口消费的
+旧私有 option key（adapter 输出覆盖同名私有 key），**GQL 过滤结构逐字节不变**。
+
+字段词汇表（OCAP 实体字段，design §3.2：词汇表语义归 provider）：
+
+| 类 | 字段 | 算子 |
+|---|---|---|
+| 标量 | sender / receiver / direction / validity / issuerAddress / ownerAddress / factoryAddress / tokenAddress / from / to | `eq` |
+| 列表 | types / tokens / assets / factories / accounts / rollups / stakes / delegations / addressList | `eq`（单值）/ `in` |
+| 时间 | `time` | `gte`→startDateTime / `lte`→endDateTime（ISO 串） |
+
+安全两层（任一违反 = `AFSValidationError`，绝不触达 GQL 变量）：
+
+1. core 文法（dot-path 白名单、原型键拒绝、算子 arity）；
+2. 词汇表门——表外字段、类不允许的算子、非字符串值一律 strict 拒绝。
+   注入形值（如 `") { evil } #`）作为**数据**进 GQL variable，惰性无害。
+
+空哨兵语义：`eq: ""` / `in: []`（表单未触碰态）= 不过滤，镜像 extractor 既有的
+空值语义。测试：`test/where-adapter.test.ts`（7 extractor 等价 + 安全负例）。
+
+## See also
+
+- [`runtimes/cloudflare/README.md`](../../../runtimes/cloudflare/README.md) — Cloudflare worker dev workflow
+- [`planning/provider-resource-distribution/`](../../../planning/provider-resource-distribution/README.md) — design rationale for the `_providers/<name>@<version>/` namespace
+- [`planning/afs-ui/afs-live-updates/`](../../../planning/afs-ui/afs-live-updates/) — AFS event vocab + broker + OCAP producer design

package/aup/accounts/default.json

@@ -0,0 +1,64 @@
+{
+  "id": "accts-view",
+  "type": "view",
+  "props": {
+    "layout": {
+      "direction": "column",
+      "gap": "none"
+    },
+    "style": {
+      "flex": "1",
+      "overflow": "auto"
+    }
+  },
+  "children": [
+    {
+      "id": "accts-title",
+      "type": "text",
+      "props": { "content": "Accounts", "level": 1 }
+    },
+    {
+      "id": "accts-view-list",
+      "type": "afs-list",
+      "src": "${_parentPath}",
+      "props": {
+        "layout": "table",
+        "columns": [
+          {
+            "key": "content.address",
+            "label": "Address",
+            "mobileRole": "title",
+            "format": "did",
+            "width": "200px"
+          },
+          {
+            "key": "content._monikerDisplay",
+            "label": "Name",
+            "width": "150px"
+          },
+          {
+            "key": "content.genesisTime",
+            "label": "Created",
+            "format": "timeago",
+            "width": "120px"
+          },
+          {
+            "key": "content.renaissanceTime",
+            "label": "Updated",
+            "hideBelow": "tablet-wide",
+            "format": "timeago",
+            "width": "120px"
+          }
+        ],
+        "pageSize": 20,
+        "pagination": "manual",
+        "clickMode": "both",
+        "autoSelect": false,
+        "filter": {
+          "exclude": ".."
+        },
+        "showBreadcrumb": false
+      }
+    }
+  ]
+}