@latticexyz/network NPM

Network

This package includes general low level utilities to interact with Ethereum contracts, as well as specialized MUD contract/client sync utilities.

The general utilities can be used without MUD. For the specialized but much more powerful utilities, usage of solecs is required and recs is recommended.

See mud.dev/network for the detailed API documentation.

Example

This is a real-world example from an upcoming game built with MUD.

// setupContracts.ts

import {
  createNetwork,
  createContracts,
  Mappings,
  createTxQueue,
  createSyncWorker,
  createEncoder,
  NetworkComponentUpdate,
  createSystemExecutor,
} from "@latticexyz/network";

import { Component as SolecsComponent, World as WorldContract } from "@latticexyz/solecs";
import { abi as WorldAbi } from "@latticexyz/solecs/abi/World.json";
import ComponentAbi from "@latticexyz/solecs/abi/Component.json";

import {
  Component,
  Components,
  EntityIndex,
  getComponentEntities,
  getComponentValueStrict,
  removeComponent,
  Schema,
  setComponent,
  Type,
  World,
} from "@latticexyz/recs";

import { keccak256, stretch, toEthAddress } from "@latticexyz/utils";

import { defineStringComponent } from "@latticexyz/std-client";

import { bufferTime, filter, Observable, Subject } from "rxjs";
import { computed, IComputedValue } from "mobx";
import { Contract, ethers, Signer, Wallet } from "ethers";
import { JsonRpcProvider } from "@ethersproject/providers";

import { SystemTypes } from "<contracts>/types/SystemTypes";
import { SystemAbis } from "<contracts>/types/SystemAbis.mjs";
import { config } from "./config";

export type ContractComponents = {
  [key: string]: Component<Schema, { contractId: string }>;
};

export async function setupContracts<C extends ContractComponents>(world: World, components: C) {
  const SystemsRegistry = defineStringComponent(world, {
    id: "SystemsRegistry",
    metadata: { contractId: "world.component.systems" },
  });

  const ComponentsRegistry = defineStringComponent(world, {
    id: "ComponentsRegistry",
    metadata: { contractId: "world.component.components" },
  });

  components = {
    ...components,
    SystemsRegistry,
    ComponentsRegistry,
  };

  const mappings: Mappings<C> = {};

  for (const key of Object.keys(components)) {
    const { contractId } = components[key].metadata;
    mappings[keccak256(contractId)] = key;
  }

  const network = await createNetwork(config);

  const signerOrProvider = computed(() => network.signer.get() || network.providers.get().json);

  const { contracts, config: contractsConfig } = await createContracts<{ World: WorldContract }>({
    config: { World: { abi: WorldAbi, address: config.worldAddress } },
    signerOrProvider,
  });

  const { txQueue, dispose: disposeTxQueue } = createTxQueue(contracts, network);

  const systems = createSystemExecutor<SystemTypes>(world, network, SystemsRegistry, SystemAbis, {
    devMode: config.devMode,
  });

  const { ecsEvent$, config$, dispose } = createSyncWorker<C>();

  function startSync() {
    config$.next({
      provider: networkConfig.provider,
      worldContract: contractsConfig.World,
      initialBlockNumber: config.initialBlockNumber ?? 0,
      chainId: config.chainId,
      disableCache: false,
      snapshotServiceUrl: networkConfig.snapshotServiceUrl,
      streamServiceUrl: networkConfig.streamServiceUrl,
    });
  }

  const { txReduced$ } = applyNetworkUpdates(world, components, ecsEvent$, mappings);

  const encoders = createEncoders(world, ComponentsRegistry, signerOrProvider);

  return { txQueue, txReduced$, encoders, network, startSync, systems };
}

async function createEncoders(
  world: World,
  components: Component<{ value: Type.String }>,
  signerOrProvider: IComputedValue<JsonRpcProvider | Signer>
) {
  const encoders = {} as Record<string, ReturnType<typeof createEncoder>>;

  async function fetchAndCreateEncoder(entity: EntityIndex) {
    const componentAddress = toEthAddress(world.entities[entity]);
    const componentId = getComponentValueStrict(components, entity).value;
    const componentContract = new Contract(
      componentAddress,
      ComponentAbi.abi,
      signerOrProvider.get()
    ) as SolecsComponent;
    const [componentSchemaPropNames, componentSchemaTypes] = await componentContract.getSchema();
    encoders[componentId] = createEncoder(componentSchemaPropNames, componentSchemaTypes);
  }

  // Initial setup
  for (const entity of getComponentEntities(components)) fetchAndCreateEncoder(entity);

  // Keep up to date
  const subscription = components.update$.subscribe((update) => fetchAndCreateEncoder(update.entity));
  world.registerDisposer(() => subscription?.unsubscribe());

  return encoders;
}

/**
 * Sets up synchronization between contract components and client components
 */
function applyNetworkUpdates<C extends Components>(
  world: World,
  components: C,
  ecsEvent$: Observable<NetworkComponentUpdate<C>>,
  mappings: Mappings<C>
) {
  const txReduced$ = new Subject<string>();

  const ecsEventSub = ecsEvent$.subscribe((update) => {
    const entityIndex = world.entityToIndex.get(update.entity) ?? world.registerEntity({ id: update.entity });
    const componentKey = mappings[update.component];

    if (update.value === undefined) {
      // undefined value means component removed
      removeComponent(components[componentKey] as Component<Schema>, entityIndex);
    } else {
      setComponent(components[componentKey] as Component<Schema>, entityIndex, update.value);
    }

    if (update.lastEventInTx) txReduced$.next(update.txHash);
  });

  return { txReduced$: txReduced$.asObservable() };
}

@everything-registry/sub-chunk-536 @infinitebrahmanuniverse/nolb-_lat

9 months ago

10 months ago

9 months ago

9 months ago

0.0.0-main-20230706101146

10 months ago

11 months ago

11 months ago

9 months ago

9 months ago

9 months ago

10 months ago

9 months ago

9 months ago

0.0.0-main-20230705230250

10 months ago

10 months ago

9 months ago

9 months ago

9 months ago

10 months ago

9 months ago

9 months ago

9 months ago

10 months ago

10 months ago

10 months ago

9 months ago

10 months ago

11 months ago

10 months ago

10 months ago

10 months ago

10 months ago

10 months ago

10 months ago

10 months ago

9 months ago

10 months ago

0.0.0-main-20230713104632

10 months ago

2.0.0-main-753bdce4

9 months ago

2.0.0-indexing-1d07fea9

10 months ago

2.0.0-main-53522998

10 months ago

0.0.0-main-20230704121617

10 months ago

2.0.0-main-83d9589f

9 months ago

0.0.0-main-20230713090002

10 months ago

2.0.0-main-f03531d9

10 months ago

2.0.0-main-d62e76d2

9 months ago

2.0.0-main-78b3b1de

10 months ago

0.0.0-main-20230705095946

10 months ago

9 months ago

10 months ago

9 months ago

10 months ago

9 months ago

2.0.0-indexing-3b1f31fc

10 months ago

9 months ago

9 months ago

10 months ago

9 months ago

10 months ago

10 months ago

9 months ago

9 months ago

10 months ago

9 months ago

2.0.0-indexing-7e4f029f

10 months ago

0.0.0-main-20230705152036

10 months ago

0.0.0-main-20230712164118

10 months ago

9 months ago

9 months ago

9 months ago

10 months ago

9 months ago

10 months ago

0.0.0-main-20230706110436

10 months ago

2.0.0-main-48c51b52

9 months ago

2.0.0-main-6de86f16

10 months ago

2.0.0-main-a7b30c79

10 months ago

2.0.0-indexing-3fee14a7

10 months ago

10 months ago

10 months ago

10 months ago

9 months ago

0.0.0-main-20230713085937

10 months ago

2.0.0-main-e826a6df

9 months ago

2.0.0-main-1af2f495

9 months ago

0.0.0-main-20230706134710

10 months ago

0.0.0-indexing-20230707130424

10 months ago

9 months ago

9 months ago

9 months ago

10 months ago

10 months ago

9 months ago

9 months ago

0.0.0-main-20230705225731

10 months ago

0.0.0-main-20230705224651

10 months ago

9 months ago

9 months ago

10 months ago

10 months ago

0.0.0-main-20230706111131

10 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

0.0.0-main-20230711112802

10 months ago

10 months ago

10 months ago

9 months ago

10 months ago

10 months ago

0.0.0-main-20230712123334

10 months ago

9 months ago

9 months ago

9 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

12 months ago

11 months ago

12 months ago

12 months ago

11 months ago

12 months ago

12 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

12 months ago

11 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

12 months ago

11 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

11 months ago

12 months ago

12 months ago

11 months ago

12 months ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

1 year ago

12 months ago

1 year ago

12 months ago

12 months ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

1 year ago

1 year ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

12 months ago

12 months ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

12 months ago

1 year ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

12 months ago

1 year ago

11 months ago

1 year ago

12 months ago

1 year ago

1 year ago

1 year ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

11 months ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

2 years ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago