Skip to content

Overview

Using our TypeScript SDK, you can create, modify, and delete entities on a golem-base op-geth node all from a python application.

This SDK provides two client interfaces for interacting with a golem-base op-geth node:

  • GolemBaseROClient: Read-only access.
  • GolemBaseClient: Full read-write access.

Use the provided factory functions to create client instances:

  • createROClient: creates a read-only client that implements GolemBaseROClient.
  • createClient: creates a read-write client that implements GolemBaseClient.

Internal Note: The SDK uses internal classes behind the scenes to implement these interfaces. These are not exposed publicly and may change at any time. Use only the exported interfaces and factory functions.

createClient (function)

createClient(chainId, accountData, rpcUrl, wsUrl, logger?): Promise<GolemBaseClient>

Creates a read-write client for a golem-base op-geth node. This client supports all available operations, including writing new entities and fetching metadata.

Parameters

  • chainId (number): The numeric chain ID of the Ethereum-compatible network you're connecting to.

  • accountData (AccountData): An object containing private key or account credentials for signing transactions.

  • rpcUrl (string): The HTTP endpoint of the golem-base op-geth node.

  • wsUrl (string): The WebSocket endpoint of the same node, used for event listening or subscriptions.

  • logger (optional) (Logger): A pino-like logger instance for structured logs. Defaults to a minimal hidden logger if not provided.

Returns

A Promise that resolves to a GolemBaseClient instance.

Example

coming soon

createROClient (function)

createROClient(chainId, rpcUrl, wsUrl, logger?): GolemBaseROClient

Creates a read-only client for querying a golem-base op-geth node. This client can fetch metadata, search for keys, and inspect the current state, but cannot write to the blockchain.

Parameters

  • chainId (number): The chain ID of the Ethereum-compatible network.

  • rpcUrl (string): The HTTP endpoint for RPC requests.

  • wsUrl (string): The WebSocket endpoint for listening to events.

  • logger (optional) (Logger): A logger instance. Defaults to a silent logger if omitted.

Returns

An instance of GolemBaseROClient.

Example

coming soon

GolemBaseROClient (Interface)

The GolemBaseROClient interface provides read-only access to a golem-base op-geth node. It allows you to query entities, fetch metadata, subscribe to events, and interact with annotations without modifying the blockchain state.

Methods

getRawClient

getRawClient(): Internal

Returns the raw internal client used under the hood. This includes low-level Ethereum client access (via viem.sh).

This is considered an advanced feature. Use with caution if you need to make low-level Ethereum calls directly.

Returns:

The internal client object used by the SDK.

getEntityCount

getEntityCount(): Promise<number>

Fetches the total number of entities stored in GolemBase.

Returns: A promise that resolves to the total count of entities.

Example:

getAllEntityKeys

getAllEntityKeys(): Promise<Hex[]>

Retrieves all entity keys stored in GolemBase.

Returns: A promise that resolves to an array of entity keys (Hex[]).

getEntitiesOfOwner

getEntitiesOfOwner(address: Hex): Promise<Hex[]>

Retrieves all entity keys owned by a specific Ethereum address.

Parameters:

  • address (Hex): The address whose owned entities should be returned.

Returns:

A promise that resolves to an array of entity keys owned by the address.

getStorageValue

getStorageValue(key: Hex): Promise<Uint8Array>

Fetches the raw base64-encoded storage value associated with a given entity key.

Parameters:

  • key (Hex): The entity key to fetch the data for.

Returns:

A Uint8Array containing the binary value stored in the entity.

queryEntities

queryEntities(query: string): Promise<{ entityKey: Hex, storageValue: Uint8Array }[]>

Queries entities in GolemBase using annotations or metadata filters.

Parameters:

  • query (string): A query string in the GolemBase filter syntax.

Returns:

A promise that resolves to an array of matching entity key + value pairs.

getEntitiesToExpireAtBlock

getEntitiesToExpireAtBlock(blockNumber: bigint): Promise<Hex[]>

Finds all entities that are scheduled to expire at a specific block.

Parameters:

  • blockNumber (bigint): The block number to check against.

Returns:

A promise that resolves to an array of entity keys expiring at the given block.

getEntityMetaData

getEntityMetaData(key: Hex): Promise<EntityMetaData>

Retrieves metadata for a given entity key.

Parameters:

  • key (Hex): The key to retrieve metadata for.

Returns:

An EntityMetaData object with structured information about the entity.

watchLogs

watchLogs(args: {...}): () => void

Subscribes to real-time logs for changes to GolemBase entities.

Parameters:

  • fromBlock (bigint): Block to start watching from.

  • onCreated (function): Called when a new entity is created.

  • onUpdated (function): Called when an entity is updated.

  • onExtended (function): Called when an entity's BTL is extended.

  • onDeleted (function): Called when an entity is deleted.

  • onError? (function): Optional error callback.

  • pollingInterval? (number): Optional polling interval (used with HTTP transport).

  • transport? ("http" | "websocket"): Transport type; defaults to WebSocket.

Returns:

A function that you can call to unsubscribe from the log stream.

Example:

Notes

This interface is returned by createROClient() and used as the base for GolemBaseClient.

All methods are read-only. To write data, use createClient() and the extended GolemBaseClient.

GolemBaseClient (Client Interface)

The GolemBaseClient interface provides read-write access to a golem-base op-geth node. It allows you to query entities, fetch metadata, subscribe to events, and interact with annotations as well as create, update, delete, and extend entities.

Methods

createEntities

createEntities(creates, args?)

Creates one or more new entities on the node.

Parameters:

  • creates (GolemBaseCreate[]): Entities to create.

  • args? (optional): Same structure as sendTransaction.

Returns:

An array of CreateEntityReceipt objects, each including the new entity key and its expiration block.

updateEntities

updateEntities(updates, args?)

Updates one or more existing entities.

Parameters:

  • updates (GolemBaseUpdate[]): Entities to update.

  • args? (optional): Same structure as sendTransaction.

Returns:

An array of UpdateEntityReceipt objects, with updated entity keys and new expiration blocks.

deleteEntities

deleteEntities(deletes, args?)

Deletes one or more entities from the node.

Parameters:

  • deletes (Hex[]): Entity keys to delete.

  • args? (optional): Same structure as sendTransaction.

Tip: Hex is a specialized type based on string; you can generally simply pass a string in for this parameter.

Returns:

An array of DeleteEntityReceipt objects (usually just the deleted keys).

extendEntities

extendEntities(extensions, args?)

Extends the BTL (Block-To-Live) of one or more entities.

Parameters:

  • extensions (GolemBaseExtend[]): Entities and new expiration data.

  • args? (optional): Same structure as sendTransaction.

Returns:

An array of ExtendEntityReceipt objects, each showing the old and new expiration blocks.

getOwnerAddress

getOwnerAddress(): Promise<Hex>

Retrieves the Ethereum address of the account this client is authenticated with.

Returns:

A promise that resolves to the address as a Hex string.

Example:

sendTransaction

sendTransaction(...)

Submits a single transaction that may contain any combination of creates, updates, deletes, or extensions.

Parameters:

  • creates? (GolemBaseCreate[]): New entities to create.

  • updates? (GolemBaseUpdate[]): Entities to update.

  • deletes? (Hex[]): Keys of entities to delete.

  • extensions? (GolemBaseExtend[]): Entities to extend BTL for.

  • args?: optional config object:

  • txHashCallback? ((txHash: Hex) => void): Called with the transaction hash.

  • gas? (bigint): Override gas limit.

  • maxFeePerGas? / maxPriorityFeePerGas? (bigint): Manually specify gas pricing.

Returns:

An object with arrays of receipts:

{
  createEntitiesReceipts: CreateEntityReceipt[],
  updateEntitiesReceipts: UpdateEntityReceipt[],
  deleteEntitiesReceipts: DeleteEntityReceipt[],
  extendEntitiesReceipts: ExtendEntityReceipt[],
}

Example:

getRawClient

getRawClient(): Internal

Returns the raw internal client used under the hood. This includes low-level Ethereum client access (via viem.sh).

This is considered an advanced feature. Use with caution if you need to make low-level Ethereum calls directly.

Returns:

The internal client object used by the SDK.

getEntityCount

getEntityCount(): Promise<number>

Fetches the total number of entities stored in GolemBase.

Returns: A promise that resolves to the total count of entities.

getAllEntityKeys

getAllEntityKeys(): Promise<Hex[]>

Retrieves all entity keys stored in GolemBase.

Returns: A promise that resolves to an array of entity keys (Hex[]).

getEntitiesOfOwner

getEntitiesOfOwner(address: Hex): Promise<Hex[]>

Retrieves all entity keys owned by a specific Ethereum address.

Parameters:

  • address (Hex): The address whose owned entities should be returned.

Returns:

A promise that resolves to an array of entity keys owned by the address.

getStorageValue

getStorageValue(key: Hex): Promise<Uint8Array>

Fetches the raw base64-encoded storage value associated with a given entity key.

Parameters:

  • key (Hex): The entity key to fetch the data for.

Returns:

A Uint8Array containing the binary value stored in the entity.

queryEntities

queryEntities(query: string): Promise<{ entityKey: Hex, storageValue: Uint8Array }[]>

Queries entities in GolemBase using annotations or metadata filters.

Parameters:

  • query (string): A query string in the GolemBase filter syntax.

Returns:

A promise that resolves to an array of matching entity key + value pairs.

getEntitiesToExpireAtBlock

getEntitiesToExpireAtBlock(blockNumber: bigint): Promise<Hex[]>

Finds all entities that are scheduled to expire at a specific block.

Parameters:

  • blockNumber (bigint): The block number to check against.

Returns:

A promise that resolves to an array of entity keys expiring at the given block.

getEntityMetaData

getEntityMetaData(key: Hex): Promise<EntityMetaData>

Retrieves metadata for a given entity key.

Parameters:

  • key (Hex): The key to retrieve metadata for.

Returns:

An EntityMetaData object with structured information about the entity.

watchLogs

watchLogs(args: {...}): () => void

Subscribes to real-time logs for changes to GolemBase entities.

Parameters:

  • fromBlock (bigint): Block to start watching from.

  • onCreated (function): Called when a new entity is created.

  • onUpdated (function): Called when an entity is updated.

  • onExtended (function): Called when an entity's BTL is extended.

  • onDeleted (function): Called when an entity is deleted.

  • onError? (function): Optional error callback.

  • pollingInterval? (number): Optional polling interval (used with HTTP transport).

  • transport? ("http" | "websocket"): Transport type; defaults to WebSocket.

Returns:

A function that you can call to unsubscribe from the log stream.