homestar-wasm

大纲

• 描述
• 在 IPLD 和 WIT 之间进行解释

描述

这个 wasm 库管理了 wasmtime 运行时，提供从/到 Wasm Interace Types (WIT) 解释器/翻译层的 IPLD 解释器，并实现了与 Ipvm 标准的 Wasm 任务一起工作的输入接口。

更多信息，请参阅我们的 Homestar 读取说明。

在 IPLD 和 WIT 之间进行解释

我们的递归解释器能够基于已知的 WIT 接口类型，双向翻译运行时的 IPLD 数据模型 和 WIT 值。

基本类型

我们将首先介绍 WIT 基本类型。

布尔值

本节概述了 IPLD 布尔值 (Ipld::Bool) 和 WIT bool 运行时值之间的转换过程。

• IPLD 到 WIT 转换:

  当一个 WIT 函数期望一个 bool 输入时，一个 Ipld::Bool 值（无论是 true 还是 false）被映射到一个 bool WIT 运行时值。

  示例：考虑一个如下定义的 WIT 函数

  export fn: func(a: bool) -> bool;
  

  给定此函数的 JSON 输入

  {
    "args": [true]
  }
  

  true 转换为 Ipld::Bool，然后翻译并作为布尔参数（bool）传递给 fn。

• WIT 到 IPLD 的翻译:

  相反，当 WIT 函数返回布尔值时，它可以翻译回 Ipld::Bool。

IPLD 架构定义:

type IPLDBooleanAsWit bool

整数

本节概述了 IPLD 整数值（Ipld::Integer）与 WIT integer 运行时值之间的转换过程。

组件模型 支持以下这些 整数 类型。

ty ::= 'u8' | 'u16' | 'u32' | 'u64'
     | 's8' | 's16' | 's32' | 's64'

• IPLD 到 WIT 转换:

  通常，当 WIT 函数期望整数输入时，一个 Ipld::Integer 值会被映射到整数 WIT 运行时值。

  示例：考虑一个如下定义的 WIT 函数

  export fn: func(a: s32) -> s32;
  

  给定此函数的 JSON 输入

  {
    "args": [1]
  }
  

  1 转换为 Ipld::Integer，然后翻译并作为整数参数（s32）传递给 fn。

  注意：然而，如果 WIT 接口输入参数是 float 类型，但传入的值是 Ipld::Integer，则 IPLD 值将被强制转换为 float，并在剩余的计算中保持该类型。这种转换是为了提供给 JavaScript 的便利，例如，数字 1.0 转换为 1。

• WIT 到 IPLD 的翻译:

  相反，当 WIT 函数返回整数值（非浮点数）时，它可以转换回 Ipld::Integer。

IPLD 架构定义:

type IPLDIntegerAsWit union {
  | U8        int
  | U16       int
  | U32       int
  | U64       int
  | S8        int
  | S16       int
  | S32       int
  | S64       int
  | Float32In int
  | Float64In int
} representation kinded

type WitAsIpldInteger union {
  | U8          int
  | U16         int
  | U32         int
  | U64         int
  | S8          int
  | S16         int
  | S32         int
  | S64         int
  | Float32Out  float
  | Float64Out  float
} representation kinded

浮点数

本节概述了 IPLD 浮点值（Ipld::Float）与 WIT float 运行时值之间的转换过程。

组件模型 支持以下浮点类型。

ty ::= 'float32' | 'float64'

• IPLD 到 WIT 转换:

  通常，当 WIT 函数期望浮点数输入时，一个 Ipld::Float 值会被映射到浮点 WIT 运行时值。如果需要，进行从 f32 到 f64 的类型转换。

  示例：考虑一个如下定义的 WIT 函数

  export fn: func(a: f64) -> f64;
  

  给定此函数的 JSON 输入

  {
    "args": [1.0]
  }
  

  1.0 转换为 Ipld::Float，然后翻译并作为浮点参数（f64）传递给 fn。

  注意：然而，如果 WIT 接口输入参数是 WIT 整数类型之一，但传入的值是 Ipld::Integer，则 IPLD 值将被强制转换为该整数类型，并在剩余的计算中保持该类型。

• WIT 到 IPLD 的翻译:

  相反，当 WIT 函数返回 float32 或 float64 值时，它可以转换回 Ipld::Float。

  注意：在将 float32 转换为 float64 时，后者是 IPLD 的默认精度（见 IPLD），精度将会丢失。在这次转换中，解释器将使用十进制精度。

IPLD 架构定义:

type IPLDFloatAsWit union {
  | Float32 float
  | Float64 float
} representation kinded

type WitAsIpldFloat union {
  | Float32 float
  | Float64 float
} representation kinded

字符串

本节概述了 IPLD 字符串值（Ipld::String）与各种 WIT 运行时值之间的转换过程。一个 Ipld::String 值可以解释为一个 string、一个 char 或一个（没有有效负载的）enum 区分符。

• string

  • IPLD 到 WIT 转换

    当 WIT 函数期望一个 string 输入时，一个 Ipld::String 值会被映射为一个 WIT 运行时值中的 string。

    示例:

    export fn: func(a: string) -> string;
    

    给定此函数的 JSON 输入

    {
      "args": ["Saspirilla"]
    }
    

    "Saspirilla" 被转换为 Ipld::String，然后将其翻译并作为字符串参数传递给 fn。

  • WIT 到 IPLD 的翻译:

    相反，当从 WIT 函数返回一个 string 值时，它会转换回一个 Ipld::String。

• char

  • IPLD 到 WIT 转换

    当 WIT 函数期望一个 char 输入时，一个 Ipld::String 值会被映射为一个 WIT 运行时值中的 char。

    示例:

    export fn: func(a: char) -> char;
    

    给定此函数的 JSON 输入

    {
      "args": ["S"]
    }
    

    "S" 被转换为 Ipld::String，然后将其翻译并作为 char 参数传递给 fn。

  • WIT 到 IPLD 的翻译:

    相反，当从 WIT 函数返回一个 char 值时，它会转换回一个 Ipld::String。

• enum:

  枚举语句定义了一个新的类型，其语义等价于一个没有有效负载类型的变体。

  • IPLD 到 WIT 转换

    当 WIT 函数期望一个 enum 输入时，一个 Ipld::String 值会被映射为一个 WIT 运行时值中的 enum。

    示例:

    enum color {
        Red,
        Green,
        Blue
    }
    
    export fn: func(a: color) -> string;
    

    给定此函数的 JSON 输入

    {
      "args": ["Green"]
    }
    

    "Green" 被转换为 Ipld::String，然后将其翻译并作为 enum 参数传递给 fn（例如 color）。您必须提供一个匹配其中一个区分符的字符串。

  • WIT 到 IPLD 的翻译:

    相反，当从 WIT 函数返回一个 enum 值时，它可以转换回一个 Ipld::String 值。

IPLD 架构定义:

type Enum enum {
  | Red
  | Green
  | Blue
}

type IPLDStringAsWit union {
 | Enum     Enum
 | String   string
 | Char     string
 | Listu8In string
} representation kinded

type WitAsIpldString union {
 | Enum      Enum
 | String    string
 | Char      string
 | Listu8Out bytes
} representation kinded

字节

本节概述了 IPLD 字节值（Ipld::Bytes）与各种 WIT 运行时值之间的转换过程。一个 Ipld::Bytes 值可以解释为一个 list<u8> 或一个 string。

• list:

  • IPLD 到 WIT 转换

    当WIT函数期望接收一个list<u8>输入时，一个Ipld::Bytes值被映射为一个list<u8> WIT运行时值。

    示例:

    export fn: func(a: list<u8>) -> list<u8>;
    

    给定此函数的 JSON 输入

    {
      "args": [{"/": {"bytes": "aGVsbDA"}}]
    }
    

    "aGVsbDA"被转换为一个Ipld::Bytes，然后被转换成字节并作为一个list<u8>参数传递给fn。

  • WIT 到 IPLD 的翻译:

    相反，当一个list<u8>值从WIT函数返回时，如果列表包含有效的u8值，则将其转换回一个Ipld::Bytes值。

• string

  • IPLD 到 WIT 转换

    当WIT函数期望接收一个string输入时，一个Ipld::Bytes值被映射为一个string WIT运行时值。

    示例:

    export fn: func(a: string) -> string;
    

    给定此函数的 JSON 输入

    {
      "args": [{"/": {"bytes": "aGVsbDA"}}]
    }
    

    "aGVsbDA"被转换为一个Ipld::Bytes，然后被转换成字符串并作为一个string参数传递给fn。

  • WIT 到 IPLD 的翻译:

    在这里，当一个字符串值从WIT函数返回时，它被转换为一个Ipld::String值，因为我们无法确定它最初是bytes。.

type IPLDBytesAsWit union {
  | ListU8   bytes
  | StringIn bytes
} representation kinded

type WitAsIpldBytes union {
  | ListU8    bytes
  | StringOut string
} representation kinded

type None unit representation null

type IPLDNullAsWit union {
  | None
  | String string
} representation kinded

type WitAsIpldNull union {
  | None
  | String string
} representation kinded

type IPLDLinkAsWit &String link

type WitAsIpldLink &String link

type IPLDListAsWit union {
  | List [any]
  | Tuple [any]
  | Flags [string]
} representation kinded

type WitAsIpldList union {
  | List [any]
  | Tuple [any]
  | Flags [string]
} representation kinded

type TupleAsMap {string:any} representation listpairs

type IPLDMapAsWit union {
  | Record {string:any}
  | Variant {string:any}
  | List TupleAsMap
} representation kinded

type WitAsIpldMap union {
  | Record {string:any}
  | Variant {string:any}
  | List TupleAsMap
} representation kinded

type IpldAsWitOption union {
  | Some any
  | None
} representation kinded

type WitAsIpldOption union {
  | Some any
  | None
} representation kinded

type Null unit representation null

type IpldAsWitResult union {
  | Ok [any, Null]
  | Err [Null, any]
} representation kinded

type WitAsIpldResult union {
  | Ok [any, Null]
  | OkNone [1, Null]
  | Err [Null, any]
  | ErrNone [Null, 1]
} representation kinded

{
  "args": [null, null]
}