Constants & Types

This section provides an overview of the fundamental constants and type definitions used throughout the Blocklet SDK and the broader Blocklet Server ecosystem. Understanding these shared definitions is crucial for ensuring data consistency, enabling robust interactions, and developing applications that seamlessly integrate with the Blocklet platform. These definitions serve as the backbone for various SDK functionalities, including data structures for Blocklets, users, notifications, and server configurations.

Core Constants#

Constants define fixed values used across the Blocklet ecosystem, ensuring predictable behavior and clear communication. These often represent status codes, types, or prefixes.

Service Prefix#

The SERVICE_PREFIX defines a standard URL path prefix used for well-known services within the Blocklet Server. This ensures consistent routing and access to core functionalities.

Name	Type	Description
SERVICE_PREFIX	string	The base path for well-known Blocklet services, typically /.well-known/service.

Enumerated Maps#

The Blocklet Server utilizes several enumerated maps to represent predefined sets of integer values for various statuses, types, and match conditions. These maps provide clear, symbolic names for numerical codes, improving readability and maintainability.

StatusCodeMap

Defines standard HTTP-like status codes for RPC responses.

Name	Value
OK	0
BLOCKLET_NOT_FOUND	1
BLOCKLET_NOT_PURCHASED	2
FORBIDDEN	403
INTERNAL	500
TIMEOUT	504

BlockletStatusMap

Describes the various lifecycle statuses a Blocklet can be in on the Blocklet Server.

Name	Value
ADDED	0
DOWNLOADING	1
DOWNLOADED	2
INSTALLING	3
INSTALLED	4
STARTING	5
RUNNING	6
STOPPING	7
STOPPED	8
ERROR	9
UPGRADING	10
RESTARTING	11
CORRUPTED	12
WAITING	13
DELETED	14
UNKNOWN	15

BackendServiceTypeMap

Defines the types of backend services that can be configured for routing within the Blocklet Server.

Name	Value
DAEMON	0
BLOCKLET	1
REDIRECT	2
NONE	3
GENERAL_PROXY	4
DIRECT_RESPONSE	5
REWRITE	6
COMPONENT	7

NotificationAttachmentTypeMap

Specifies the different types of content that can be included as attachments in Blocklet notifications.

Name	Value
ASSET	0
VC	1
TOKEN	2
TEXT	3
IMAGE	4
DIVIDER	5
TRANSACTION	6
DAPP	7
LINK	8
SECTION	9

HeaderMatchTypeMap

Defines how HTTP header values are matched in routing rules.

Name	Value
EXACT	0
PARTIAL	1
REGEXP	2

PublishTypeMap

Indicates the type of project being published (e.g., a resource or a complete Blocklet package).

Name	Value
RESOURCE	0
PACK	1

ReleaseStatusMap

Describes the status of a Blocklet release within the publishing workflow.

Name	Value
DRAFT	0
PUBLISHED	1

Key Data Types#

These types define the structure of data objects exchanged between the Blocklet SDK and the Blocklet Server, ensuring type safety and clarity in application development.

TNodeState#

Represents the overall state and configuration of a Blocklet Server instance.

Property	Type	Description
did	string	The Decentralized Identifier of the Blocklet Server.
pk	string	The public key of the Blocklet Server.
version	string	The current software version of the Blocklet Server.
name	string	The user-friendly name of the Blocklet Server.
description	string	A description of the Blocklet Server.
port	string	The port on which the Blocklet Server is running.
initialized	boolean	Indicates if the Blocklet Server has completed its initial setup.
nodeOwner	TWalletInfo	Information about the owner's wallet, if set.
createdAt	number	Timestamp of when the Blocklet Server was created.
startedAt	number	Timestamp of when the Blocklet Server was last started.
initializedAt	number	Timestamp of when the Blocklet Server was initialized.
mode	string	The operational mode of the Blocklet Server (e.g., 'production', 'development').
routing	TNodeRouting	Details about the server's routing configuration.
environments	TConfigEntry[]	List of environment variables configured for the server.
uptime	number	The uptime of the Blocklet Server in seconds.
autoUpgrade	boolean	Indicates if automatic upgrades are enabled.
nextVersion	string	The next version available for upgrade.
upgradeSessionId	string	Session ID for ongoing upgrades.
registerUrl	string	URL for registering the Blocklet Server.
enableWelcomePage	boolean	Indicates if the welcome page is enabled.
webWalletUrl	string	URL for the web-based DID Wallet.
blockletRegistryList	TBlockletStore[]	List of Blocklet Stores connected to the server.
ownerNft	TOwnerNft	Information about the owner's NFT.
diskAlertThreshold	number	Disk space usage threshold for alerts.
trustedPassports	TTrustedPassport[]	List of trusted DID Passport issuers.
launcher	TLauncherInfo	Information about the Blocklet Launcher.
enablePassportIssuance	boolean	Indicates if DID Passport issuance is enabled.
didRegistry	string	The DID registry used by the server.
didDomain	string	The DID Domain associated with the server.
status	number	Numeric status code of the server.
trustedFactories	TTrustedFactory[]	List of trusted NFT factories.
enableBetaRelease	boolean	Indicates if beta releases are enabled.
runtimeConfig	TNodeRuntimeConfig	Runtime configuration settings for the node.
nftDomainUrl	string	URL for NFT domains.
enableFileSystemIsolation	boolean	Indicates if file system isolation is enabled.
enableDocker	boolean	Indicates if Docker integration is enabled.
isDockerInstalled	boolean	Indicates if Docker is installed.
enableDockerNetwork	boolean	Indicates if Docker network is enabled.
enableSessionHardening	boolean	Indicates if session hardening is enabled.
sessionSalt	string	Salt used for session hardening.

TBlockletMeta#

Contains the static metadata and descriptive information about a Blocklet, typically found in its blocklet.json file.

Property	Type	Description
did	string	The DID of the Blocklet.
name	string	The internal name of the Blocklet.
version	string	The version of the Blocklet.
description	string	A brief description of the Blocklet.
interfaces	TBlockletMetaInterface[]	Definitions of interfaces exposed by the Blocklet.
author	TBlockletMetaPerson	Information about the Blocklet's author.
main	string	The main entry point file for the Blocklet.
stats	TBlockletStats	Download, star, and purchase statistics for the Blocklet.
homepage	string	The homepage URL of the Blocklet.
path	string	The file path to the Blocklet.
community	string	URL for the Blocklet's community support.
documentation	string	URL for the Blocklet's documentation.
support	string	URL for the Blocklet's support page.
screenshots	string[]	URLs to screenshots of the Blocklet.
keywords	string[]	Keywords associated with the Blocklet.
group	string	The group the Blocklet belongs to.
logo	string	URL to the Blocklet's logo.
title	string	The display title of the Blocklet.
dist	TBlockletDist	Distribution information (tarball URL, integrity hash).
maintainers	TBlockletMetaPerson[]	List of Blocklet maintainers.
contributors	TBlockletMetaPerson[]	List of Blocklet contributors.
repository	TBlockletRepository	Repository information for the Blocklet.
payment	TBlockletPayment	Payment configuration for the Blocklet.
nftFactory	string	The NFT factory associated with the Blocklet.
lastPublishedAt	number	Timestamp of the last publication.
capabilities	TBlockletCapabilities	Capabilities supported by the Blocklet.
components	TChildConfig[]	Child components required by this Blocklet.
environments	TEnvironment[]	Environment variables required by the Blocklet.
requirements	TRequirement	System requirements for the Blocklet.
bundleDid	string	DID of the bundle this Blocklet belongs to.
bundleName	string	Name of the bundle this Blocklet belongs to.
navigation	Record<string, any>[]	Navigation items for the Blocklet.
resources	string[]	List of resources provided by the Blocklet.
resource	TBlockletResource	Detailed resource export configuration.
engine	Record<string, any>	Engine specific configuration.
owner	TBlockletMetaOwner	Owner information.
docker	TBlockletDockerMeta	Docker specific metadata.
events	TBlockletEvent[]	Events emitted by the Blocklet.

TBlockletState#

Represents the dynamic runtime state of a deployed Blocklet on the Blocklet Server, including its status, configurations, and resource usage.

Property	Type	Description
meta	TBlockletMeta	The static metadata of the Blocklet.
status	BlockletStatus	The current operational status (e.g., RUNNING, STOPPED).
createdAt	number	Timestamp when the Blocklet was added to the server.
installedAt	number	Timestamp when the Blocklet was installed.
startedAt	number	Timestamp when the Blocklet was last started.
pausedAt	number	Timestamp when the Blocklet was last paused.
stoppedAt	number	Timestamp when the Blocklet was last stopped.
updatedAt	number	Timestamp when the Blocklet was last updated.
environments	TConfigEntry[]	Runtime environment variables.
configs	TConfigEntry[]	Runtime configuration entries.
diskInfo	TDiskInfo	Disk usage information.
runtimeInfo	TRuntimeInfo	Runtime process information (PID, memory, CPU).
appRuntimeInfo	TRuntimeInfo	Runtime information specific to the Blocklet application.
source	BlockletSource	The source from which the Blocklet was deployed.
deployedFrom	string	Origin of the deployment.
bundleSource	Record<string, any>	Source of the Blocklet bundle.
port	number	The network port the Blocklet is exposed on.
engine	TBlockletEngine	Information about the Blocklet's runtime engine.
mode	string	Operational mode of the Blocklet.
ports	Record<string, any>	Mapped ports for the Blocklet.
children	TComponentState[]	State of child components.
optionalComponents	TOptionalComponentState[]	State of optional components.
trustedPassports	TTrustedPassport[]	Trusted DID Passports for the Blocklet.
trustedFactories	TTrustedFactory[]	Trusted NFT factories for the Blocklet.
enablePassportIssuance	boolean	Indicates if DID Passport issuance is enabled for this Blocklet.
dynamic	boolean	Indicates if the Blocklet is dynamically deployed.
mountPoint	string	The URL mount point for the Blocklet.
settings	TBlockletSettings	Blocklet-specific settings.
appDid	string	The application DID of the Blocklet.
site	TRoutingSite	Routing site configuration for the Blocklet.
controller	TBlockletController	Controller information for the Blocklet.
migratedFrom	TBlockletMigrateRecord[]	Records of migrations.
appPid	string	Permanent ID of the Blocklet application.
externalSk	boolean	Indicates if an external secret key is used.
externalSkSource	string	Source of the external secret key.
structVersion	string	Structure version of the Blocklet.
enableDocker	boolean	Indicates if Docker is enabled for the Blocklet.
enableDockerNetwork	boolean	Indicates if Docker network is enabled for the Blocklet.
vaults	TBlockletVaultRecord[]	Vault records associated with the Blocklet.

Here's a diagram illustrating the composition of TBlockletState:

TNotification#

Defines the structure of a notification message, including sender, receiver, content, and associated actions or attachments, used by the Notifications Service.

Property	Type	Description
sender	string	The DID of the entity sending the notification.
receiver	string	The DID of the intended recipient.
title	string	The title of the notification.
description	string	A detailed description or body of the notification.
action	string	A primary action associated with the notification (deprecated, use actions).
entityType	string	The type of entity the notification is about.
entityId	string	The ID of the entity the notification is about.
read	boolean	Indicates if the notification has been read.
createdAt	number	Timestamp when the notification was created.
id	string	Unique identifier for the notification.
severity	NotificationSeverity	The severity level of the notification (e.g., INFO, SUCCESS, ERROR).
source	NotificationSource	The source of the notification (e.g., SYSTEM, COMPONENT).
attachments	TNotificationAttachment[]	List of rich content attachments (deprecated, use blocks).
blocks	TNotificationAttachment[]	Structured content blocks for rich notifications.
actions	TNotificationAction[]	List of actionable buttons or links within the notification.
componentDid	string	The DID of the Blocklet component that generated the notification.
type	NotificationType	The type of notification (e.g., NOTIFICATION, CONNECT, FEED).
receivers	TNotificationReceiver[]	Detailed information about each receiver and their send status.
data	Record<string, any>	Additional arbitrary data associated with the notification.
feedType	string	Specific type for feed-style notifications.
statistics	TNotificationStatistics	Statistics related to sending the notification across channels.
activity	TNotificationActivity	Activity details for activity-type notifications.
actorInfo	TUserInfo	Information about the actor involved in the notification activity.

Here's a diagram illustrating the composition of TNotification:

TUserInfo#

Defines the comprehensive profile information for a user within the Blocklet Server, including DID, roles, and connected accounts.

Property	Type	Description
did	string	The user's DID.
pk	string	The user's public key.
role	string	The user's assigned role.
avatar	string	URL to the user's avatar image.
fullName	string	The user's full name.
email	string	The user's email address.
approved	boolean	Indicates if the user is approved.
createdAt	number	Timestamp when the user account was created.
updatedAt	number	Timestamp when the user account was last updated.
locale	string	The user's preferred locale.
passports	TPassport[]	List of DID Passports associated with the user.
firstLoginAt	number	Timestamp of the user's first login.
lastLoginAt	number	Timestamp of the user's last login.
remark	string	Any remarks about the user.
lastLoginIp	string	The IP address from which the user last logged in.
sourceProvider	string	The identity provider used for the user's last login.
sourceAppPid	string	The permanent application ID from which the user originated.
connectedAccounts	TConnectedAccount[]	List of connected external accounts (e.g., social logins).
extra	Record<string, any>	Additional custom data.
tags	TTag[]	Tags associated with the user.
didSpace	Record<string, any>	Information about the user's DID Space.
userSessions	TUserSession[]	List of active user sessions.
url	string	The user's profile URL.
phone	string	The user's phone number.
inviter	string	The DID of the user who invited this user.
generation	number	The generation level of the user (e.g., in a referral hierarchy).
emailVerified	boolean	Indicates if the user's email is verified.
phoneVerified	boolean	Indicates if the user's phone number is verified.
metadata	TUserMetadata	Additional metadata about the user (bio, location, links, etc.).
address	TUserAddress	The user's physical address information.
userSessionsCount	number	The total count of user sessions.

TRoutingRule#

Defines a single routing rule used by the Blocklet Server's routing engine to direct incoming requests.

Property	Type	Description
id	string	Unique identifier for the routing rule.
from	TRoutingRuleFrom	Specifies the conditions for matching incoming requests (path, headers).
to	TRoutingRuleTo	Defines where the matched request should be routed (port, type, DID, URL, etc.).
isProtected	boolean	Indicates if the rule is protected and cannot be easily modified or deleted.

TPaging#

A standard type used for pagination metadata in API responses, providing information about the total number of items, page size, and current page.

Property	Type	Description
total	number	The total number of items available.
pageSize	number	The maximum number of items per page.
pageCount	number	The total number of pages.
page	number	The current page number.

Validation Schemas as Type Definitions#

Beyond explicit TypeScript interfaces, the Blocklet SDK utilizes Joi validation schemas (found in src/validators) to define the expected structure and constraints of data. These schemas effectively act as runtime type definitions for inputs to various API methods, ensuring data integrity.

Notification Validation Constants#

The notification.ts validator defines several constant objects that mirror the enumerated maps, providing string representations for notification-related types, severities, and attachment types. These are used for validation and consistency.

NOTIFICATION_TYPES

Name	Value
NOTIFICATION	'notification'
CONNECT	'connect'
FEED	'feed'
HI	'hi'
PASSTHROUGH	'passthrough'

SEVERITIES

Name	Value
NORMAL	'normal'
SUCCESS	'success'
ERROR	'error'
WARNING	'warning'

ATTACHMENT_TYPES

Name	Value
ASSET	'asset'
VC	'vc'
TOKEN	'token'
TEXT	'text'
IMAGE	'image'
DIVIDER	'divider'
TRANSACTION	'transaction'
DAPP	'dapp'
LINK	'link'
SECTION	'section'

ACTIVITY_TYPES

Name	Value
COMMENT	'comment'
LIKE	'like'
FOLLOW	'follow'
TIPS	'tips'
MENTION	'mention'
ASSIGN	'assign'
UN_ASSIGN	'un_assign'

ACTIVITY_TARGET_TYPES

Name	Value
DISCUSSION	'discussion'
BLOG	'blog'
DOC	'doc'
BOOKMARK	'bookmark'
COMMENT	'comment'
USER	'user'

Schema Examples#

Validators like notificationSchema and eventSchema define the detailed structure for TNotification and TEvent objects, respectively. They ensure that data conforms to the expected format before being processed by the SDK or Blocklet Server.

For instance, notificationSchema validates the comprehensive structure of a TNotification object:

This schema, along with others, defines the precise properties and their validation rules, acting as a definitive guide for developers on the expected data structures.

By leveraging these shared constants and type definitions, Blocklet applications can maintain high levels of data consistency and interoperability within the Blocklet Server ecosystem. These foundational elements are critical for building reliable and scalable decentralized applications.

To see how these types are put into practice, explore the Notifications and Auth Service documentation.