@dojoengine/sdk
Version:
Dojo SDK: Build onchain and provable apps faster
992 lines (974 loc) • 38.8 kB
TypeScript
import * as torii$1 from '@dojoengine/torii-wasm/node';
import { Clause as Clause$1, PatternMatching, ComparisonOperator } from '@dojoengine/torii-wasm/node';
import { StarknetDomain, TypedData, Account, BigNumberish, CairoCustomEnum, CairoOption } from 'starknet';
import * as torii from '@dojoengine/torii-wasm/types';
import { Query, PaginationDirection, Clause, OrderBy, Pagination as Pagination$2, Entity, Subscription } from '@dojoengine/torii-wasm/types';
import { Result } from 'neverthrow';
import { Pagination as Pagination$1 } from '@dojoengine/torii-wasm';
type ToUnion<T> = T extends infer U ? U : never;
type ExtractPrimitiveKeys<T> = T extends Record<infer K, any> ? K : never;
type PrimitiveTypeKeys = ToUnion<ExtractPrimitiveKeys<torii.Primitive>>;
type MemberValueParam = {
type: PrimitiveTypeKeys;
value: any;
} | any;
/**
* Converts a value to a Torii primitive type.
*
* @param {MemberValue} value - The value to convert.
* @returns {torii.MemberValue} - The converted primitive value.
* @throws {Error} - If the value type is unsupported.
*/
declare function convertToPrimitive(value: MemberValueParam, shortStringToFelt: typeof torii.cairoShortStringToFelt): torii.MemberValue;
declare const defaultToriiPagination: Pagination$2;
/**
* A generic pagination class that handles cursor-based pagination for query results.
* This class manages the state of paginated items and provides methods to navigate through pages.
*
* @template T - The schema type that extends SchemaType
* @template Inner - The type of items being paginated (must be an array type)
*/
declare class Pagination<T extends SchemaType, Inner extends any[]> {
limit: number;
cursor?: string | undefined;
direction?: string | undefined;
private items;
/**
* Creates a new Pagination instance
*
* @param limit - The maximum number of items to return per page
* @param cursor - Optional cursor string for pagination
* @param direction - Optional direction of pagination (defaults to "Forward")
*/
constructor(limit: number, cursor?: string | undefined, direction?: string | undefined);
/**
* Creates a Pagination instance from a ToriiQueryBuilder
*
* @param query - The query builder to extract pagination parameters from
* @returns A new Pagination instance configured with the query's pagination settings
*/
static fromQuery<T extends SchemaType, Inner extends any[]>(query: ToriiQueryBuilder<T>, nextCursor?: string): Pagination<T, Inner>;
/**
* Sets the items for the current page
*
* @param items - The items to set for the current page
* @returns The Pagination instance for method chaining
*/
withItems(items: Inner): this;
/**
* Gets the current page's items
*
* @returns The array of items for the current page
*/
getItems(): Inner;
/**
* Gets a query builder configured for the next page
*
* @param query - The base query builder to configure
* @returns A new query builder configured for the next page
*/
getNextQuery(query: ToriiQueryBuilder<T>): ToriiQueryBuilder<T>;
/**
* Gets a query builder configured for the previous page
*
* @param query - The base query builder to configure
* @returns A new query builder configured for the previous page
*/
getPreviousQuery(query: ToriiQueryBuilder<T>): ToriiQueryBuilder<T>;
}
type ToriiQueryBuilderOptions = Omit<Partial<Query>, "clause">;
declare class ToriiQueryBuilder<T extends SchemaType> {
private query;
constructor(options?: ToriiQueryBuilderOptions);
/**
* Set the maximum number of results to return
*/
withLimit(limit: number): ToriiQueryBuilder<T>;
/**
* Set the offset for pagination
* @deprecated Use `withCursor` instead
*/
withOffset(): ToriiQueryBuilder<T>;
/**
* Set the cursor for pagination
* undefined is default, fetch from starting point
* `next_cursor` is return from queries
*/
withCursor(cursor: string): ToriiQueryBuilder<T>;
/**
* Set the maximum number of results to return
*/
withDirection(direction: PaginationDirection): ToriiQueryBuilder<T>;
/**
* Add the clause to filter results
*/
withClause(clause: Clause): ToriiQueryBuilder<T>;
/**
* Set whether to include hashed keys in the response
* HashedKeys represent internal torii entity id.
*/
includeHashedKeys(): ToriiQueryBuilder<T>;
/**
* Add a single order by clause
*/
addOrderBy(member: string, direction: "Asc" | "Desc"): ToriiQueryBuilder<T>;
/**
* Add multiple order by clauses at once
*/
withOrderBy(orderBy: OrderBy[]): ToriiQueryBuilder<T>;
/**
* Add a single entity model to filter
*/
addEntityModel(model: keyof T & string): ToriiQueryBuilder<T>;
/**
* Set multiple entity models at once
*/
withEntityModels(models: (keyof T & string)[]): ToriiQueryBuilder<T>;
/**
* Build the final query
*/
build(): Query;
/**
* Create a new builder instance with pagination settings
*
*/
static withPagination<T extends Record<string, Record<string, any>>>(cursor: string, limit: number, direction: PaginationDirection): ToriiQueryBuilder<T>;
/**
* Returns inner clause inside a Result wrapper.
*/
getClause(): Result<Clause, string>;
getPagination(): Pagination$1;
/**
* Check is query is historical
*/
isHistorical(): boolean;
}
type HistoricalToriiQueryBuilderOptions = Omit<Partial<ToriiQueryBuilderOptions>, "historical">;
declare class HistoricalToriiQueryBuilder<T extends SchemaType> extends ToriiQueryBuilder<T> {
constructor(options?: ToriiQueryBuilderOptions);
}
/**
* SchemaType represents the structure of your Dojo world models.
* Each namespace contains models defined by their field types.
*
* @example
* ```typescript
* const schema = {
* world: {
* Player: {
* id: 'felt252',
* name: 'string',
* score: 'u32'
* },
* Item: {
* id: 'felt252',
* name: 'string',
* durability: 'u8'
* }
* }
* } satisfies SchemaType;
* ```
*/
type SchemaType = {
/**
* namespace: Your namespace for grouping related models.
* This is typically used to organize models by their domain or context.
* For example, 'world', 'game', 'inventory', etc.
*/
[namespace: string]: {
/**
* model: Your model name, case sensitive.
* This represents a specific entity or concept within your namespace.
* For example, 'Player', 'Item', 'Quest', etc.
*/
[model: string]: {
/**
* Dynamic fields of the model.
* These can be of any type, typically representing the properties of your model.
*/
[field: string]: any;
};
};
};
/**
* Standardized result of a query - an array of parsed entities.
*/
type StandardizedQueryResult<T extends SchemaType> = Array<ParsedEntity<T>>;
/**
* Parsed entity with its ID and models.
* Ensures that each model's data adheres to the schema's field types.
*
* @example
* ```typescript
* // Given a schema:
* const schema = {
* world: {
* Player: {
* id: 'felt252',
* name: 'string',
* score: 'u32'
* }
* }
* } satisfies SchemaType;
*
* // A ParsedEntity might look like:
* const entity: ParsedEntity<typeof schema> = {
* entityId: '0x123',
* models: {
* world: {
* Player: {
* id: '0x123',
* name: 'Alice',
* score: 100
* }
* }
* }
* };
* ```
*/
type ParsedEntity<T extends SchemaType> = {
entityId: string;
models: {
[K in keyof T]: {
[M in keyof T[K]]?: T[K][M] extends object ? Partial<T[K][M]> : T[K][M];
};
};
};
/**
* Utility type to extract all models' data from SchemaType.
* This is useful for typing messages and model data.
*/
type UnionOfModelData<T extends SchemaType> = {
[K in keyof T]: {
[L in keyof T[K]]: T[K][L];
}[keyof T[K]];
}[keyof T];
/**
* Response type for queries with pagination support.
*/
type ToriiResponse<T extends SchemaType> = Pagination<T, StandardizedQueryResult<T>>;
/**
* Response type for subscriptions - includes initial data and subscription handle.
*/
type SubscribeResponse<T extends SchemaType> = [
ToriiResponse<T>,
torii.Subscription
];
type AttributesFilter = {
name: string;
value: string;
};
/**
* Request type for getting tokens.
*/
interface GetTokenRequest {
contractAddresses?: string[];
attributesFilter?: AttributesFilter[];
tokenIds?: string[];
pagination?: torii.Pagination;
}
/**
* Request type for getting token balances.
*/
interface GetTokenBalanceRequest extends GetTokenRequest {
accountAddresses?: string[];
}
type ContractType = "WORLD" | "ERC20" | "ERC721" | "ERC1155" | "UDC" | "OTHER";
type GetTokenContracts = {
contractAddresses?: string[];
contractTypes?: string[];
pagination?: torii.Pagination;
};
/**
* Success result for subscription callbacks.
*/
type Success<T> = {
data: T;
error: undefined;
};
/**
* Failure result for subscription callbacks.
*/
type Failure<E> = {
data: undefined;
error: E;
};
/**
* Arguments passed to subscription callbacks.
* Either contains data or an error, but not both.
*/
type SubscriptionCallbackArgs<T, E = Error> = Success<T> | Failure<E>;
/**
* Callback function type for subscriptions.
*/
type SubscriptionCallback<T> = (response: SubscriptionCallbackArgs<T>) => void;
/**
* Request type for subscribing to token balance updates.
*/
type SubscribeTokenBalanceRequest = GetTokenBalanceRequest & {
callback: SubscriptionCallback<torii.TokenBalance>;
};
/**
* Request type for updating token balance subscriptions.
*/
type UpdateTokenBalanceSubscriptionRequest = GetTokenBalanceRequest & {
subscription: torii.Subscription;
};
type SubscribeTokenRequest = GetTokenRequest & {
callback: SubscriptionCallback<torii.Token>;
};
/**
* SDK interface for interacting with the DojoEngine.
* Provides methods for querying, subscribing, and managing your Dojo world.
*
* @template T - The schema type defining your world's models.
*
* @example
* ```typescript
* const sdk = await init<typeof schema>({
* client: { worldAddress: "0x...", toriiUrl: "http://localhost:8080" },
* domain: { name: "MyApp", version: "1.0.0", chainId: "SN_MAIN" }
* });
*
* // Query entities
* const { items } = await sdk.getEntities({
* query: new ToriiQueryBuilder().withClause(...)
* });
*
* // Subscribe to updates
* const [initial, subscription] = await sdk.subscribeEntityQuery({
* query: new ToriiQueryBuilder().withClause(...),
* callback: ({ data, error }) => {
* if (error) console.error(error);
* else console.log(data);
* }
* });
* ```
*/
interface SDK<T extends SchemaType> {
/**
* The underlying Torii client instance.
* Use this for advanced operations not covered by the SDK methods.
*/
client: torii.ToriiClient;
/**
* Subscribes to entity updates based on the provided query.
* Returns initial data and a subscription handle.
*
* @param {SubscribeParams<T>} params - Query and callback parameters
* @returns {Promise<SubscribeResponse<T>>} - Initial data and subscription handle
*
* @example
* ```typescript
* const [initial, subscription] = await sdk.subscribeEntityQuery({
* query: new ToriiQueryBuilder()
* .withClause(KeysClause([ModelsMapping.Player], [address])),
* callback: ({ data, error }) => {
* if (data) console.log('Entity updated:', data);
* }
* });
* ```
*/
subscribeEntityQuery: (params: SubscribeParams<T>) => Promise<SubscribeResponse<T>>;
/**
* Subscribes to event messages based on the provided query.
* Returns initial data and a subscription handle.
*
* @param {SubscribeParams<T>} params - Query and callback parameters
* @returns {Promise<SubscribeResponse<T>>} - Initial data and subscription handle
*/
subscribeEventQuery: (params: SubscribeParams<T>) => Promise<SubscribeResponse<T>>;
/**
* Subscribes to token balance updates.
* Returns initial balances and a subscription handle.
*
* @param {SubscribeTokenBalanceRequest} request - Filter and callback parameters
* @returns {Promise<[torii.TokenBalances, torii.Subscription]>} - Initial balances and subscription
*/
subscribeTokenBalance: (request: SubscribeTokenBalanceRequest) => Promise<[torii.TokenBalances, torii.Subscription]>;
/**
* Subscribes to token updates
*
* # Parameters
* @param {SubscribeTokenRequest} request
* @returns {Promise<[torii.Tokens, torii.Subscription]>}
*/
subscribeToken: (request: SubscribeTokenRequest) => Promise<[torii.Tokens, torii.Subscription]>;
/**
* Fetches entities from the Torii client based on the provided query.
*
* @param {GetParams<T>} params - Query parameters
* @returns {Promise<ToriiResponse<T>>} - Paginated query results
*
* @example
* ```typescript
* const result = await sdk.getEntities({
* query: new ToriiQueryBuilder()
* .withClause(KeysClause([ModelsMapping.Player], [address]))
* .limit(10)
* });
*
* // Access entities
* result.items.forEach(entity => {
* console.log(entity.models.world.Player);
* });
*
* // Load more if available
* if (result.hasNextPage()) {
* const nextPage = await result.fetchNextPage();
* }
* ```
*/
getEntities: (params: GetParams<T>) => Promise<ToriiResponse<T>>;
/**
* Fetches event messages from the Torii client based on the provided query.
*
* @param {GetParams<T>} params - Query parameters
* @returns {Promise<ToriiResponse<T>>} - Paginated query results
*/
getEventMessages: (params: GetParams<T>) => Promise<ToriiResponse<T>>;
/**
* Generates typed data for signing messages.
* Used for creating off-chain messages that can be verified on-chain.
*
* @param {string} nsModel - Model name prefixed with namespace (e.g., "world-Player")
* @param {M} message - The message data conforming to the model structure
* @param {Array} modelMapping - Optional custom type mappings
* @param {Record} additionalTypes - Optional additional EIP-712 types
* @returns {TypedData} - EIP-712 typed data ready for signing
*/
generateTypedData: <M extends UnionOfModelData<T>>(nsModel: string, message: M, modelMapping?: Array<{
name: string;
type: string;
}>, additionalTypes?: Record<string, Array<{
name: string;
type: string;
}>>) => TypedData;
/**
* Sends a signed message to the Torii server.
* In web environments, requires an Account. In Node.js, uses configured signer.
*
* @param {TypedData} data - The typed data to sign and send
* @param {Account} account - The account to sign with (web only)
* @returns {Promise<Result<Uint8Array, string>>} - Success with message ID or error
*/
sendMessage: (data: TypedData, account?: Account) => Promise<Result<string, string>>;
/**
* Sends multiple signed messages to the Torii server in a batch.
* In web environments, requires an Account. In Node.js, uses configured signer.
*
* @param {TypedData[]} data - Array of typed data to sign and send
* @param {Account} account - The account to sign with (web only)
* @returns {Promise<Result<string[], string>>} - Success with array of message IDs or error
*/
sendMessageBatch: (data: TypedData[], account?: Account) => Promise<Result<string[], string>>;
/**
* Sends already signed messages to the Torii server in a batch.
* This method allows you to send pre-signed messages directly without signing them again.
*
* @param {torii.Message[]} data - Array of signed messages with message content and signatures
* @returns {Promise<Result<string[], string>>} - Success with array of message IDs or error
*/
sendSignedMessageBatch: (data: torii.Message[]) => Promise<Result<string[], string>>;
/**
* Gets token information.
*
* @param {GetTokenRequest} request - Filter parameters
* @returns {Promise<torii.Tokens>} - Token information
*/
getTokens(request: GetTokenRequest): Promise<torii.Tokens>;
/**
* Gets token contracts.
*
* @param {GetTokenContracts} request - Filter parameters
* @returns {Promise<torii.TokenContracts>} - Token information
*/
getTokenContracts(request: GetTokenContracts): Promise<torii.TokenContracts>;
/**
* Gets token balances for specified accounts.
*
* @param {GetTokenBalanceRequest} request - Filter parameters
* @returns {Promise<torii.TokenBalances>} - Token balances
*/
getTokenBalances(request: GetTokenBalanceRequest): Promise<torii.TokenBalances>;
/**
* Creates a subscription for token balance updates.
* Unlike `subscribeTokenBalance`, this only returns the subscription handle.
*
* @param {SubscribeTokenBalanceRequest} request - Filter and callback parameters
* @returns {torii.Subscription} - Subscription handle
*/
onTokenBalanceUpdated: (request: SubscribeTokenBalanceRequest) => Promise<torii.Subscription>;
/**
* Subscribes to token updates
*
* # Parameters
* @param {string[]} contract_addresses - Array of contract addresses to filter (empty for all)
* @param {string[]} token_ids - Array of token ids to filter (empty for all)
* @param {Function} callback - JavaScript function to call on updates
*
* # Returns
* Result containing subscription handle or error
* @returns torii.Subscription
*/
onTokenUpdated: (request: SubscribeTokenRequest) => Promise<torii.Subscription>;
/**
* Updates an existing token balance subscription with new filters.
*
* @param {UpdateTokenBalanceSubscriptionRequest} request - New filter parameters
* @returns {Promise<void>}
*/
updateTokenBalanceSubscription: (request: UpdateTokenBalanceSubscriptionRequest) => Promise<void>;
/**
* Updates an existing entity subscription with new clauses.
*
* @param {torii.Subscription} subscription - Existing subscription to update
* @param {torii.Clause} clauses - New filter clauses
* @returns {Promise<void>}
*/
updateEntitySubscription: (subscription: torii.Subscription, clauses: torii.Clause) => Promise<void>;
/**
* Updates an existing event message subscription with new clauses.
*
* @param {torii.Subscription} subscription - Existing subscription to update
* @param {torii.Clause} clauses - New filter clauses
* @returns {Promise<void>}
*/
updateEventMessageSubscription: (subscription: torii.Subscription, clauses: torii.Clause, historical: boolean) => Promise<void>;
/**
* Gets controller information for the specified contract addresses.
*
* @param {string[]} contract_addresses - Contract addresses to query (empty for all)
* @param {string[]} usernames - usernames to query (empty for all)
* @param {torii.Pagination} pagination - torii pagination object
* @returns {Promise<torii.Controllers>} - Controller information
*/
getControllers: (contract_addresses: string[], usernames: string[], pagination?: torii.Pagination) => Promise<torii.Controllers>;
}
/**
* Client configuration type with required world address.
*/
type SDKClientConfig = Partial<Omit<torii.ClientConfig, "worldAddress">> & {
worldAddress: torii.ClientConfig["worldAddress"];
};
/**
* Configuration interface for initializing the SDK.
*
* @example
* ```typescript
* const config: SDKConfig = {
* client: {
* worldAddress: "0x...",
* toriiUrl: "http://localhost:8080",
* relayUrl: "/ip4/127.0.0.1/tcp/9090"
* },
* domain: {
* name: "MyApp",
* version: "1.0.0",
* chainId: "SN_MAIN"
* },
* // Node.js only:
* signer: signingKey,
* identity: "0x..."
* };
* ```
*/
interface SDKConfig {
/**
* Configuration for the Torii client connection.
*/
client: SDKClientConfig;
/**
* The Starknet domain configuration for EIP-712 typed data.
*/
domain: StarknetDomain;
/**
* Signing key for off-chain messages (Node.js only).
* Required when using `sendMessage` in Node.js environments.
*/
signer?: torii.SigningKey;
/**
* Identity address for off-chain messages (Node.js only).
* This should match the `identity` field in your Dojo models.
*/
identity?: string;
/**
* Enable debug logging for queries and subscriptions.
*/
withLogger?: boolean;
}
/**
* @deprecated - Use SDKConfig.withLogger instead
*/
interface SDKFunctionOptions {
logging?: boolean;
}
/**
* Parameters for subscription methods.
*/
interface SubscribeParams<T extends SchemaType> {
/**
* Query builder instance configured with your filters.
*/
query: ToriiQueryBuilder<T>;
/**
* Callback function invoked when data changes.
* Receives either data or an error, but not both.
*/
callback: SubscriptionCallback<StandardizedQueryResult<T>>;
/**
* @deprecated - Use `query.historical()` instead
*/
historical?: boolean;
}
/**
* Parameters for get/fetch methods.
*/
interface GetParams<T extends SchemaType> {
/**
* Query builder instance configured with your filters.
*/
query: ToriiQueryBuilder<T>;
/**
* @deprecated - Use `query.historical()` instead
*/
historical?: boolean;
}
type ClauseBuilderInterface = {
build(): Clause$1;
};
type ModelPath<T, K extends keyof T> = K extends string ? T[K] extends Record<string, any> ? {
[SubK in keyof T[K]]: `${K}-${SubK & string}`;
}[keyof T[K]] : never : never;
type GetModelType<T, Path extends string> = Path extends `${infer Namespace}-${infer Model}` ? Namespace extends keyof T ? Model extends keyof T[Namespace] ? T[Namespace][Model] : never : never : never;
/**
* Saves some keyboard strokes to get a KeysClause.
*
* @param models - the models you want to query, has to be in form of ns-Model
* @param keys - the keys that has the model. You can use `undefined` as a wildcard to match any key
* @param pattern - either VariableLen or FixedLen - to check exact match of key number
* @return ClauseBuilder<T>
*/
declare function KeysClause<T extends SchemaType>(models: ModelPath<T, keyof T>[], keys: (string | undefined)[], pattern?: PatternMatching): ClauseBuilder<T>;
/**
* Saves some keyboard strokes to get a HashedKeysClause.
*
* @param keys - the hashed_keys (entityId) that you want to query over
* @return ClauseBuilder<T>
*/
declare function HashedKeysClause<T extends SchemaType>(keys: BigNumberish[]): ClauseBuilder<T>;
/**
* Saves some keyboard strokes to get a MemberClause.
*
* @template T - the schema type
* @param model - the model you want to query, has to be in form of ns-Model
* @param member - the member of the model on which you want to apply operator
* @param operator - the operator to apply
* @param value - the value to operate on.
* @return ClauseBuilder<T>
*/
declare function MemberClause<T extends SchemaType, Path extends ModelPath<T, keyof T>, M extends keyof GetModelType<T, ModelPath<T, keyof T>>>(model: Path, member: M & string, operator: ComparisonOperator, value: GetModelType<T, Path>[M] | GetModelType<T, Path>[M][] | MemberValueParam): ClauseBuilder<T>;
/**
* Saves some keyboard strokes to get a Composite "Or" Clause
*
* @template T - the schema type
* @param clauses - the inner clauses that you want to compose
* @return CompositeBuilder<T>
*/
declare function AndComposeClause<T extends SchemaType>(clauses: ClauseBuilderInterface[]): CompositeBuilder<T>;
/**
* Saves some keyboard strokes to get a Composite "And" Clause
* @template T - the schema type
* @param clauses - the inner clauses that you want to compose
* @return CompositeBuilder<T>
*/
declare function OrComposeClause<T extends SchemaType>(clauses: ClauseBuilderInterface[]): CompositeBuilder<T>;
declare class ClauseBuilder<T extends SchemaType> {
private clause;
constructor();
/**
* Create a clause based on entity keys
*/
keys(models: ModelPath<T, keyof T>[], keys: (string | undefined)[], pattern?: PatternMatching): ClauseBuilder<T>;
/**
* Create a hashed keys clause based on entity keys
* keys: an array of your keys array (no need to hash it, just pass raw keys)
*/
hashed_keys(keys: BigNumberish[]): ClauseBuilder<T>;
/**
* Create a member clause for comparing values
*/
where<Path extends ModelPath<T, keyof T>, M extends keyof GetModelType<T, Path>>(model: Path, member: M & string, operator: ComparisonOperator, value: GetModelType<T, Path>[M] | GetModelType<T, Path>[M][] | MemberValueParam): ClauseBuilder<T>;
/**
* Start a composite clause chain
*/
compose(): CompositeBuilder<T>;
/**
* Build the final clause
*/
build(): Clause$1;
}
declare class CompositeBuilder<T extends Record<string, Record<string, any>>> {
private orClauses;
private andClauses;
or(clauses: ClauseBuilderInterface[]): CompositeBuilder<T>;
and(clauses: ClauseBuilderInterface[]): CompositeBuilder<T>;
build(): Clause$1;
}
declare const NO_SIGNER = "No signer configured in sdk.init()";
declare const NO_IDENTITY = "No identity configured in sdk.init()";
declare const NO_ACCOUNT = "Account is undefined";
declare const UNDEFINED_CLAUSE = "Clause has not been defined yet. Use `.withClause()` to do so";
/**
* Generates typed data for any user-defined message.
*
* @template M - The message type defined by the schema models.
* @param {string} nsModel - Model name prefixed with namespace joined by a hyphen.
* @param {M} message - The user-defined message content, must be part of the schema models.
* @param {StarknetDomain} [domain] - The domain object. If not provided, uses the default domain from options.
* @returns {TypedData} - The generated typed data.
*/
declare function generateTypedData<T extends SchemaType, M extends UnionOfModelData<T>>(nsModel: string, message: M, domain: StarknetDomain, modelMapping?: Array<{
name: string;
type: string;
}>, additionnalTypes?: Record<string, Array<{
name: string;
type: string;
}>>): TypedData;
/**
* Check if a value is a CairoOption
* @param value - The value to check
* @returns True if the value is a CairoOption, false otherwise
*/
declare function isCairoOption(value: unknown): value is CairoOption<unknown>;
/**
* Merge two CairoOption instances
* @param target - The target CairoOption
* @param source - The source CairoOption
* @returns A new CairoOption instance with the merged value
*/
declare function mergeCairoOption<T extends SchemaType>(target: MergedModels<T>, source: Partial<MergedModels<T>>): MergedModels<T>;
/**
* Check if a value is a CairoCustomEnum
* @param value - The value to check
* @returns True if the value is a CairoCustomEnum, false otherwise
*/
declare function isCairoCustomEnum(value: unknown): value is CairoCustomEnum;
/**
* Merge two CairoCustomEnum instances
* @param target - The target CairoCustomEnum
* @param source - The source CairoCustomEnum
* @returns A new CairoCustomEnum instance with the merged value
*/
declare function mergeCairoCustomEnum<T extends SchemaType>(target: MergedModels<T>, source: Partial<MergedModels<T>>): MergedModels<T>;
/**
* Merged models type
* @template T - The schema type
* @returns The merged models type
*/
type MergedModels<T extends SchemaType> = ParsedEntity<T>["models"][keyof ParsedEntity<T>["models"]];
declare function deepMerge<T extends SchemaType>(target: MergedModels<T>, source: Partial<MergedModels<T>>): MergedModels<T>;
/**
* Custom hook to retrieve a specific model for a given entityId within a specified namespace.
*
* @param entityId - The ID of the entity.
* @param model - The model to retrieve, specified as a string in the format "namespace-modelName".
* @returns The model structure if found, otherwise undefined.
*/
declare function getModelByEntityId<N extends keyof SchemaType, M extends keyof SchemaType[N] & string, Schema extends SchemaType>(entityId: BigNumberish, model: `${N}-${M}`, value: StandardizedQueryResult<Schema>): SchemaType[N][M] | undefined;
/**
* Custom hook to retrieve a specific model for a given entityId within a specified namespace.
*
* @param entityId - The ID of the entity.
* @param model - The model to retrieve, specified as a string in the format "namespace-modelName".
* @returns The model structure if found, otherwise undefined.
*/
declare function getModel<N extends keyof SchemaType, M extends keyof SchemaType[N] & string, Schema extends SchemaType>(model: `${N}-${M}`, value: StandardizedQueryResult<Schema>): SchemaType[N][M] | undefined;
declare function parseEntities<T extends SchemaType>(entities: torii.Entity[], options?: {
logging?: boolean;
}): StandardizedQueryResult<T>;
/**
* Creates a callback function for entity subscription that processes entity data and invokes the provided callback.
* This function is used to standardize entity data handling in subscription callbacks.
*
* @template T - The schema type that defines the structure of the entity data
* @param {SubscriptionCallback<StandardizedQueryResult<T>>} callback - The callback function to be invoked with parsed entity data or error
* @returns {Function} A function that accepts a hashed key and entity data, parses the entity data, and invokes the provided callback
*/
declare function subscribeQueryModelCallback<T extends SchemaType>(callback: SubscriptionCallback<StandardizedQueryResult<T>>): (entityData: Entity) => void;
type Strict<T> = {
[K in keyof T]-?: NonNullable<T[K]>;
};
/**
* Creates a safe callback wrapper that handles errors
* @param callback - The user-provided callback
* @param defaultValue - Default value to check against
* @returns Wrapped callback that handles try/catch
*/
declare function safeCallback<T>(callback: SubscriptionCallback<T>, defaultValue: T): (res: T) => void;
declare const defaultTokenBalance: torii.TokenBalance;
declare function parseTokenRequest<T extends GetTokenRequest & GetTokenBalanceRequest & GetTokenContracts>(req: T): Strict<T>;
/**
* @param {GetTokenRequest} request
* @returns {Promise<torii.Tokens>}
*/
declare function getTokens(client: torii.ToriiClient, request: GetTokenRequest): Promise<torii.Tokens>;
/**
* @param {GetTokenContracts} request
* @returns {Promise<torii.Tokens>}
*/
declare function getTokenContracts(client: torii.ToriiClient, request: GetTokenContracts): Promise<torii.TokenContracts>;
/**
* @param {GetTokenBalanceRequest} request
* @returns {Promise<torii.TokenBalances>}
*/
declare function getTokenBalances(client: torii.ToriiClient, request: GetTokenBalanceRequest): Promise<torii.TokenBalances>;
/**
* Subscribes to token balance updates
*
* # Parameters
* @param {SubscribeTokenBalanceRequest} request
*
* # Returns
* Result containing subscription handle or error
* @returns torii.Subscription
*/
declare function onTokenBalanceUpdated(client: torii.ToriiClient, request: SubscribeTokenBalanceRequest): Promise<torii.Subscription>;
/**
* Updates an existing token balance subscription
*
* # Parameters
* @param {torii.Subscription} subscription - Existing subscription to update
* @param {UpdateTokenBalanceSubscriptionRequest} request
*
* # Returns
* Result containing unit or error
* @returns {Promise<void>}
*/
declare function updateTokenBalanceSubscription(client: torii.ToriiClient, request: UpdateTokenBalanceSubscriptionRequest): Promise<void>;
/**
* Subscribes to token balance updates and returns initial data with subscription
*
* # Parameters
* @param {SubscribeTokenBalanceRequest} request - Request parameters
*
* # Returns
* Array containing initial token balances and subscription handle
* @returns {Promise<[torii.TokenBalances, torii.Subscription]>}
*/
declare function subscribeTokenBalance(client: torii.ToriiClient, request: SubscribeTokenBalanceRequest): Promise<[torii.TokenBalances, torii.Subscription]>;
declare const defaultToken: torii.Token;
/**
* Subscribes to token updates
*
* # Parameters
* @param {SubscribeTokenRequest} request
*
* # Returns
* Result containing subscription handle or error
* @returns torii.Subscription
*/
declare function onTokenUpdated(client: torii.ToriiClient, request: SubscribeTokenRequest): Promise<torii.Subscription>;
/**
* Subscribes to token updates and returns initial data with subscription
*
* # Parameters
* @param {SubscribeTokenRequest} request - Request parameters
*
* # Returns
* Array containing initial tokens and subscription handle
* @returns {Promise<[torii.Tokens, torii.Subscription]>}
*/
declare function subscribeToken(client: torii.ToriiClient, request: SubscribeTokenRequest): Promise<[torii.Tokens, torii.Subscription]>;
interface GrpcClientInterface {
getEntities(query: torii.Query): Promise<torii.Entities>;
onEntityUpdated(clause: torii.Clause | undefined, callback: (entityData: torii.Entity) => void): Promise<torii.Subscription>;
updateEntitySubscription(subscription: torii.Subscription, clauses: torii.Clause): Promise<void>;
getEventMessages(query: torii.Query): Promise<torii.Entities>;
onEventMessageUpdated(clause: torii.Clause | undefined, callback: (entityData: torii.Entity) => void): Promise<torii.Subscription>;
updateEventMessageSubscription(subscription: torii.Subscription, clauses: torii.Clause): Promise<void>;
getTokens(params: {
contract_addresses?: string[];
token_ids?: any[];
pagination?: torii.Pagination;
}): Promise<torii.Tokens>;
getTokenContracts(params: {
contract_addresses?: string[];
contract_types?: torii.ContractType[];
pagination?: torii.Pagination;
}): Promise<torii.TokenContracts>;
getTokenBalances(params: {
contract_addresses?: string[];
account_addresses?: string[];
token_ids?: any[];
pagination?: torii.Pagination;
}): Promise<torii.TokenBalances>;
onTokenBalanceUpdated(contractAddresses: string[], accountAddresses: string[], tokenIds: any[], callback: (res: torii.TokenBalance) => void): Promise<torii.Subscription>;
onTokenUpdated(contractAddresses: string[], tokenIds: any[], callback: (res: torii.Token) => void): Promise<torii.Subscription>;
updateTokenBalanceSubscription(subscription: torii.Subscription, contract_addresses: string[], account_addresses: string[], token_ids: any[]): Promise<void>;
publishMessage(message: torii.Message): Promise<string>;
publishMessageBatch(messages: torii.Message[]): Promise<string[]>;
getControllers(params: {
contract_addresses?: string[];
usernames?: string[];
pagination?: torii.Pagination;
}): Promise<torii.Controllers>;
}
type DojoWorkerCallback = () => Promise<Subscription[]>;
/**
* Creates a worker process that manages subscriptions.
*
* This function executes the provided callback to obtain subscriptions,
* and sets up signal handlers to ensure proper cleanup when the process
* is terminated. When SIGTERM or SIGINT signals are received, all subscriptions
* are freed before the process exits.
*
* @param callback - A function that returns a Promise resolving to an array of Subscriptions
* @returns A Promise that resolves when the worker is set up
*
* @example
* ```ts
* await createWorker(async () => {
* const client = await createClient();
* return [client.subscribe(...)];
* });
* ```
*/
declare function createWorker(callback: DojoWorkerCallback): Promise<void>;
interface InitGrpcOptions {
toriiUrl?: string;
worldAddress: string;
}
declare function initGrpc(options: InitGrpcOptions): GrpcClientInterface;
declare const defaultClientConfig: Partial<torii$1.ClientConfig>;
/**
* Initializes the SDK for Node.js environment with the provided configuration and schema.
*
* @template T - The schema type.
* @param {SDKConfig} options - The configuration object for the SDK.
* @returns {Promise<SDK<T>>} - A promise that resolves to the initialized SDK instance.
*
* @example
* ```typescript
* import { init } from "@dojoengine/sdk/node";
* import { schema } from "./models.gen";
*
* const sdk = await init<typeof schema>({
* client: {
* worldAddress: "0x...",
* toriiUrl: "http://localhost:8080",
* },
* domain: {
* name: "MyApp",
* version: "1.0.0",
* chainId: "SN_MAIN",
* },
* signer: signingKey,
* identity: "0x...",
* });
* ```
*/
declare function init<T extends SchemaType>(options: SDKConfig & {
grpcClient?: GrpcClientInterface;
}): Promise<SDK<T>>;
export { AndComposeClause, type AttributesFilter, ClauseBuilder, type ContractType, type DojoWorkerCallback, type GetParams, type GetTokenBalanceRequest, type GetTokenContracts, type GetTokenRequest, type GrpcClientInterface, HashedKeysClause, HistoricalToriiQueryBuilder, type HistoricalToriiQueryBuilderOptions, type InitGrpcOptions, KeysClause, MemberClause, type MemberValueParam, type MergedModels, NO_ACCOUNT, NO_IDENTITY, NO_SIGNER, OrComposeClause, Pagination, type ParsedEntity, type SDK, type SDKClientConfig, type SDKConfig, type SDKFunctionOptions, type SchemaType, type StandardizedQueryResult, type SubscribeParams, type SubscribeResponse, type SubscribeTokenBalanceRequest, type SubscribeTokenRequest, type SubscriptionCallback, type SubscriptionCallbackArgs, ToriiQueryBuilder, type ToriiResponse, UNDEFINED_CLAUSE, type UnionOfModelData, type UpdateTokenBalanceSubscriptionRequest, convertToPrimitive, createWorker, deepMerge, defaultClientConfig, defaultToken, defaultTokenBalance, defaultToriiPagination, generateTypedData, getModel, getModelByEntityId, getTokenBalances, getTokenContracts, getTokens, init, initGrpc, isCairoCustomEnum, isCairoOption, mergeCairoCustomEnum, mergeCairoOption, onTokenBalanceUpdated, onTokenUpdated, parseEntities, parseTokenRequest, safeCallback, subscribeQueryModelCallback, subscribeToken, subscribeTokenBalance, updateTokenBalanceSubscription };