Developer Best Practices

This library targets developers building SDKs, CLIs, bots, or dashboards on top of Qubic. Below are recommended patterns so you can integrate quickly and safely.

Prefer high-level wrappers

• Use QubicNodeClient unless you explicitly need raw HTTP clients.
• Public RPCs don’t expose gRPC yet; if you self-host or when it opens up, generate stubs from live_service.proto instead of rolling custom codecs.
• Wrap automation runtime profiles when building bots to avoid duplicating scheduling logic.

Validate inputs early

• Leverage the exported Zod schemas (e.g., ProposalDataSchema, TransactionSchema) to validate user input before hitting the network.
• Use TSDoc to document parameter expectations; pull those into the docs workspace for clarity.

Isolate secrets

• Store seeds via encryptSecret/decryptSecret and zeroize buffers after use.
• Keep QUBIC_SEED outside your codebase; inject via env vars or secret stores.

Instrument everything

• Use instrumentRequest + TelemetryMetricsRegistry so you capture latency/error metrics for every RPC.
• Combine with the Prometheus server example to expose /metrics for dashboards.

Test deterministically

• Mock services with MockLiveServiceClient in unit tests.
• Replay snapshot fixtures in CI to simulate busy ticks.
• Gate smoke tests behind QUBIC_SMOKE_TESTS=true to avoid flaky builds.

Extend responsibly

• When building @qubiq/sdk, @qubiq/cli, or other downstream packages, depend on @qubiq/core types so you inherit schema updates automatically.
• For custom modules, export factory functions instead of mutating singletons; this keeps state predictable when users embed multiple instances.

Document as you go

• Use the apps/docs app (Fumadocs) to write MDX guides alongside code.
• Import .source metadata to render type references and search indexes (apps/docs/lib/source.ts).
• Keep release notes (docs/release-notes.md) and compliance files (LICENSE/NOTICE) updated so adopters know what’s included.