golem-base-sdk
    Preparing search index...

    Interface GolemBaseClient

    The GolemBaseClient interface provides both read and write operations for interacting with the Golem Base L2 network.

    This client can perform CRUD operations on entities, manage their BTL (Block-to-Live), and handle transactions on the blockchain.

    This interface extends the GolemBaseROClient interface, inheriting all its read-only methods.

    const client = await createClient(chainId, accountData, rpcUrl, wsUrl);

    // Create entities with annotations
    const receipts = await client.createEntities([
      {
        data: new TextEncoder().encode("Hello, GolemBase!"),
        btl: 1000,
        stringAnnotations: [new Annotation("type", "message")],
        numericAnnotations: []
      }
    ]);
    interface GolemBaseClient {
        createEntities(
            creates: GolemBaseCreate[],
            args?: {
                gas?: bigint;
                maxFeePerGas?: bigint;
                maxPriorityFeePerGas?: bigint;
                txHashCallback?: (txHash: `0x${string}`) => void;
            },
        ): Promise<CreateEntityReceipt[]>;
        deleteEntities(
            deletes: `0x${string}`[],
            args?: {
                gas?: bigint;
                maxFeePerGas?: bigint;
                maxPriorityFeePerGas?: bigint;
                txHashCallback?: (txHash: `0x${string}`) => void;
            },
        ): Promise<DeleteEntityReceipt[]>;
        extendEntities(
            extensions: GolemBaseExtend[],
            args?: {
                gas?: bigint;
                maxFeePerGas?: bigint;
                maxPriorityFeePerGas?: bigint;
                txHashCallback?: (txHash: `0x${string}`) => void;
            },
        ): Promise<ExtendEntityReceipt[]>;
        getAllEntityKeys(): Promise<`0x${string}`[]>;
        getEntitiesOfOwner(address: `0x${string}`): Promise<`0x${string}`[]>;
        getEntitiesToExpireAtBlock(blockNumber: bigint): Promise<`0x${string}`[]>;
        getEntityCount(): Promise<number>;
        getEntityMetaData(key: `0x${string}`): Promise<EntityMetaData>;
        getOwnerAddress(): Promise<`0x${string}`>;
        getRawClient(): internal.GolemBaseClient;
        getStorageValue(key: `0x${string}`): Promise<Uint8Array<ArrayBufferLike>>;
        queryEntities(
            query: string,
        ): Promise<{ entityKey: `0x${string}`; storageValue: Uint8Array }[]>;
        sendTransaction(
            creates?: GolemBaseCreate[],
            updates?: GolemBaseUpdate[],
            deletes?: `0x${string}`[],
            extensions?: GolemBaseExtend[],
            args?: {
                gas?: bigint;
                maxFeePerGas?: bigint;
                maxPriorityFeePerGas?: bigint;
                txHashCallback?: (txHash: `0x${string}`) => void;
            },
        ): Promise<
            {
                createEntitiesReceipts: CreateEntityReceipt[];
                deleteEntitiesReceipts: DeleteEntityReceipt[];
                extendEntitiesReceipts: ExtendEntityReceipt[];
                updateEntitiesReceipts: UpdateEntityReceipt[];
            },
        >;
        updateEntities(
            updates: GolemBaseUpdate[],
            args?: {
                gas?: bigint;
                maxFeePerGas?: bigint;
                maxPriorityFeePerGas?: bigint;
                txHashCallback?: (txHash: `0x${string}`) => void;
            },
        ): Promise<UpdateEntityReceipt[]>;
        watchLogs(
            args: {
                fromBlock: bigint;
                onCreated: (
                    args: { entityKey: `0x${string}`; expirationBlock: number },
                ) => void;
                onDeleted: (args: { entityKey: `0x${string}` }) => void;
                onError?: (error: Error) => void;
                onExtended: (
                    args: {
                        entityKey: `0x${string}`;
                        newExpirationBlock: number;
                        oldExpirationBlock: number;
                    },
                ) => void;
                onUpdated: (
                    args: { entityKey: `0x${string}`; expirationBlock: number },
                ) => void;
                pollingInterval?: number;
                transport?: "http" | "websocket";
            },
        ): () => void;
    }

    Hierarchy

    Index

    Methods

    createEntities deleteEntities extendEntities getAllEntityKeys getEntitiesOfOwner getEntitiesToExpireAtBlock getEntityCount getEntityMetaData getOwnerAddress getRawClient getStorageValue queryEntities sendTransaction updateEntities watchLogs

    Methods

    • Create one or more new entities in GolemBase with specified data and annotations.

      Each entity is stored with a configurable BTL (Block-to-Live) that determines when the entity will automatically expire and be removed from the network.

      Parameters

      • creates: GolemBaseCreate[]

        Array of entity creation specifications

      • Optionalargs: {
            gas?: bigint;
            maxFeePerGas?: bigint;
            maxPriorityFeePerGas?: bigint;
            txHashCallback?: (txHash: `0x${string}`) => void;
        }

        Optional transaction parameters

        • Optionalgas?: bigint

          Manual gas limit override

        • OptionalmaxFeePerGas?: bigint

          Maximum fee per gas unit (EIP-1559)

        • OptionalmaxPriorityFeePerGas?: bigint

          Maximum priority fee per gas unit (EIP-1559)

        • OptionaltxHashCallback?: (txHash: `0x${string}`) => void

          Callback invoked with transaction hash when submitted

      Returns Promise<CreateEntityReceipt[]>

      Promise resolving to an array of creation receipts, each including the new entity key and its expiration block.

      Will throw an error if the transaction fails or any entity creation fails

      const receipts = await client.createEntities([
        {
          data: new TextEncoder().encode(JSON.stringify({ message: "Hello World" })),
          btl: 1000, // Entity expires in 1000 blocks
          stringAnnotations: [
            new Annotation("type", "greeting"),
            new Annotation("version", "1.0")
          ],
          numericAnnotations: [
            new Annotation("priority", 1)
          ]
        }
      ]);

      console.log('Created entity:', receipts[0].entityKey);
      console.log('Expires at block:', receipts[0].expirationBlock);

    • Deletes one or more entities from GolemBase permanently.

      Only the entity owner can delete their entities. Deleted entities cannot be recovered and their storage is immediately freed on the network.

      Parameters

      • deletes: `0x${string}`[]

        Array of hexadecimal entity keys to delete

      • Optionalargs: {
            gas?: bigint;
            maxFeePerGas?: bigint;
            maxPriorityFeePerGas?: bigint;
            txHashCallback?: (txHash: `0x${string}`) => void;
        }

        Optional transaction parameters

        • Optionalgas?: bigint

          Manual gas limit override

        • OptionalmaxFeePerGas?: bigint

          Maximum fee per gas unit (EIP-1559)

        • OptionalmaxPriorityFeePerGas?: bigint

          Maximum priority fee per gas unit (EIP-1559)

        • OptionaltxHashCallback?: (txHash: `0x${string}`) => void

          Callback invoked with transaction hash when submitted

      Returns Promise<DeleteEntityReceipt[]>

      A promise that resolves to an array of DeleteEntityReceipt objects (usually just the deleted keys).

      Will throw an error if the transaction fails, entity doesn't exist, or caller lacks permission

      const receipts = await client.deleteEntities([
        "0x1234567890abcdef...",
        "0xfedcba0987654321..."
      ]);

      receipts.forEach(receipt => {
        console.log('Deleted entity:', receipt.entityKey);
      });

    • Extends the BTL (Block-to-Live) of one or more entities in GolemBase.

      This operation increases the lifetime of entities by adding additional blocks to their expiration time, preventing them from being automatically deleted.

      Parameters

      • extensions: GolemBaseExtend[]

        Array of BTL extension specifications

      • Optionalargs: {
            gas?: bigint;
            maxFeePerGas?: bigint;
            maxPriorityFeePerGas?: bigint;
            txHashCallback?: (txHash: `0x${string}`) => void;
        }

        Optional transaction parameters

        • Optionalgas?: bigint

          Manual gas limit override

        • OptionalmaxFeePerGas?: bigint

          Maximum fee per gas unit (EIP-1559)

        • OptionalmaxPriorityFeePerGas?: bigint

          Maximum priority fee per gas unit (EIP-1559)

        • OptionaltxHashCallback?: (txHash: `0x${string}`) => void

          Callback invoked with transaction hash when submitted

      Returns Promise<ExtendEntityReceipt[]>

      A promise resolving to n array of ExtendEntityReceipt objects, each showing the old and new expiration blocks.

      Will throw an error if the transaction fails, entity doesn't exist, or caller lacks permission

      const receipts = await client.extendEntities([
        {
          entityKey: "0x1234567890abcdef...",
          numberOfBlocks: 500 // Add 500 more blocks to the entity's lifetime
        }
      ]);

      receipts.forEach(receipt => {
        console.log(`Entity ${receipt.entityKey}:`);
        console.log(`  Old expiration: block ${receipt.oldExpirationBlock}`);
        console.log(`  New expiration: block ${receipt.newExpirationBlock}`);
      });

    • Returns all entity keys stored in GolemBase.

      Returns Promise<`0x${string}`[]>

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

    • Retrieves all entity keys owned by a specific Ethereum address.

      Parameters

      • address: `0x${string}`

        The address whose owned entities should be returned.

      Returns Promise<`0x${string}`[]>

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

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

      Parameters

      • blockNumber: bigint

        The block number to check against.

      Returns Promise<`0x${string}`[]>

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

    • Returns the total number of entities stored in GolemBase.

      Returns Promise<number>

      A promise that resolves to the total count of entities.

    • Retrieves metadata for a given entity key.

      Parameters

      • key: `0x${string}`

        The key to retrieve metadata for.

      Returns Promise<EntityMetaData>

      An EntityMetaData object with structured information about the entity.

    • Get the Ethereum address of the owner of the Ethereum account used by this client

      Returns Promise<`0x${string}`>

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

      Will throw an error if the client is not properly configured with account data

      const client = await createClient(chainId, accountData, rpcUrl, wsUrl);
      const address = await client.getOwnerAddress();
      console.log('Account address:', address); // 0x742d35Cc9e1e3FbD...

    • Returns the raw internal client used under the hood. The internal client which exposes low-level methods and also gives access to the raw viem.sh ethereum clients, which allows to call low-level ethereum methods directly

      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 internal.GolemBaseClient

      The internal client object used by the SDK.

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

      Parameters

      • key: `0x${string}`

        The entity key to fetch the data for.

      Returns Promise<Uint8Array<ArrayBufferLike>>

      A Uint8Array containing the base64 encoded value stored in the entity.

    • Queries entities in GolemBase using annotations or metadata filters.

      Parameters

      • query: string

        A query string in the GolemBase filter syntax.

      Returns Promise<{ entityKey: `0x${string}`; storageValue: Uint8Array }[]>

      A promise that resolves to an array of matching entity keys.

    • Send a combined transaction to GolemBase that can include multiple operations: create, update, delete, and extend operations in a single atomic transaction.

      Parameters

      • Optionalcreates: GolemBaseCreate[]

        Array of create operations to include in this transaction

      • Optionalupdates: GolemBaseUpdate[]

        Array of update operations to include in this transaction

      • Optionaldeletes: `0x${string}`[]

        Array of entity keys to delete in this transaction

      • Optionalextensions: GolemBaseExtend[]

        Array of BTL extension operations to include in this transaction

      • Optionalargs: {
            gas?: bigint;
            maxFeePerGas?: bigint;
            maxPriorityFeePerGas?: bigint;
            txHashCallback?: (txHash: `0x${string}`) => void;
        }

        Optional transaction configuration

        • Optionalgas?: bigint

          Manual gas limit override for the transaction

        • OptionalmaxFeePerGas?: bigint

          Maximum fee per gas unit (EIP-1559)

        • OptionalmaxPriorityFeePerGas?: bigint

          Maximum priority fee per gas unit (EIP-1559)

        • OptionaltxHashCallback?: (txHash: `0x${string}`) => void

          Callback function invoked with the transaction hash once submitted

      Returns Promise<
          {
              createEntitiesReceipts: CreateEntityReceipt[];
              deleteEntitiesReceipts: DeleteEntityReceipt[];
              extendEntitiesReceipts: ExtendEntityReceipt[];
              updateEntitiesReceipts: UpdateEntityReceipt[];
          },
      >

      A promise that resolves to an object with arrays of receipts for each type of operation.

      Will throw an error if the transaction fails or is reverted

      const result = await client.sendTransaction(
        [{ data: new TextEncoder().encode("create"), btl: 1000, stringAnnotations: [], numericAnnotations: [] }],
        [{ entityKey: "0x123...", data: new TextEncoder().encode("update"), btl: 2000, stringAnnotations: [], numericAnnotations: [] }],
        ["0x456..."],
        [{ entityKey: "0x789...", numberOfBlocks: 500 }],
        { txHashCallback: (hash) => console.log('TX Hash:', hash) }
      );

    • Update one or more existing entities in GolemBase with new data and annotations.

      Updates replace the entire entity content, including data and annotations. The BTL can also be modified to extend or reduce the entity's lifetime.

      Parameters

      • updates: GolemBaseUpdate[]

        Array of entity update specifications containing entity keys and new data

      • Optionalargs: {
            gas?: bigint;
            maxFeePerGas?: bigint;
            maxPriorityFeePerGas?: bigint;
            txHashCallback?: (txHash: `0x${string}`) => void;
        }

        Optional transaction parameters

        • Optionalgas?: bigint

          Manual gas limit override

        • OptionalmaxFeePerGas?: bigint

          Maximum fee per gas unit (EIP-1559)

        • OptionalmaxPriorityFeePerGas?: bigint

          Maximum priority fee per gas unit (EIP-1559)

        • OptionaltxHashCallback?: (txHash: `0x${string}`) => void

          Callback invoked with transaction hash when submitted

      Returns Promise<UpdateEntityReceipt[]>

      A promise that resolves to an array of UpdateEntityReceipt objects, each including the entity key and its new expiration block.

      Will throw an error if the transaction fails, entity doesn't exist, or caller lacks permission

      const receipts = await client.updateEntities([
        {
          entityKey: "0x1234567890abcdef...",
          data: new TextEncoder().encode(JSON.stringify({ message: "Updated content" })),
          btl: 2000, // Extend lifetime to 2000 blocks
          stringAnnotations: [new Annotation("status", "updated")],
          numericAnnotations: []
        }
      ]);

    • Install callbacks that will be invoked for every GolemBase transaction

      Parameters

      • args: {
            fromBlock: bigint;
            onCreated: (
                args: { entityKey: `0x${string}`; expirationBlock: number },
            ) => void;
            onDeleted: (args: { entityKey: `0x${string}` }) => void;
            onError?: (error: Error) => void;
            onExtended: (
                args: {
                    entityKey: `0x${string}`;
                    newExpirationBlock: number;
                    oldExpirationBlock: number;
                },
            ) => void;
            onUpdated: (
                args: { entityKey: `0x${string}`; expirationBlock: number },
            ) => void;
            pollingInterval?: number;
            transport?: "http" | "websocket";
        }
        • fromBlock: bigint

          The starting block, events trigger the callbacks starting from this block

        • onCreated: (args: { entityKey: `0x${string}`; expirationBlock: number }) => void

          A callback that's invoked whenever entities are created

        • onDeleted: (args: { entityKey: `0x${string}` }) => void

          A callback that's invoked whenever entities are deleted

        • OptionalonError?: (error: Error) => void

          A callback that's invoked whenever there is an error during the processing

        • onExtended: (
              args: {
                  entityKey: `0x${string}`;
                  newExpirationBlock: number;
                  oldExpirationBlock: number;
              },
          ) => void

          A callback that's invoked whenever entities have their BTL extended

        • onUpdated: (args: { entityKey: `0x${string}`; expirationBlock: number }) => void

          A callback that's invoked whenever entitier are updated

        • OptionalpollingInterval?: number

          In that case of HTTP transport, the polling interval in milliseconds. Defaults to the default polling interval of viem

        • Optionaltransport?: "http" | "websocket"

          The transport to use, either HTTP or WebSocket (the default)

      Returns () => void

      a callback to cancel the subscription and stop receiving notifications

    Settings

    Member Visibility

    On This Page

    Methods