ordfs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ORDFS - Ordinals File System

ORDFS - 铭文文件系统

HTTP gateway for accessing on-chain content (inscriptions) from BSV blockchain.

Live Gateway: https://ordfs.network Repository: https://github.com/b-open-io/go-ordfs-server

用于从BSV区块链访问链上内容（铭文）的HTTP网关。

在线网关：https://ordfs.network 代码仓库：https://github.com/b-open-io/go-ordfs-server

Quick Reference

快速参考

Endpoint	Purpose
`/{txid}_{vout}`	Direct content access
`/content/{pointer}`	Content with options
`/content/{pointer}:{seq}`	Specific version
`/content/{pointer}/{file}`	File from directory
`/preview/{b64Html}`	Preview HTML code
`/v2/metadata/{outpoint}`	Metadata only

端点	用途
`/{txid}_{vout}`	直接访问内容
`/content/{pointer}`	带选项的内容访问
`/content/{pointer}:{seq}`	特定版本内容
`/content/{pointer}/{file}`	目录中的文件
`/preview/{b64Html}`	预览HTML代码
`/v2/metadata/{outpoint}`	仅获取元数据

Content Access Patterns

内容访问模式

Basic Content URL

基础内容URL

https://ordfs.network/{txid}_{vout}

Example:

https://ordfs.network/abc123...def_0

https://ordfs.network/{txid}_{vout}

示例:

https://ordfs.network/abc123...def_0

Outpoint Formats

输出点格式

All formats resolve to the same content:

Format	Example
Underscore	`abc123..._0`
Period	`abc123....0`
Txid only	`abc123...` (defaults to vout 0)

所有格式都指向相同内容：

格式	示例
下划线分隔	`abc123..._0`
点分隔	`abc123....0`
仅Txid	`abc123...` （默认使用vout 0）

Content Endpoint with Options

带选项的内容端点

/content/{pointer}[:{sequence}][/{filepath}]

Query Parameters:

Param	Default	Description
`content`	true	Include content data
`map`	false	Include MAP metadata
`out`	false	Include raw output (base64)
`parent`	false	Include parent reference
`raw`	-	Return directory JSON instead of index.html

Examples:

/content/abc123..._0?map=true          # With MAP metadata
/content/abc123..._0?content=false     # Metadata only
/content/abc123..._0?raw               # Directory listing

/content/{pointer}[:{sequence}][/{filepath}]

查询参数:

参数	默认值	说明
`content`	true	包含内容数据
`map`	false	包含MAP元数据
`out`	false	包含原始输出（base64编码）
`parent`	false	包含父级引用
`raw`	-	返回目录JSON而非index.html

示例:

/content/abc123..._0?map=true          # 包含MAP元数据
/content/abc123..._0?content=false     # 仅获取元数据
/content/abc123..._0?raw               # 目录列表

Sequence Versioning

版本序列管理

Track inscription updates using sequence numbers.

通过序列号跟踪铭文更新。

Special "-1" (Latest)

特殊值“-1”（最新版本）

/content/{pointer}         # Same as :-1, gets latest version
/content/{pointer}:-1      # Explicit latest

Behavior: Short TTL caching (60s), returns most recent version.

/content/{pointer}         # 等同于:-1，获取最新版本
/content/{pointer}:-1      # 显式指定最新版本

行为: 短TTL缓存（60秒），返回最新版本内容。

Specific Sequence

特定版本序列

/content/{pointer}:0       # Original inscription
/content/{pointer}:5       # 5th update

Behavior: Long TTL caching (30 days), immutable content.

/content/{pointer}:0       # 原始铭文
/content/{pointer}:5       # 第5次更新版本

行为: 长TTL缓存（30天），内容不可变。

Response Headers

响应头

Header	Description
`X-Outpoint`	Current outpoint
`X-Origin`	Original inscription outpoint
`X-Ord-Seq`	Sequence number
`X-Map`	JSON MAP metadata
`X-Parent`	Parent inscription outpoint

响应头	说明
`X-Outpoint`	当前输出点
`X-Origin`	原始铭文输出点
`X-Ord-Seq`	版本序列号
`X-Map`	JSON格式的MAP元数据
`X-Parent`	父级铭文输出点

Directories (ord-fs/json)

目录（ord-fs/json）

Inscriptions with content type

ord-fs/json

represent directories.

内容类型为

ord-fs/json

的铭文代表目录。

Directory Format

目录格式

json

{
  "index.html": "ord://abc123..._0",
  "style.css": "abc123..._1",
  "app.js": "def456..._0"
}

Values can be:

```
ord://txid_vout
```
- Full ordinal reference
```
txid_vout
```
or
```
txid
```
- Direct reference

json

{
  "index.html": "ord://abc123..._0",
  "style.css": "abc123..._1",
  "app.js": "def456..._0"
}

值可以是:

```
ord://txid_vout
```
- 完整序数引用
```
txid_vout
```
或
```
txid
```
- 直接引用

Accessing Directory Files

访问目录中的文件

/content/{directory_pointer}/index.html
/content/{directory_pointer}/style.css
/content/{directory_pointer}/app.js

/content/{directory_pointer}/index.html
/content/{directory_pointer}/style.css
/content/{directory_pointer}/app.js

SPA Routing

SPA路由

For SPAs, unknown paths fall back to

index.html

/content/{pointer}/unknown/path  → Returns index.html

对于单页应用（SPA），未知路径会回退到

index.html

/content/{pointer}/unknown/path  → 返回index.html

Raw Directory JSON

原始目录JSON

Add

?raw

to get the directory listing instead of index.html:

/content/{pointer}?raw

添加

?raw

参数可获取目录列表的JSON数据，而非index.html:

/content/{pointer}?raw

Preview Endpoint

预览端点

Test HTML inscriptions before broadcasting.

在广播前测试HTML铭文。

Base64 HTML Preview

Base64编码HTML预览

/preview/{base64EncodedHtml}

Example:

javascript

const html = "<html><body>Hello!</body></html>";
const b64 = btoa(html);
const previewUrl = `https://ordfs.network/preview/${b64}`;

/preview/{base64EncodedHtml}

示例:

javascript

const html = "<html><body>Hello!</body></html>";
const b64 = btoa(html);
const previewUrl = `https://ordfs.network/preview/${b64}`;

POST Preview

POST方式预览

bash

curl -X POST https://ordfs.network/preview \
  -H "Content-Type: text/html" \
  -d "<html><body>Hello!</body></html>"

bash

curl -X POST https://ordfs.network/preview \
  -H "Content-Type: text/html" \
  -d "<html><body>Hello!</body></html>"

Recursive Inscriptions

递归铭文

Reference other inscriptions from HTML/JS content.

在HTML/JS内容中引用其他铭文。

Pattern

模式

html

<script src="/content/abc123..._0"></script>
<img src="/def456..._0" />
<link href="/content/style123..._0/main.css" rel="stylesheet">

html

<script src="/content/abc123..._0"></script>
<img src="/def456..._0" />
<link href="/content/style123..._0/main.css" rel="stylesheet">

Base Path Handling

基础路径处理

ORDFS sets up base paths for recursive content to resolve correctly.

ORDFS会为递归内容设置基础路径，确保引用正确解析。

API Endpoints

API端点

V1 Endpoints

V1端点

Endpoint	Purpose
`/v1/bsv/block/latest`	Latest block info
`/v1/bsv/block/height/{h}`	Block by height
`/v1/bsv/block/hash/{hash}`	Block by hash
`/v1/bsv/tx/{txid}`	Raw transaction

端点	用途
`/v1/bsv/block/latest`	获取最新区块信息
`/v1/bsv/block/height/{h}`	通过高度获取区块
`/v1/bsv/block/hash/{hash}`	通过哈希获取区块
`/v1/bsv/tx/{txid}`	获取原始交易数据

V2 Endpoints

V2端点

Endpoint	Purpose
`/v2/tx/{txid}`	Raw transaction
`/v2/tx/{txid}/proof`	Merkle proof
`/v2/tx/{txid}/beef`	BEEF format proof
`/v2/tx/{txid}/{vout}`	Specific output
`/v2/block/tip`	Latest block header
`/v2/chain/height`	Current height
`/v2/metadata/{outpoint}`	Inscription metadata
`/v2/stream/{outpoint}`	Streaming content

端点	用途
`/v2/tx/{txid}`	获取原始交易数据
`/v2/tx/{txid}/proof`	获取默克尔证明
`/v2/tx/{txid}/beef`	获取BEEF格式的证明
`/v2/tx/{txid}/{vout}`	获取指定输出
`/v2/block/tip`	获取最新区块头
`/v2/chain/height`	获取当前区块高度
`/v2/metadata/{outpoint}`	获取铭文元数据
`/v2/stream/{outpoint}`	流式获取内容

DNS-Based Access

基于DNS的访问

Map custom domains to inscriptions.

将自定义域名映射到铭文。

DNS TXT Record

DNS TXT记录

Create

_ordfs.yourdomain.com

_ordfs.yourdomain.com IN TXT "ordfs=abc123..._0:5"

Format:

ordfs={pointer}[:{sequence}]

创建

_ordfs.yourdomain.com

记录：

_ordfs.yourdomain.com IN TXT "ordfs=abc123..._0:5"

格式：

ordfs={pointer}[:{sequence}]

How It Works

工作原理

User visits
```
yourdomain.com/path/to/file
```
ORDFS resolves DNS TXT record
Returns content from inscription directory

用户访问
```
yourdomain.com/path/to/file
```
ORDFS解析DNS TXT记录
返回对应铭文目录中的内容

Common Usage Patterns

常见使用模式

Image Display

图片展示

typescript

// Using bitcoin-image for normalization
import { getDisplayUrl } from "bitcoin-image";

const imageUrl = await getDisplayUrl("ord://abc123..._0");
// Returns: https://ordfs.network/abc123..._0

// Direct construction
const url = `https://ordfs.network/${txid}_${vout}`;

typescript

// 使用bitcoin-image进行URL标准化
import { getDisplayUrl } from "bitcoin-image";

const imageUrl = await getDisplayUrl("ord://abc123..._0");
// 返回：https://ordfs.network/abc123..._0

// 直接构造URL
const url = `https://ordfs.network/${txid}_${vout}`;

Fetch Content

获取内容

typescript

// Get inscription content
const response = await fetch(`https://ordfs.network/${origin}`);
const content = await response.text();

// Get with metadata
const metaResponse = await fetch(
  `https://ordfs.network/content/${origin}?map=true`
);
const mapData = metaResponse.headers.get("X-Map");

typescript

// 获取铭文内容
const response = await fetch(`https://ordfs.network/${origin}`);
const content = await response.text();

// 附带元数据获取
const metaResponse = await fetch(
  `https://ordfs.network/content/${origin}?map=true`
);
const mapData = metaResponse.headers.get("X-Map");

Check Latest Version

检查最新版本

typescript

// Get latest sequence
const response = await fetch(`https://ordfs.network/content/${origin}`);
const sequence = response.headers.get("X-Ord-Seq");
const currentOutpoint = response.headers.get("X-Outpoint");

typescript

// 获取最新版本序列
const response = await fetch(`https://ordfs.network/content/${origin}`);
const sequence = response.headers.get("X-Ord-Seq");
const currentOutpoint = response.headers.get("X-Outpoint");

Caching Behavior

缓存行为

Request Type	Cache TTL
Specific sequence ( `:N` )	30 days
Latest sequence (default)	60 seconds
Block headers (depth 100+)	30 days
Block headers (depth 4-99)	1 hour
Block tip	No cache

请求类型	缓存有效期（TTL）
特定版本序列（ `:N` ）	30天
最新版本（默认）	60秒
区块头（深度100+）	30天
区块头（深度4-99）	1小时
区块顶端	无缓存

ordfs

Original

Translation

ORDFS - Ordinals File System

ORDFS - 铭文文件系统

Quick Reference

快速参考

Content Access Patterns

内容访问模式

Basic Content URL

基础内容URL

Outpoint Formats

输出点格式

Content Endpoint with Options

带选项的内容端点

Sequence Versioning

版本序列管理

Special "-1" (Latest)

特殊值“-1”（最新版本）

Specific Sequence

特定版本序列

Response Headers

响应头

Directories (ord-fs/json)

目录（ord-fs/json）

Directory Format

目录格式

Accessing Directory Files

访问目录中的文件

SPA Routing

SPA路由

Raw Directory JSON

原始目录JSON

Preview Endpoint

预览端点

Base64 HTML Preview

Base64编码HTML预览

POST Preview

POST方式预览

Recursive Inscriptions

递归铭文

Pattern

模式

Base Path Handling

基础路径处理

API Endpoints

API端点

V1 Endpoints

V1端点

V2 Endpoints

V2端点

DNS-Based Access

基于DNS的访问

DNS TXT Record

DNS TXT记录

How It Works

工作原理

Common Usage Patterns

常见使用模式

Image Display

图片展示

Fetch Content

获取内容

Check Latest Version

检查最新版本

Caching Behavior

缓存行为

Additional Resources

其他资源

Reference Files

参考文档

Examples

示例代码

Related Packages

相关包