@geoprotocol/geo-sdk

中文文档
0.20.6发布于 2026/11/12MITTypeScriptES Module构建来源已验证近 30 天下载 4983

与"图"互动的工具集.

中文使用文档
文档目录42 节
  1. 安装
  2. 大赦国际
  3. 概览
  4. 数据流动
  5. 空间
  6. 实体
  7. 关系
  8. 操作和编辑
  9. 使用
  10. 赞助的EIP-7702 交易
  11. 进口
  12. 网络配置
  13. 当地合同 V2 验证
  14. 操作 API
  15. 属性、 类型和实体
  16. 类型值
  17. 关系
  18. 块
  19. 图像
  20. 评论
  21. 二. 审查
  22. 客户端 API
  23. geo.api
  24. geo.images
  25. geo.storage
  26. geo.entities
  27. geo.comments
  28. geo.personalSpaces
  29. geo.daoSpaces
  30. geo.responses
  31. 附有担保钱包的完整出版流程
  32. 完整的个人空间创建流程
  33. 公用事业
  34. 身份证
  35. 职位
  36. 钱包客户端
  37. 遗产 API
  38. 遗产 Graph
  39. 遗产 Ipfs
  40. 遗产 personalSpace
  41. 遗产 daoSpace
  42. 遗留编码帮助

地理 SDK

与"图"互动的工具集.

安装

npm install @geoprotocol/geo-sdk

大赦国际

如果您使用AI编码助手(如克洛德代码, Codex, Cursor)与这个SDK合作, 请检查 地理浏览器/地理技能 帮助代理有效使用Geo SDK的技能和提示.

概览

数据流动

"图"中的数据同时生活在链外和链上. 这些数据是写给IPFS的,由此产生的内容标识符在被索引堆栈读取之前被放入链上. 在索引器完成数据处理后,它被API所曝光.

CleanShot 2025-01-22 at 10 51 23@2x

空间

在图上,知识被组织成空间. 任何人都可以为社区、项目或个人创造空间。 空间在链上组织成一套智能合同. 这些合同代表空间本身、数据和管理过程.

实体

一个实体是一个独特的标识符,代表一个人,一个地方,一个想法,一个概念,或者其他任何东西. 实体由描述实体的三重关系组成。 一个实体的数据可以同时由多个空间组成. 这种财产使得图中的多元化得以实现.

更多关于实体和知识图

关系

关系描述图中的边缘. 关系本身就是包含关系细节的实体. 例如,一家公司可以拥有团队成员. 每个团队成员关系可以有一个属性来描述人物加入团队的时间. 这是一个属性图模型.

操作和编辑

该图中的数据被存储为 Op( 操作) 。 操作是适用于实体的一组更改。 修改可以是设定或删除三重关系或关系。 三重和关系都作为行动组织代表.

在写入数据时,这些操作被分组为称为编辑的逻辑集. 一个编辑器有一个名称,作者和元数据来代表一组更改. 此编辑在被上传到IPFS之前被编码为二进制表示.

GRC-20 中的操作和编辑

使用

首选的API有两个部分:

  • Ops 建立GRC-20操作.
  • createGeoClient(...) 处理配置的工作流程,如API呼叫、上传、RPC读取和交易呼叫数据.
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 });

赞助的EIP-7702 交易

使用 createGeoWalletClient 需要枢密院支持的道德操守办公室、当地道德操守办公室或 在保存 EOA 的同时发送 Geo 赞助交易的其他支持的签名符 地址作为账户身份.

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

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

const walletClient = await createGeoWalletClient({
  signer, // Privy viem wallet client, EIP-1193 provider, or local account
  network: GeoTestnetConfig,
});

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

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

GeoTestnetConfig 包括Geo默认的赞助RPC URL. 使用 defineGeoNetworkConfig 当您想要使用自定义链 RPC URL 时 赞助项目.

进口

当方便重要时使用根包 :

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

用于捆绑敏感代码的子路径导出

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

使用 Ops 从 @geoprotocol/geo-sdk 对于行动建设者。 配置工作流程位于后面 createGeoClient。 。 。 .

网络配置

使用内置测试网配置 :

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

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

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

network ,客户端则需要完整配置对象。 过 GeoTestnetConfig,而不是字符串 "TESTNET"。 。 。 .

定义自定义部署 :

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 });

运行时间不提供时通过抓取执行 globalThis.fetch,或者当您想要测试隔离时:

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

当地合同 V2 验证

在与本地geobrowser 合同核对时, 部署该堆 首先,它写 .deployments.json,然后将SDK选入测试指向它:

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

测试建立自定义 defineGeoNetworkConfig(...) 从部署文件 并解码 DAO 创建、更新- 投票设定提案和版本投票 与合同v2 ABIs的调取数据.

操作 API

Ops函数构建操作数组,在发布前可以合并.

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

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

属性、 类型和实体

创建属性、类型和实体:

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];

更新一个实体 :

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

未设置属性值 :

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

创建关系属性 :

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

类型值

实体值为已键入对象。 这个 type 字段决定值形状 :

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]),
    },
  ],
});

关系

创建、更新和删除关系实体 :

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,
});

关系还可以带有自己的实体价值:

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

块

创建带有生成或稳定ID的文本和数据块 :

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

const { id: textBlockId, ops: textBlockOps } = Ops.textBlocks.create({
  fromId: pageId,
  text: "# Heading",
});

const { id: dataBlockId, ops: dataBlockOps } = Ops.dataBlocks.create({
  fromId: pageId,
  sourceType: "QUERY",
  id: stableDataBlockId,
});

图像

图像创作经过 geo.images.create(...)。配置客户端上传图像,在可能时检测到维度,并返回图像实体操作.

评论

创建一个实体的注释 :

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

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

当您已有回覆链上下文时创建嵌入式注释 :

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

更新评论 :

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

使用 geo.comments.create(...) 当从配置的 API 获取回执链上下文时.

二. 审查

创建和更新提案审查业务:

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.",
});

客户端 API

一次创建已配置的客户端,并将其用于需要API来源,上传,RPC URL或合同地址的工作流程.

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

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

geo.api

使用 geo.api.graphql(...) 用于低级图QL请求:

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);
}

使用 geo.api.getEditCalldata(...) 当调用数据必须来自 API:

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

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

对于个人空间编辑, 偏好 geo.personalSpaces.publishEdit(...)。 。 。 .

geo.images

在一个呼叫中上传图像并构建图像实体操作 :

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);

也可以通过一个 Blob 直接 :

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

使用 geo.images.create(...) 当您想要上传一个图像并在一个呼叫中创建图像实体操作。 使用 geo.storage.uploadImage(...) 仅当您需要原始上传的 CID 并检测到没有图形操作的维度时 :

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

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

上传 CSV 内容 :

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

geo.entities

从空格中删除一个实体:

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

实体删除查询所配置的API在目标空间中的当前值和关系,然后建立操作来取消这些值并删除这些关系. 该实体在该空间中向空态过渡;它没有在全球被摧毁.

geo.comments

在保存回复链时创建注释 :

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

对另一项评论的答复:

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

更新评论 :

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

geo.personalSpaces

检查地址是否有个人空间 :

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

创建个人空间 :

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

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

geo.personalSpaces.create(...) 并返回初始配置文件 。 在创建 - 空格交易被挖掘后, 您知道新的 spaceId并立即将生成的空间实体设定为空间主题:

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,
});

发布编辑到个人空间 :

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,
});

这个 author 字段是作者的个人空间ID,而不是钱包地址.

geo.daoSpaces

DAO帮助者瞄准合同v2表面. 投票设置使用百分比 和二级投票时间 合同的比基整数。 使用 DAO 合同的网络配置 位于合同v2部署点.

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

创建 DAO 空间 :

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,
});

在 DAO 创建编辑中包含额外的初始操作 :

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

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

向 DAO 空间建议编辑 :

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

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

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

创建新版本的现有编辑建议 :

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

若为 updateProposal: true 设置和 versionId 被省略, SDK 读取 dAO 地址来自 SpaceRegistry.spaceIdToAddress(...),然后读取 latestProposalVersion(...) 从已配置的 RPC 网络上传编辑前. 过 versionId 当您已经知道下一个版本或当您的自定义网络配置没有 RPC URL 时.

管理 DAO 成员和编辑器 :

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

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

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

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

编辑器只更改支持 SLOW 投票。 成员更改可以使用默认或明示 votingMode。 。 。 .

建议的投票设定修改:

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

只支持更新投票设置 SLOW 投票.

管理一个空格的快速路径访问 :

// Editor-only, takes effect immediately. Not a proposal, so there is no proposalId.
// Any space can be restricted, including another editor, and lifting it takes a SLOW vote.
const restrict = geo.daoSpaces.restrictMemberFastPath({
  authorSpaceId: editorSpaceId,
  spaceId: daoSpaceId,
  memberSpaceId,
});

// Lifting a restriction is a governance action: SLOW proposal only.
const unrestrict = geo.daoSpaces.proposeUnrestrictMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  restrictedMemberSpaceId: memberSpaceId,
});

// Adds a space and lifts its restriction in one SLOW proposal (addMember, then unrestrictSpace).
// The way back to fast-path access for a space that left while restricted: a restricted space can't request membership itself.
const addBack = geo.daoSpaces.proposeAddMemberWithFastPath({
  authorSpaceId,
  spaceId: daoSpaceId,
  newMemberSpaceId: memberSpaceId,
});

仅使用 proposeAddMemberWithFastPath 对于已经不是成员或编辑器的空间,一旦添加,将保留限制(DAO限制新成员,或者空间已经限制). 否则,该提案将无法执行.

请求加入 DAO 空间 :

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

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

DAO建议 ID 和 DAO 空间 ID 是 bytes16 十六元字符串,通常是 0x 加上32个十六进制字符.

就一项提案进行表决:

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

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

versionId 默认为 1在对后一提案进行表决时明确通过 版本.

执行已通过的提案:

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

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

geo.responses

在三个独立轴线上响应一个实体:

  • 校正 : upvote, (中文(简体) ), downvote,以及 unvote
  • 斯丹斯: agree, (中文(简体) ), disagree,以及 unagree
  • 速度 : verify, (中文(简体) ), dispute,以及 unverify

每个清晰的方法只去除其匹配的响应类型. 譬如说, unverify 不从同一个用户中去掉一个上标或协议.

创建目录响应调用数据 :

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

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

const unvote = geo.responses.unvote({
  authorSpaceId,
  spaceId,
  entityId,
});

创建姿态响应呼叫数据 :

const agree = geo.responses.agree({ authorSpaceId, spaceId, entityId });
const disagree = geo.responses.disagree({ authorSpaceId, spaceId, entityId });
const unagree = geo.responses.unagree({ authorSpaceId, spaceId, entityId });

创建真实响应调用数据 :

const verify = geo.responses.verify({ authorSpaceId, spaceId, entityId });
const dispute = geo.responses.dispute({ authorSpaceId, spaceId, entityId });
const unverify = geo.responses.unverify({
  authorSpaceId,
  spaceId,
  entityId,
});

用钱包客户端提交任何已返回的交易 :

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

附有担保钱包的完整出版流程

此示例使用被赞助者发布编辑到已有个人空间 地理钱包客户端 .

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

const privateKey = `0x${privateKeyFromGeoWallet}` as `0x${string}`;
const signer = privateKeyToAccount(privateKey);
const geo = createGeoClient({ network: GeoTestnetConfig });
const walletClient = await createGeoWalletClient({
  signer,
  network: GeoTestnetConfig,
});
const accountAddress = signer.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 walletClient.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});

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

完整的个人空间创建流程

此示例创建了带有 EOA 钱包的个人空间, 然后发布初始配置 ops 返回 geo.personalSpaces.create(...)。 。 。 .

import { createPublicClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import {
  GeoTestnetConfig,
  createGeoClient,
  createGeoWalletClient,
} 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 createGeoWalletClient({
  signer: account,
  network: GeoTestnetConfig,
});

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);

公用事业

身份证

实体、财产、关系、空间和提议使用全球独特的身份证。 犬科SDK ID是一个UUID v4,没有破折号.

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

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

职位

Position 为定单关系和其他定单项目提供分数索引帮助.

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

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

钱包客户端

createGeoWalletClient 是提交 SDK 交易的默认方式. 它默认使用来自网络的Geo赞助交易配置.

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

const walletClient = await createGeoWalletClient({
  signer,
  network: GeoTestnetConfig,
});

小心私钥. 不要让他们接受版本控制.

遗产 API

遗留的命名空间仍为兼容性导出, 但新代码更可取 Ops 财务报告和审定财务报表 createGeoClient。 。 。 .

遗产 API首选 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(...) 或者说 Ops.comments.create(...) 附有答复的上下文
TextBlock.make(...)Ops.textBlocks.create(...)
DataBlock.make(...)Ops.dataBlocks.create(...)
Ipfs.publishEdit(...)geo.personalSpaces.publishEdit(...) 或者说 geo.daoSpaces.proposeEdit(...)
Ipfs.uploadImage(...)geo.storage.uploadImage(...)
Ipfs.uploadCSV(...)geo.storage.uploadCSV(...)
personalSpace.*geo.personalSpaces.*
daoSpace.*geo.daoSpaces.*
根编码助手在可用的情况下配置客户端交易助手

遗产 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",
});

遗产关系助手 :

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,
});

遗产图像和评论助手 :

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",
});

遗产 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");

遗产 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",
});

遗产 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,
  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",
});

遗产DAO成员帮助者:

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

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

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

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

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

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

遗留编码帮助

当需要精确的调用数据原始数据时,低等编码帮助器仍然可用以兼容性:

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",
);

版本与发布记录

@geoprotocol/geo-sdk 共发布 52 个版本,首次发布于 2026/01/23;过去 12 个月发布了 52 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.20.6latest2026/11/124 天前
0.20.52026/11/124 天前
0.20.42026/11/124 天前
0.20.32026/08/063 个月前
0.20.22026/07/313 个月前
0.20.12026/07/303 个月前

其他发布通道:beta → 0.20.0-beta.10。

关于 @geoprotocol/geo-sdk 的常见问题

@geoprotocol/geo-sdk 是什么?

与"图"互动的工具集.

如何安装 @geoprotocol/geo-sdk?

在项目目录运行 npm install @geoprotocol/geo-sdk,或使用 pnpm add / yarn add / bun add。

@geoprotocol/geo-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geoprotocol/geo-sdk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geoprotocol/geo-sdk 可以商用吗?

@geoprotocol/geo-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geoprotocol/geo-sdk 的下载量有多少?

根据 npm 官方下载统计,@geoprotocol/geo-sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,983 次,日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geoprotocol/geo-sdk 还在维护吗?

最新版本 0.20.6 发布于 2026/11/12(4 天前);至今共发布 52 个版本,其中过去 12 个月发布了 52 个;首次发布于 2026/01/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。