SDK API reference (generated)

source: scripts/gen-api-refs.mjs

This page is generated by scripts/gen-api-refs.mjs from the SDK sources on each build, so it stays in sync with the code. It is the exported public surface; the narrative reference with examples lives in identity, entitlements, and the JavaScript and Python pages.

Sources: citrate-sdk-js@328bdea, citrate-sdk-python@850b3c1.

JavaScript, @citratelabs/sdk

identity

Symbol	Kind	Summary
`UserId`	type	A 0x-prefixed 32-byte hex user id (the raw stable identifier the factory salts with)
`uuidToUserId`	function	Derive the raw 32-byte AA userId from an OIDC subject UUID
`addressToUserId`	function	Left-pad a 20-byte EOA address to a 32-byte AA userId (SIWE-keyed principals)
`predictWalletAddress`	function	Predict the counterfactual smart-wallet address for a userId. Pure + offline
`verifyWalletAddressOnChain`	function	Verify the locally-predicted address against the on-chain factory (ground truth)
`generateVerifier`	function	A 43-char base64url verifier (256 bits of entropy)
`challengeFromVerifier`	function	S256 challenge for a verifier
`verifyIdToken`	function	Verify an OIDC ID token and return its (now-trusted) claims. Throws IdTokenError on any failure
`DeployPermit`	interface	A factory deploy permit signed by the authority's identity-signer

entitlements

Symbol	Kind	Summary
`TIERS`	const	The five tiers the authority mints (mirrors citrate-identity `TIERS`)
`CapabilitySet`	interface	What a principal may do. Explicit set membership — never derived from an ordering
`DEFAULT_CAPABILITIES`	const	The canonical default tier→capability map
`normalizeTier`	function	Normalize an entitlement tier value at the trust boundary. Unknown/garbage collapses to
`EntitlementClaimLike`	interface	The minimal shape of the entitlement claim this module reads
`capabilities`	function	Capabilities for a raw tier value (normalized first)
`can`	function	Whether a claim grants a capability. Applies the same fail-safe + role-bypass semantics as

Python, citrate-labs-sdk

citrate_sdk.identity

Symbol	Kind	Summary
`WalletPredictionError`	class
`uuid_to_user_id`	def	keccak256(utf8(lowercase(uuid))) — matches the authority's wallet-claims.ts
`address_to_user_id`	def	Left-pad a 20-byte EOA to a 32-byte AA userId (SIWE-keyed principals)
`generate_verifier`	def	A 43-char base64url verifier (256 bits of entropy)
`challenge_from_verifier`	def
`Pkce`	class
`create_pkce`	def
`IdTokenError`	class
`IdentityError`	class
`TokenSet`	class
`UserInfo`	class
`IdentityClient`	class

citrate_sdk.entitlements

Symbol	Kind	Summary
`CapabilitySet`	class
`normalize_tier`	def	Fail-safe: unknown/garbage/non-str collapses to `public`. Never escalates
`capabilities`	def

citrate_sdk.gateway

Symbol	Kind	Summary
`GatewayError`	class
`GatewayClient`	class

Command line

citrate (Python)

usage: citrate [-h] {contract,wallet,entitlement,gateway} ...

Citrate SDK command line

positional arguments:
  {contract,wallet,entitlement,gateway}
    contract            Print the federation contract table
    wallet              Embedded smart-account wallet helpers
    entitlement         Entitlement capabilities
    gateway             Inference gateway

optional arguments:
  -h, --help            show this help message and exit