Technical Architecture

How Logbook works under the hood.

#System Overview

Logbook consists of five components:

1. 1Frontend: Next.js web application hosted on Cloudflare Pages
2. 2Smart Contract: Move module on the Sui blockchain (currently Testnet)
3. 3Seal key servers: independent servers that release decryption keys according to the contract's rules
4. 4Walrus: decentralized storage for documents about a campaign (AI report, results certificate)
5. 5Edge API routes: a thin server layer for gas sponsoring, Google sign-in (zkLogin) and AI features

There is no application database. Campaigns and responses live on-chain, documents live on Walrus with their hashes on-chain, and the only server-side storage is a cache of those documents.

#Frontend

#Technology Stack

• Framework: Next.js 16 with React 19
• Styling: Tailwind CSS 4
• State Management: Zustand for forms, React state and hooks for data
• Blockchain SDK: @mysten/sui 2.x, @mysten/dapp-kit-react for wallets, @mysten/seal for encryption, @mysten/enoki for zkLogin

#Key Features

• Client-side rendering: pages read the blockchain directly from the browser
• Encryption and decryption happen only in the browser (WebCrypto + Seal)
• Data refresh via polling with a user-selectable interval
• Responsive design with a mobile AI assistant

#Reading the Blockchain

Sui's JSON-RPC API has been retired, so the app uses two transports:

• gRPC to a full node for current state: objects, balances, epochs, transaction execution
• GraphQL to the indexer for history: events and past transactions

#Smart Contract

#Location

Deployed on Sui Testnet (mainnet is planned). See the Smart Contract page for the package ID.

#Objects

• Campaign: title, questions, privacy settings, address list, encrypted content key
• Response: one child object per respondent, holding plaintext or encrypted answers
• CampaignRegistry: global index of all campaigns

#Functions

• create_campaign, update_campaign, delete_campaign
• submit_response: record a participant's answers
• add_to_allowlist, remove_from_allowlist: manage address-list campaigns
• seal_approve: the access policy that Seal key servers evaluate

Campaigns close automatically at their end time; there is no separate finalize step.

#Encryption Layer (Seal)

Private campaigns use Seal, threshold encryption for Sui:

1. 1The browser encrypts data for an identity that encodes the campaign and, where needed, the respondent
2. 2To decrypt, the browser signs a short-lived session message (wallet signature, or silently with the zkLogin key)
3. 3Each key server simulates the contract's seal_approve function for the requesting address
4. 4If the policy passes, the server returns its key share; 2 of 3 shares are needed on Testnet

No single server, including Logbook's own, can read private data. See Data Storage for which key protects what.

#Edge API Routes

Small stateless functions running on Cloudflare's edge:

• /api/sponsor: the treasury pays gas for Logbook transactions of Google users and of SDK integrators. Only Logbook contract functions on the configured package are sponsored, with daily quotas per address and per API key.
• /api/zklogin/*: exchanges the Google code for a token, derives the Sui address and requests the zero-knowledge proof through Mysten's Enoki service
• /api/generate-campaign and /api/analyze: AI campaign assistant and results analysis (DeepSeek). Wallet addresses are not sent to the AI.
• /api/v1/*: public read-only REST API (see API & SDK)
• /mcp with /oauth/* and /.well-known/oauth-*: the remote MCP server for AI agents and its OAuth 2.1 authorization server; sessions and tokens live in Cloudflare KV, the session's signing key encrypted with a server secret
• /api/oauth/*: the consent page's back end (prepares the zkLogin nonce, finishes the Google sign-in, issues the authorization code)
• /api/documents: uploads the files a campaign is about (signed by the uploader, daily quota) and serves cache copies by content hash
• /api/reports: uploads campaign documents (AI report, results certificate) to Walrus for the creator and keeps a cache copy. Uploads require a signature of the campaign's on-chain creator; documents of private campaigns arrive already encrypted. The pointer and hash are written on-chain by the creator, not by the server

#Clients and Where Keys Live

The web app is one client of the protocol; the same libraries (interface/lib) are bundled into the TypeScript SDK and into the MCP tools, so the protocol logic exists once. What differs between clients is who holds the key that signs:

#Data Flow

#Creating a Campaign

1. 1User fills the form in the frontend
2. 2For private campaigns the browser generates a content key, encrypts the content, and wraps the key (password and/or Seal)
3. 3Frontend builds the create_campaign transaction
4. 4User signs with a wallet, or with zkLogin (gas sponsored by the treasury)
5. 5Campaign object is created on-chain

#Submitting a Response

1. 1User selects answers
2. 2If answers are not public, the browser encrypts them (content key or Seal)
3. 3Frontend builds the submit_response transaction and the user signs it
4. 4A Response object is attached to the campaign
5. 5Vote counts are updated by the contract only when answers are public

#Reading Results

1. 1Frontend loads the Campaign object and its responses over gRPC
2. 2Public answers are tallied straight from the chain
3. 3Encrypted answers are decrypted in the browser for users the policy allows, then tallied client-side
4. 4Updates arrive via polling

#Security

#On-Chain

• Move language prevents common vulnerabilities
• One response per address enforced by contract
• Only the creator can edit or delete a campaign, and only before the first response
• Address lists and answer visibility are enforced by the contract through Seal, not by the website

#Frontend

• Wallet users: private keys never leave the wallet
• Google users: a temporary (ephemeral) key pair and the Google token are kept in the browser's localStorage and cleared on logout; the key is valid for up to 30 epochs (about 30 days)
• Campaign content keys and Seal session keys live in sessionStorage (session keys expire after 15 minutes)
• Campaign passwords travel in the link fragment (after #), which browsers never send to servers