@dojoengine/grpc

gRPC-Web client for Dojo, providing TypeScript bindings for torii's protobuf definitions.

Installation

pnpm add @dojoengine/grpc

Usage

import { createDojoGrpcClient } from "@dojoengine/grpc";

// Create a client instance
const client = createDojoGrpcClient({
    url: "http://localhost:8080", // Your torii gRPC endpoint
});

// Example: Get world metadata
const metadata = await client.worldClient.worldMetadata({}).response;
console.log("World:", metadata.world);

// Example: Subscribe to entities
const subscription = client.worldClient.subscribeEntities({
    clause: {
        keys: {
            keys: [],
            patternMatching: PatternMatching.FixedLen,
            models: [],
        },
    },
});

// Handle streaming responses
for await (const response of subscription.responses) {
    console.log("Entity update:", response.entity);
}

Performance Comparison

This package includes comprehensive benchmarks comparing performance with @dojoengine/torii-wasm.

Running Benchmarks

# Run all benchmarks
pnpm run bench

# Generate comparison report
pnpm run bench:report

# Run benchmarks and generate report
pnpm run bench:full

Benchmark Categories

1. Entity Queries: Single entity, batch retrieval, complex queries, pagination
2. Subscriptions: Setup time, message throughput, concurrent connections
3. Serialization: Small/large payloads, complex structures, batch processing
4. Integration: Full lifecycle, mixed workloads, error recovery

Performance Considerations

• gRPC-Web uses Protocol Buffers for efficient binary serialization
• torii-wasm uses native WebAssembly bindings for direct memory access
• Choice depends on your specific use case:
  • gRPC-Web: Better for standard web environments, easier debugging
  • torii-wasm: Better for high-performance applications, lower overhead

Development

Update Proto Files

To update the proto files from the torii repository:

pnpm run update:proto

Generate TypeScript Code

To regenerate the TypeScript bindings after updating proto files:

pnpm run build:proto

Build

pnpm run build

Test

pnpm run test

API Reference

createDojoGrpcClient(config)

Creates a new gRPC-Web client instance.

Parameters

• config.url: The base URL of the torii gRPC-Web endpoint
• config.options: Optional RPC options

Returns

A DojoGrpcClient instance with:

• worldClient: The generated World service client with all RPC methods

Generated Types

All protobuf message types and enums are exported from the package:

import type {
    Entity,
    Model,
    Query,
    Transaction,
    // ... other types
} from "@dojoengine/grpc";