Allocyn API and SDK

A read-only REST API (/v1), a typed TypeScript SDK (@allocyn/sdk) and developer docs for the Allocyn contract on GenLayer Studionet.

Package	What it is
packages/sdk	@allocyn/sdk: reads, plus writes signed by the caller's own wallet. Never handles keys.
packages/api	Zero-dependency Node HTTP server. Reads the contract; no database, no wallet. Serves /openapi.json and the docs under /docs/.
docs	Markdown sources and a static-site builder (15 sections, search, copy buttons, diagrams, live "Try it").
scripts	sync-core.mjs (copies the shared, parity-tested core from the web app), preview-server.mjs (API + docs on a simulated contract).

Contract: Smart Agreement at 0x5729a3b514654Ec5966A1DCa8e5088ef7A70bBDA on Studionet (chain 61999), source https://github.com/Said1235/Smart-Agreement.git, pinned SHA-256 58fd38776f25d54f22a9d1560f78b348215ac13d3a863d4f7be00609b9355f57.

Run

Node 22.6 or newer.

npm install                 # links the workspaces; installs genlayer-js
cp .env.example .env
npm run docs:build
npm start                   # http://localhost:8787  (docs at /docs/, spec at /openapi.json)

Deploy

Vercel (root directory allocyn, config in vercel.json) or any Node host: see docs/content/15-deploy.md. The Vercel path has been tested locally with a stand-in for genlayer-js only; the first real deploy is the test. api/index.mjs is committed on purpose (Vercel needs it before the build); regenerate it with npm run vercel:build.

Test

npm test                    # sdk + api + docs
npm run sync:check          # the SDK's copy of the shared core equals the web app's
node scripts/preview-server.mjs   # explore the API and docs against a simulated contract

What the tests prove, and what they do not

They run the real SDK, the real HTTP server and the real docs build against an in-memory test double of the contract (SimContract), and check data shapes and hashes against fixtures generated by running the contract's own Python code. They do not prove anything about the live Studionet RPC, a real wallet, real validators or the deployed bytecode. See docs/content/12-networks.md for the manual checks.

Rules

• No component signs for someone else; none asks for or stores a private key or seed phrase (the API refuses to start if one is in its environment).
• No simulated writes: the API has no POST. Relaying user-signed transactions is not implemented.
• Everything the API returns is read from the contract at request time.

When the contract changes

See "Updating the contract" in docs/content/12-networks.md. In short: the SDK's pinned limits and source hash live in the web app's lib/contract/spec.ts; update them there, run npm run sync, regenerate the parity fixtures, run the tests. A limits change is detected at runtime (matchesPinned: false) and writes are refused until the SDK is updated.