@geoprotocol/geo-sdk 0.18.3 → 0.20.0-beta.0

package/README.md

@@ -14,623 +14,1299 @@ If you're using an AI coding assistant (e.g. Claude Code, Codex, Cursor) to work
 
 ## Overview
 
-### Data flow
+### 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.
+
 ![CleanShot 2025-01-22 at 10 51 23@2x](https://github.com/user-attachments/assets/f0cee8e0-43f9-4663-a2e7-54de6d962115)
 
 ### 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 multiple smart contracts. These smart contracts represent the space itself, its data and its governance process. Depending on which onchain actions you're taking you might be interacting with one or more of these smart contracts.
-
-### 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 model that is commonly called a property graph.
+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 comprised of triples and relations which provide semantic meaning as to 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.
+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](https://www.geobrowser.io/space/720eb279c64d56735dccd17a2a416ba2/a72654b014fa405bbf1250ba901bc082)
 
-### Ops and edits
+### 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 other metadata to represent the set of changes. This edit is then encoded into a binary representation for storage efficiency.
+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](https://github.com/yanivtal/graph-improvement-proposals/blob/new-ops/grcs/0020-knowledge-graph.md#101-operations-op)
 
 ## Using
 
-### Unique IDs
+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.
+
+```ts
+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
 
-Entities throughout The Graph are referenced via globally unique identifiers. The SDK exposes APIs for creating these IDs.
+Use the root package when convenience matters:
 
 ```ts
-import { Id } from "@geoprotocol/geo-sdk";
+import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";
+```
+
+Subpath exports are available for bundle-sensitive code
 
-const newId = Id.generate();
+```ts
+import { entities, relations } from "@geoprotocol/geo-sdk/ops";
+import { createGeoClient } from "@geoprotocol/geo-sdk/client";
+import {
+  GeoTestnetConfig,
+  defineGeoNetworkConfig,
+} from "@geoprotocol/geo-sdk/networks";
 ```
 
-### Creating properties, types and entities
+Use `Ops` from `@geoprotocol/geo-sdk` for op builders. Configured workflows live behind `createGeoClient`.
 
-Working with triple and relations ops is a low level API and give you maximum flexibility. In order to ease the process of creating and updating data, the library also exports APIs for creating properties, types and entities.
+### Network Configuration
+
+Use the built-in testnet config:
 
 ```ts
-import { Graph } from '@geoprotocol/geo-sdk';
+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:
 
-// create a property
-const propertyResult = Graph.createProperty({
-  name: 'name of the property',
-  dataType: 'TEXT', // BOOLEAN | INTEGER | FLOAT | DECIMAL | TEXT | BYTES | DATE | TIME | DATETIME | SCHEDULE | POINT | EMBEDDING | RELATION
+```ts
+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",
+  },
 });
 
-// create a type
-const { id: personTypeId, ops: createPersonTypeOps } = Graph.createType({
-  name: 'name of the type',
-  properties: […listOfPropertyIds],
+const geo = createGeoClient({ network: local });
+```
+
+Pass a fetch implementation when your runtime does not provide `globalThis.fetch`, or when you want test isolation:
+
+```ts
+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:
+
+```sh
+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
 
-// create an image
-const { id: imageId, ops: createImageOps } = await Graph.createImage({
-  url: 'https://example.com/image.png',
-  // blob: new Blob([fs.readFileSync(path.join(__dirname, 'cover.png'))], { type: 'image/png' });
+Ops functions build operation arrays that can be combined before publishing.
+
+```ts
+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:
+
+```ts
+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],
 });
 
-// create an entity
-const { id: restaurantId, ops: createRestaurantOps } = Graph.createEntity({
-  name: 'name of the entity',
-  description: 'description of the entity',
-  types: […listOfTypeIds],
-  cover: imageId,
+const { id: restaurantId, ops: entityOps } = Ops.entities.create({
+  name: "Yum Yum",
+  description: "A restaurant serving fusion cuisine",
+  types: [restaurantTypeId],
   values: [
     {
-      property: propertyId,
-      type: 'text',
-      value: 'value of the property',
-    }
-  ],
-  relations: {
-    // relation property
-    [relationPropertyId]: {
-      toEntity: 'id of the entity',
-      id: 'id of the relation', // optional
-      position: positionString, // optional
+      property: websitePropertyId,
+      type: "text",
+      value: "https://example.com",
     },
-  },
+  ],
 });
-```
 
-#### Typed values
+const ops = [...propertyOps, ...typeOps, ...entityOps];
+```
 
-Values are passed as typed objects with a `type` field that determines the value format:
+Update an entity:
 
 ```ts
-import { Graph, Id } from "@geoprotocol/geo-sdk";
-
-const { id: personId, ops: createPersonOps } = Graph.createEntity({
+const { ops } = Ops.entities.update({
+  id: restaurantId,
+  name: "Yum Yum Kitchen",
   values: [
-    // Text value (with optional language)
     {
-      property: someTextPropertyId,
+      property: websitePropertyId,
       type: "text",
-      value: "Hello",
-      language: Id("dad6e52a5e944e559411cfe3a3c3ea64"), // optional
-    },
-    // Number value — integer (with optional unit)
-    {
-      property: someIntPropertyId,
-      type: "integer",
-      value: 42,
-      unit: Id("016c9b1cd8a84e4d9e844e40878bb235"), // optional
+      value: "https://yum.example",
     },
-    // Number value — float (with optional unit)
+  ],
+});
+```
+
+Unset property values:
+
+```ts
+const { ops } = Ops.entities.update({
+  id: restaurantId,
+  unset: [
+    { property: websitePropertyId },
+    { property: descriptionPropertyId, language: "all" },
+  ],
+});
+```
+
+Create relation properties:
+
+```ts
+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:
+
+```ts
+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: someFloatPropertyId,
-      type: "float",
-      value: 42.5,
-      unit: Id("016c9b1cd8a84e4d9e844e40878bb235"), // optional
+      property: reviewedAtPropertyId,
+      type: "datetime",
+      value: "2024-01-15T14:30:00Z",
     },
-    // Boolean value
     {
-      property: someBooleanPropertyId,
-      type: "boolean",
-      value: true,
+      property: schedulePropertyId,
+      type: "schedule",
+      value: "FREQ=WEEKLY;BYDAY=MO,WE,FR",
     },
-    // Point value (with optional altitude)
     {
-      property: somePointPropertyId,
+      property: locationPropertyId,
       type: "point",
       lon: -122.4194,
       lat: 37.7749,
-      alt: 10.5, // optional
-    },
-    // Date value (ISO 8601 format: YYYY-MM-DD)
-    {
-      property: someDatePropertyId,
-      type: "date",
-      value: "2024-01-15",
-    },
-    // Time value (ISO 8601 format with timezone)
-    {
-      property: someTimePropertyId,
-      type: "time",
-      value: "14:30:00Z",
-    },
-    // Datetime value (ISO 8601 combined format)
-    {
-      property: someDatetimePropertyId,
-      type: "datetime",
-      value: "2024-01-15T14:30:00Z",
     },
-    // Schedule value (iCalendar RRULE format)
     {
-      property: someSchedulePropertyId,
-      type: "schedule",
-      value: "FREQ=WEEKLY;BYDAY=MO,WE,FR",
+      property: bytesPropertyId,
+      type: "bytes",
+      value: new Uint8Array([1, 2, 3]),
     },
   ],
 });
 ```
 
-#### Example Flow
+### Relations
 
-```ts
-import { Graph, type Op } from "@geoprotocol/geo-sdk";
+Create, update, and delete relation entities:
 
-const ops: Array<Op> = [];
+```ts
+import { Ops, Position } from "@geoprotocol/geo-sdk";
 
-// create an age property
-const { id: agePropertyId, ops: createAgePropertyOps } = Graph.createProperty({
-  dataType: "INTEGER",
-  name: "Age",
+const { id: relationId, ops: createRelationOps } = Ops.relations.create({
+  fromEntity: personId,
+  toEntity: restaurantId,
+  type: likesPropertyId,
+  position: Position.generate(),
 });
-ops.push(...createAgePropertyOps);
 
-// create a likes property
-const { id: likesPropertyId, ops: createLikesPropertyOps } =
-  Graph.createProperty({
-    dataType: "RELATION",
-    name: "Likes",
-  });
-ops.push(...createLikesPropertyOps);
+const { ops: updateRelationOps } = Ops.relations.update({
+  id: relationId,
+  position: Position.generateBetween(previousPosition, nextPosition),
+});
 
-// create a person type
-const { id: personTypeId, ops: createPersonTypeOps } = Graph.createType({
-  name: "Person",
-  cover: personCoverId,
-  properties: [agePropertyId, likesPropertyId],
+const { ops: deleteRelationOps } = Ops.relations.delete({
+  id: relationId,
 });
-ops.push(...createPersonTypeOps);
+```
 
-// create a restaurant cover image
-const { id: restaurantCoverId, ops: createRestaurantCoverOps } =
-  await Graph.createImage({
-    url: "https://example.com/image.png",
-  });
-ops.push(...createRestaurantCoverOps);
+Relations can also carry their own entity values:
 
-// create a restaurant entity with a website property
-const restaurantTypeId = "a1b2c3d4e5f647889012345678abcdef";
-const { id: restaurantId, ops: createRestaurantOps } = Graph.createEntity({
-  name: "Yum Yum",
-  description: "A restaurant serving fusion cuisine",
-  cover: restaurantCoverId,
-  types: [restaurantTypeId],
-  values: [
+```ts
+const { ops } = Ops.relations.create({
+  fromEntity: personId,
+  toEntity: companyId,
+  type: teamMemberPropertyId,
+  entityName: "Team member",
+  entityValues: [
     {
-      property: WEBSITE_PROPERTY,
-      type: "text",
-      value: "https://example.com",
+      property: joinedDatePropertyId,
+      type: "date",
+      value: "2024-05-01",
     },
   ],
 });
-ops.push(...createRestaurantOps);
+```
 
-// create a person cover image
-const { id: personCoverId, ops: createPersonCoverOps } =
-  await Graph.createImage({
-    url: "https://example.com/avatar.png",
-  });
-ops.push(...createPersonCoverOps);
+### Images
 
-// create a person entity with a likes relation to the restaurant entity
-const { id: personId, ops: createPersonOps } = Graph.createEntity({
-  name: "Jane Doe",
-  types: [personTypeId],
-  cover: personCoverId,
-  values: [
+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:
+
+```ts
+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:
+
+```ts
+const { ops } = Ops.comments.create({
+  content: "Replying to the parent comment.",
+  replyTo: {
+    entityId: parentCommentId,
+    spaceId,
+  },
+  replyToRelations: [
     {
-      property: agePropertyId,
-      type: "integer",
-      value: 42,
+      entityId: rootEntityId,
+      spaceId,
+      position: "a0",
     },
   ],
-  relations: {
-    [likesPropertyId]: {
-      toEntity: restaurantId,
-    },
+});
+```
+
+Update a comment:
+
+```ts
+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:
+
+```ts
+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.",
 });
-ops.push(...createPersonOps);
 ```
 
-### Updating entities
+## Client API
 
-Update an entity's name, description, and property values. Also supports unsetting properties.
+Create a configured client once and use it for workflows that need API origins, uploads, RPC URLs, or contract addresses.
 
 ```ts
-import { Graph } from "@geoprotocol/geo-sdk";
+import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";
 
-// Update values
-const { ops: updateOps } = Graph.updateEntity({
-  id: entityId,
-  name: "Updated Name",
-  description: "Updated description",
-  values: [
-    {
-      property: agePropertyId,
-      type: "integer",
-      value: 43,
-    },
-  ],
+const geo = createGeoClient({ network: GeoTestnetConfig });
+```
+
+### `geo.api`
+
+Use `geo.api.graphql(...)` for low-level GraphQL requests:
+
+```ts
+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:
+
+```ts
+const { to, data } = await geo.api.getEditCalldata({
+  spaceId,
+  cid: "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
 });
 
-// Unset property values
-const { ops: unsetOps } = Graph.updateEntity({
-  id: entityId,
-  unset: [
-    { property: propertyId }, // unset all languages
-    { property: propertyId2, language: { type: "all" } }, // explicit all languages
-  ],
+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:
+
+```ts
+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:
+
+```ts
+const file = new Blob([imageBytes], { type: "image/png" });
+
+const imageFromBlob = await geo.images.create({
+  blob: file,
+  name: "Cover image",
 });
+
+console.log(imageFromBlob.cid);
 ```
 
-### Deleting entities
+### `geo.storage`
 
-Delete an entity by removing all its values and relations in a specific space. This is an async operation that queries the API to discover what to delete.
+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:
 
 ```ts
-import { Graph } from "@geoprotocol/geo-sdk";
+const uploaded = await geo.storage.uploadImage({
+  url: "https://example.com/photo.png",
+});
 
-const { ops: deleteOps } = await Graph.deleteEntity({
+console.log(uploaded.cid);
+console.log(uploaded.dimensions);
+```
+
+Upload CSV content:
+
+```ts
+const cid = await geo.storage.uploadCSV(`name,score
+Alice,10
+Bob,8`);
+```
+
+### `geo.entities`
+
+Delete an entity from a space:
+
+```ts
+const { ops } = await geo.entities.delete({
   id: entityId,
-  spaceId: spaceId,
-  network: "TESTNET", // optional, defaults to "TESTNET"
+  spaceId,
 });
 ```
 
-> **Note:** `deleteEntity` queries the API to discover the entity's properties and relations, then generates ops to unset all values and delete all relations. The entity itself transitions to an empty state rather than being permanently destroyed.
+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.
 
-### Relations
+### `geo.comments`
 
-Relations describe edges between entities in the knowledge graph. Each relation is itself an entity, which means relations can have their own properties (e.g., a "Team Member" relation could have a "joined date" property).
+Create a comment while preserving reply-to chains:
 
 ```ts
-import { Graph, Position } from "@geoprotocol/geo-sdk";
+const comment = await geo.comments.create({
+  content: "This should be easier to find.",
+  replyTo: {
+    entityId,
+    spaceId,
+  },
+});
+```
 
-// Create a relation
-const { id: relationId, ops: createRelOps } = Graph.createRelation({
-  fromEntity: personId,
-  toEntity: restaurantId,
-  type: likesPropertyId, // the relation type property
-  position: Position.generateBetween(), // optional ordering
+Reply to another comment:
+
+```ts
+const reply = await geo.comments.create({
+  content: "Following up here.",
+  replyTo: {
+    entityId: comment.id,
+    spaceId,
+  },
 });
+```
 
-// Update a relation (change position)
-const { ops: updateRelOps } = Graph.updateRelation({
-  id: relationId,
-  position: Position.generateBetween(posA, posB),
+Update a comment:
+
+```ts
+const { ops } = geo.comments.update({
+  id: comment.id,
+  content: "Updated comment text.",
+  resolved: true,
 });
+```
 
-// Delete a relation
-const { ops: deleteRelOps } = Graph.deleteRelation({
-  id: relationId,
+### `geo.personalSpaces`
+
+Check whether an address already has a personal space:
+
+```ts
+const hasExistingSpace = await geo.personalSpaces.hasSpace({
+  address: account.address,
 });
 ```
 
-### Positions
+Create a personal space:
+
+```ts
+const createSpace = geo.personalSpaces.create({
+  name: "Alice",
+  accountAddress: account.address,
+});
 
-The `Position` module provides fractional indexing for ordering entities, relations, and other ordered items without renumbering.
+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:
 
 ```ts
-import { Position } from "@geoprotocol/geo-sdk";
+const profileTx = await geo.personalSpaces.publishEdit({
+  name: "Create personal space profile",
+  spaceId,
+  author: spaceId,
+  ops: createSpace.ops,
+});
 
-// Generate a position (for first item)
-const pos1 = Position.generate();
+await walletClient.sendTransaction({
+  to: profileTx.to,
+  data: profileTx.calldata,
+});
 
-// Generate a position between two existing positions
-const between = Position.generateBetween(pos1, pos2);
+const topicTx = geo.personalSpaces.setTopic({
+  spaceId,
+  topicId: createSpace.spaceEntityId,
+});
 
-// Generate at the start (before first item)
-const first = Position.generateBetween(null, pos1);
+await walletClient.sendTransaction({
+  to: topicTx.to,
+  data: topicTx.calldata,
+});
+```
 
-// Generate at the end (after last item)
-const last = Position.generateBetween(pos1, null);
+Publish any edit to a personal space:
 
-// Compare positions
-const result = Position.compare(posA, posB); // -1, 0, or 1
+```ts
+const { ops } = Ops.entities.create({
+  name: "Test Entity",
+});
 
-// Sort an array of positions
-const sorted = Position.sort([pos3, pos1, pos2]);
+const tx = await geo.personalSpaces.publishEdit({
+  name: "Create Test Entity",
+  spaceId,
+  author: spaceId,
+  ops,
+});
+
+await walletClient.sendTransaction({
+  to: tx.to,
+  data: tx.calldata,
+});
 ```
 
-### Publishing an edit onchain using your Geo Account
+The `author` field is the author's personal space ID, not a wallet address.
 
-The Geo Genesis browser uses a smart account associated with your account to publish edits. There may be situations where you want to use the same account in your code as you do on Geo Genesis. In order to get the smart account wallet client you can use the `getSmartAccountWalletClient` function.
+### `geo.daoSpaces`
 
-To use `getSmartAccountWalletClient` you'll need the private key associated with your Geo account. You can get your private key using https://www.geobrowser.io/export-wallet.
+DAO helpers target the contracts v2 surface. Voting settings use percentages
+and days on the SDK side; the SDK maps them to ratio-base integers and seconds
+for the contract. Use a network config whose DAO contract addresses point at a
+contracts v2 deployment.
 
-Transaction costs from your smart account will be sponsored by the Geo team for the duration of the early access period. Eventually you will need to provide your own API key or provide funds to your smart account.
+```ts
+const votingSettings = {
+  partialPercentageSupportThreshold: 50,
+  universalPercentageSupportThreshold: 90,
+  flatSupportThreshold: 1,
+  quorum: 1,
+  durationInDays: 2,
+  disableFastPathAccessForNewMembers: true,
+  executionGracePeriodInDays: 14,
+};
+```
+
+Create a DAO space:
 
 ```ts
-import { getSmartAccountWalletClient } from "@geoprotocol/geo-sdk";
+const tx = await geo.daoSpaces.create({
+  name: "Research DAO",
+  author: authorSpaceId,
+  initialEditorSpaceIds: [authorSpaceId],
+  initialMemberSpaceIds: [authorSpaceId],
+  votingSettings,
+});
 
-// IMPORTANT: Be careful with your private key. Don't commit it to version control.
-// You can get your private key using https://www.geobrowser.io/export-wallet
-const privateKey = `0x${privateKeyFromGeoWallet}`;
-const smartAccountWalletClient = await getSmartAccountWalletClient({
-  privateKey,
-  // rpcUrl, // optional
+await walletClient.sendTransaction({
+  to: tx.to,
+  data: tx.calldata,
 });
 ```
 
-### Personal Spaces
+Include extra initial ops in the DAO creation edit:
+
+```ts
+const { ops } = Ops.entities.create({
+  name: "DAO Welcome Page",
+});
 
-Personal spaces are owned by a single address and don't require voting for governance. The SDK provides a `personalSpace` module with helper functions for creating and publishing to personal spaces.
+const tx = await geo.daoSpaces.create({
+  name: "Research DAO",
+  author: authorSpaceId,
+  initialEditorSpaceIds: [authorSpaceId],
+  votingSettings,
+  ops,
+});
+```
 
-#### Creating a personal space
+Propose an edit to a DAO space:
 
 ```ts
-import { personalSpace, getWalletClient } from "@geoprotocol/geo-sdk";
+const { ops } = Ops.entities.update({
+  id: entityId,
+  name: "Updated entity name",
+});
 
-const walletClient = await getWalletClient({
-  privateKey: addressPrivateKey,
+const proposal = await geo.daoSpaces.proposeEdit({
+  name: "Update entity name",
+  ops,
+  author: authorSpaceId,
+  daoSpaceAddress,
+  callerSpaceId: authorSpaceId,
+  daoSpaceId,
+  votingMode: "FAST",
 });
 
-// Get the calldata for creating a personal space
-const { to, calldata } = personalSpace.createSpace();
+await walletClient.sendTransaction({
+  to: proposal.to,
+  data: proposal.calldata,
+});
+```
 
-// Submit the transaction
-const txHash = await walletClient.sendTransaction({
-  account: walletClient.account,
-  to,
-  data: calldata,
+Create a new version of an existing edit proposal:
+
+```ts
+const updatedProposal = await geo.daoSpaces.proposeEdit({
+  name: "Update entity name, revision 2",
+  ops,
+  author: authorSpaceId,
+  daoSpaceAddress,
+  callerSpaceId: authorSpaceId,
+  daoSpaceId,
+  proposalId,
+  updateProposal: true,
+  versionId: 2,
 });
 ```
 
-#### Publishing to a personal space
+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:
 
 ```ts
-import { personalSpace } from "@geoprotocol/geo-sdk";
+const addMember = geo.daoSpaces.proposeAddMember({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  daoSpaceAddress,
+  newMemberSpaceId: memberSpaceId,
+  votingMode: "FAST",
+});
 
-const { cid, editId, to, calldata } = await personalSpace.publishEdit({
-  name: "My Edit",
-  spaceId, // your personal space ID (dashless hex UUID)
-  ops, // array of Op from Graph.* functions
-  author: spaceId, // your personal space ID (same as spaceId for personal spaces)
-  network: "TESTNET",
+const removeMember = geo.daoSpaces.proposeRemoveMember({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  daoSpaceAddress,
+  memberToRemoveSpaceId: memberSpaceId,
+});
+
+const addEditor = geo.daoSpaces.proposeAddEditor({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  daoSpaceAddress,
+  newEditorSpaceId: editorSpaceId,
 });
 
-const txHash = await walletClient.sendTransaction({ to, data: calldata });
+const removeEditor = geo.daoSpaces.proposeRemoveEditor({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  daoSpaceAddress,
+  editorToRemoveSpaceId: editorSpaceId,
+});
 ```
 
-> **Important:** The `author` field must be a **personal space ID** (dashless hex UUID), not a wallet address or entity ID. For personal spaces, this is the same as `spaceId`. Verified from SDK source: `personal-space/types.ts` defines author as `/** The author's personal space ID. */`.
+Editor changes only support `SLOW` voting. Member changes can use the default or an explicit `votingMode`.
+
+Propose voting-settings changes:
 
-### DAO Spaces
+```ts
+const updateVoting = geo.daoSpaces.proposeUpdateVotingSettings({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  daoSpaceAddress,
+  votingSettings: {
+    partialPercentageSupportThreshold: 60,
+    universalPercentageSupportThreshold: 95,
+    flatSupportThreshold: 2,
+    quorum: 2,
+    durationInDays: 5,
+    disableFastPathAccessForNewMembers: true,
+    executionGracePeriodInDays: 14,
+  },
+});
+```
 
-DAO spaces use governance (voting) for publishing changes. The SDK provides a `daoSpace` module for proposing edits and managing membership.
+Updating voting settings only supports `SLOW` voting.
 
-#### Proposing an edit to a DAO space
+Request membership in a DAO space:
 
 ```ts
-import { daoSpace, Graph } from "@geoprotocol/geo-sdk";
+const request = geo.daoSpaces.proposeRequestMembership({
+  authorSpaceId: requesterSpaceId,
+  spaceId: daoSpaceId,
+});
+
+await walletClient.sendTransaction({
+  to: request.to,
+  data: request.calldata,
+});
+```
 
-const { ops } = Graph.createEntity({ name: "New Entity" });
+DAO proposal IDs and DAO space IDs are bytes16 hex strings, usually `0x` plus 32 hex characters.
 
-const { editId, cid, to, calldata, proposalId } = await daoSpace.proposeEdit({
-  name: "Add new entity",
-  ops,
-  author: callerSpaceId, // your personal space ID (as `0x${string}`)
-  daoSpaceAddress: "0xDAOSpaceContractAddress", // the DAO space contract address
-  callerSpaceId: "0xCallerBytes16SpaceId", // your personal space ID (bytes16 hex)
-  daoSpaceId: "0xDAOBytes16SpaceId", // the DAO space ID (bytes16 hex)
-  network: "TESTNET",
+Vote on a proposal:
+
+```ts
+const vote = geo.daoSpaces.voteProposal({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  proposalId,
+  versionId: 1,
+  vote: "YES",
 });
 
-await walletClient.sendTransaction({ to, data: calldata });
+await walletClient.sendTransaction({
+  to: vote.to,
+  data: vote.calldata,
+});
 ```
 
-> **Note:** `callerSpaceId` and `daoSpaceId` must be `0x`-prefixed bytes16 hex strings (e.g., `0x` + 32 hex chars). `author` is your personal space ID, also `0x`-prefixed.
+`versionId` defaults to `1`. Pass it explicitly when voting on a later proposal
+version.
 
-#### Requesting membership in a DAO space
+Execute a passed proposal:
 
 ```ts
-import { daoSpace } from "@geoprotocol/geo-sdk";
+const execute = geo.daoSpaces.executeProposal({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  proposalId,
+});
+
+await walletClient.sendTransaction({
+  to: execute.to,
+  data: execute.calldata,
+});
+```
 
-const { to, calldata, proposalId } = daoSpace.proposeRequestMembership({
-  requesterSpaceId: "0xRequesterPersonalSpaceId",
-  daoSpaceAddress: "0xDAOSpaceContractAddress",
-  daoSpaceId: "0xDAOBytes16SpaceId",
+### `geo.entityVotes`
+
+Upvote, downvote, or withdraw a vote on an entity:
+
+```ts
+const upvote = geo.entityVotes.upvote({
+  authorSpaceId,
+  spaceId,
+  entityId,
 });
 
-await walletClient.sendTransaction({ to, data: calldata });
+const downvote = geo.entityVotes.downvote({
+  authorSpaceId,
+  spaceId,
+  entityId,
+});
+
+const withdraw = geo.entityVotes.withdraw({
+  authorSpaceId,
+  spaceId,
+  entityId,
+});
 ```
 
-## Full Publishing Flow with Smart Account
+Submit any returned transaction with your wallet client:
 
-This example shows the complete flow for publishing an edit using a Geo smart account (Safe with Pimlico paymaster) on testnet. Gas is sponsored, so no testnet ETH is required.
+```ts
+await walletClient.sendTransaction({
+  to: upvote.to,
+  data: upvote.calldata,
+});
+```
+
+## Full Publishing Flow With A Smart Account
 
-The smart account address must already have a personal space. You can create one via the [Geo Genesis browser](https://www.geobrowser.io).
+This example publishes an edit to an existing personal space using a Geo smart account.
 
 ```ts
-import { createPublicClient, type Hex, http } from "viem";
+import { createPublicClient, http, type Hex } from "viem";
 import {
-  Graph,
-  personalSpace,
+  GeoTestnetConfig,
+  Ops,
+  createGeoClient,
   getSmartAccountWalletClient,
-  TESTNET_RPC_URL,
 } from "@geoprotocol/geo-sdk";
 import { SpaceRegistryAbi } from "@geoprotocol/geo-sdk/abis";
-import { TESTNET } from "@geoprotocol/geo-sdk/contracts";
 
-// IMPORTANT: Be careful with your private key. Don't commit it to version control.
-// You can get your private key using https://www.geobrowser.io/export-wallet
 const privateKey = `0x${privateKeyFromGeoWallet}` as `0x${string}`;
-
-// Get smart account wallet client (Safe + Pimlico paymaster)
+const geo = createGeoClient({ network: GeoTestnetConfig });
 const smartAccount = await getSmartAccountWalletClient({ privateKey });
-const smartAccountAddress = smartAccount.account.address;
+const accountAddress = smartAccount.account.address;
 
-// Check if a personal space exists for this smart account address
-const hasExistingSpace = await personalSpace.hasSpace({
-  address: smartAccountAddress,
+const hasSpace = await geo.personalSpaces.hasSpace({
+  address: accountAddress,
 });
-if (!hasExistingSpace) {
-  throw new Error("No personal space found for this smart account address.");
+
+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(TESTNET_RPC_URL),
+  transport: http(rpcUrl),
 });
 
-// Look up the space ID for this smart account address
 const spaceIdHex = (await publicClient.readContract({
-  address: TESTNET.SPACE_REGISTRY_ADDRESS,
+  address: spaceRegistryAddress,
   abi: SpaceRegistryAbi,
   functionName: "addressToSpaceId",
-  args: [smartAccountAddress],
+  args: [accountAddress],
 })) as Hex;
 
-// Convert bytes16 hex to UUID string (without dashes)
 const spaceId = spaceIdHex.slice(2, 34).toLowerCase();
-console.log("spaceId", spaceId);
 
-// Create an entity
-const { ops, id: entityId } = Graph.createEntity({
+const { id: entityId, ops } = Ops.entities.create({
   name: "Test Entity",
+  description: "Created via Geo SDK",
 });
-console.log("entityId", entityId);
 
-// Publish to IPFS and get calldata for on-chain submission
-const { cid, editId, to, calldata } = await personalSpace.publishEdit({
-  name: "Test Edit",
+const tx = await geo.personalSpaces.publishEdit({
+  name: "Create Test Entity",
   spaceId,
-  ops,
   author: spaceId,
-  network: "TESTNET",
+  ops,
 });
-console.log("cid", cid);
-console.log("editId", editId);
 
-// Send transaction via smart account (account and chain are baked in)
 const txHash = await smartAccount.sendTransaction({
-  to,
-  data: calldata,
+  to: tx.to,
+  data: tx.calldata,
 });
-console.log("txHash", txHash);
 
-const receipt = await publicClient.waitForTransactionReceipt({
-  hash: txHash,
-});
-console.log("Successfully published edit to space", spaceId);
+await publicClient.waitForTransactionReceipt({ hash: txHash });
+console.log("Published entity", entityId, "to space", spaceId);
 ```
 
-## Full Publishing Flow (EOA Wallet)
+## Full Personal Space Creation Flow
 
-This example shows the complete flow for creating a personal space and publishing an edit on testnet using the `personalSpace` module with an EOA wallet.
+This example creates a personal space with an EOA wallet and then publishes the initial profile ops returned by `geo.personalSpaces.create(...)`.
 
 ```ts
-import { createPublicClient, type Hex, http } from "viem";
+import { createPublicClient, http, type Hex } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import {
-  Graph,
-  personalSpace,
+  GeoTestnetConfig,
+  createGeoClient,
   getWalletClient,
-  TESTNET_RPC_URL,
 } from "@geoprotocol/geo-sdk";
 import { SpaceRegistryAbi } from "@geoprotocol/geo-sdk/abis";
-import { TESTNET } from "@geoprotocol/geo-sdk/contracts";
 
-// IMPORTANT: Be careful with your private key. Don't commit it to version control.
-// You can get your private key using https://www.geobrowser.io/export-wallet
-const addressPrivateKey = "0xTODO" as `0x${string}`;
-const { address } = privateKeyToAccount(addressPrivateKey);
+const privateKey = "0xTODO" as `0x${string}`;
+const account = privateKeyToAccount(privateKey);
+const geo = createGeoClient({ network: GeoTestnetConfig });
 
-// Take the address and enter it in Faucet to get some testnet ETH https://faucet.conduit.xyz/geo-test-zc16z3tcvf
-
-// Get wallet client for testnet
 const walletClient = await getWalletClient({
-  privateKey: addressPrivateKey,
+  privateKey,
 });
 
-const account = walletClient.account;
+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(TESTNET_RPC_URL),
+  transport: http(rpcUrl),
 });
 
-// Check if a personal space already exists for this address
-const hasExistingSpace = await personalSpace.hasSpace({
+const hasSpace = await geo.personalSpaces.hasSpace({
   address: account.address,
 });
 
-// Create a personal space if one doesn't exist
-if (!hasExistingSpace) {
-  console.log("Creating personal space...");
+let spaceIdHex = (await publicClient.readContract({
+  address: spaceRegistryAddress,
+  abi: SpaceRegistryAbi,
+  functionName: "addressToSpaceId",
+  args: [account.address],
+})) as Hex;
 
-  const { to, calldata } = personalSpace.createSpace();
+if (!hasSpace) {
+  const createSpace = geo.personalSpaces.create({
+    name: "Alice",
+    accountAddress: account.address,
+  });
 
-  const createSpaceTxHash = await walletClient.sendTransaction({
+  const createSpaceHash = await walletClient.sendTransaction({
     account: walletClient.account,
-    to,
-    data: calldata,
+    to: createSpace.to,
+    data: createSpace.calldata,
   });
 
-  await publicClient.waitForTransactionReceipt({ hash: createSpaceTxHash });
-}
+  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,
+  });
 
-// Look up the space ID
-const spaceIdHex = (await publicClient.readContract({
-  address: TESTNET.SPACE_REGISTRY_ADDRESS,
-  abi: SpaceRegistryAbi,
-  functionName: "addressToSpaceId",
-  args: [account.address],
-})) as Hex;
+  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 });
+}
 
-// Convert bytes16 hex to UUID string (without dashes)
 const spaceId = spaceIdHex.slice(2, 34).toLowerCase();
-console.log("spaceId", spaceId);
+console.log("Personal space ID", spaceId);
+```
 
-// Create an entity with some data
-const { ops, id: entityId } = Graph.createEntity({
-  name: "Test Entity",
-  description: "Created via SDK",
+## Utilities
+
+### IDs
+
+Entities, properties, relations, spaces, and proposals use globally unique IDs. The canonical SDK ID is a UUID v4 without dashes.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+import {
+  getSmartAccountWalletClient,
+  getWalletClient,
+} from "@geoprotocol/geo-sdk";
+
+const smartAccountWalletClient = await getSmartAccountWalletClient({
+  privateKey,
 });
-console.log("entityId", entityId);
 
-// Publish to IPFS and get calldata for on-chain submission
-const { cid, editId, to, calldata } = await personalSpace.publishEdit({
-  name: "Test Edit",
+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`
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+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",
 });
-console.log("cid", cid);
-console.log("editId", editId);
 
-// Submit the edit on-chain
-const publishTxHash = await walletClient.sendTransaction({
-  account: walletClient.account,
-  to,
-  data: calldata,
+const execute = daoSpace.executeProposal({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  proposalId,
+  network: "TESTNET",
+});
+```
+
+Legacy DAO membership helpers:
+
+```ts
+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",
 });
-console.log("publishTxHash", publishTxHash);
 
-const publishReceipt = await publicClient.waitForTransactionReceipt({
-  hash: publishTxHash,
+daoSpace.proposeRemoveEditor({
+  authorSpaceId,
+  spaceId: daoSpaceId,
+  daoSpaceAddress,
+  editorToRemoveSpaceId,
+  network: "TESTNET",
 });
-console.log("Successfully published edit to space", spaceId);
+
+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:
+
+```ts
+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",
+);
 ```