Skip to main content

HCS-12 Validation & Schemas

The Standards SDK exposes runtime validation for HashLinks components and messages, plus a WASM validator to enforce the module interface contract.

Zod Schemas & Helpers​

import {
  validateActionRegistration,
  validateBlockRegistration,
  validateAssemblyMessage,
  validateAssemblyRegistration,
  validateHashLinksRegistration,
  safeValidate,
  validateWithSchema,
} from '@hashgraphonline/standards-sdk/hcs-12';

// Validate a block definition before registering
const blockResult = validateBlockRegistration(blockDefinition);
if (!blockResult.valid) {
  console.error(blockResult.errors);
}

// Safer variant that never throws
const ok = safeValidate(() => validateActionRegistration(actionReg));
  • validateActionRegistration – ensures action registration (WASM mapping + metadata) is well-formed
  • validateBlockRegistration – validates block definition (attributes, actions, template link)
  • validateAssemblyMessage – validates assembly ops/messages
  • validateAssemblyRegistration – validates assembly composition payloads
  • validateHashLinksRegistration – high-level registry entry validation
  • safeValidate – wraps a validation call and returns a consistent result shape
  • validateWithSchema – pass a custom Zod schema to validate arbitrary data

WASM Module Contract​

HashLinks requires WASM modules to expose a minimal interface so SDKs can interact with them consistently:

  • INFO() → string (JSON) describing module metadata: name, version, declared actions and types
  • POST(...) → state-changing entrypoint for operations
  • GET(...) → read-only entrypoint for queries
import { WasmValidator } from '@hashgraphonline/standards-sdk/hcs-12';

const validator = new WasmValidator();
const result = await validator.validate(wasmBuffer);

if (!result.valid) {
  console.error(result.errors);
}

console.log(result.exports);          // e.g., ['INFO', 'POST', 'GET']
console.log(result.exportSignatures);  // parsed function signatures if available

The validator inspects exports/imports, basic signatures, and can report missing functions (INFO, POST, GET). It does not execute untrusted code: it parses the module structure to verify the contract.

  1. Build your WASM module and run WasmValidator.validate() locally.
  2. Validate registrations (validate*) before broadcasting to HCS.
  3. In CI: fail fast on invalid blocks/actions/assemblies.
  4. At runtime: use safeValidate for graceful error handling.

Common Errors​

  • Missing INFO/POST/GET export → add required functions to the module.
  • Invalid attribute types in a block → ensure types align with UI/renderer expectations.
  • Assembly references unresolved → register actions/blocks first, then bind in assemblies.