Developer quick start. Local setup, dev commands, package guidelines, and how to add new protocol events and API routes.
Everything you need to go from zero to a running local dev cluster.
# Clone the repository
git clone https://github.com/decenterlize/decenterlizemarket.git
cd decenterlizemarket
# Install dependencies (pnpm required)
pnpm install
# Start infrastructure (PostgreSQL, Redis)
docker compose up -d
# Copy environment template
cp .env.example .env
# Run database migrations
pnpm db:migrate
# Start the dev server
pnpm dev| Command | Description |
|---|---|
pnpm dev | Start single node in development mode |
pnpm dev:cluster | Start a multi-node local cluster (3 nodes) |
pnpm dev:btc | Start with Bitcoin testnet/regtest configuration |
pnpm dev:evm | Start with EVM local chain (Hardhat/Anvil) |
pnpm dev:sol | Start with Solana localnet |
pnpm test | Run the full test suite (vitest) |
pnpm build | Production build |
pnpm bench:dashboard | Start the benchmark dashboard on port 4400 |
pnpm db:migrate | Run database migrations |
pnpm db:seed | Seed development data |
Each package has a specific role and a strict dependency direction. Packages higher in the stack can depend on packages below them, but never the reverse.
services/protocol — The foundation. Zero external dependencies. Pure Zod schemas and deterministic validation logic. Every function must be deterministic: same input, same output, every time. No IO, no randomness, no side effects. If you're adding something here, it must be a protocol rule that every node computes identically.
services/db — Database layer. Drizzle ORM schemas for PostgreSQL. Can depend on protocol for type definitions. Each node has its own isolated database. No shared DB across nodes.
services/agent — Node runtime. Mesh networking, gossip protocol, peer management, heartbeat. Can depend on protocol and db. This is the process lifecycle layer.
services/server — Business logic. tRPC routers, API handlers, chain-specific settlement. Can depend on all other packages. This is where marketplace logic lives.
services/cache — Redis caching and rate limiting. Used by server and agent.
When you need to add a new event type to the protocol:
services/protocol/src/events/. Use Zod for the payload schema. The schema must be deterministic (no optional fields that affect validation).export const MY_NEW_EVENT = z.object({
type: z.literal("MY_NEW_EVENT"),
payload: z.object({
// your fields here
}),
nodeId: z.string(),
timestamp: z.number(),
signature: z.string(),
});services/protocol/src/events/index.ts.services/server/ that processes the event when received via gossip.services/server/src/.export const myRouter = router({
myEndpoint: protectedProcedure
.input(z.object({ /* input schema */ }))
.mutation(async ({ input, ctx }) => {
// implementation
}),
});protectedProcedure which verifies the Ed25519 signature in the request headers.The project uses vitest for all testing:
- dev-cluster/ — Session attestation, UI integrity
- governance/ — Misbehavior strikes
- mpc/ — Key safety
- node-auth/ — Authentication edge cases
- verification/ — TX-plan quorum
__tests__/ cover API routes and cross-package flows.services/server/__tests__/ cover specific attack vectors:Run the full suite with pnpm test. Run a specific test file with pnpm vitest run path/to/test.ts.
Key environment variables (see .env.example for the full list):
| Variable | Description |
|---|---|
DATABASE_URL | PostgreSQL connection string |
REDIS_URL | Redis connection string |
NODE_ID | Unique node identifier |
NODE_PRIVATE_KEY | Ed25519 private key (hex) |
BTC_RPC_URL | Bitcoin RPC endpoint |
ETH_RPC_URL | Ethereum RPC endpoint |
SOL_RPC_URL | Solana RPC endpoint |
FULL_NODE_CHAT | Set to 1 to store all chat threads (not just assigned shards) |
FULL_NODE_MEDIA | Set to 1 to cache all media (not just assigned shards) |