Geo SDK

A collection of tools for interacting with The Graph.

Installing

npm install @geoprotocol/geo-sdk

AI Harnesses

If you're using an AI coding assistant (e.g. Claude Code, Codex, Cursor) to work with this SDK, check out geobrowser/geo-skills for skills and prompts that help agents use the Geo SDK effectively.

Overview

Data Flow

Data in The Graph lives both offchain and onchain. This data is written to IPFS, and the resulting content identifier is then posted onchain before being read by the indexing stack. After the indexer finishes processing the data it's exposed by the API.

Spaces

On The Graph, knowledge is organized into spaces. Anyone can create a space for a community, project or individual. Spaces are organized onchain into a set of smart contracts. These contracts represent the space itself, its data and its governance process.

Entities

An entity is a unique identifier representing a person, a place, an idea, a concept, or anything else. Entities are composed from triples and relations that describe what the entity is. An entity's data can be composed from multiple spaces at once. This property is what enables pluralism within The Graph.

More about entities and knowledge graphs

Relations

Relations describe the edges within the graph. Relations are themselves entities that include details about the relationship. For example, a Company can have Team Members. Each Team Member relation can have an attribute describing when the person joined the team. This is a property graph model.

Ops And Edits

Data in The Graph is stored as an Op (operation). Ops represent a set of changes applied to entities. A change could be setting or deleting a triple or a relation. Both triples and relations are represented as Ops.

When writing data, these ops are grouped into a logical set called an edit. An edit has a name, authors, and metadata to represent the set of changes. This edit is encoded into a binary representation before being uploaded to IPFS.

Ops and edits in GRC-20

Using

The preferred API has two parts:

Ops builds GRC-20 operations.
createGeoClient(...) handles configured workflows such as API calls, uploads, RPC reads, and transaction calldata.

import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });

const { id: entityId, ops } = Ops.entities.create({
  name: "Test Entity",
  description: "Created with the new API",
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

await walletClient.sendTransaction({ to: tx.to, data: tx.calldata });

Imports

Use the root package when convenience matters:

import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";

Subpath exports are available for bundle-sensitive code

import { entities, relations } from "@geoprotocol/geo-sdk/ops";
import { createGeoClient } from "@geoprotocol/geo-sdk/client";
import {
  GeoTestnetConfig,
  defineGeoNetworkConfig,
} from "@geoprotocol/geo-sdk/networks";

Use Ops from @geoprotocol/geo-sdk for op builders. Configured workflows live behind createGeoClient.

Network Configuration

Use the built-in testnet config:

import { GeoTestnetConfig, createGeoClient } from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });

console.log(geo.network.id); // "TESTNET"

network is required, and the client expects the full config object. Pass GeoTestnetConfig, not the string "TESTNET".

Define a custom deployment:

import { createGeoClient, defineGeoNetworkConfig } from "@geoprotocol/geo-sdk";

const local = defineGeoNetworkConfig({
  id: "LOCAL",
  name: "Local Geo",
  apiOrigin: "http://localhost:3000",
  chain: {
    id: 31337,
    name: "Anvil",
    rpcUrl: "http://localhost:8545",
  },
  contracts: {
    SPACE_REGISTRY_ADDRESS: "0x0000000000000000000000000000000000000001",
    DAO_SPACE_FACTORY_ADDRESS: "0x0000000000000000000000000000000000000002",
  },
});

const geo = createGeoClient({ network: local });

Pass a fetch implementation when your runtime does not provide globalThis.fetch, or when you want test isolation:

const geo = createGeoClient({
  network: GeoTestnetConfig,
  fetch: customFetch,
});

Local Contracts V2 Validation

When working against the local-geobrowser contracts checkout, deploy that stack first so it writes .deployments.json, then point the SDK opt-in test at it:

cd /path/to/local-geobrowser
just init-infra
just init-contract

cd /path/to/geo-sdk
GEO_LOCAL_GEOBROWSER_DEPLOYMENTS=/path/to/local-geobrowser/.deployments.json \
  pnpm exec vitest run src/contracts-v2/local-geobrowser.e2e.test.ts

The test builds a custom defineGeoNetworkConfig(...) from the deployment file and decodes DAO creation, update-voting-settings proposal, and versioned vote calldata against the contracts v2 ABIs.

Ops API

Ops functions build operation arrays that can be combined before publishing.

import type { Op } from "@geoprotocol/geo-sdk";

const ops: Op[] = [];
ops.push(...entityOps);
ops.push(...relationOps);

Properties, Types, And Entities

Create a property, a type, and an entity:

import { Ops } from "@geoprotocol/geo-sdk";

const { id: websitePropertyId, ops: propertyOps } = Ops.properties.create({
  name: "Website",
  dataType: "TEXT",
});

const { id: restaurantTypeId, ops: typeOps } = Ops.types.create({
  name: "Restaurant",
  properties: [websitePropertyId],
});

const { id: restaurantId, ops: entityOps } = Ops.entities.create({
  name: "Yum Yum",
  description: "A restaurant serving fusion cuisine",
  types: [restaurantTypeId],
  values: [
    {
      property: websitePropertyId,
      type: "text",
      value: "https://example.com",
    },
  ],
});

const ops = [...propertyOps, ...typeOps, ...entityOps];

Update an entity:

const { ops } = Ops.entities.update({
  id: restaurantId,
  name: "Yum Yum Kitchen",
  values: [
    {
      property: websitePropertyId,
      type: "text",
      value: "https://yum.example",
    },
  ],
});

Unset property values:

const { ops } = Ops.entities.update({
  id: restaurantId,
  unset: [
    { property: websitePropertyId },
    { property: descriptionPropertyId, language: "all" },
  ],
});

Create relation properties:

const { id: likesPropertyId, ops } = Ops.properties.create({
  name: "Likes",
  dataType: "RELATION",
  relationValueTypes: [restaurantTypeId],
});

Typed Values

Entity values are typed objects. The type field determines the value shape:

import { Ops } from "@geoprotocol/geo-sdk";

const { ops } = Ops.entities.create({
  name: "Cafe visit",
  values: [
    { property: namePropertyId, type: "text", value: "Morning Coffee" },
    { property: openPropertyId, type: "boolean", value: true },
    { property: visitsPropertyId, type: "integer", value: 42 },
    { property: ratingPropertyId, type: "float", value: 4.8 },
    { property: openedDatePropertyId, type: "date", value: "2024-01-15" },
    { property: opensAtPropertyId, type: "time", value: "08:30:00Z" },
    {
      property: reviewedAtPropertyId,
      type: "datetime",
      value: "2024-01-15T14:30:00Z",
    },
    {
      property: schedulePropertyId,
      type: "schedule",
      value: "FREQ=WEEKLY;BYDAY=MO,WE,FR",
    },
    {
      property: locationPropertyId,
      type: "point",
      lon: -122.4194,
      lat: 37.7749,
    },
    {
      property: bytesPropertyId,
      type: "bytes",
      value: new Uint8Array([1, 2, 3]),
    },
  ],
});

Relations

Create, update, and delete relation entities:

import { Ops, Position } from "@geoprotocol/geo-sdk";

const { id: relationId, ops: createRelationOps } = Ops.relations.create({
  fromEntity: personId,
  toEntity: restaurantId,
  type: likesPropertyId,
  position: Position.generate(),
});

const { ops: updateRelationOps } = Ops.relations.update({
  id: relationId,
  position: Position.generateBetween(previousPosition, nextPosition),
});

const { ops: deleteRelationOps } = Ops.relations.delete({
  id: relationId,
});

Relations can also carry their own entity values:

const { ops } = Ops.relations.create({
  fromEntity: personId,
  toEntity: companyId,
  type: teamMemberPropertyId,
  entityName: "Team member",
  entityValues: [
    {
      property: joinedDatePropertyId,
      type: "date",
      value: "2024-05-01",
    },
  ],
});

Images

Image creation goes through geo.images.create(...). The configured client uploads the image, detects dimensions when possible, and returns the image entity ops.

Comments

Create a comment on an entity:

import { Ops } from "@geoprotocol/geo-sdk";

const { id: commentId, ops } = Ops.comments.create({
  content: "Looks good to me.",
  replyTo: {
    entityId,
    spaceId,
  },
});

Create a nested comment when you already have reply-chain context:

const { ops } = Ops.comments.create({
  content: "Replying to the parent comment.",
  replyTo: {
    entityId: parentCommentId,
    spaceId,
  },
  replyToRelations: [
    {
      entityId: rootEntityId,
      spaceId,
      position: "a0",
    },
  ],
});

Update a comment:

const { ops } = Ops.comments.update({
  id: commentId,
  content: "Updated comment text.",
  resolved: true,
});

Use geo.comments.create(...) when reply-chain context should be fetched from the configured API.

Proposal Reviews

Create and update proposal review ops:

import { Ops } from "@geoprotocol/geo-sdk";

const { id: reviewId, ops: createReviewOps } = Ops.proposalReviews.create({
  proposal: {
    id: proposalId,
    name: "Improve restaurant data",
  },
  pass: true,
  content: "The proposal is complete and accurate.",
  completeness: 1,
  accuracy: 0.8,
  skill: 0.8,
  effort: 0.6,
});

const { ops: updateReviewOps } = Ops.proposalReviews.update({
  proposalReviewId: reviewId,
  pass: false,
  content: "Needs more sources.",
});

Client API

Create a configured client once and use it for workflows that need API origins, uploads, RPC URLs, or contract addresses.

import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });

`geo.api`

Use geo.api.graphql(...) for low-level GraphQL requests:

const response = await geo.api.graphql<{
  entity: { id: string; name: string | null } | null;
}>(`
  query {
    entity(id: "3af3e22d21694a078681516710b7ecf1") {
      id
      name
    }
  }
`);

if (response.errors) {
  console.error(response.errors);
}

Use geo.api.getEditCalldata(...) when calldata must come from the API:

const { to, data } = await geo.api.getEditCalldata({
  spaceId,
  cid: "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
});

await walletClient.sendTransaction({ to, data });

For personal-space edits, prefer geo.personalSpaces.publishEdit(...).

`geo.images`

Upload an image and build image entity ops in one call:

const imageFromUrl = await geo.images.create({
  url: "https://example.com/cover.png",
  name: "Cover image",
  description: "Image used as the space cover.",
});

console.log(imageFromUrl.id);
console.log(imageFromUrl.cid);
console.log(imageFromUrl.ops);

You can also pass a Blob directly:

const file = new Blob([imageBytes], { type: "image/png" });

const imageFromBlob = await geo.images.create({
  blob: file,
  name: "Cover image",
});

console.log(imageFromBlob.cid);

`geo.storage`

Use geo.images.create(...) when you want to upload an image and create image entity ops in one call. Use geo.storage.uploadImage(...) only when you need the raw uploaded CID and detected dimensions without graph ops:

const uploaded = await geo.storage.uploadImage({
  url: "https://example.com/photo.png",
});

console.log(uploaded.cid);
console.log(uploaded.dimensions);

Upload CSV content:

const cid = await geo.storage.uploadCSV(`name,score
Alice,10
Bob,8`);

`geo.entities`

Delete an entity from a space:

const { ops } = await geo.entities.delete({
  id: entityId,
  spaceId,
});

Entity deletion queries the configured API for current values and relations in the target space, then builds ops to unset those values and delete those relations. The entity transitions to an empty state in that space; it is not globally destroyed.

`geo.comments`

Create a comment while preserving reply-to chains:

const comment = await geo.comments.create({
  content: "This should be easier to find.",
  replyTo: {
    entityId,
    spaceId,
  },
});

Reply to another comment:

const reply = await geo.comments.create({
  content: "Following up here.",
  replyTo: {
    entityId: comment.id,
    spaceId,
  },
});

Update a comment:

const { ops } = geo.comments.update({
  id: comment.id,
  content: "Updated comment text.",
  resolved: true,
});

`geo.personalSpaces`

Check whether an address already has a personal space:

const hasExistingSpace = await geo.personalSpaces.hasSpace({
  address: account.address,
});

Create a personal space:

const createSpace = geo.personalSpaces.create({
  name: "Alice",
  accountAddress: account.address,
});

await walletClient.sendTransaction({
  to: createSpace.to,
  data: createSpace.calldata,
});

geo.personalSpaces.create(...) also returns initial profile ops. After the create-space transaction is mined and you know the new spaceId, publish those ops into the space and immediately set the generated space entity as the space topic:

const profileTx = await geo.personalSpaces.publishEdit({
  name: "Create personal space profile",
  spaceId,
  author: spaceId,
  ops: createSpace.ops,
});

await walletClient.sendTransaction({
  to: profileTx.to,
  data: profileTx.calldata,
});

const topicTx = geo.personalSpaces.setTopic({
  spaceId,
  topicId: createSpace.spaceEntityId,
});

await walletClient.sendTransaction({
  to: topicTx.to,
  data: topicTx.calldata,
});

Publish any edit to a personal space:

const { ops } = Ops.entities.create({
  name: "Test Entity",
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

await walletClient.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});

The author field is the author's personal space ID, not a wallet address.

`geo.daoSpaces`

DAO helpers target the contracts v2 surface. Voting settings use percentages and second-level voting durations on the SDK side; the SDK maps percentages to ratio-base integers for the contract. Use a network config whose DAO contract addresses point at a contracts v2 deployment.

const votingSettings = {
  partialPercentageSupportThreshold: 50,
  universalPercentageSupportThreshold: 90,
  flatSupportThreshold: 1,
  quorum: 1,
  durationInSeconds: 2 * 24 * 60 * 60,
  disableFastPathAccessForNewMembers: true,
  executionGracePeriodInDays: 14,
};

Create a DAO space:

const tx = await geo.daoSpaces.create({
  name: "Research DAO",
  author: authorSpaceId,
  initialEditorSpaceIds: [authorSpaceId],
  initialMemberSpaceIds: [authorSpaceId],
  votingSettings,
});

await walletClient.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});

Include extra initial ops in the DAO creation edit:

const { ops } = Ops.entities.create({
  name: "DAO Welcome Page",
});

const tx = await geo.daoSpaces.create({
  name: "Research DAO",
  author: authorSpaceId,
  initialEditorSpaceIds: [authorSpaceId],
  votingSettings,
  ops,
});

Propose an edit to a DAO space:

const { ops } = Ops.entities.update({
  id: entityId,
  name: "Updated entity name",
});

const proposal = await geo.daoSpaces.proposeEdit({
  name: "Update entity name",
  ops,
  author: authorSpaceId,
  daoSpaceAddress,
  callerSpaceId: authorSpaceId,
  daoSpaceId,
  votingMode: "FAST",
});

await walletClient.sendTransaction({
  to: proposal.to,
  data: proposal.calldata,
});

Create a new version of an existing edit proposal:

const updatedProposal = await geo.daoSpaces.proposeEdit({
  name: "Update entity name, revision 2",
  ops,
  author: authorSpaceId,
  daoSpaceAddress,
  callerSpaceId: authorSpaceId,
  daoSpaceId,
  proposalId,
  updateProposal: true,
  versionId: 2,
});

If updateProposal: true is set and versionId is omitted, the SDK reads latestProposalVersion(...) from the configured network RPC before uploading the edit. Pass versionId when you already know the next version or when your custom network config has no RPC URL.

Manage DAO members and editors:

const addMember = geo.daoSpaces.proposeAddMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  newMemberSpaceId: memberSpaceId,
  votingMode: "FAST",
});

const removeMember = geo.daoSpaces.proposeRemoveMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  memberToRemoveSpaceId: memberSpaceId,
});

const addEditor = geo.daoSpaces.proposeAddEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  newEditorSpaceId: editorSpaceId,
});

const removeEditor = geo.daoSpaces.proposeRemoveEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  editorToRemoveSpaceId: editorSpaceId,
});

Editor changes only support SLOW voting. Member changes can use the default or an explicit votingMode.

Propose voting-settings changes:

const updateVoting = geo.daoSpaces.proposeUpdateVotingSettings({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  votingSettings: {
    partialPercentageSupportThreshold: 60,
    universalPercentageSupportThreshold: 95,
    flatSupportThreshold: 2,
    quorum: 2,
    durationInSeconds: 5 * 24 * 60 * 60,
    disableFastPathAccessForNewMembers: true,
    executionGracePeriodInDays: 14,
  },
});

Updating voting settings only supports SLOW voting.

Request membership in a DAO space:

const request = geo.daoSpaces.proposeRequestMembership({
  authorSpaceId: requesterSpaceId,
  spaceId: daoSpaceId,
});

await walletClient.sendTransaction({
  to: request.to,
  data: request.calldata,
});

DAO proposal IDs and DAO space IDs are bytes16 hex strings, usually 0x plus 32 hex characters.

Vote on a proposal:

const vote = geo.daoSpaces.voteProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
  versionId: 1,
  vote: "YES",
});

await walletClient.sendTransaction({
  to: vote.to,
  data: vote.calldata,
});

versionId defaults to 1. Pass it explicitly when voting on a later proposal version.

Execute a passed proposal:

const execute = geo.daoSpaces.executeProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
});

await walletClient.sendTransaction({
  to: execute.to,
  data: execute.calldata,
});

`geo.entityVotes`

Upvote, downvote, or withdraw a vote on an entity:

const upvote = geo.entityVotes.upvote({
  authorSpaceId,
  spaceId,
  entityId,
});

const downvote = geo.entityVotes.downvote({
  authorSpaceId,
  spaceId,
  entityId,
});

const withdraw = geo.entityVotes.withdraw({
  authorSpaceId,
  spaceId,
  entityId,
});

Submit any returned transaction with your wallet client:

await walletClient.sendTransaction({
  to: upvote.to,
  data: upvote.calldata,
});

Full Publishing Flow With A Smart Account

This example publishes an edit to an existing personal space using a Geo smart account.

import { createPublicClient, http, type Hex } from "viem";
import {
  GeoTestnetConfig,
  Ops,
  createGeoClient,
  getSmartAccountWalletClient,
} from "@geoprotocol/geo-sdk";
import { SpaceRegistryAbi } from "@geoprotocol/geo-sdk/abis";

const privateKey = `0x${privateKeyFromGeoWallet}` as `0x${string}`;
const geo = createGeoClient({ network: GeoTestnetConfig });
const smartAccount = await getSmartAccountWalletClient({ privateKey });
const accountAddress = smartAccount.account.address;

const hasSpace = await geo.personalSpaces.hasSpace({
  address: accountAddress,
});

if (!hasSpace) {
  throw new Error("No personal space found for this account.");
}

const spaceRegistryAddress = GeoTestnetConfig.contracts?.SPACE_REGISTRY_ADDRESS;
const rpcUrl = GeoTestnetConfig.chain?.rpcUrl;
if (!spaceRegistryAddress || !rpcUrl) {
  throw new Error("GeoTestnetConfig is missing registry or RPC configuration.");
}

const publicClient = createPublicClient({
  transport: http(rpcUrl),
});

const spaceIdHex = (await publicClient.readContract({
  address: spaceRegistryAddress,
  abi: SpaceRegistryAbi,
  functionName: "addressToSpaceId",
  args: [accountAddress],
})) as Hex;

const spaceId = spaceIdHex.slice(2, 34).toLowerCase();

const { id: entityId, ops } = Ops.entities.create({
  name: "Test Entity",
  description: "Created via Geo SDK",
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

const txHash = await smartAccount.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});

await publicClient.waitForTransactionReceipt({ hash: txHash });
console.log("Published entity", entityId, "to space", spaceId);

Full Personal Space Creation Flow

This example creates a personal space with an EOA wallet and then publishes the initial profile ops returned by geo.personalSpaces.create(...).

import { createPublicClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import {
  GeoTestnetConfig,
  createGeoClient,
  getWalletClient,
} from "@geoprotocol/geo-sdk";
import { SpaceRegistryAbi } from "@geoprotocol/geo-sdk/abis";

const privateKey = "0xTODO" as `0x${string}`;
const account = privateKeyToAccount(privateKey);
const geo = createGeoClient({ network: GeoTestnetConfig });

const walletClient = await getWalletClient({
  privateKey,
});

const rpcUrl = GeoTestnetConfig.chain?.rpcUrl;
const spaceRegistryAddress = GeoTestnetConfig.contracts?.SPACE_REGISTRY_ADDRESS;
if (!rpcUrl || !spaceRegistryAddress) {
  throw new Error("GeoTestnetConfig is missing registry or RPC configuration.");
}

const publicClient = createPublicClient({
  transport: http(rpcUrl),
});

const hasSpace = await geo.personalSpaces.hasSpace({
  address: account.address,
});

let spaceIdHex = (await publicClient.readContract({
  address: spaceRegistryAddress,
  abi: SpaceRegistryAbi,
  functionName: "addressToSpaceId",
  args: [account.address],
})) as Hex;

if (!hasSpace) {
  const createSpace = geo.personalSpaces.create({
    name: "Alice",
    accountAddress: account.address,
  });

  const createSpaceHash = await walletClient.sendTransaction({
    account: walletClient.account,
    to: createSpace.to,
    data: createSpace.calldata,
  });

  await publicClient.waitForTransactionReceipt({ hash: createSpaceHash });

  spaceIdHex = (await publicClient.readContract({
    address: spaceRegistryAddress,
    abi: SpaceRegistryAbi,
    functionName: "addressToSpaceId",
    args: [account.address],
  })) as Hex;

  const spaceId = spaceIdHex.slice(2, 34).toLowerCase();
  const profileTx = await geo.personalSpaces.publishEdit({
    name: "Create personal space profile",
    spaceId,
    author: spaceId,
    ops: createSpace.ops,
  });

  const profileHash = await walletClient.sendTransaction({
    account: walletClient.account,
    to: profileTx.to,
    data: profileTx.calldata,
  });

  await publicClient.waitForTransactionReceipt({ hash: profileHash });

  const topicTx = geo.personalSpaces.setTopic({
    spaceId,
    topicId: createSpace.spaceEntityId,
  });

  const topicHash = await walletClient.sendTransaction({
    account: walletClient.account,
    to: topicTx.to,
    data: topicTx.calldata,
  });

  await publicClient.waitForTransactionReceipt({ hash: topicHash });
}

const spaceId = spaceIdHex.slice(2, 34).toLowerCase();
console.log("Personal space ID", spaceId);

Utilities

IDs

Entities, properties, relations, spaces, and proposals use globally unique IDs. The canonical SDK ID is a UUID v4 without dashes.

import { Id, IdUtils } from "@geoprotocol/geo-sdk";

const generatedId = IdUtils.generate();
const checkedId = Id(generatedId);
const bytes = IdUtils.toBytes(checkedId);

Positions

Position provides fractional indexing helpers for ordered relations and other ordered items.

import { Position } from "@geoprotocol/geo-sdk";

const first = Position.generate();
const between = Position.generateBetween(first, null);
const sorted = Position.sort([between, null, first]);

Wallet Helpers

The Geo Genesis browser uses a smart account associated with your account. You can use the same account from code by exporting your private key from https://www.geobrowser.io/export-wallet.

import {
  getSmartAccountWalletClient,
  getWalletClient,
} from "@geoprotocol/geo-sdk";

const smartAccountWalletClient = await getSmartAccountWalletClient({
  privateKey,
});

const eoaWalletClient = await getWalletClient({
  privateKey,
});

Be careful with private keys. Do not commit them to version control.

Legacy API

The legacy namespaces remain exported for compatibility, but new code should prefer Ops and createGeoClient.

Legacy API	Preferred API
`Graph.createEntity(...)`	`Ops.entities.create(...)`
`Graph.updateEntity(...)`	`Ops.entities.update(...)`
`Graph.deleteEntity(...)`	`geo.entities.delete(...)`
`Graph.createImage(...)`	`geo.images.create(...)`
`Graph.createComment(...)`	`geo.comments.create(...)` or `Ops.comments.create(...)` with supplied reply context
`Ipfs.publishEdit(...)`	`geo.personalSpaces.publishEdit(...)` or `geo.daoSpaces.proposeEdit(...)`
`Ipfs.uploadImage(...)`	`geo.storage.uploadImage(...)`
`Ipfs.uploadCSV(...)`	`geo.storage.uploadCSV(...)`
`personalSpace.*`	`geo.personalSpaces.*`
`daoSpace.*`	`geo.daoSpaces.*`
root encoding helpers	configured client transaction helpers where available

Legacy `Graph`

import { Graph } from "@geoprotocol/geo-sdk";

const { id: propertyId, ops: propertyOps } = Graph.createProperty({
  name: "Website",
  dataType: "TEXT",
});

const { id: typeId, ops: typeOps } = Graph.createType({
  name: "Restaurant",
  properties: [propertyId],
});

const { id: entityId, ops: entityOps } = Graph.createEntity({
  name: "Yum Yum",
  types: [typeId],
  values: [
    {
      property: propertyId,
      type: "text",
      value: "https://example.com",
    },
  ],
});

const { ops: updateOps } = Graph.updateEntity({
  id: entityId,
  name: "Updated name",
});

const { ops: deleteOps } = await Graph.deleteEntity({
  id: entityId,
  spaceId,
  network: "TESTNET",
});

Legacy relation helpers:

const { id: relationId, ops: createRelationOps } = Graph.createRelation({
  fromEntity: personId,
  toEntity: restaurantId,
  type: likesPropertyId,
});

const { ops: updateRelationOps } = Graph.updateRelation({
  id: relationId,
  position,
});

const { ops: deleteRelationOps } = Graph.deleteRelation({
  id: relationId,
});

Legacy image and comment helpers:

const image = await Graph.createImage({
  url: "https://example.com/image.png",
  network: "TESTNET",
});

const comment = await Graph.createComment({
  content: "Looks good.",
  replyTo: { entityId, spaceId },
  network: "TESTNET",
});

Legacy `Ipfs`

import { Ipfs } from "@geoprotocol/geo-sdk";

const edit = await Ipfs.publishEdit({
  name: "Create entity",
  author: spaceId,
  ops,
  network: "TESTNET",
});

const image = await Ipfs.uploadImage(
  { url: "https://example.com/image.png" },
  "TESTNET",
);

const csvCid = await Ipfs.uploadCSV("name,score\nAlice,10", "TESTNET");

Legacy `personalSpace`

import { personalSpace } from "@geoprotocol/geo-sdk";

const hasSpace = await personalSpace.hasSpace({
  address: account.address,
});

const createSpace = personalSpace.createSpace();

const publish = await personalSpace.publishEdit({
  name: "My Edit",
  spaceId,
  author: spaceId,
  ops,
  network: "TESTNET",
});

Legacy `daoSpace`

import { daoSpace } from "@geoprotocol/geo-sdk";

const createDao = await daoSpace.createSpace({
  name: "Research DAO",
  author: authorSpaceId,
  initialEditorSpaceIds: [authorSpaceId],
  votingSettings,
  network: "TESTNET",
});

const proposal = await daoSpace.proposeEdit({
  name: "Update entity",
  ops,
  author: authorSpaceId,
  daoSpaceAddress,
  callerSpaceId: authorSpaceId,
  daoSpaceId,
  network: "TESTNET",
});

const vote = daoSpace.voteProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
  versionId: 1,
  vote: "YES",
  network: "TESTNET",
});

const execute = daoSpace.executeProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
  network: "TESTNET",
});

Legacy DAO membership helpers:

daoSpace.proposeAddMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  newMemberSpaceId,
  network: "TESTNET",
});

daoSpace.proposeRemoveMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  memberToRemoveSpaceId,
  network: "TESTNET",
});

daoSpace.proposeAddEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  newEditorSpaceId,
  network: "TESTNET",
});

daoSpace.proposeRemoveEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  editorToRemoveSpaceId,
  network: "TESTNET",
});

daoSpace.proposeUpdateVotingSettings({
  authorSpaceId,
  spaceId: daoSpaceId,
  daoSpaceAddress,
  votingSettings,
  network: "TESTNET",
});

daoSpace.proposeRequestMembership({
  authorSpaceId: requesterSpaceId,
  spaceId: daoSpaceId,
  network: "TESTNET",
});

Legacy Encoding Helpers

Low-level encoding helpers are still available for compatibility when you need exact calldata primitives:

import {
  getCreateDaoSpaceCalldata,
  getCreatePersonalSpaceCalldata,
  getProcessGeoProposalArguments,
} from "@geoprotocol/geo-sdk";

const personalSpaceCalldata = getCreatePersonalSpaceCalldata();

const daoSpaceCalldata = getCreateDaoSpaceCalldata({
  votingSettings,
  initialEditorSpaceIds: [authorSpaceId],
  initialMemberSpaceIds: [],
  initialEditsContentUri:
    "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
});

const proposalArgs = getProcessGeoProposalArguments(
  spacePluginAddress,
  "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
);

Name		Name	Last commit message	Last commit date
Latest commit History 107 Commits
.changeset		.changeset
.claude		.claude
.cursor		.cursor
.github/workflows		.github/workflows
docs/plans		docs/plans
examples		examples
scripts		scripts
src		src
.gitignore		.gitignore
.tool-versions		.tool-versions
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
abis.ts		abis.ts
biome.jsonc		biome.jsonc
contracts.ts		contracts.ts
create-private-key.ts		create-private-key.ts
index.ts		index.ts
lite.ts		lite.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

Geo SDK

Installing

AI Harnesses

Overview

Data Flow

Spaces

Entities

Relations

Ops And Edits

Using

Imports

Network Configuration

Local Contracts V2 Validation

Ops API

Properties, Types, And Entities

Typed Values

Relations

Images

Comments

Proposal Reviews

Client API

geo.api

geo.images

geo.storage

geo.entities

geo.comments

geo.personalSpaces

geo.daoSpaces

geo.entityVotes

Full Publishing Flow With A Smart Account

Full Personal Space Creation Flow

Utilities

IDs

Positions

Wallet Helpers

Legacy API

Legacy Graph

Legacy Ipfs

Legacy personalSpace

Legacy daoSpace

Legacy Encoding Helpers

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 34

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`geo.api`

`geo.images`

`geo.storage`

`geo.entities`

`geo.comments`

`geo.personalSpaces`

`geo.daoSpaces`

`geo.entityVotes`

Legacy `Graph`

Legacy `Ipfs`

Legacy `personalSpace`

Legacy `daoSpace`

Packages