本文详细梳理了两者的每一个主要区别，帮助你在选择服务商或构建统一抽象层时做出明智的决策。

认证方式

Anthropic 强制要求 anthropic-version 头来锁定 API 行为版本，将 API 版本管理与模型名称解耦。OpenAI 则通过模型名称和接口变更来实现版本控制。

系统提示词

这是两者之间最直观的架构差异之一。

OpenAI 将系统提示词放在 messages 数组内部：

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ]
}

Anthropic 使用独立的顶层 system 参数，与消息数组完全分离：

{
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Anthropic 的 system 字段还支持内容块数组（不仅仅是字符串），从而可以通过 cache_control 对系统提示词进行缓存。

消息角色与排序

OpenAI 有 4 种不同角色，Anthropic 只有 2 种（user 和 assistant）。Anthropic 严格要求消息交替排列——不能连续出现两条相同角色的消息。OpenAI 则更灵活，会自动拼接同角色的连续消息。

响应格式

OpenAI 将响应包装在 choices 数组中（支持通过 n 参数生成多个补全）：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello!"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 7,
    "total_tokens": 20
  }
}

Anthropic 直接返回类型化的内容块数组：

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "Hello!"}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 13,
    "output_tokens": 7,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

关键参数

迁移时最容易踩的两个坑：Anthropic 强制要求每个请求都设置 max_tokens（OpenAI 默认使用模型最大值），以及 Anthropic 的温度范围上限为 1.0，而 OpenAI 可达 2.0。

工具调用 / 函数调用

这是两个 API 之间最大的架构分歧之一。

工具定义

OpenAI 使用 type/function 包装结构：

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather for a location",
      "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }
  }]
}

Anthropic 采用更扁平的结构，使用 input_schema：

{
  "tools": [{
    "name": "get_weather",
    "description": "Get weather for a location",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"]
    }
  }]
}

响应中的工具调用

OpenAI 通过独立的 tool_calls 数组返回工具调用，参数为需要解析的 JSON 字符串：

"tool_calls": [{
  "id": "call_abc123",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris\"}"
  }
}]

Anthropic 以内容块形式返回工具调用，input 为已解析的 JSON 对象：

"content": [{
  "type": "tool_use",
  "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
  "name": "get_weather",
  "input": {"location": "Paris"}
}]

返回工具结果

OpenAI 使用专用的 tool 角色：

{"role": "tool", "tool_call_id": "call_abc123", "content": "Sunny, 22C"}

Anthropic 将工具结果作为内容块放在 user 消息中，并提供显式的 is_error 标志：

{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01D7...",
    "content": "Sunny, 22C",
    "is_error": false
  }]
}

工具选择

视觉 / 多模态

OpenAI 使用 data URL 方案编码 base64 图片：

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,{BASE64_DATA}",
    "detail": "high"
  }
}

Anthropic 使用独立字段分别指定媒体类型和数据：

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "BASE64_DATA"
  }
}

Anthropic 拥有独特的一等公民 document 块类型，支持 PDF 和文本文件，并可选启用引用功能——这是 OpenAI Chat Completions 接口所不具备的。

流式传输

两个 API 都使用 Server-Sent Events，但事件结构截然不同。

OpenAI 使用扁平的无名称 data: 行流，以 data: [DONE] 结束：

data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

Anthropic 使用命名事件类型，具有结构化的生命周期：

event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_start
data: {"type":"content_block_start","index":0,...}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_stop
data: {"type":"message_stop"}

Anthropic 的流式传输更为精细，包含 6 种以上的命名事件类型，覆盖完整的消息生命周期。这使得处理混合内容（文本与工具调用交织）更加方便，但增加了解析复杂度。OpenAI 的方式更简洁——本质上只有一种事件类型加一个终止标记。

错误处理

OpenAI 包含 param 字段，指明是哪个参数导致了错误：

{
  "error": {
    "message": "Incorrect API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic 使用基于 type 的辨别模式：

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Anthropic 将 overloaded_error 与 api_error 区分开来，使得针对容量问题实现退避逻辑更加容易。

速率限制

两者在遇到速率限制时都返回 HTTP 429，并建议使用指数退避加随机抖动。

各自独有的功能

OpenAI 独有

• 多个补全——n 参数可在单次请求中生成 N 个替代回复
• 对数概率——logprobs 返回 token 级别的概率信息
• 结构化输出——response_format 配合 json_schema 保证 JSON 结构
• 频率/存在惩罚用于控制重复
• 音频输入/输出多模态消息支持
• 种子参数用于可复现输出

Anthropic 独有

• 扩展思考——显式 thinking 参数配合 budget_tokens，返回可见的思考块
• 提示缓存——内容块上的 cache_control 支持 TTL 选项，使用量数据中包含缓存命中/未命中统计
• PDF/文档处理——原生 document 内容块，支持引用
• Top K 采样——top_k 参数控制 token 选择
• 内置服务端工具——web_search、code_execution、text_editor 等运行在 Anthropic 基础设施上
• 工具错误标志——工具结果上的 is_error 字段

SDK 快速参考

# OpenAI
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

# Anthropic
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.content[0].text)

迁移清单

如果你正在两者之间切换，或者构建统一的抽象层，以下是需要注意的关键事项：

1. 移动系统提示词——从 messages 内部（OpenAI）移到顶层 system 字段（Anthropic），反之亦然
2. 设置 max_tokens——在 Anthropic 中为必填，在 OpenAI 中为可选
3. 限制温度范围——Anthropic 上限为 1.0；OpenAI 允许到 2.0
4. 重构工具定义——parameters vs input_schema，包装对象差异
5. 处理工具结果的方式不同——tool 角色（OpenAI）vs user 消息中的内容块（Anthropic）
6. 解析工具调用参数——JSON 字符串（OpenAI）vs 已解析对象（Anthropic）
7. 消息交替排列——Anthropic 强制要求，OpenAI 灵活处理
8. 更新认证头——Authorization: Bearer vs x-api-key + anthropic-version
9. 适配流式解析器——扁平数据块 vs 命名生命周期事件
10. 解包响应——choices[0].message.content vs content[0].text

两个 API 都很强大且设计精良，但它们体现了不同的设计哲学。OpenAI 的 Chat Completions API 倾向于灵活性和向后兼容，而 Anthropic 的 Messages API 则更注重显式性和结构化数据。理解这些差异将帮助你无论选择哪家服务商都能构建出稳健的集成方案。

This guide covers every major difference so you can make informed decisions when choosing between them or building an abstraction layer that supports both.

Authentication

Anthropic's mandatory anthropic-version header pins the API behavior to a specific version, decoupling API versioning from model names. OpenAI versions through model names and endpoint changes instead.

System Prompts

This is one of the most visible architectural differences.

OpenAI places the system prompt inside the messages array:

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ]
}

Anthropic uses a dedicated top-level system parameter, separate from the messages array:

{
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Anthropic's system field also accepts an array of content blocks (not just a string), which enables features like prompt caching on the system prompt via cache_control.

Message Roles and Ordering

OpenAI has 4 distinct roles. Anthropic has only 2 (user and assistant). Anthropic strictly requires alternating user/assistant messages—you cannot have two consecutive messages of the same role. OpenAI is more flexible and will concatenate consecutive same-role messages.

Response Format

OpenAI wraps the response in a choices array (supporting the n parameter for multiple completions):

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello!"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 7,
    "total_tokens": 20
  }
}

Anthropic returns content directly as an array of typed content blocks:

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "Hello!"}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 13,
    "output_tokens": 7,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Key Parameters

Two things often trip up developers migrating between them: Anthropic requires max_tokens in every request (OpenAI defaults to the model maximum), and Anthropic's temperature range caps at 1.0 while OpenAI goes up to 2.0.

Tool Use / Function Calling

This is one of the largest architectural divergences between the two APIs.

Tool Definition

OpenAI wraps tools in a type/function structure:

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather for a location",
      "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }
  }]
}

Anthropic uses a flatter structure with input_schema:

{
  "tools": [{
    "name": "get_weather",
    "description": "Get weather for a location",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"]
    }
  }]
}

Tool Calls in Response

OpenAI returns tool calls on a separate tool_calls array with arguments as a JSON string that must be parsed:

"tool_calls": [{
  "id": "call_abc123",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris\"}"
  }
}]

Anthropic returns tool calls as content blocks with input as a parsed JSON object:

"content": [{
  "type": "tool_use",
  "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
  "name": "get_weather",
  "input": {"location": "Paris"}
}]

Returning Tool Results

OpenAI uses a dedicated tool role:

{"role": "tool", "tool_call_id": "call_abc123", "content": "Sunny, 22C"}

Anthropic places tool results as content blocks inside a user message, with an explicit is_error flag:

{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01D7...",
    "content": "Sunny, 22C",
    "is_error": false
  }]
}

Tool Choice

Vision / Multimodal

OpenAI uses the data URL scheme for base64 images:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,{BASE64_DATA}",
    "detail": "high"
  }
}

Anthropic uses separate fields for media type and data:

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "BASE64_DATA"
  }
}

Anthropic has a unique first-class document block type for PDFs and text files with optional citation support—a feature OpenAI's Chat Completions endpoint doesn't offer.

Streaming

Both APIs use Server-Sent Events, but with fundamentally different structures.

OpenAI uses a flat stream of unnamed data: lines, ending with data: [DONE]:

data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

Anthropic uses named event types with a structured lifecycle:

event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_start
data: {"type":"content_block_start","index":0,...}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_stop
data: {"type":"message_stop"}

Anthropic's streaming is more granular with 6+ named event types covering the full message lifecycle. This makes mixed content (text interleaved with tool calls) easier to handle but adds parsing complexity. OpenAI's approach is simpler—essentially one event type plus a sentinel.

Error Handling

OpenAI includes a param field indicating which parameter caused the error:

{
  "error": {
    "message": "Incorrect API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic uses a type-based discrimination pattern:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Anthropic distinguishes overloaded_error from api_error, making it easier to implement backoff logic specifically for capacity issues.

Rate Limiting

Both return HTTP 429 for rate limit errors and recommend exponential backoff with jitter.

Unique Features

OpenAI-only

• Multiple completions — the n parameter generates N alternative responses per request
• Log probabilities — logprobs returns token-level probability information
• Structured output — response_format with json_schema for guaranteed JSON structure
• Frequency/presence penalties for controlling repetition
• Audio input/output support in multimodal messages
• Seed parameter for reproducible outputs

Anthropic-only

• Extended thinking — explicit thinking parameter with budget_tokens, returns visible thinking blocks
• Prompt caching — cache_control on content blocks with TTL options, with cache hit/miss reporting in usage
• PDF/document processing — native document content blocks with citation support
• Top K sampling — top_k parameter for controlling token selection
• Built-in server tools — web_search, code_execution, text_editor, etc. that run on Anthropic's infrastructure
• Tool error flag — is_error field on tool results

SDK Quick Reference

# OpenAI
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

# Anthropic
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.content[0].text)

Migration Checklist

If you're switching between the two or building a unified abstraction, here are the key things to watch for:

1. Move system prompts — from inside messages (OpenAI) to the top-level system field (Anthropic), or vice versa
2. Set max_tokens — it's required in Anthropic, optional in OpenAI
3. Clamp temperature — Anthropic caps at 1.0; OpenAI allows up to 2.0
4. Restructure tool definitions — parameters vs input_schema, wrapper object differences
5. Handle tool results differently — tool role (OpenAI) vs content blocks in user message (Anthropic)
6. Parse tool call arguments — JSON string (OpenAI) vs parsed object (Anthropic)
7. Enforce message alternation — required for Anthropic, flexible in OpenAI
8. Update auth headers — Authorization: Bearer vs x-api-key + anthropic-version
9. Adapt streaming parsers — flat chunks vs named lifecycle events
10. Unwrap responses — choices[0].message.content vs content[0].text

Both APIs are powerful and well-designed, but they reflect different philosophies. OpenAI's Chat Completions API leans toward flexibility and backwards compatibility, while Anthropic's Messages API favors explicitness and structured data. Understanding these differences will help you build robust integrations regardless of which provider you choose.

身份验证：Lens Chain 上的挑战-响应机制

Palus 没有使用标准的「Sign in with Ethereum」（SIWE / EIP-4361）流程，而是实现了一套由 Lens GraphQL API 驱动的自定义挑战-响应系统。签名原语相同——通过 EVM 钱包调用 personal_sign——但消息格式和验证完全由 Lens 后端处理。

链配置

链定义从 @lens-chain/sdk/viem 导入，并在 constants.ts 中配置：

import { chains } from "@lens-chain/sdk/viem";

export const IS_TESTNET = import.meta.env.VITE_USE_TESTNET === "true";
export const CHAIN = IS_TESTNET ? chains.testnet : chains.mainnet;

Web3Provider.tsx 中的 wagmi 配置为 Lens Chain（https://rpc.lens.xyz）和以太坊主网（通过 Infura）设置了传输层，并配置了四种钱包连接器：MetaMask SDK、浏览器注入钱包、WalletConnect 和 Family Accounts。

登录流程

整个流程位于 Login.tsx，分为三个步骤：

第一步：请求挑战

前端调用 Challenge.graphql 中定义的 challenge GraphQL mutation：

mutation Challenge($request: ChallengeRequest!) {
  challenge(request: $request) {
    id
    text
  }
}

ChallengeRequest 输入根据用户与账户的关系有两种形式：

• accountOwner: { owner, account, app } —— 当连接的钱包直接拥有该 Lens 账户时
• accountManager: { manager, account, app } —— 当钱包是授权管理者时

API 返回一个唯一的 id（UUID）和一个 text 字符串——这是一条自定义挑战消息，而非 SIWE 格式。

第二步：签名挑战

挑战文本通过 wagmi 的 useSignMessage hook 进行签名，该 hook 在连接的钱包上调用 personal_sign：

const signature = await signMessageAsync({
  message: challenge?.data?.challenge?.text
});

在签名之前，useHandleWrongNetwork 会确保钱包连接到正确的链。如果不在正确的链上，会通过 useSwitchChain 触发链切换。

第三步：验证身份

签名后的挑战通过 Authenticate.graphql 提交：

mutation Authenticate($request: SignedAuthChallenge!) {
  authenticate(request: $request) {
    ... on AuthenticationTokens {
      accessToken
      refreshToken
    }
    ... on ForbiddenError {
      reason
    }
  }
}

验证成功后，Lens API 返回 JWT accessToken 和 refreshToken。这些令牌存储在基于 localStorage 的 Zustand 持久化 store 中（useAuthStore.ts）。

令牌管理

身份验证完成后，每个 GraphQL 请求都通过 authLink.ts 中的 Apollo Link 中间件携带 JWT，设置 X-Access-Token 请求头。

令牌刷新由 tokenManager.ts 处理。它会检查访问令牌是否将在 5 分钟内过期，如果是，则调用 Refresh mutation，使用指数退避策略（最多重试 5 次）。去重机制确保同一时间只有一个刷新请求在进行中。

钱包选择

WalletSelector.tsx 负责钱包连接。它筛选并展示四种连接器类型：MetaMask SDK（由于已知 bug 在 Android 上禁用）、浏览器注入钱包提供者（仅在 window.ethereum 存在时显示）、WalletConnect v2 和 Family Accounts。

Grove：Lens 的内容寻址存储

Grove 是 Lens Protocol 的存储层，Palus 用它来存储所有用户生成的内容——图片、文件和 JSON 元数据（帖子内容、个人资料元数据等）。它取代 IPFS 成为主要存储后端，同时仍支持 IPFS 作为回退方案。

存储客户端

客户端在 storageClient.ts 中以零配置方式初始化：

import { StorageClient } from "@lens-chain/storage-client";

export const storageClient = StorageClient.create();

@lens-chain/storage-client 包处理与 Grove API（https://api.grove.storage/）的所有通信。

访问控制列表（ACL）

每次上传到 Grove 都包含一个 ACL，用于确定谁可以修改内容。Palus 使用 @lens-chain/storage-client 中的两种 ACL 类型：

• immutable(chainId) —— 内容永久存储，任何人都无法修改
• lensAccountOnly(account, chainId) —— 只有指定的 Lens 账户所有者可以修改内容

当提供了账户地址时（例如针对特定个人资料的内容），使用账户范围的 ACL。对于公共/共享内容，则应用不可变 ACL。

上传文件

文件上传由 uploadFiles.ts 处理。每个文件通过 storageClient.uploadFile(file, { acl }) 单独上传，响应提供一个 lens:// URI。该函数还支持 base64 编码的图片（用于分享通知截图），通过先将其转换为 File 对象来实现。

const storageNodeResponse = await storageClient.uploadFile(file, { acl });
return {
  mimeType: file.type || FALLBACK_TYPE,
  uri: storageNodeResponse.uri  // 例如 "lens://abc123..."
};

上传元数据

JSON 元数据（帖子内容等）通过 uploadMetadata.ts 中的 storageClient.uploadAsJson(data, { acl }) 上传。

该函数包含回退机制：如果 Grove 上传失败，会回退到 Thirdweb 存储（上传到 IPFS），确保即使 Grove 暂时不可用，元数据也始终能够持久化。

try {
  const upload = await storageClient.uploadAsJson(data, { acl });
  uri = upload.uri;
} catch (e) {
  // 回退到 thirdweb/IPFS
  const storage = new ThirdwebStorage({ clientId: THIRD_WEB_CLIENT_ID });
  const file = new File([JSON.stringify(data)], "metadata.json", {
    type: "application/json"
  });
  uri = await storage.upload(file, { uploadWithoutDirectory: true });
}

解析内容 URL

渲染内容时，lens:// URI 需要被解析为 HTTP URL。这由 sanitizeDStorageUrl.ts 完成，它处理多种存储协议：

• lens:// → https://api.grove.storage/
• ipfs:// → https://gw.ipfs-lens.dev/ipfs/
• ar:// → https://gateway.arweave.net/
• 原始 IPFS CID（以 Qm 开头）也会被检测并路由到 IPFS 网关

Lens API：无需密钥

位于 api.lens.xyz 的 Lens GraphQL API 是开放的——不需要 API 密钥。httpLink.ts 中的 Apollo HTTP link 只需设置一个 origin 请求头即可直接连接。需要身份验证的操作使用通过上述挑战-响应流程获取的 JWT 访问令牌。

总结

Palus 展示了钱包级签名（由 wagmi/viem 在 Lens Chain 上处理）与应用级身份验证（由 Lens GraphQL API 的挑战-响应系统处理）之间的清晰分离。内容存储通过 Grove 进行抽象，并配有合理的回退机制。整个认证令牌生命周期——从初始登录到刷新和过期——都通过 Apollo 中间件和 Zustand 状态透明管理。

Authentication: Challenge-Response on Lens Chain

Palus does not use the standard "Sign in with Ethereum" (SIWE / EIP-4361) flow. Instead, it implements a custom challenge-response system powered by the Lens GraphQL API. The signing primitive is the same — personal_sign via an EVM wallet — but the message format and verification are entirely handled by the Lens backend.

Chain Configuration

The chain is imported from @lens-chain/sdk/viem and configured in constants.ts:

import { chains } from "@lens-chain/sdk/viem";

export const IS_TESTNET = import.meta.env.VITE_USE_TESTNET === "true";
export const CHAIN = IS_TESTNET ? chains.testnet : chains.mainnet;

The wagmi config in Web3Provider.tsx wires up transports for both Lens Chain (https://rpc.lens.xyz) and Ethereum mainnet (via Infura), along with four wallet connectors: MetaMask SDK, injected browser wallets, WalletConnect, and Family Accounts.

The Sign-In Flow

The entire flow lives in Login.tsx and follows three steps:

Step 1: Request a Challenge

The frontend calls the challenge GraphQL mutation defined in Challenge.graphql:

mutation Challenge($request: ChallengeRequest!) {
  challenge(request: $request) {
    id
    text
  }
}

The ChallengeRequest input can take two shapes depending on the user's relationship to the account:

• accountOwner: { owner, account, app } — when the connected wallet directly owns the Lens account
• accountManager: { manager, account, app } — when the wallet is an authorized manager

The API returns a unique id (UUID) and a text string — a custom challenge message, not a SIWE-formatted one.

Step 2: Sign the Challenge

The challenge text is signed using wagmi's useSignMessage hook, which calls personal_sign on the connected wallet:

const signature = await signMessageAsync({
  message: challenge?.data?.challenge?.text
});

Before signing, useHandleWrongNetwork ensures the wallet is connected to the correct chain. If it isn't, it triggers a chain switch via useSwitchChain.

Step 3: Authenticate

The signed challenge is submitted via Authenticate.graphql:

mutation Authenticate($request: SignedAuthChallenge!) {
  authenticate(request: $request) {
    ... on AuthenticationTokens {
      accessToken
      refreshToken
    }
    ... on ForbiddenError {
      reason
    }
  }
}

On success, the Lens API returns JWT accessToken and refreshToken pairs. These are stored in a Zustand persistent store (useAuthStore.ts) backed by localStorage.

Token Management

Once authenticated, every GraphQL request includes the JWT via an Apollo Link middleware in authLink.ts. It sets the X-Access-Token header on each request.

Token refresh is handled by tokenManager.ts, which checks if the access token is expiring within 5 minutes and, if so, calls the Refresh mutation using exponential backoff (up to 5 retries). A deduplication mechanism ensures only one refresh is in-flight at a time.

Wallet Selection

WalletSelector.tsx handles wallet connection. It filters and presents four connector types: MetaMask SDK (disabled on Android due to a known bug), injected providers (only shown when window.ethereum exists), WalletConnect v2, and Family Accounts.

Grove: Lens's Content-Addressed Storage

Grove is Lens Protocol's storage layer, used by Palus for all user-generated content — images, files, and JSON metadata (post content, profile metadata, etc.). It replaces IPFS as the primary storage backend while still supporting IPFS as a fallback.

Storage Client

The client is initialized in storageClient.ts with zero configuration:

import { StorageClient } from "@lens-chain/storage-client";

export const storageClient = StorageClient.create();

The @lens-chain/storage-client package handles all communication with the Grove API at https://api.grove.storage/.

Access Control Lists (ACLs)

Every upload to Grove includes an ACL that determines who can modify the content. Palus uses two ACL types from @lens-chain/storage-client:

• immutable(chainId) — content is permanent and cannot be modified by anyone
• lensAccountOnly(account, chainId) — only the specified Lens account owner can modify the content

When an account address is provided (e.g., for profile-specific content), the account-scoped ACL is used. For public/shared content, the immutable ACL is applied.

Uploading Files

File uploads are handled by uploadFiles.ts. Each file is uploaded individually via storageClient.uploadFile(file, { acl }), and the response provides a lens:// URI. The function also supports base64-encoded images (used for sharing notification screenshots) by converting them to File objects first.

const storageNodeResponse = await storageClient.uploadFile(file, { acl });
return {
  mimeType: file.type || FALLBACK_TYPE,
  uri: storageNodeResponse.uri  // e.g., "lens://abc123..."
};

Uploading Metadata

JSON metadata (post content, etc.) is uploaded through uploadMetadata.ts via storageClient.uploadAsJson(data, { acl }).

This function includes a fallback mechanism: if the Grove upload fails, it falls back to Thirdweb storage (which uploads to IPFS), ensuring metadata is always persisted even if Grove is temporarily unavailable.

try {
  const upload = await storageClient.uploadAsJson(data, { acl });
  uri = upload.uri;
} catch (e) {
  // Fallback to thirdweb/IPFS
  const storage = new ThirdwebStorage({ clientId: THIRD_WEB_CLIENT_ID });
  const file = new File([JSON.stringify(data)], "metadata.json", {
    type: "application/json"
  });
  uri = await storage.upload(file, { uploadWithoutDirectory: true });
}

Resolving Content URLs

When rendering content, lens:// URIs must be resolved to HTTP URLs. This is done by sanitizeDStorageUrl.ts, which handles multiple storage protocols:

• lens:// → https://api.grove.storage/
• ipfs:// → https://gw.ipfs-lens.dev/ipfs/
• ar:// → https://gateway.arweave.net/
• Raw IPFS CIDs (starting with Qm) are also detected and routed through the IPFS gateway

The Lens API: No Key Required

The Lens GraphQL API at api.lens.xyz is open — no API key is needed. The Apollo HTTP link in httpLink.ts simply sets an origin header and connects directly. Authenticated operations use the JWT access token obtained through the challenge-response flow described above.

Summary

Palus demonstrates a clean separation between wallet-level signing (handled by wagmi/viem on Lens Chain) and application-level authentication (handled by the Lens GraphQL API's challenge-response system). Content storage is abstracted through Grove with sensible fallbacks, and the entire auth token lifecycle — from initial sign-in through refresh and expiry — is managed transparently via Apollo middleware and Zustand state.

• Diagnosed and fixed the "AI response did not include content" error that appeared when using Gemma4 via Ollama
• Root cause: Gemma4 sends thinking tokens in delta.reasoning with empty delta.content, and sometimes produces zero content tokens after tool calls
• Added parsing for delta.reasoning and delta.reasoning_content fields in the SSE streaming parser
• Reasoning text is streamed to the UI in real-time so users see the model thinking
• When content is empty but reasoning exists, reasoning is used as fallback content
• Added retry logic for empty responses after tool execution

Key decisions

• Chose to use reasoning as fallback content rather than silently discarding it, since for some models that's the only output produced
• Added one retry on empty post-tool responses before throwing the error, giving the model a second chance
• Supported both reasoning (Ollama/Gemma4) and reasoning_content (DeepSeek-style) field names for broader compatibility

Files changed

• Planet/Views/Articles/ArticleAIChatView.swift — Added reasoning field parsing in SSE streaming, fallback content logic, and retry on empty post-tool responses

• Writer media — Continuity Camera import from iPhone, video compression controls with FPS display and revert-to-original flow, media paste in title and body fields, markdown and text file drop support
• Publishing destinations — Cloudflare Pages publishing with token verification and deploy logging, SSH rsync (#453), new Publishing settings tab with IPNS toggle
• AI article assistant — In-article AI chat with SSE streaming and tool use, write_article with append mode and heading extraction, support for local network AI servers
• Hybrid search — BM25 + vector semantic search, multi-language NLEmbedding with automatic language detection, CJK tokenization, search API endpoint with preview word boundary snapping
• Custom Finder app icon — Apply custom icon via NSWorkspace.setIcon with security-scoped bookmarks and bookmark validation
• IPFS tools sheet — View IPFS peer identity, publish logging
• Prevent computer sleep — Option to keep Mac awake during long-running operations

Improvements

• Article selection & navigation — Restore last selected article on launch, auto-scroll sidebar, preserve selection after saving/moving drafts, navigate to existing planet when re-following, FollowingPlanet avatar jump in toolbar
• QuickPost & Writer editing — Auto-expand QuickPost height, numbered list and markdown todo autocomplete, discard confirmation, Writer auto-focus title with Tab/Enter/Shift-Tab navigation, Retina screenshot logical width in image tags
• Publish reliability — Concurrent publish guard preventing overlapping IPFS/rsync/Cloudflare deploys, atomic writes for all persistent data and published content, await HTML rendering before publish, skip rebuilding unchanged planet edits
• Performance — Optimized article list for unread view with many items, fixed main thread blocking on sidebar switch, full CPU utilization during rebuild, publish log building off main thread, improved search responsiveness
• UI polish — Smart Feeds icon shadows, white pinned article icon when selected, star and unread dot vertical alignment fixes, filter button layout for macOS 26, sidebar context menu icons, UUID row in Edit Planet info
• Dependencies — Replaced ENSKit with lightweight ENSDataKit, removed unused HDWalletKit, updated Sparkle to 2.9.0
• Site templates & feeds — Multiple template updates, allow templates without assets directory, podcast author name, .jpeg media label support
• Developer tooling — Helper scripts for tag management, commit summaries, and changelog generation; Flask-based Sparkle release notes generator with search and Planet API sync

Bug Fixes

• CJK input method — Fixed IME composing text being destroyed in Writer and QuickPost, extracted shared MarkdownEditorTextView
• Crash fixes — Force unwrap on invalid UUID in DraftModel.load, force unwraps in GPS stripping on corrupt EXIF data, try! crash on IPFS repo directory listing at launch
• Publish pipeline — Rebuild progress bar accuracy, premature dismissal, and Escape key bypass; publish log viewer hangs during long runs; ops persistence and concurrency; KeychainHelper silently losing save/delete errors
• Content & rendering — DNS-type following webview blank on startup restore, .article import losing properties with batch atomicity fix, raw pixel width for image tags instead of DPI-adjusted, list rendering glitch on Enter, Quick Post media paste, aggregation correctness

Cleanup & Refactoring

• Farcaster removal — Removed all Farcaster-related features
• Memory management — Free CMarkRenderer AST node and HTML buffer, removed unnecessary C string pointer usage
• Code deduplication — Reduced duplicated code in MyPlanetSidebarItem, extracted shared settings layout components, refactored MyPlanetModel.prewarm, simplified dependency graph

• Continuity Camera — Import photos and videos directly from iPhone into Writer
• Video compression — Video info row in Writer, compression controls with real-time FPS readout during export, Revert to Original flow for compressed videos
• Media paste & markdown drop — Paste images and videos into Writer body and title fields, drag-and-drop markdown and text files as article content
• Publishing destinations — Cloudflare Pages publishing with token verification, SSH rsync as optional destination (#453), new Publishing settings tab with IPNS toggle
• AI chat assistant — In-article AI chat view with SSE streaming, tool use support (write_article with append mode and h1 extraction), configurable AI servers including local network discovery
• QuickPost enhancements — Auto-expanding editor height, numbered list and todo autocomplete, discard confirmation dialog, unified autocomplete rules shared with Writer
• Prevent computer sleep — Option to keep the Mac awake while Planet is running
• External data monitoring — Directory monitor detects external changes to planet JSON data and triggers live updates

Improvements

• Article selection & navigation — Restore last selected article on launch, auto-scroll sidebar to selection, preserve selection after saving or moving drafts, add FollowingPlanet avatar jump in article toolbar
• Performance — Optimize article list for unread view with many items, avoid rebuilding unchanged planet edits, improve search responsiveness, fix main thread blocking when switching sidebar views
• Writer focus flow — Auto-focus title on open, Tab/Enter to move to body, Shift-Tab back to title
• Follow UX — Improved follow action with avatar resolution, navigate to existing planet when re-following a known feed
• IPFS & publishing — Refined daemon status labels, reload article when IPFS comes online, added publish logging, downgrade IPNS keepalive errors to warning
• Dependencies — Replaced ENSKit with lightweight ENSDataKit, removed unused HDWalletKit, updated Sparkle to 2.9.0
• UI polish — Social symbols with Juicebox moved to Social tab, new symbol assets (git, markdown), Cloudflare and iTerm menu icons, .jpeg added to media labels, macOS 26 filter button layout, author name in podcast feed, site template updates

Bug Fixes

• Article list alignment — Fix star icon, unread dot, and text vertical alignment across article list items; fix star visibility and pinned icon color when row is selected
• QuickPost CJK input — Fix input method (IME) composing text being destroyed during CJK entry
• Media handling — Fix Quick Post media paste not processing attachments correctly
• CMarkRenderer memory — Free AST node and HTML buffer after rendering, validate buffer, replace C string pointer usage with native Swift handling
• Ops persistence — Fix persistence and concurrency issues in the operations queue

Cleanup & Refactoring

• Remove Farcaster — Strip all Farcaster-related features from the codebase
• Code organization — Deduplicate MyPlanetSidebarItem, extract shared settings layout components, move ArticleAIChatView to its own file, simplify MyPlanetModel.prewarm
• Developer tooling — Shell scripts for tag changelogs (what.sh), commit summaries (progress.sh), and tag creation (tag.sh); improved pre-commit versioning hook; build documentation and agent context files