算盘示例

挑战

决议

爬虫

团队

本次黑客马拉松的参赛作品由以下人员提交：

1. 约书亚·奥莫博拉（@koha）：https://github.com/kohasummons
2. Mercy Thaddeus（@mercythaddeus）：https://github.com/ThaddeusMercy
3. 安德鲁·米拉克尔：https://github.com/koolamusic
4. MJ（@0xilance）：https://github.com/0xilance

挑战

在学习新的智能合约语言时，在学习了语法和数据类型之后，最好的方法之一是通过示例、样板和探索各种策略来实现你在之前的语言中会做的事情。在 Web3 领域，有一些策略已被证明是有效的。

1. Openzeppelin 库格式
2. Scaffold（“插入 ETH、Stark、Soroban”）格式
3. 以“智能合约语言”为例
4. 工厂合同+向导和生成器

我们可以轻松地将它们分组为魔力象限中的“引导程序” - “样板” - “库”，这些不同的策略使您能够快速地从新0 - 1的智能合约语言中转换。

毋庸置疑，基于项目的学习是精通 Soroban 的最有效方法，就像精通任何其他智能合约语言或编程语言一样。然而，Soroban 带来的艰巨挑战，尤其对于使用过 Solidity 等更广泛智能合约语言的开发者而言，在于其乍一看令人望而生畏的外观。对于不熟悉 Rust 的人来说，Soroban 的语法和概念可能显得陌生且难以理解，这构成了巨大的入门门槛。这种陌生感和感知到的复杂性导致区块链开发者坚持使用他们更熟悉的语言，尽管 Soroban 可能带来潜在的优势。

决议

我们构建的Soroban by Example是一个综合资源，旨在帮助开发人员，特别是那些从 Solidity 等其他智能合约语言过渡的开发人员，通过基于项目的方法学习和采用 Soroban。

算盘示例的主要目标

1. 熟悉度：帮助开发人员从其他智能合约语言中找到知名概念的实现
2. 开发人员体验：为出色的 DX 提供交互式且用户友好的文档浏览器
3. 简单性：保持示例片段干净、简单，并专注于核心概念
4. 集成游乐场：允许开发人员探索、修改和尝试示例合约
5. 人工智能辅助变体：使用人工智能助手生成示例合同的定制变体

💡 然而，尽管我们胸怀远大目标，但在尝试将世界融入 Soroban 的过程中仍面临一些挑战。本质上，我们需要研究更流行的区块链生态系统及其范式，以适应 Stellar 上的智能合约编写方式。

• ZERO_ADDRESSEVM 具有用于刻录代币和 NFT 并执行大量修改功能的概念，然而，这与 Soroban 的上下文无关，在 Soroban 中ZERO_ADDRESS，模块是无用的，而不是修改器，更受欢迎

• Solidity 是最流行的智能合约语言，它使用继承作为可扩展性的一种形式，但这不适用于 Soroban，因为您需要的主机端的所有资源都可以通过传入&env函数来访问主机环境。这意味着在 Soroban 中，我们更倾向于函数组合而不是继承。

对于我们团队中的一些人来说，这是我们第一次涉足 Soroban 生态系统，即使是曾在 EVM 生态系统中担任过协议 DevRel 职位并参与过团队建设的Koha也认为 Soroban 更令人兴奋🤣。不得不适应其他更流行的智能合约语言的标准/系统，这很无聊。

我们是如何走到这一步的（我们的失败尝试）

在实现这一点之前，我们尝试过很多次来实现目标。我们的第一次尝试——AI代码生成器，旨在构建一个自定义 GPT 来学习算盘并获取示例合约。

💡 为了实现这一初始里程碑，我们必须使用 Stellar 开发者文档中的文档来训练自定义 GPT。为此，我们编写了一个简单的爬虫脚本，用于抓取开发者文档并将其分块成文本文件。爬虫脚本的具体实现请参见我们的GitHub 代码库。

然而，经过几次测试运行后，我们意识到这个 GPT 在理解 JTBD（待完成的工作）方面并不是很好，并且在rust被要求执行更高级的指令（例如生成特定类型的合同和测试）时仍然会产生幻觉。

替代路径

对于 AI 代码生成器，我们发现了一些选项，例如kapa.ai，然而经过进一步探索，我们意识到该实现存在局限性，因为它只能满足文档搜索和建议。

这也意味着我们无法避免自己手动整理示例并逐一审查每个出版物。

最终决议

经过多次试验和错误之后，我们决定最好的方法是手动管理每个示例合约，并训练/微调一个名为“Soroboy”的示例生成器模型——Soroboy 与 GPT 不同，因为这次它将存在于示例智能合约页面的上下文中。

我们首先在Notion 工作区中整理所有合约示例，并跟踪它们的 Okashi Playground 链接。这意味着从核心概念入手，并生成基准合约，这是一个很好的起点。

当用户访问我们的示例网站时，他们可以与 Soroboy 进行对话以生成该页面上的合同示例的变体。

在下面的例子中，Soroboy 能够生成only_owner具有多个所有者而不是一个所有者的合约变体

动图

为了实现这一点，我们必须手动整理算盘合约，并对其进行审核。这方面的探索侧重于基于示例训练人工智能模型，以便模型能够利用这些示例进行情境探索。我们的想法是生成现有合约的变体。工作流程大致如下。

• 以现有的算盘为例
• 根据特定用例修改合同的输入提示
• 根据上下文和新的“用例”指令生成新的示例代码

💡 为了实现这一点，我们使用了 Vector 存储库LanceDB ，它是一个用Rust构建的内存数据库，并使用 [Apache-Arrow 数据格式] 进行紧凑存储。

Lance 非常适合这次探索，因为你所有的向量嵌入都只是一些可以在 GitHub 上追踪的文件。你可以看看我们的rag embeddings，了解一下它是什么样子的。

对于生成功能，API 调用目前路由至 OpenAI GPT-4o。为了能够将 AI 模块注入文档页面，我们必须实现一个自定义的 React 库和 API 服务器来管理相关交互。

偏离原计划

我们最终执行的几件事不在我们的原计划之内，那就是将 Okashi 游乐场嵌入到文档网站中。

如果你查看我们的Root Notion 数据库，你会注意到，我们所有的文档页面在准备阶段都提供了自己的Okashi游乐场。我们选择 Okashi 是因为它使用起来非常简单，而且我们不需要维护一个包含大量示例合约的仓库。Cargo.toml

这对于测试和探索非常有用，在开发这个项目的过程中，我们的团队想知道，如果用户能够以某种codesandbox方式简单地编译和运行这些合约，他们的体验会是什么样的。

Okashi 是我们的首选，但是 Okashi 也存在一些限制，我们希望维护人员能够开放支持，以大大改进 DX

• 复制：我们能否将 Okashi 上的合同复制到我们自己的工作区或任何地方？
• 可嵌入的小部件：我们可以在任何网站上注入 Okashi 的 iframe 版本作为小部件吗？

如果您查看我们网站上的简单算盘循环示例，您会注意到页面中嵌入了一个 Okashi 小部件。事实上，所有页面都内置了一个 Okashi 小部件。我们通过编写一个custom_proxy_server作为我们网站和 Okashi 之间的中间件来实现这一点。

该服务器只是转换了 Okashi 请求，以便我们可以获取 Okashi 的完整 DOM 对象并修改视图以适应我们的 Widget 功能。

我们认为这是一种“黑客”行为——一种相当粗暴的实现我们目的的方式，让我们能够提供项目预期的体验。我们已经在 Discord 上联系了 Morgan 和 Okashi 团队，希望能够引起他们的注意，并将此功能纳入 Okashi 的功能中。

回想起来，我认为我们低估了为了实现这个项目的核心目标我们需要做的工作量，我们生产的一些产品

1. Stellar 网站抓取工具 - https://github.com/kohasummons/crawler
2. Okashi 代理服务器 - https://github.com/koolamusic/okashi-proxy/
3. OpenAI API 服务器（非开源“repo 中的 API 密钥和环境😂”
4. 算盘示例文档网站 - https://sorobanexamples.xyz
5. ChatGPT 上的 Soroban 自定义 GPT - https://chatgpt.com/g/g-oW0Pjt0tu-soroban-v1
6. 项目存储库 — 参见 Notion 数据库
7. 所有合约示例的向量嵌入

超越黑客马拉松

Soroban 是一种令人惊叹的智能合约语言，我们打算继续维护这个项目，并探索 Soroban 并用它创建新的项目。

• Monorepo：在接下来的几周内，我们将致力于将所有代码工件整合到一个 monorepo 中，以改善代码组织和对每个模块的贡献，从而增强 Soroban by Example 的体验和交付。
• 多语言支持：整合完成后，我们将致力于整合另外三种语言“西班牙语、法语和普通话”，希望得到社区的支持

我们这个项目的目标除了提高 Soroban 生态系统的可发现性，并展示许多简单的用例和样板，以便开发人员和探索 Soroban 生态系统的个人可以与之互动之外，还将提供

• DevRel 咨询服务，旨在为生态系统内的 DevTools 构建开发者文档，从而提升面向开发者的产品开发团队的 DX 体验。我们团队的成员已在 EVM 和 Move 区块链（请填写项目名称和协议）的多个项目中担任 DevRel 角色。
• Soroban 咨询：为那些将恒星生态系统作为首选区块链以在恒星内构建创新解决方案的组织和创始人提供咨询服务

一些未来的更新

1. 改进页面上渲染示例的用户体验，以便我们可以为游乐场和静态文本添加标签，这样显示游乐场就成为像 AI 助手一样的可选功能
2. 人工智能的记忆模块用于保存新生成的代码，用于学习、微调和发布新的示例用例
3. 计量使用 AI 世代。为了可持续发展，我们可能会将 AI 世代限制为每天 100 次，本质上的目标是将我们的 OpenAI 支出保持在每天最多 5 美元以下，并每 24 小时重置一次。

灵感与脚注

我们从生态系统中的项目中汲取了很多灵感，突破了 Soroban 的可能性界限。

1. 恒星算盘示例：
2. Coinfabrik Stellar 示例
3. 数学算盘
4. iMath 算盘
5. AMM DEX 算盘
6. Solidity 示例
7. 开罗范例
8. 恒星资产代币游乐场
9. 冈西
10. Soroban Rust SDK 文档https://docs.rs/soroban-sdk/21.5.0/soroban_sdk/index.html