Agent skill

update-grpc-proto

Update @dojoengine/grpc proto files from Torii repository

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/update-grpc-proto

SKILL.md

Update gRPC Proto Files

Update the @dojoengine/grpc package with the latest proto files from the Torii repository.

When to Use

Use this skill when:

  • Torii has been updated with new RPC methods
  • Proto definitions have changed upstream
  • New features need to be exposed via gRPC
  • Types need to be synchronized with Torii

Step-by-Step Process

Step 1: Update Proto Files

bash
cd packages/grpc && bun run update:proto

This downloads the latest proto files from:

  • https://raw.githubusercontent.com/dojoengine/torii/main/crates/proto/proto/

Step 2: Review Proto Changes

bash
git diff packages/grpc/proto/

Document what changed:

  • New RPC methods
  • Modified message types
  • New fields on existing types

Step 3: Rebuild TypeScript Bindings

bash
cd packages/grpc && bun run build:proto

This generates TypeScript from proto files using protobuf-ts.

Step 4: Identify New RPCs

Compare src/generated/world.client.ts with src/torii-client.ts:

typescript
// Generated client interface - IWorldClient
interface IWorldClient {
    subscribeContracts(...): ServerStreamingCall<...>;
    worlds(...): UnaryCall<...>;
    // ... all RPC methods
}

Check which methods in IWorldClient are not yet wrapped in ToriiGrpcClient.

Step 5: Implement Missing Methods

For each new RPC, follow these patterns:

5a. Add Request Mapper (mappings/query.ts)

typescript
export function createRetrieveNewThingRequest(
    query: NewThingQuery
): RetrieveNewThingRequest {
    return {
        query: {
            // Map SDK types to proto types
            field: query.field,
            pagination: mapPagination(query.pagination),
        },
    };
}

5b. Add Response Mapper (mappings/types.ts)

typescript
export function mapNewThingResponse(
    response: RetrieveNewThingResponse
): NewThingPage {
    return {
        items: response.items.map(mapNewThing),
        nextCursor: response.next_cursor || undefined,
    };
}

export function mapNewThing(thing: ProtoNewThing): NewThingView {
    return {
        id: thing.id,
        // Map proto fields to SDK types
        address: bufferToHex(thing.address),
    };
}

5c. Add Types (types.ts)

typescript
export interface NewThingView {
    id: string;
    address: string;
}

export interface NewThingPage {
    items: NewThingView[];
    nextCursor?: string;
}

5d. Add Client Method (torii-client.ts)

For query methods:

typescript
async getNewThings(query: NewThingQuery): Promise<NewThingPage> {
    const request = createRetrieveNewThingRequest(query);
    const response = await this.client.worldClient.retrieveNewThings(request).response;
    return this.mappers.newThingsResponse(response);
}

For subscription methods:

typescript
async onNewThingUpdated(
    filters: string[] | null | undefined,
    callback: Function
): Promise<Subscription> {
    return this.createStreamSubscription({
        createStream: () =>
            this.client.worldClient.subscribeNewThings({
                filters: filters?.map(hexToBuffer) || [],
            }),
        onMessage: (response: SubscribeNewThingsResponse) => {
            if (response.thing) {
                callback(
                    this.mappers.newThing(response.thing),
                    response.subscription_id
                );
            }
        },
    });
}

For update subscription methods:

typescript
async updateNewThingSubscription(
    subscription: Subscription,
    filters: string[]
): Promise<void> {
    const grpcSubscription = this.findSubscription(subscription);
    if (!grpcSubscription) {
        throw new Error("Subscription not found");
    }
    await this.client.worldClient.updateNewThingsSubscription({
        subscription_id: BigInt(grpcSubscription.id),
        filters: filters.map(hexToBuffer),
    }).response;
}

5e. Export from index.ts

typescript
export type { NewThingView, NewThingPage } from "./types";

Step 6: Run Tests

bash
cd packages/grpc && bun run test

Add new tests for new methods if needed.

Step 7: Lint and Format

bash
cd packages/grpc && bun run lint && bun run format

Step 8: Build Package

bash
cd packages/grpc && bun run build

Step 9: Create Changeset

bash
bun run changeset

Select @dojoengine/grpc and describe the proto updates.

Key Files Reference

File Purpose
packages/grpc/scripts/update-proto.sh Downloads proto from Torii
packages/grpc/scripts/build-proto.sh Generates TypeScript
packages/grpc/proto/*.proto Proto definitions
packages/grpc/src/generated/world.client.ts Generated gRPC client
packages/grpc/src/torii-client.ts SDK client implementation
packages/grpc/src/mappings/query.ts Request mappers
packages/grpc/src/mappings/types.ts Response mappers
packages/grpc/src/types.ts SDK type definitions
packages/grpc/src/index.ts Package exports

Troubleshooting

Proto download fails

Check network connectivity and verify Torii repo URL is correct.

Build fails after proto update

Check for breaking changes in proto definitions. May need to update mappers.

TypeScript errors in generated files

Re-run bun run build:proto to regenerate. Check protobuf-ts version compatibility.

Tests fail

Update tests to match new proto structure. Check mapper implementations.

Didn't find tool you were looking for?

Be as detailed as possible for better results