Versioning and Compatibility

The Walrus Memory relayer is the public protocol/API layer for SDKs, MCP clients, and self-hosted deployments. Treat every route, signed header, response field, runtime config field, and documented environment variable on this page as a versioned contract.

How does the relayer use SemVer?

The relayer package version follows SemVer, and the public API contract is exposed separately as apiVersion.

Change	Required bump	Examples
Compatible public behavior	patch	bug fix, clearer error body, additive docs
Additive public surface	minor	new response field, new route, new optional env var, new feature flag
Breaking public surface	major	removing or renaming a header, route, env var, response field, auth canonical format, or changing field meaning

Public surfaces include:

• HTTP routes under /api/*, /health, /version, /config, /sponsor, and /api/mcp*
• signed auth headers and the canonical signature format
• JSON request/response field names and status-code semantics
• runtime config and environment variables used by self-hosted relayers
• MCP transport behavior and bearer credential expectations

Which SDK versions are compatible with the relayer?

Relayer API	Relayer package	TypeScript SDK	Python SDK	MCP package	Notes
1.x	0.1.x	>=0.0.4	>=0.1.0	>=0.0.1	Requires x-nonce; TypeScript and Python SDKs use x-seal-session for relayer-mode decrypt flows; MCP sends a bearer credential (a delegate key, or an OAuth access token that the relayer resolves to one) at SSE open; the legacy x-delegate-key header is deprecated

SDKs and MCP clients read /version before protected requests and fail with an explicit compatibility error when the relayer API major or minimum SDK version is unsupported.

How do you check compatibility at runtime?

Modern relayers expose compatibility metadata at GET /version and include the same block in GET /health.

To check compatibility manually, request GET /version from your relayer. Confirm that your SDK version is at or above the matching minSupportedSdk value and that the apiVersion major matches a row in the compatibility matrix.

Source: relayer/versioning-and-compatibility.md

{
  "relayerVersion": "0.1.0",
  "apiVersion": "1.0.0",
  "minSupportedSdk": {
    "typescript": "0.0.4",
    "python": "0.1.0",
    "mcp": "0.0.1"
  },
  "featureFlags": {
    "auth.accountBoundNonce": true,
    "auth.sealSessionHeader": true,
    "runtime.versionEndpoint": true
  },
  "deprecations": [
    {
      "surface": "header:x-delegate-key",
      "deprecatedSince": "1.0.0",
      "removalApiVersion": "2.0.0",
      "guidance": "Use x-seal-session for relayer-managed SEAL decrypt flows; manual-mode requests should send no decrypt credential."
    }
  ],
  "build": {
    "commit": "optional-git-sha",
    "buildTimestamp": "optional-build-time"
  }
}

/health keeps the legacy version field for older monitoring checks. New automation should prefer relayerVersion.

How does the deprecation process work?

Breaking changes must follow this process unless there is an active security incident:

1. Add a deprecation notice to /version.deprecations.
2. Document the replacement path and removal apiVersion.
3. Keep the old surface working for the rest of the current API major.
4. Add or update contract tests and docs in the same PR.
5. Remove the surface only in the next API major.

This process applies to headers, routes, environment variables, response fields, feature flags, and MCP transport behavior.

Environment variables

Environment variables documented in Environment Variables are public contract items for self-hosted deployments. Renaming, removing, or changing their meaning is a breaking relayer API change.

Additive env vars might ship in a minor release. Deprecating an env var requires a /version.deprecations entry, docs update, and a replacement path. SEAL_KEY_SERVERS is currently deprecated in favor of SEAL_SERVER_CONFIGS and remains supported through relayer API 1.x.

Contract checks

CI runs pnpm check:compatibility, which verifies that:

• relayer API and minimum supported SDK/MCP constants are valid SemVer contract values
• SDK/MCP compatibility baselines match the relayer's minimum supported versions
• SDK/MCP package versions are not older than the compatibility baseline they advertise
• this policy document contains the current API version and compatibility matrix values
• test_seal_approve_delegate_requires_matching_owner (ENoAccess) remains in the Move suite; CI also runs that test by name so deleting it fails the gate

If a public compatibility value changes, update the implementation, this document, and the relevant changelog/deprecation notes together.

Legacy version field in /health

The /health response has the following shape:

• status: string.
• version: string. This is the legacy field.
• relayerVersion, apiVersion, and minSupportedSdk: optional. Modern relayers include them. Older relayers might omit them.

Treat the compatibility fields as absent on older relayers, and fall back to version only for basic monitoring. /health and /version do not require authentication. A passing /health check confirms the relayer is reachable. It does not confirm that your signing key or account ID are valid.

Seal decrypt credentials

Signed headers authenticate the caller, but they do not decrypt data. The routes that return stored memories, /api/recall, /api/ask, and /api/restore, also need a Seal credential in relayer mode:

• Relayer-managed (relayer mode): The client sends x-seal-session, a base64-encoded Seal SessionKey. The official SDKs build, cache, and send this header.
• Legacy: x-delegate-key sends the delegate private key to the relayer. It is deprecated.
• Server fallback: A relayer configured with SERVER_SUI_PRIVATE_KEY decrypts with its own key, so the client sends neither header.

Manual-mode requests send only the signed headers and omit decrypt credentials. Writes through /api/remember do not need a Seal credential.