Approved Libraries

The allowlist, not the denylist

Valdium contracts can only import from a fixed, governance-curated list of packages. Anything not on the list is rejected at compile time before the contract can be deployed. The check happens in the consensus rules, not in tooling — a node that lets an unapproved import through will fork itself off the chain.

This sounds restrictive because it is. The reason: a smart contract platform's attack surface is the union of every line of code that ever ships on it. If the platform lets you import arbitrary npm packages, the platform's attack surface is npm — half a million packages of varying quality, half of which have transitive dependencies on the other half. Valdium picks small, audited, deterministic libraries and keeps the surface tractable.

What gets a library on the list

An approved library has to pass four gates:

Deterministic. Same input bytes, same output bytes, every time, on every machine, in every runtime. No Date.now(), no Math.random(), no filesystem, no network. The runtime would block these anyway — but the analyzer catches them at compile time too.
SES-compatible. The library has to run under the Hardened JavaScript lockdown without trying to mutate built-in prototypes or escape the compartment. Most modern functional libraries pass; older OO libraries that monkey-patch Array.prototype do not.
Audited. A working public security audit from a recognised firm (or a community audit accepted by a governance vote) is the minimum bar. The audit report is linked from the library's entry below.
Useful. "Could be implemented in 30 lines" libraries don't get added; the contract author can write 30 lines. The list aims at substantial dependencies whose absence would force every contract author to re-implement a hard primitive badly.

Current approved set

Package	Version	Purpose
`@valdium/std`	1.x	Built-in types and helpers: `Address`, `U256`, `BigInt256`, balance math, safe coercions
`@valdium/access`	1.x	Role-based access control: `OwnerOnly`, `Roles`, `Pausable`
`@valdium/token`	1.x	Reference token implementations: fungible, non-fungible, semi-fungible
`@valdium/math`	1.x	Fixed-point math, safe multiply/divide, bit operations
`@valdium/merkle`	1.x	Merkle proof verification with BLAKE3 leaves
`@valdium/multisig`	1.x	K-of-N multisig primitives
`ses`	1.x	The Hardened JavaScript runtime itself

That's the entire list at testnet launch. It will grow — slowly, and only through the governance process described below.

How a library lands on the list

The path is:

Open a governance proposal with the package name, the version range to allowlist, a link to the audit, and a written rationale.
Discussion runs for at least seven days on the forum. Audit findings get poked at; the community asks "what does this enable that's not already possible?"
If the discussion converges, the proposal moves to an on-chain vote. Validators stake-weighted-vote with a 14-day window.
If the vote passes, the package and version are baked into the next protocol release. From the release block onward, contracts can import it.

Removing a library follows the same flow in reverse. Removals are rare but possible — a CVE in an allowlisted library that can't be patched without breaking compatibility is the canonical example.

Versions are pinned

The allowlist includes a specific version range, not the floating latest tag. @valdium/std@1.x means any 1.* release; @valdium/std@1.4.2 means exactly that. Patch upgrades that fix bugs without changing surface go through a streamlined vote; minor upgrades that add new exports go through the full proposal flow.

Contract authors should pin to exact versions in their package.json for reproducible verification:

{
  "dependencies": {
    "@valdium/std": "1.4.2",
    "@valdium/token": "1.2.0"
  }
}

What's deliberately not on the list

A few categories that would be on most chains' lists and are not here, with reasons:

Anything from npm that calls out to a JS standard library beyond what SES exposes. Most popular Node packages assume Buffer, fs, crypto — none of which exist inside a contract VM.

RegExp-heavy libraries. Some regex patterns have non-deterministic worst-case runtime in v8; we can't ship anything whose gas cost depends on engine internals.

Promise-based async libraries. Contract execution is synchronous by design — every state transition resolves in one block. Promise libraries don't make sense inside the VM.

Build · Writing Contracts → Build · Hardened JavaScript →