Merge pull request #29 from FhenixProtocol/vocs-init

architect-dev · web-flow · commit ed2b0b56b671 · 2026-02-23T18:09:20.000+01:00
[AR-84] [AR-89] Initialize documentation (vocs)
diff --git a/.changeset/README.md b/.changeset/README.md
@@ -15,6 +15,7 @@ This directory contains configuration and changeset files for managing versionin
   - `@cofhe/react`
   - `@cofhe/example-react`
   - `@cofhe/abi`
+  - `@cofhe/site`
 
 ## Contributor workflow
 
@@ -32,7 +33,7 @@ pnpm changeset
 
 ## Maintainer workflow
 
-1. Review and merge the auto‑opened Changesets “Version Packages” PR when you’re ready to cut a stable.
+1. Review and merge the auto‑opened Changesets "Version Packages" PR when you're ready to cut a stable.
 2. On merge, CI runs the stable job in `.github/workflows/publish.yml` and publishes to the `latest` dist‑tag.
 3. All packages in the fixed group publish together with the same version due to the fixed group in `.changeset/config.json`.
 
@@ -61,6 +62,7 @@ pnpm changeset status
 - Triggers: `push` to `master`
   - Beta job runs when commit message does NOT contain `Version Packages`
   - Stable job runs when commit message DOES contain `Version Packages`
+  - Docs deployment runs after stable releases to GitHub Pages
 - OIDC permissions are enabled (`id-token: write`, `contents: read`); npm provenance is enabled by default.
 
 ## Configuration
@@ -79,8 +81,13 @@ pnpm changeset status
 
 ## Troubleshooting
 
-- CI didn’t publish beta: ensure the merge commit message doesn’t include `Version Packages` and the workflow ran.
-- CI didn’t publish stable: ensure you merged the auto “Version Packages” PR and the workflow ran the stable job.
+- CI didn't publish beta: ensure the merge commit message doesn't include `Version Packages` and the workflow ran.
+- CI didn't publish stable: ensure you merged the auto "Version Packages" PR and the workflow ran the stable job.
+- Docs didn't deploy:
+  - Ensure GitHub Pages is configured to use "GitHub Actions" as the source in repository settings
+  - Check that the workflow has completed successfully
+  - Verify `pages: write` permission is set in the workflow
+  - For custom domains, configure them through repository settings (Settings → Pages → Custom domain), not via CNAME file
 - Private deps install errors: Trusted Publishers covers publish, not install; use a read‑only token for installs if needed.
 
 ## References
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -7,4 +7,4 @@
   "linked": [],
   "access": "public",
   "updateInternalDependencies": "patch"
-}
+}
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -54,10 +54,10 @@ jobs:
         with:
           version: 8
 
-      - name: Setup Node.js 20.x
+      - name: Setup Node.js 22.x
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org
 
       - name: Ensure latest npm
@@ -89,10 +89,10 @@ jobs:
         with:
           version: 8
 
-      - name: Setup Node.js 20.x
+      - name: Setup Node.js 22.x
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org
 
       - name: Ensure latest npm
diff --git a/package.json b/package.json
@@ -1,7 +1,8 @@
 {
   "private": true,
   "scripts": {
-    "build": "turbo run build --filter='!./examples/*'",
+    "build": "turbo run build --filter='!./examples/*' --filter='!./packages/site'",
+    "build:docs": "pnpm --filter @cofhe/site build",
     "dev": "turbo run dev",
     "test": "turbo run test",
     "test:integration": "pnpm --filter \"./packages/hardhat-plugin-test\" test:integration",
diff --git a/packages/site/README.md b/packages/site/README.md
@@ -0,0 +1,11 @@
+This is a [Vocs](https://vocs.dev) project bootstrapped with the Vocs CLI.
+
+## Requirements
+
+- Node.js >= 22
+
+## Development
+
+- `pnpm --filter @cofhe/site dev`
+- `pnpm --filter @cofhe/site build`
+- `pnpm --filter @cofhe/site preview`
diff --git a/packages/site/package.json b/packages/site/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "@cofhe/site",
+  "private": true,
+  "version": "0.2.1",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "vocs dev",
+    "build": "vocs build",
+    "preview": "vocs preview"
+  },
+  "dependencies": {
+    "glob": "^11.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vocs": "^1.4.1"
+  },
+  "devDependencies": {
+    "@cofhe/sdk": "workspace:*",
+    "@types/react": "latest",
+    "typescript": "latest"
+  }
+}
diff --git a/packages/site/pages/example.mdx b/packages/site/pages/example.mdx
@@ -0,0 +1,3 @@
+# Example
+
+This is an example page.
diff --git a/packages/site/pages/foundry.mdx b/packages/site/pages/foundry.mdx
@@ -0,0 +1 @@
+The `@cofhe/foundry` package is currently in development.
diff --git a/packages/site/pages/getting-started.mdx b/packages/site/pages/getting-started.mdx
@@ -0,0 +1,3 @@
+# Get started
+
+Hello world!
diff --git a/packages/site/pages/hardhat.mdx b/packages/site/pages/hardhat.mdx
@@ -0,0 +1 @@
+Getting started with cofhesdk hardhat plugin (TOP LEVEL)
diff --git a/packages/site/pages/hardhat/client.mdx b/packages/site/pages/hardhat/client.mdx
@@ -0,0 +1,5 @@
+# Client
+
+Creating & connecting the Hardhat client
+
+WIP
diff --git a/packages/site/pages/hardhat/getting-started.mdx b/packages/site/pages/hardhat/getting-started.mdx
@@ -0,0 +1 @@
+Getting started with cofhesdk hardhat plugin
diff --git a/packages/site/pages/hardhat/logging.mdx b/packages/site/pages/hardhat/logging.mdx
@@ -0,0 +1,5 @@
+# Logging
+
+How to read logs, how to enable / disable
+
+WIP
diff --git a/packages/site/pages/hardhat/mock-contracts.mdx b/packages/site/pages/hardhat/mock-contracts.mdx
@@ -0,0 +1,5 @@
+# Mock Contracts
+
+Deep dive on mocks: how it replicates inputs / ops / decryption in mock environment, how sdk integrates (sdk knows if in mock environment and handles it)
+
+WIP
diff --git a/packages/site/pages/hardhat/testing.mdx b/packages/site/pages/hardhat/testing.mdx
@@ -0,0 +1,5 @@
+# Testing
+
+How to write hardhat tests and read "encrypted" data directly
+
+WIP
diff --git a/packages/site/pages/index.mdx b/packages/site/pages/index.mdx
@@ -32,11 +32,11 @@ The SDK ships multiple entrypoints so you can pick the right defaults for your r
 
 ```ts twoslash
 // @noErrors
-import { createCofheClient, createCofheConfig } from '@cofhe/sdk/web';
+import { createCofhesdkClient, createCofhesdkConfig } from '@cofhe/sdk/web';
 // or
 import {
-  createCofheClient as createCofheClientNode,
-  createCofheConfig as createCofheConfigNode,
+  createCofhesdkClient as createCofhesdkClientNode,
+  createCofhesdkConfig as createCofhesdkConfigNode,
 } from '@cofhe/sdk/node';
 
 import { PermitUtils } from '@cofhe/sdk/permits';
diff --git a/packages/site/pages/migrating-from-cofhejs.mdx b/packages/site/pages/migrating-from-cofhejs.mdx
@@ -0,0 +1,61 @@
+# Migrating from `cofhejs`
+
+`cofhesdk` is an improved replacement for `cofhejs`. Improvements are focused around:
+- explicit api
+- developer experience
+- flexibility
+
+### Key Changes:
+
+- Functions are encapsulated in a new `client` class.
+- No longer need to wait for initialization (keys fetched during encrypt)
+- Permits must be explicitly generated, preventing unknown signature requests in users' wallets.
+- Top level configuration of cofhesdk behavior.
+- Explicit overrides and settings in `encryptInputs` and `decryptHandle` functions.
+- Better feedback and error handling in functions.
+- Better multichain usage
+
+### Requirements:
+
+- Node.js: 18+
+- React: 18+
+- TypeScript: 5+
+- Wagmi: 2+
+- Viem: 2+
+
+### Installation:
+
+```bash
+npm install @cofhe/sdk
+```
+
+### Migration
+
+#### Initializing the library
+
+`cofhejs` is initialized with `cofhejs.initializeWithViem(...)`. Initialization involves fetching FHE keys, connecting to the supplied provider and signer, and 
+`cofhesdk` encapsulates all functions in a new `client`, which is created with a `config` param
+
+- link to config api for full breakdown of options
+
+#### Encrypting inputs
+
+- Why - more explicit, more customizable, loads keys during encrypt
+- Old - example (encrypt)
+- New - example (encryptInputs)
+- Customizable - setAccount, setChainId, setSecurityZone, setStepCallback
+
+#### Decrypting handles
+
+- Why - more explicit, more customizable
+- Old - example (unseal)
+- New - example (decryptHandle)
+- Customizable - setAccount, setChainId, setPermitHash, setPermit
+
+#### Permits
+
+- Why - Permits require a user signature (must be transparent and understandable), permits are complex with overlapping use cases, so a more explicit api was needed
+- Why - Better type safety
+- Old - example of auto-generation, example of usage in unseal
+- New - example of manual generation, example of usage in decryptHandle
+- 
diff --git a/packages/site/pages/quick-start.mdx b/packages/site/pages/quick-start.mdx
@@ -0,0 +1,5 @@
+# Quick Start
+
+Getting started with cofhesdk
+
+WIP
diff --git a/packages/site/pages/react.mdx b/packages/site/pages/react.mdx
@@ -0,0 +1 @@
+The `@cofhe/react` package is currently in development.
diff --git a/packages/site/pages/sdk/client.mdx b/packages/site/pages/sdk/client.mdx
@@ -2,14 +2,14 @@
 
 This page covers the core SDK lifecycle:
 
-1. Create config (`createCofheConfig`)
-2. Create client (`createCofheClient`)
+1. Create config (`createCofhesdkConfig`)
+2. Create client (`createCofhesdkClient`)
 3. Connect to client (`client.connect`)
 4. Managing connection (change account / disconnect)
 
 ## 1) Create config
 
-Import `createCofheConfig` from the entrypoint that matches your runtime:
+Import `createCofhesdkConfig` from the entrypoint that matches your runtime:
 
 - Browser apps: `@cofhe/sdk/web`
 - Node.js scripts/backends: `@cofhe/sdk/node`
@@ -18,10 +18,10 @@ The only required field is `supportedChains`.
 
 ```ts twoslash
 // @noErrors
-import { createCofheConfig } from '@cofhe/sdk/web';
+import { createCofhesdkConfig } from '@cofhe/sdk/web';
 import { chains } from '@cofhe/sdk/chains';
 
-const config = createCofheConfig({
+const config = createCofhesdkConfig({
   supportedChains: [chains.sepolia],
 
   // Optional knobs
@@ -32,20 +32,20 @@ const config = createCofheConfig({
 
 ## 2) Create cofhe client
 
-Import `createCofheClient` from the entrypoint that matches your runtime:
+Import `createCofhesdkClient` from the entrypoint that matches your runtime:
 
 - Browser apps: `@cofhe/sdk/web`
 - Node.js scripts/backends: `@cofhe/sdk/node`
 
 ```ts twoslash
 // @noErrors
-import { createCofheClient } from '@cofhe/sdk/web';
+import { createCofhesdkClient } from '@cofhe/sdk/web';
 import type { CofhesdkConfig } from '@cofhe/sdk';
 
 // config from the previous step
 declare const config: CofhesdkConfig;
 
-const cofheClient = createCofheClient(config);
+const cofheClient = createCofhesdkClient(config);
 
 cofheClient.connected; // false
 cofheClient.connecting; // false
@@ -66,14 +66,14 @@ Connecting initializes the SDK's in-memory connection state (`account`, `chainId
 
 ```ts twoslash
 // @noErrors
-import { createCofheClient } from '@cofhe/sdk/web';
+import { createCofhesdkClient } from '@cofhe/sdk/web';
 import type { CofhesdkConfig } from '@cofhe/sdk';
 import type { PublicClient, WalletClient } from 'viem';
 import { createPublicClient, createWalletClient, http } from 'viem';
 import { sepolia } from 'viem/chains';
 
 declare const config: CofhesdkConfig;
-const cofheClient = createCofheClient(config);
+const cofheClient = createCofhesdkClient(config);
 
 const publicClient = createPublicClient({
   chain: sepolia,
diff --git a/packages/site/pages/sdk/decrypt-to-tx.mdx b/packages/site/pages/sdk/decrypt-to-tx.mdx
@@ -0,0 +1,3 @@
+# Decrypting to Transact
+
+WIP
diff --git a/packages/site/pages/sdk/decrypt-to-view.mdx b/packages/site/pages/sdk/decrypt-to-view.mdx
@@ -0,0 +1,5 @@
+# Decrypting to View
+
+Decrypting to view data
+
+WIP
diff --git a/packages/site/pages/sdk/encrypting-inputs.mdx b/packages/site/pages/sdk/encrypting-inputs.mdx
@@ -0,0 +1,3 @@
+# Encrypting Inputs
+
+WIP
diff --git a/packages/site/pages/sdk/permits.mdx b/packages/site/pages/sdk/permits.mdx
@@ -0,0 +1,5 @@
+# Permits
+
+Creating & managing permits
+
+WIP
diff --git a/packages/site/tsconfig.json b/packages/site/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}
diff --git a/packages/site/vocs.config.ts b/packages/site/vocs.config.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/turbo.json b/turbo.json

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Example`
	`2`	`+`
	`3`	`+This is an example page.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+The `@cofhe/foundry` package is currently in development.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Get started`
	`2`	`+`
	`3`	`+Hello world!`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Getting started with cofhesdk hardhat plugin (TOP LEVEL)`