@meddleware/dev 0.0.1

package/docs/sui/environment.md

@@ -0,0 +1,101 @@
+# Environment setup
+
+## Active network
+
+The Sui CLI stores network configuration in `~/.sui/sui_config/client.yaml`. To switch networks:
+
+```bash
+sui client switch --env testnet
+sui client envs   # list all configured environments
+```
+
+## Active address
+
+```bash
+sui client active-address   # show the current active address
+sui client addresses         # list all known addresses
+sui client switch --address <ADDRESS>
+```
+
+## Gas and the testnet faucet
+
+Fund a testnet address from the faucet:
+
+```bash
+# Via CLI
+sui client faucet --address <ADDRESS>
+
+# Or navigate to https://faucet.sui.io/ and paste the address
+```
+
+Check balance:
+
+```bash
+sui client balance
+```
+
+## Localnet
+
+For contract development and integration testing, a local network is the fastest iteration loop:
+
+```bash
+# Start a local network with a built-in faucet
+sui start --with-faucet
+# → Fullnode: http://127.0.0.1:9000
+# → Faucet: http://127.0.0.1:9123
+
+# Add the localnet environment (first time only)
+sui client new-env --alias localnet --rpc http://127.0.0.1:9000
+sui client switch --env localnet
+
+# Fund the active address from the local faucet
+sui client faucet
+```
+
+### Publishing contracts to localnet
+
+```bash
+cd blockchain/sui/contracts/core
+sui move build --build-env localnet
+sui client publish --gas-budget 200000000
+```
+
+Keep the published package address — you'll need it to call entry functions in tests.
+
+## TypeScript SDK — network configuration
+
+The `@mysten/sui` SDK reads the network from your build config or at runtime:
+
+```ts
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const network = (import.meta.env.VITE_NETWORK ?? 'testnet') as 'localnet' | 'testnet' | 'mainnet'
+
+const client = new SuiClient({
+  url: network === 'localnet'
+    ? 'http://127.0.0.1:9000'
+    : getFullnodeUrl(network),
+})
+```
+
+::: warning Public fullnodes
+Public testnet fullnodes use **gRPC/GraphQL** (JSON-RPC was retired in September 2026). The `SuiClient` from `@mysten/sui ^2.x` uses GraphQL transport by default — ensure you are on a current SDK version.
+:::
+
+## Useful CLI commands
+
+```bash
+# Object details
+sui client object <OBJECT_ID>
+
+# Call a Move function
+sui client call \
+  --package <PACKAGE_ID> \
+  --module <MODULE> \
+  --function <FUNCTION> \
+  --args <ARG1> <ARG2> \
+  --gas-budget 10000000
+
+# Read Move events
+sui client events --package <PACKAGE_ID>
+```

package/docs/sui/index.md

@@ -0,0 +1,46 @@
+# Sui development
+
+Guides for building on the Meddleware Sui contracts and SDKs.
+
+## In this section
+
+| Topic | Description |
+| --- | --- |
+| [Environment setup](./environment) | Localnet, testnet, active address, gas |
+| [PTB patterns](./ptb-patterns) | TypeScript transaction building patterns |
+| [Walrus Storage](./walrus-storage/) | SDK setup and integration guide |
+| [Sealed Storage](./sealed-storage/) | Encrypt/store/decrypt with on-chain policies |
+| [Access Gate](./access-gate/) | NFT gate passes and gateway deployment |
+| [DAO](./dao/) | Governance interaction patterns |
+
+## Contract layout
+
+The on-chain packages are published under:
+
+```
+blockchain/sui/contracts/
+├── core/           — vault_core (accounting, share minting/burning)
+├── adapters/       — vault_adapters (strategy integration)
+├── governor/       — vault_governor (DaoAdminCap-gated ops)
+├── fee_distributor/— vault_fee_distributor
+├── config/         — vault_config (DAO-governed parameters)
+├── dao/            — vault_dao
+└── access-gate/    — access_gate (NFT pass minting/consumption)
+```
+
+## SDK packages
+
+| Package | npm | Purpose |
+| --- | --- | --- |
+| `@meddleware/walrus-client` | ✓ | Walrus blob upload, read, extend, enumerate |
+| `@meddleware/seal-client` | ✓ | Encrypt/store/decrypt with Seal + Walrus |
+| `@meddleware/nft-gate-client` | ✓ | Access Gate challenge/proof construction |
+| `@meddleware/ui` | ✓ | Vue 3 components (includes `suiExplorerUrl`, `CopyableAddress`) |
+
+## Testnet vs mainnet
+
+All contract addresses in this documentation are **testnet**. Check the [API reference](https://docs.meddleware.co.uk/blockchain/sui/) for the canonical address tables.
+
+::: tip Using the Sui MCP
+If you have the `sui-docs` MCP configured (`https://sui.mcp.kapa.ai`), consult it for current Sui framework types, SDK patterns, and deprecation notices before writing Move or TypeScript.
+:::

package/docs/sui/ptb-patterns.md

@@ -0,0 +1,136 @@
+# PTB patterns
+
+Programmable Transaction Blocks (PTBs) let you compose multiple Move calls into a single atomic transaction. The Meddleware apps use PTBs for every multi-step on-chain operation.
+
+## Basic structure
+
+```ts
+import { Transaction } from '@mysten/sui/transactions'
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const client = new SuiClient({ url: getFullnodeUrl('testnet') })
+const tx = new Transaction()
+
+// Add Move calls, object inputs, and coin splits here
+// ...
+
+// Sign and execute (with a wallet or a keypair)
+const result = await client.signAndExecuteTransaction({
+  transaction: tx,
+  signer: keypair,
+  options: { showEffects: true, showObjectChanges: true },
+})
+```
+
+## Common patterns
+
+### Calling a Move function
+
+```ts
+tx.moveCall({
+  target: `${PACKAGE_ID}::${MODULE}::${FUNCTION}`,
+  arguments: [
+    tx.object(objectId),          // pass an existing on-chain object
+    tx.pure.u64(1000n),           // pass a scalar
+    tx.pure.address(recipientAddr),
+  ],
+})
+```
+
+### Splitting coins for a payment
+
+```ts
+const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(feeMist)])
+tx.moveCall({
+  target: `${PACKAGE}::module::pay`,
+  arguments: [coin],
+})
+```
+
+### Multi-step composition (example: deposit → allocate)
+
+```ts
+// 1. Split exact SUI amount
+const [depositCoin] = tx.splitCoins(tx.gas, [tx.pure.u64(amountMist)])
+
+// 2. Deposit into vault (returns mwSUI shares)
+const [shares] = tx.moveCall({
+  target: `${VAULT_PACKAGE}::vault_core::deposit`,
+  arguments: [depositCoin, tx.object(VAULT_ID), tx.object(CONFIG_ID)],
+})
+
+// 3. Transfer shares to caller (or keep for further use)
+tx.transferObjects([shares], tx.pure.address(callerAddress))
+```
+
+### Reading a result across calls
+
+Results from `moveCall` are returned as `TransactionResult` values. Pass them to subsequent calls:
+
+```ts
+const [mintedNft] = tx.moveCall({ target: `${PKG}::nft::mint`, arguments: [...] })
+tx.moveCall({
+  target: `${PKG}::vault::deposit_nft`,
+  arguments: [mintedNft],  // result used as argument
+})
+```
+
+## Dry-run before sending
+
+```ts
+const dryRunResult = await client.dryRunTransaction({
+  transaction: await tx.build({ client }),
+})
+if (dryRunResult.effects.status.status !== 'success') {
+  console.error('Dry-run failed:', dryRunResult.effects.status.error)
+}
+```
+
+## Setting gas budget
+
+```ts
+tx.setGasBudget(20_000_000n)  // 0.02 SUI; adjust to operation complexity
+```
+
+For complex multi-step PTBs (rebalance, multi-strategy allocation), use 100–200 MIST × number of strategy steps as a baseline and dry-run to confirm.
+
+## Wallet integration
+
+In a Vue app using `@mysten/dapp-kit`:
+
+```ts
+import { useCurrentAccount, useSignAndExecuteTransaction } from '@mysten/dapp-kit'
+
+const account = useCurrentAccount()
+const { mutate: signAndExecute } = useSignAndExecuteTransaction()
+
+function executeMyPTB() {
+  const tx = new Transaction()
+  // ... build tx ...
+  signAndExecute(
+    { transaction: tx },
+    {
+      onSuccess: (result) => { console.log('digest:', result.digest) },
+      onError:   (err)    => { console.error(err) },
+    },
+  )
+}
+```
+
+## Error handling
+
+Move aborts are surfaced as numeric codes in `effects.status.error`. Map them to human-readable messages for your users:
+
+```ts
+const VAULT_ERRORS: Record<number, string> = {
+  1: 'Insufficient balance',
+  5: 'Below minimum deposit',
+  85: 'Stale strategy NAV — refresh all active strategy NAVs in the same PTB',
+}
+
+function describeAbort(error: string): string {
+  const match = error.match(/MoveAbort\(.*?,\s*(\d+)\)/)
+  const code = match ? parseInt(match[1]) : -1
+  return VAULT_ERRORS[code] ?? `Unknown error (code ${code})`
+}
+```

package/docs/sui/sealed-storage/index.md

@@ -0,0 +1,49 @@
+# Sealed Storage — SDK setup
+
+[User docs →](https://docs.meddleware.co.uk/blockchain/sui/sealed-storage/) | [API reference →](https://docs.meddleware.co.uk/blockchain/sui/sealed-storage/reference)
+
+Sealed Storage combines Walrus blob storage with Seal's decentralised key management and on-chain Move access-control policies. Only addresses that satisfy the policy can decrypt.
+
+## Install
+
+```bash
+npm install @meddleware/seal-client @meddleware/walrus-client @mysten/seal @mysten/sui
+```
+
+## Initialise the client
+
+```ts
+import { SealClient } from '@meddleware/seal-client'
+import { WalrusRelayClient } from '@meddleware/walrus-client'
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const suiClient  = new SuiClient({ url: getFullnodeUrl('testnet') })
+const walrus     = new WalrusRelayClient({ relayUrl: RELAY_URL, suiClient, network: 'testnet' })
+const sealClient = new SealClient({ suiClient, network: 'testnet' })
+```
+
+## Three-step flow
+
+Sealed Storage works in three steps:
+
+1. **Encrypt** — the client encrypts the data locally using a Seal key derived from the policy ID.
+2. **Store** — the encrypted ciphertext is uploaded to Walrus; a manifest records the `blobId` and policy address.
+3. **Decrypt** — the reader presents the manifest; Seal verifies their wallet satisfies the policy and returns the decryption key.
+
+See [Integration guide](./integration) for the full code walkthrough and [Writing policies](./policies) for policy authoring.
+
+## Manifest shape
+
+```ts
+interface SealManifest {
+  version: 1
+  policyId: string      // Move object ID of the access policy
+  blobId: string        // Walrus blob ID of the ciphertext
+  encryptedKey: string  // base64 — Seal-encrypted data key
+  contentType: string
+}
+```
+
+The manifest itself is public — store it anywhere (Walrus, on-chain, your database). It contains no plaintext.
+
+<!-- white-label: operator guide for running a custom Seal key server committee — planned -->

package/docs/sui/sealed-storage/integration.md

@@ -0,0 +1,125 @@
+# Sealed Storage — Integration guide
+
+## Full encrypt → store → decrypt flow
+
+### Encrypt and store
+
+```ts
+import { SealClient } from '@meddleware/seal-client'
+import { WalrusRelayClient } from '@meddleware/walrus-client'
+
+async function encryptAndStore(
+  sealClient: SealClient,
+  walrus: WalrusRelayClient,
+  file: File,
+  policyId: string,  // on-chain Move policy object ID
+  epochs = 5,
+): Promise<SealManifest> {
+  // 1. Encrypt locally — key is derived from policyId
+  const { ciphertext, encryptedKey } = await sealClient.encrypt(file, { policyId })
+
+  // 2. Upload ciphertext to Walrus
+  const result = await walrus.store(
+    new File([ciphertext], file.name, { type: 'application/octet-stream' }),
+    { epochs },
+  )
+
+  // 3. Return the manifest (store this somewhere accessible)
+  return {
+    version: 1,
+    policyId,
+    blobId: result.blobId,
+    encryptedKey,
+    contentType: file.type,
+  }
+}
+```
+
+### Decrypt
+
+```ts
+async function decryptManifest(
+  sealClient: SealClient,
+  walrus: WalrusRelayClient,
+  manifest: SealManifest,
+  signer: { address: string; sign: (msg: Uint8Array) => Promise<Uint8Array> },
+): Promise<Blob> {
+  // 1. Request the decryption key from Seal
+  //    Seal verifies on-chain that signer.address satisfies the policy
+  const key = await sealClient.requestKey({
+    policyId: manifest.policyId,
+    encryptedKey: manifest.encryptedKey,
+    signer,
+  })
+
+  // 2. Download the ciphertext from Walrus
+  const ciphertext = await walrus.read(manifest.blobId)
+
+  // 3. Decrypt locally
+  const plaintext = await sealClient.decrypt(ciphertext, key)
+  return new Blob([plaintext], { type: manifest.contentType })
+}
+```
+
+## Using with dapp-kit
+
+Wire the wallet signer from `@mysten/dapp-kit`:
+
+```ts
+import { useCurrentAccount, useSignPersonalMessage } from '@mysten/dapp-kit'
+
+const account = useCurrentAccount()
+const { mutateAsync: signPersonalMessage } = useSignPersonalMessage()
+
+const signer = {
+  address: account.value!.address,
+  sign: async (msg: Uint8Array) => {
+    const { signature } = await signPersonalMessage({ message: msg })
+    return signature
+  },
+}
+```
+
+## Error handling
+
+```ts
+try {
+  const key = await sealClient.requestKey({ policyId, encryptedKey, signer })
+} catch (err) {
+  if (err instanceof SealPolicyError) {
+    // Wallet does not satisfy the policy
+    console.error('Access denied:', err.policyId, err.reason)
+  } else if (err instanceof SealKeyServerError) {
+    // Key server unavailable or quorum not reached
+    console.error('Key server error:', err.message)
+  }
+  throw err
+}
+```
+
+## Vue composable
+
+```ts
+// composables/useSealDecrypt.ts
+import { ref } from 'vue'
+
+export function useSealDecrypt(sealClient: SealClient, walrus: WalrusRelayClient) {
+  const decrypting = ref(false)
+  const result     = ref<Blob | null>(null)
+  const error      = ref<Error | null>(null)
+
+  async function decrypt(manifest: SealManifest, signer: SealSigner) {
+    decrypting.value = true
+    error.value      = null
+    try {
+      result.value = await decryptManifest(sealClient, walrus, manifest, signer)
+    } catch (e) {
+      error.value = e as Error
+    } finally {
+      decrypting.value = false
+    }
+  }
+
+  return { decrypting, result, error, decrypt }
+}
+```

package/docs/sui/sealed-storage/policies.md

@@ -0,0 +1,81 @@
+# Writing policies
+
+Access policies are Move objects that implement the Seal policy interface. The `seal_policies_sui` package provides built-in policy types; you can also author custom policies.
+
+## Built-in policy types
+
+| Policy | Condition for access |
+| --- | --- |
+| `AllowlistPolicy` | Address is on an explicit allowlist managed by the policy owner |
+| `NftGatePolicy` | Address holds a qualifying NFT from a specified gate |
+| `TimeLockPolicy` | Current epoch ≥ unlock epoch |
+| `ThresholdPolicy` | m-of-n signers from a configured set |
+
+## NFT gate policy (most common)
+
+Create a policy that requires an active Access Gate pass:
+
+```move
+// seal_policies_sui::nft_gate_policy
+public fun create(
+    gate_id: ID,           // access_gate::Gate object ID
+    ctx: &mut TxContext,
+): NftGatePolicy
+```
+
+In TypeScript, after publishing the policy, record its object ID in your manifest.
+
+```ts
+import { Transaction } from '@mysten/sui/transactions'
+
+const tx = new Transaction()
+const [policy] = tx.moveCall({
+  target: `${SEAL_POLICIES_PACKAGE}::nft_gate_policy::create`,
+  arguments: [tx.pure.id(GATE_OBJECT_ID)],
+})
+tx.transferObjects([policy], tx.pure.address(ownerAddress))
+await client.signAndExecuteTransaction({ transaction: tx, signer })
+```
+
+## Time-lock policy
+
+```ts
+const [policy] = tx.moveCall({
+  target: `${SEAL_POLICIES_PACKAGE}::time_lock_policy::create`,
+  arguments: [tx.pure.u64(unlockEpoch)],
+})
+```
+
+## Custom policy
+
+A policy must expose a public `approve` function that Seal calls during key request:
+
+```move
+module my_policy::my_policy {
+    use sui::tx_context::TxContext;
+
+    public struct MyPolicy has key, store {
+        id: UID,
+        // your policy state
+    }
+
+    /// Seal calls this to check whether the requester is permitted.
+    /// Abort if access is denied.
+    public fun approve(policy: &MyPolicy, requester: address, _ctx: &TxContext) {
+        assert!(is_allowed(policy, requester), EAccessDenied);
+    }
+}
+```
+
+The `approve` function is the only required interface. Any state can live in the policy object.
+
+## Policy lifecycle
+
+- Policies are shared or owned objects on-chain.
+- The creator controls mutation (e.g. adding to an allowlist) via the object's admin cap.
+- Revoking access for an allowlist policy: remove the address via the admin function.
+- Policies cannot be retroactively applied to already-encrypted blobs — encryption and the policy are bound at encrypt time.
+
+::: warning Pre-mainnet requirement
+The Seal key server committee for mainnet is not yet formed. Testnet policies work against the testnet Seal committee. See [DEFERRED_WORK.md](https://github.com/meddleware-org/vault) for the mainnet committee timeline.
+:::

package/docs/sui/walrus-storage/index.md

@@ -0,0 +1,67 @@
+# Walrus Storage — SDK setup
+
+[User docs →](https://docs.meddleware.co.uk/blockchain/sui/walrus-storage/) | [API reference →](https://docs.meddleware.co.uk/blockchain/sui/walrus-storage/reference)
+
+`@meddleware/walrus-client` wraps the Walrus blob store and the Meddleware relay layer: upload blobs, read them back, extend their storage lifetime, and enumerate blobs owned by an address.
+
+## Install
+
+```bash
+npm install @meddleware/walrus-client @mysten/walrus @mysten/sui
+```
+
+## Initialise the client
+
+```ts
+import { WalrusRelayClient } from '@meddleware/walrus-client'
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+
+const suiClient = new SuiClient({ url: getFullnodeUrl('testnet') })
+
+const walrus = new WalrusRelayClient({
+  relayUrl: import.meta.env.VITE_WALRUS_RELAY_URL ?? 'https://walrus-relay.meddleware.co.uk',
+  suiClient,
+  network: 'testnet',
+})
+```
+
+The relay URL points at a Meddleware-hosted Walrus relay. For a gated relay, the client constructs an NFT gate proof automatically when you supply a wallet signer (see [Integration guide](./integration)).
+
+## Core types
+
+```ts
+// Blob storage result
+interface BlobStoreResult {
+  blobId: string
+  expiryEpoch: number
+  cost: bigint         // in MIST
+  newlyCreated: boolean
+}
+
+// Blob metadata
+interface BlobInfo {
+  blobId: string
+  size: number
+  expiryEpoch: number
+  owner: string
+}
+```
+
+## Quick upload
+
+```ts
+const file = new File(['Hello, Walrus!'], 'hello.txt', { type: 'text/plain' })
+const result = await walrus.store(file, { epochs: 5 })
+console.log('Stored at blobId:', result.blobId)
+```
+
+## Quick read
+
+```ts
+const data = await walrus.read(blobId)
+const text = new TextDecoder().decode(data)
+```
+
+See [Integration guide](./integration) for detailed patterns, error handling, and wallet signing.
+
+<!-- white-label: operator customization guide (relay domain, tip config, NFT gate setup) — planned -->