@meddleware/dev 0.0.1

package/docs/getting-started/toolchain.md

@@ -0,0 +1,83 @@
+# Toolchain
+
+## Node.js
+
+The workspace targets **Node.js 22.18.0 or ≥ 24.12.0**. Use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to manage versions:
+
+```bash
+# fnm (recommended — fast, written in Rust)
+curl -fsSL https://fnm.vercel.app/install | bash
+fnm install 24
+fnm use 24
+node --version  # v24.x.x
+```
+
+## Sui and Walrus CLIs — suiup
+
+All Sui and Walrus binaries are managed by **suiup**, a version manager analogous to rustup:
+
+```bash
+# Install suiup
+curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh
+# suiup installs to ~/.local/bin/suiup; symlinks at /usr/local/bin/sui and /usr/local/bin/walrus
+
+# Install the testnet-channel binaries
+suiup install sui@testnet
+suiup install walrus@testnet
+
+# Pin to the exact versions used in this workspace
+suiup install sui@testnet-v1.76.1
+suiup switch sui@testnet-v1.76.1
+
+suiup install walrus@testnet-v1.53.0
+suiup switch walrus@testnet-v1.53.0
+
+# Verify
+sui --version     # sui testnet-v1.76.1
+walrus --version  # walrus testnet-v1.53.0
+```
+
+### Checking for updates
+
+```bash
+suiup show    # installed and active versions
+suiup status  # check whether newer testnet releases are available
+```
+
+When a new testnet release ships, install and switch:
+
+```bash
+suiup install sui@testnet-vX.Y.Z
+suiup switch  sui@testnet-vX.Y.Z
+suiup install walrus@testnet-vX.Y.Z
+suiup switch  walrus@testnet-vX.Y.Z
+```
+
+## Sui wallet
+
+Install any Sui-compatible wallet browser extension. [Slush](https://slush.app/) is recommended for development.
+
+Create a new address for testnet work:
+
+```bash
+sui client new-address ed25519
+# Copy the address shown and fund it from the testnet faucet
+```
+
+Fund the address from the [Sui testnet faucet](https://faucet.sui.io/).
+
+## npm workspaces
+
+The monorepo uses npm workspaces. Install all dependencies from the workspace root:
+
+```bash
+cd workspace/
+npm install
+```
+
+Individual packages can be built or tested independently:
+
+```bash
+cd repos/walrus-ui && npm run build
+cd repos/seal-ui   && npm run type-check
+```

package/docs/index.md

@@ -0,0 +1,44 @@
+---
+layout: home
+
+hero:
+  name: "Meddleware Dev"
+  text: "Build on the platform"
+  tagline: Integration guides, design-system usage, and Sui development patterns.
+  actions:
+    - theme: brand
+      text: Getting started
+      link: /getting-started/
+    - theme: alt
+      text: Sui development
+      link: /sui/
+    - theme: alt
+      text: User docs →
+      link: https://docs.meddleware.co.uk
+
+features:
+  - title: Design system
+    details: Consume @meddleware/design-tokens and @meddleware/ui in a Vue 3 app — sacred-geometry scales, seasonal theming, focus/noise utilities.
+    link: /design-system/
+    linkText: Design system
+  - title: Walrus Storage
+    details: Upload, read, and extend blobs with the @meddleware/walrus-client SDK. Self-host your own Walrus relay.
+    link: /sui/walrus-storage/
+    linkText: Walrus Storage
+  - title: Sealed Storage
+    details: Encrypt data on Walrus with on-chain access-control policies. Write Move policies and integrate the @meddleware/seal-client SDK.
+    link: /sui/sealed-storage/
+    linkText: Sealed Storage
+  - title: Access Gate
+    details: Create NFT access-gate passes, verify them in your app, and deploy the nft-gate gateway.
+    link: /sui/access-gate/
+    linkText: Access Gate
+  - title: DAO
+    details: Interact with the Meddleware DAO from code — governance PTBs, on-chain objects, and treasury reads.
+    link: /sui/dao/
+    linkText: DAO
+  - title: API reference
+    details: Full TypeDoc SDK reference lives in the user docs — every exported function, type, and class.
+    link: https://docs.meddleware.co.uk/blockchain/sui/
+    linkText: API reference →
+---

package/docs/sui/access-gate/gateway.md

@@ -0,0 +1,159 @@
+# Deploy the NFT Gate gateway
+
+The NFT Gate gateway handles the off-chain challenge/proof protocol. It issues nonces, verifies NFT ownership on-chain, and returns short-lived JWTs. Two implementations are available: a Rust/Axum service and a Cloudflare Workers implementation.
+
+## Implementations
+
+| Implementation | Location | Best for |
+| --- | --- | --- |
+| Rust/Axum | `services/nft-gate/gateway/` | Self-hosted, k8s, low latency |
+| Cloudflare Worker | `services/nft-gate/worker/` | Edge deployment, zero-infra |
+
+---
+
+## Rust/Axum gateway
+
+### Build
+
+```bash
+cd services/nft-gate/gateway
+cargo build --release
+```
+
+### Configuration
+
+The gateway reads environment variables:
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `SUI_NETWORK` | `testnet` or `mainnet` | `testnet` |
+| `SUI_RPC_URL` | Sui gRPC endpoint | testnet default |
+| `JWT_SECRET` | HMAC-SHA256 signing secret (≥32 bytes) | — required |
+| `CHALLENGE_TTL_SECS` | Nonce expiry | `120` |
+| `TOKEN_TTL_SECS` | JWT lifetime | `3600` |
+| `LISTEN_ADDR` | Bind address | `0.0.0.0:3000` |
+| `LOG_LEVEL` | `debug`/`info`/`warn`/`error` | `info` |
+
+Create `.env`:
+
+```bash
+SUI_NETWORK=testnet
+JWT_SECRET=<at-least-32-random-bytes-base64>
+CHALLENGE_TTL_SECS=120
+TOKEN_TTL_SECS=3600
+```
+
+### Run
+
+```bash
+cargo run --release
+# or with .env file
+env $(cat .env | xargs) cargo run --release
+```
+
+### k8s deployment
+
+A `Deployment` and `Service` manifest live in `post-bootstrap/nft-gate/`. The gateway is exposed via nginx-ingress at `https://nft-gate.meddleware.co.uk`. Secrets are mounted from a k8s `Secret` object:
+
+```yaml
+env:
+  - name: JWT_SECRET
+    valueFrom:
+      secretKeyRef:
+        name: nft-gate-secrets
+        key: jwt-secret
+```
+
+---
+
+## Cloudflare Workers implementation
+
+The Worker implementation lives in `services/nft-gate/worker/`. It is functionally equivalent to the Rust gateway but runs at the Cloudflare edge.
+
+### Prerequisites
+
+- Cloudflare account with Workers enabled.
+- Wrangler CLI: `npm install -g wrangler`.
+
+### Configuration
+
+```toml
+# services/nft-gate/worker/wrangler.toml
+name = "nft-gate"
+main = "src/index.ts"
+compatibility_date = "2025-01-01"
+
+[vars]
+SUI_NETWORK = "testnet"
+CHALLENGE_TTL_SECS = "120"
+TOKEN_TTL_SECS = "3600"
+```
+
+Store secrets:
+
+```bash
+wrangler secret put JWT_SECRET
+# Paste a random ≥32-byte base64-encoded value
+```
+
+### Deploy
+
+```bash
+cd services/nft-gate/worker
+npm install
+wrangler deploy
+```
+
+---
+
+## API endpoints
+
+Both implementations expose the same HTTP API:
+
+### `POST /challenge`
+
+Request a challenge nonce for a pass.
+
+**Body:**
+```json
+{ "gateId": "0x...", "passId": "0x..." }
+```
+
+**Response:**
+```json
+{ "challenge": "meddleware-access:v1:<nonce>", "nonce": "<hex>" }
+```
+
+### `POST /verify`
+
+Submit the signed challenge and receive a JWT.
+
+**Body:**
+```json
+{
+  "gateId": "0x...",
+  "passId": "0x...",
+  "nonce": "<hex>",
+  "address": "0x...",
+  "signature": "<base64>"
+}
+```
+
+**Response:**
+```json
+{ "token": "<jwt>", "expiresAt": 1234567890 }
+```
+
+### `GET /health`
+
+Returns `{ "status": "ok" }`. Used by the relay registry ping check.
+
+---
+
+## JSON-RPC deprecation notice
+
+::: warning Public fullnodes killed JSON-RPC in September 2026
+The gateway uses `@mysten/sui` v2.x which routes through gRPC/GraphQL automatically. Do not configure an RPC URL ending in `/json-rpc` — it will fail. If you are running your own fullnode, ensure the gRPC port is reachable.
+:::
+
+<!-- white-label: operator customization guide (custom JWT claims, RBAC, rate limits, enterprise SSO) — planned -->

package/docs/sui/access-gate/index.md

@@ -0,0 +1,62 @@
+# Access Gate — SDK setup
+
+[User docs →](https://docs.meddleware.co.uk/blockchain/sui/access-gate/) | [API reference →](https://docs.meddleware.co.uk/blockchain/sui/access-gate/reference)
+
+The Access Gate lets operators create on-chain NFT pass systems. Each gate can mint unlimited-use or single-use passes, optionally soulbound to the buyer's address. Operators and the platform earn commission on each sale.
+
+## Install
+
+```bash
+npm install @meddleware/nft-gate-client @mysten/sui
+```
+
+## Initialise the client
+
+```ts
+import { NftGateClient } from '@meddleware/nft-gate-client'
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const suiClient   = new SuiClient({ url: getFullnodeUrl('testnet') })
+const gateClient  = new NftGateClient({
+  suiClient,
+  network: 'testnet',
+  gatewayUrl: import.meta.env.VITE_NFT_GATE_URL ?? 'https://nft-gate.meddleware.co.uk',
+})
+```
+
+## Key concepts
+
+| Term | Description |
+| --- | --- |
+| `Gate` | On-chain object representing an access system (price, supply, commission config) |
+| `AdminCap` | Capability object held by the gate operator; required for privileged operations |
+| `AccessPass` | NFT minted when a user buys access |
+| Soulbound | A pass bound to one address — non-transferable |
+| Challenge/proof | Off-chain protocol: gateway issues a nonce; client signs it with the pass |
+
+## Quick start
+
+Check whether an address holds a valid pass for a gate:
+
+```ts
+const hasAccess = await gateClient.hasValidPass(gateId, walletAddress)
+```
+
+Buy a pass:
+
+```ts
+import { Transaction } from '@mysten/sui/transactions'
+
+const tx = new Transaction()
+const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(priceInMist)])
+const [pass]  = tx.moveCall({
+  target: `${ACCESS_GATE_PACKAGE}::access_gate::buy`,
+  arguments: [tx.object(gateId), coin, tx.object(PLATFORM_CONFIG_ID)],
+})
+tx.transferObjects([pass], tx.pure.address(buyerAddress))
+await signAndExecute({ transaction: tx })
+```
+
+See [Integration guide](./integration) for the full purchase → verify flow and [Deploy the gateway](./gateway) for self-hosting the challenge/proof gateway.
+
+<!-- white-label: operator guide (custom gate config, commission setup, branded pass metadata) — planned -->

package/docs/sui/access-gate/integration.md

@@ -0,0 +1,168 @@
+# Access Gate — Integration guide
+
+## Full purchase → verify flow
+
+### Purchase a pass
+
+```ts
+import { Transaction } from '@mysten/sui/transactions'
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const PACKAGE    = import.meta.env.VITE_ACCESS_GATE_PACKAGE
+const GATE_ID    = import.meta.env.VITE_GATE_ID
+const PLATFORM   = import.meta.env.VITE_PLATFORM_CONFIG_ID
+
+async function buyPass(
+  suiClient: SuiClient,
+  signer: { address: string; signAndExecute: (tx: Transaction) => Promise<string> },
+  priceInMist: bigint,
+): Promise<string> {
+  const tx = new Transaction()
+  const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(priceInMist)])
+  const [pass]  = tx.moveCall({
+    target: `${PACKAGE}::access_gate::buy`,
+    arguments: [tx.object(GATE_ID), coin, tx.object(PLATFORM)],
+  })
+  tx.transferObjects([pass], tx.pure.address(signer.address))
+
+  const digest = await signer.signAndExecute(tx)
+  return digest
+}
+```
+
+### Verify a pass off-chain (challenge/proof)
+
+The gateway issues a one-time nonce; the client must sign it with the pass object to prove ownership.
+
+```ts
+import { NftGateClient } from '@meddleware/nft-gate-client'
+
+async function getAccessToken(
+  gateClient: NftGateClient,
+  signer: { address: string; sign: (msg: Uint8Array) => Promise<Uint8Array> },
+  gateId: string,
+  passId: string,
+): Promise<string> {
+  // 1. Request a challenge from the gateway
+  const { challenge, nonce } = await gateClient.requestChallenge({ gateId, passId })
+
+  // 2. Sign the challenge with the user's wallet
+  const signature = await signer.sign(new TextEncoder().encode(challenge))
+
+  // 3. Submit the proof; receive a short-lived JWT
+  const { token } = await gateClient.submitProof({
+    gateId,
+    passId,
+    nonce,
+    signature,
+    address: signer.address,
+  })
+
+  return token
+}
+```
+
+The `token` is a signed JWT issued by the gateway. Present it in the `Authorization: Bearer <token>` header when calling any gated API endpoint.
+
+### Nonce requirements
+
+The `access_gate` Move package requires a minimum nonce length of 8 bytes. The gateway enforces this automatically. If you are calling the contract directly (not via the gateway), generate at least 8 bytes of entropy:
+
+```ts
+const nonce = crypto.getRandomValues(new Uint8Array(8))
+```
+
+### Check pass validity before gating
+
+```ts
+const hasAccess = await gateClient.hasValidPass(gateId, walletAddress)
+if (!hasAccess) {
+  // Prompt user to purchase
+}
+```
+
+## Using with dapp-kit
+
+Wire the wallet from `@mysten/dapp-kit`:
+
+```ts
+import { useCurrentAccount, useSignPersonalMessage, useSignAndExecuteTransaction } from '@mysten/dapp-kit'
+import { Transaction } from '@mysten/sui/transactions'
+
+const account = useCurrentAccount()
+const { mutateAsync: signPersonalMessage } = useSignPersonalMessage()
+const { mutateAsync: signAndExecuteTransaction } = useSignAndExecuteTransaction()
+
+const signer = {
+  address: account.value!.address,
+  sign: async (msg: Uint8Array) => {
+    const { signature } = await signPersonalMessage({ message: msg })
+    return signature
+  },
+  signAndExecute: async (tx: Transaction) => {
+    const { digest } = await signAndExecuteTransaction({ transaction: tx })
+    return digest
+  },
+}
+```
+
+## Error handling
+
+```ts
+import { NftGateError, GateNotFoundError, PassExpiredError } from '@meddleware/nft-gate-client'
+
+try {
+  const token = await getAccessToken(gateClient, signer, gateId, passId)
+} catch (err) {
+  if (err instanceof GateNotFoundError) {
+    console.error('Gate does not exist:', gateId)
+  } else if (err instanceof PassExpiredError) {
+    console.error('Pass is expired or consumed')
+  } else if (err instanceof NftGateError) {
+    console.error('Gateway error:', err.code, err.message)
+  }
+  throw err
+}
+```
+
+## Vue composable
+
+```ts
+// composables/useAccessGate.ts
+import { ref } from 'vue'
+import { NftGateClient } from '@meddleware/nft-gate-client'
+
+export function useAccessGate(gateClient: NftGateClient) {
+  const checking  = ref(false)
+  const hasAccess = ref<boolean | null>(null)
+  const token     = ref<string | null>(null)
+  const error     = ref<Error | null>(null)
+
+  async function check(gateId: string, address: string) {
+    checking.value  = true
+    error.value     = null
+    try {
+      hasAccess.value = await gateClient.hasValidPass(gateId, address)
+    } catch (e) {
+      error.value = e as Error
+    } finally {
+      checking.value = false
+    }
+  }
+
+  async function authenticate(
+    gateId: string,
+    passId: string,
+    signer: { address: string; sign: (msg: Uint8Array) => Promise<Uint8Array> },
+  ) {
+    error.value = null
+    try {
+      token.value = await getAccessToken(gateClient, signer, gateId, passId)
+    } catch (e) {
+      error.value = e as Error
+    }
+  }
+
+  return { checking, hasAccess, token, error, check, authenticate }
+}
+```

package/docs/sui/dao/index.md

@@ -0,0 +1,154 @@
+# DAO — Governance integration
+
+[User docs →](https://docs.meddleware.co.uk/blockchain/sui/dao/) | [API reference →](https://docs.meddleware.co.uk/blockchain/sui/dao/reference)
+
+The vault DAO governs privileged parameters — fee rates, strategy allocations, skim thresholds, fee recipients, and access gate policy. The `vault_dao` package issues `DaoAdminCap` to the multisig governor; `vault_governor` gates privileged operations behind it.
+
+## Key objects
+
+| Object | Description |
+| --- | --- |
+| `DaoAdminCap` | Owned object; required as a witness for all DAO-gated calls |
+| `ConfigState` | Shared object; holds all DAO-governed parameters |
+| `vault_governor` | Package that executes privileged vault operations given `DaoAdminCap` |
+
+## Reading current config
+
+```ts
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const suiClient = new SuiClient({ url: getFullnodeUrl('testnet') })
+
+// Fetch ConfigState fields
+const config = await suiClient.getObject({
+  id: CONFIG_STATE_ID,
+  options: { showContent: true },
+})
+
+const fields = (config.data?.content as any)?.fields
+console.log({
+  skimFeeBps:       fields.skim_fee_bps,
+  skimThresholdMist: fields.skim_threshold_mist,
+  buybackBps:       fields.buyback_bps,
+  feeRecipients:    fields.fee_recipients,
+})
+```
+
+## Composing a governance PTB
+
+DAO operations are PTBs that pass the `DaoAdminCap` to `vault_governor` functions. The `DaoAdminCap` must be an owned object held by the signer.
+
+### Update `skim_fee_bps`
+
+```ts
+import { Transaction } from '@mysten/sui/transactions'
+
+function buildSetSkimFeeBpsTx(
+  daoAdminCapId: string,
+  configStateId: string,
+  newBps: number,         // e.g. 1000 = 10%
+): Transaction {
+  const tx = new Transaction()
+  tx.moveCall({
+    target: `${VAULT_GOVERNOR_PACKAGE}::vault_governor::set_skim_fee_bps`,
+    arguments: [
+      tx.object(daoAdminCapId),
+      tx.object(configStateId),
+      tx.pure.u64(newBps),
+    ],
+  })
+  return tx
+}
+
+// Execute
+const tx = buildSetSkimFeeBpsTx(daoAdminCapId, CONFIG_STATE_ID, 1000)
+await signAndExecute({ transaction: tx })
+```
+
+### Update fee recipients
+
+`fee_recipients` is a vector of `(address, weight_bps)` tuples. The weights must sum to 10 000.
+
+```ts
+function buildSetFeeRecipientsTx(
+  daoAdminCapId: string,
+  configStateId: string,
+  recipients: Array<{ address: string; weightBps: number }>,
+): Transaction {
+  const tx = new Transaction()
+
+  const addrs = recipients.map(r => r.address)
+  const weights = recipients.map(r => r.weightBps)
+
+  tx.moveCall({
+    target: `${VAULT_GOVERNOR_PACKAGE}::vault_governor::set_fee_recipients`,
+    arguments: [
+      tx.object(daoAdminCapId),
+      tx.object(configStateId),
+      tx.pure(addrs,    'vector<address>'),
+      tx.pure(weights,  'vector<u64>'),
+    ],
+  })
+  return tx
+}
+```
+
+### Pause / unpause the vault
+
+```ts
+function buildPauseVaultTx(daoAdminCapId: string, vaultId: string): Transaction {
+  const tx = new Transaction()
+  tx.moveCall({
+    target: `${VAULT_GOVERNOR_PACKAGE}::vault_governor::pause`,
+    arguments: [tx.object(daoAdminCapId), tx.object(vaultId)],
+  })
+  return tx
+}
+```
+
+## Dry-run before executing
+
+Always dry-run DAO transactions before live execution:
+
+```ts
+const dryRun = await suiClient.dryRunTransactionBlock({
+  transactionBlock: await tx.build({ client: suiClient }),
+})
+
+if (dryRun.effects.status.status !== 'success') {
+  console.error('Dry-run failed:', dryRun.effects.status.error)
+} else {
+  console.log('Gas estimate:', dryRun.effects.gasUsed)
+}
+```
+
+## Event monitoring
+
+Subscribe to governance events to observe when parameters change:
+
+```ts
+const unsubscribe = await suiClient.subscribeEvent({
+  filter: { Package: VAULT_GOVERNOR_PACKAGE },
+  onMessage: (event) => {
+    console.log('Governance event:', event.type, event.parsedJson)
+  },
+})
+```
+
+Key event types emitted by `vault_governor`:
+
+| Event | Emitted when |
+| --- | --- |
+| `SkimFeeBpsUpdated` | `skim_fee_bps` changed |
+| `FeeRecipientsUpdated` | `fee_recipients` changed |
+| `VaultPaused` | Vault paused |
+| `VaultResumed` | Vault unpaused |
+| `StrategyAllocationUpdated` | Strategy allocation cap changed |
+
+## Trust assumptions
+
+- The `DaoAdminCap` holder has full governance authority. Guard the signer with a multisig policy or hardware key.
+- `ConfigState` is a shared object; any party can read it on-chain.
+- There is no timelock on governance operations at testnet. A timelock module is planned for mainnet — monitor `docs/DEFERRED_WORK.md`.
+
+<!-- white-label: operator guide (multisig setup, custom governance modules, off-chain voting integration) — planned -->