@typemove/sui 2.0.0 → 2.0.1-rc.1

package/src/move-coder.ts

@@ -0,0 +1,364 @@
+import { TypedSimulateResults, TypedEventInstance, TypedFunctionPayload } from './models.js'
+import {
+  AbstractMoveCoder,
+  ANY_TYPE,
+  DecodedStruct,
+  accountTypeString,
+  parseMoveType,
+  SPLITTER,
+  TypeDescriptor,
+  InternalMoveModule
+} from '@typemove/move'
+import { SuiGrpcClient } from '@mysten/sui/grpc'
+import type { GrpcTypes } from '@mysten/sui/grpc'
+import {
+  SuiChainAdapter,
+  ModuleWithAddress,
+  getGrpcClient,
+  getGrpcFullnodeUrl,
+  SuiEventInput,
+  SuiMoveObjectInput
+} from './sui-chain-adapter.js'
+import { toInternalModule } from './to-internal.js'
+import { dynamic_field } from './builtin/0x2.js'
+import { BcsType, bcs } from '@mysten/sui/bcs'
+
+// import { Encoding } from '@mysten/bcs/types', this doesn't get exported correctly
+export type Encoding = 'base58' | 'base64' | 'hex'
+
+import { normalizeSuiObjectId, normalizeSuiAddress } from '@mysten/sui/utils'
+
+export class MoveCoder extends AbstractMoveCoder<ModuleWithAddress, SuiEventInput | SuiMoveObjectInput> {
+  constructor(client: SuiGrpcClient) {
+    super(new SuiChainAdapter(client))
+  }
+
+  load(entry: ModuleWithAddress, address: string): InternalMoveModule {
+    address = accountTypeString(address)
+    const { address: moduleAddress, module } = entry
+    let m = this.moduleMapping.get(moduleAddress + '::' + module.name)
+    const mDeclared = this.moduleMapping.get(address + '::' + module.name)
+    if (m && mDeclared) {
+      return m
+    }
+    this.accounts.add(moduleAddress)
+    m = toInternalModule(module, moduleAddress)
+    this.loadInternal(m, address)
+    return m
+  }
+
+  protected async decode(data: any, type: TypeDescriptor): Promise<any> {
+    // UID handled before the switch to avoid the existing fall-through chain
+    // (case '0x2::url::Url' / '0x2::coin::Coin' bodies fire on non-string
+    // inputs and corrupt UID output). gRPC's unified Object.json flattens UID
+    // to a bare address string — re-wrap to `{ id: '0x<32-byte>' }` so
+    // downstream `.id.id`-style accessors keep working. The BCS-shaped path
+    // (`{ id: { bytes: Uint8Array(32) } }`) is delegated to super.decode,
+    // which then hits the inner ID case.
+    if (type.qname === '0x2::object::UID') {
+      if (typeof data === 'string') {
+        return { id: normalizeSuiObjectId(data) } as any
+      }
+      return super.decode(data, type)
+    }
+    switch (type.qname) {
+      case '0x1::ascii::Char':
+        if (data !== undefined && typeof data !== 'string') {
+          // bcs
+          const byte = (await super.decode(data, type)).byte as number
+          return String.fromCharCode(byte)
+        }
+      case '0x1::ascii::String':
+        if (data !== undefined && typeof data !== 'string') {
+          // bcs verified
+          const bytes = (await super.decode(data, type)).bytes as number[]
+          return new TextDecoder().decode(new Uint8Array(bytes))
+        }
+      case '0x2::object::ID':
+        if (data !== undefined && typeof data !== 'string') {
+          // bcs verified
+          const bytes = (await super.decode(data, type)).bytes as string
+          return normalizeSuiObjectId(bytes)
+        }
+      case '0x2::url::Url':
+        if (data !== undefined && typeof data !== 'string') {
+          // bcs
+          return (await super.decode(data, type)).url
+        }
+      case '0x2::coin::Coin':
+        if (data !== undefined && typeof data !== 'string') {
+          // bcs
+          const bytes = (await super.decode(data, type)).id.id.bytes as number[]
+          return new TextDecoder().decode(new Uint8Array(bytes))
+        }
+        return data
+      case '0x2::balance::Balance':
+        if (data.value) {
+          // bcs verfied
+          const balance = await super.decode(data, type)
+          return balance.value
+        }
+        return BigInt(data)
+      case '0x1::option::Option':
+        if (data === null) {
+          return data
+        }
+        if (data.vec) {
+          // bcs verifed
+          let vec = await super.decode(data, type)
+          vec = vec.vec
+          if (vec.length === 0) {
+            return null
+          }
+          return vec[0]
+        }
+        return this.decode(data, type.typeArgs[0])
+      case 'Address':
+        const str = data as string
+        return normalizeSuiAddress(str)
+      case '0x1::string::String':
+        if (typeof data !== 'string') {
+          // bcs
+          return new TextDecoder().decode(new Uint8Array(data.bytes))
+        }
+      default:
+        return super.decode(data, type)
+    }
+  }
+
+  decodeEvent<T>(event: SuiEventInput): Promise<TypedEventInstance<T> | undefined> {
+    return this.decodedStruct(event)
+  }
+  filterAndDecodeEvents<T>(
+    type: TypeDescriptor<T> | string,
+    resources: SuiEventInput[]
+  ): Promise<TypedEventInstance<T>[]> {
+    if (typeof type === 'string') {
+      type = parseMoveType(type)
+    }
+    return this.filterAndDecodeStruct(type, resources)
+  }
+
+  async getDynamicFields<T1, T2>(
+    objects: SuiMoveObjectInput[],
+    keyType: TypeDescriptor<T1> = ANY_TYPE,
+    valueType: TypeDescriptor<T2> = ANY_TYPE
+  ): Promise<dynamic_field.Field<T1, T2>[]> {
+    const type = new TypeDescriptor<dynamic_field.Field<T1, T2>>('0x2::dynamic_field::Field')
+    type.typeArgs = [keyType, valueType]
+    const res = await this.filterAndDecodeObjects(type, objects)
+    return res.map((o) => o.data_decoded)
+  }
+
+  filterAndDecodeObjects<T>(
+    type: TypeDescriptor<T>,
+    objects: SuiMoveObjectInput[]
+  ): Promise<DecodedStruct<SuiMoveObjectInput, T>[]> {
+    return this.filterAndDecodeStruct(type, objects)
+  }
+
+  // Decodes a parsed Move call payload against the loaded module ABI.
+  // Inputs are gRPC `Input[]`: kind=PURE carries a Uint8Array of BCS bytes
+  // that we decode using the corresponding parameter's Move type;
+  // object inputs (IMMUTABLE_OR_OWNED / SHARED / receiving) are surfaced as
+  // undefined since their on-chain values aren't part of the payload.
+  async decodeFunctionPayload(payload: GrpcTypes.MoveCall, inputs: GrpcTypes.Input[]): Promise<any> {
+    const functionType = [payload.package, payload.module, payload.function].join(SPLITTER)
+    const func = await this.getMoveFunction(functionType)
+    const params = this.adapter.getMeaningfulFunctionParams(func.params)
+    const args: any[] = []
+    for (const value of payload.arguments ?? []) {
+      const av = value as any
+      const idx: number | undefined = av?.input
+      if (idx == null || idx < 0 || idx >= inputs.length) {
+        args.push(undefined)
+        continue
+      }
+      const arg = inputs[idx]
+      if (arg?.pure) {
+        const paramType: TypeDescriptor | undefined = params[args.length]
+        try {
+          const bytes = arg.pure instanceof Uint8Array ? arg.pure : new Uint8Array(arg.pure)
+          const decoded: any = paramType ? await this.decodeBCS(paramType, bytes) : bytes
+          args.push(decoded)
+        } catch {
+          args.push(undefined)
+        }
+      } else {
+        // Object inputs (and unknown kinds) — value isn't carried in the payload.
+        args.push(undefined)
+      }
+    }
+
+    const argumentsTyped = await this.decodeArray(args, params, false)
+    return {
+      ...payload,
+      arguments_decoded: argumentsTyped
+    } as TypedFunctionPayload<any>
+  }
+
+  private bcsRegistered = new Set<string>()
+  private bcsRegistry = new Map<string, BcsType<any>>()
+
+  private async getBCSTypeWithArgs(type: TypeDescriptor, args: BcsType<any>[] = []): Promise<BcsType<any>> {
+    const qname = type.qname
+    const sig = type.getNormalizedSignature()
+    const cached = this.bcsRegistry.get(sig)
+    if (cached) {
+      return cached
+    }
+    const lowerQname = qname.toLowerCase()
+    switch (lowerQname) {
+      case 'u8':
+      case 'u16':
+      case 'u32':
+      case 'u64':
+      case 'u128':
+      case 'u256':
+      case 'bool':
+        return bcs[lowerQname]()
+      case 'address':
+        return bcs.Address
+      case 'vector':
+        return bcs.vector(args[0])
+      default:
+        if (!qname.includes('::')) {
+          throw `Unimplemented builtin type ${qname}`
+        }
+    }
+    let moveStruct
+    try {
+      moveStruct = await this.getMoveStruct(qname)
+    } catch (e) {
+      console.error('Invalid move address', qname)
+      throw e
+    }
+    const structDef: Record<string, any> = {}
+    for (const field of moveStruct.fields) {
+      if (field.type.qname.startsWith('T') && args.length) {
+        const index = +field.type.qname.slice(1)
+        structDef[field.name] = args[index]
+      } else if (field.type.typeArgs.length && args.length) {
+        structDef[field.name] = await this.getBCSTypeWithArgs(field.type, args)
+      } else {
+        structDef[field.name] = await this.getBCSType(field.type)
+      }
+    }
+    return bcs.struct(qname, structDef)
+  }
+
+  async getBCSType(type: TypeDescriptor): Promise<BcsType<any>> {
+    const args = await Promise.all(type.typeArgs.map((x) => this.getBCSType(x)))
+    const bcsType = await this.getBCSTypeWithArgs(type, args)
+    this.bcsRegistry.set(type.getNormalizedSignature(), bcsType)
+    return bcsType
+  }
+
+  async registerBCSTypes(type: TypeDescriptor): Promise<void> {
+    const sig = type.getNormalizedSignature()
+    if (this.bcsRegistered.has(sig)) {
+      return
+    }
+    this.bcsRegistered.add(sig)
+
+    const bcsType = await this.getBCSType(type)
+    this.bcsRegistry.set(type.getNormalizedSignature(), bcsType)
+  }
+
+  async decodeBCS(type: TypeDescriptor, data: Uint8Array | string, encoding?: Encoding): Promise<any> {
+    await this.registerBCSTypes(type)
+    if (typeof data == 'string') {
+      const buf = Buffer.from(data, encoding as any)
+      data = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+    }
+    const bcsType = this.bcsRegistry.get(type.getNormalizedSignature())
+    return bcsType?.parse(data)
+  }
+
+  // Replaces decodeDevInspectResult. gRPC simulateTransaction returns
+  // `commandResults: CommandResult[]` where each CommandResult.returnValues is
+  // `CommandOutput[]` of raw `{ bcs: Uint8Array }` — there is no per-return
+  // type string the way devInspect carried one. The caller must therefore pass
+  // the Move return-type signatures explicitly (codegen emits them next to
+  // each generated view helper).
+  async decodeSimulateResult<T extends any[]>(
+    simulateRes: any,
+    returnTypeSignatures: string[],
+    typeArguments?: (string | TypeDescriptor)[]
+  ): Promise<TypedSimulateResults<T>> {
+    // Generic view helpers embed return signatures like "T0" / "vector<T1>"
+    // at codegen time, but the caller supplies concrete type arguments only
+    // at runtime. Substitute them in before BCS decoding — otherwise the BCS
+    // type registry sees the bare type-parameter qname and rejects it as an
+    // unimplemented builtin.
+    const ctx = new Map<string, TypeDescriptor>()
+    if (typeArguments && typeArguments.length > 0) {
+      typeArguments.forEach((t, i) => {
+        ctx.set('T' + i, typeof t === 'string' ? parseMoveType(t) : t)
+      })
+    }
+
+    const returnValues: any[] = []
+    const commandResults = simulateRes?.commandResults
+    if (Array.isArray(commandResults)) {
+      let typeIdx = 0
+      for (const r of commandResults) {
+        const rvs = r?.returnValues
+        if (Array.isArray(rvs) && rvs.length > 0) {
+          for (const rv of rvs) {
+            const sig = returnTypeSignatures[typeIdx++]
+            if (!sig) {
+              returnValues.push(null)
+              continue
+            }
+            let type = parseMoveType(sig)
+            if (ctx.size > 0) {
+              type = type.applyTypeArgs(ctx)
+            }
+            const bcsBytes = rv?.bcs instanceof Uint8Array ? rv.bcs : new Uint8Array(rv?.bcs ?? [])
+            const bcsDecoded = await this.decodeBCS(type, bcsBytes)
+            const decoded = await this.decodeType(bcsDecoded, type)
+            returnValues.push(decoded)
+          }
+        } else {
+          returnValues.push(null)
+        }
+      }
+    }
+    return { ...simulateRes, results_decoded: returnValues as any }
+  }
+}
+
+const DEFAULT_ENDPOINT = getGrpcFullnodeUrl('mainnet')
+const CODER_MAP = new Map<string, MoveCoder>()
+
+export function defaultMoveCoder(endpoint: string = DEFAULT_ENDPOINT): MoveCoder {
+  let coder = CODER_MAP.get(endpoint)
+  if (!coder) {
+    coder = new MoveCoder(getGrpcClient(endpoint))
+    CODER_MAP.set(endpoint, coder)
+  }
+  return coder
+}
+
+const PROVIDER_CODER_MAP = new Map<SuiGrpcClient, MoveCoder>()
+
+let DEFAULT_CHAIN_ID: string | undefined
+
+export async function getMoveCoder(client: SuiGrpcClient): Promise<MoveCoder> {
+  let coder = PROVIDER_CODER_MAP.get(client)
+  if (!coder) {
+    coder = new MoveCoder(client)
+    const { chainIdentifier } = await client.core.getChainIdentifier()
+    const defaultCoder = defaultMoveCoder()
+    if (!DEFAULT_CHAIN_ID) {
+      DEFAULT_CHAIN_ID = await defaultCoder.adapter.getChainId()
+    }
+    if (chainIdentifier === DEFAULT_CHAIN_ID) {
+      coder = defaultCoder
+    }
+
+    PROVIDER_CODER_MAP.set(client, coder)
+  }
+  return coder
+}

package/src/sui-chain-adapter.ts

@@ -0,0 +1,142 @@
+import { toInternalModule } from './to-internal.js'
+import {
+  InternalMoveModule,
+  InternalMoveStruct,
+  ChainAdapter,
+  moduleQname,
+  SPLITTER,
+  TypeDescriptor
+} from '@typemove/move'
+
+import type { GrpcTypes } from '@mysten/sui/grpc'
+import { SuiGrpcClient } from '@mysten/sui/grpc'
+import type { SuiClientTypes } from '@mysten/sui/client'
+
+// Decoder-input types now use @mysten/sui/client's unified SuiClientTypes —
+// the same shapes returned by SuiGrpcClient (and that the GraphQL/JSON-RPC
+// clients implement). Per the SDK's own warnings, the `.json` field's exact
+// field names may vary between transports for some payloads; downstream code
+// reading `getData` should treat it as opaque object data.
+export type SuiEventInput = SuiClientTypes.Event
+export type SuiMoveObjectInput = SuiClientTypes.Object<{ json: true }>
+
+// Adapter ModuleType is the proto Module plus the package address (which the
+// proto doesn't carry per-entry — only the wrapping Package has storageId).
+export interface ModuleWithAddress {
+  address: string
+  module: GrpcTypes.Module
+}
+
+export class SuiChainAdapter extends ChainAdapter<ModuleWithAddress, SuiEventInput | SuiMoveObjectInput> {
+  client: SuiGrpcClient
+
+  constructor(client: SuiGrpcClient) {
+    super()
+    this.client = client
+  }
+
+  async getChainId(): Promise<string> {
+    const { chainIdentifier } = await this.client.core.getChainIdentifier()
+    return chainIdentifier ?? ''
+  }
+
+  async fetchModule(account: string, module: string): Promise<ModuleWithAddress> {
+    // gRPC has no single-module-fetch RPC; pull the whole package and filter.
+    const modules = await this.fetchModules(account)
+    const m = modules.find((x) => x.module.name === module)
+    if (!m) {
+      throw Error(`Module ${module} not found in package ${account}`)
+    }
+    return m
+  }
+
+  async fetchModules(account: string): Promise<ModuleWithAddress[]> {
+    const { response } = await this.client.movePackageService.getPackage({ packageId: account })
+    const pkg = response.package
+    if (!pkg) {
+      throw Error(`No package returned for ${account}`)
+    }
+    // gRPC returns the canonical long-form storage id (0x0000...0002); the rest
+    // of typemove keys system packages by their short form (0x2). Preserve the
+    // caller-supplied address so framework lookups and short-form import paths
+    // (`@typemove/sui/builtin/0x2`) keep working.
+    return (pkg.modules ?? []).map((module) => ({ address: account, module }))
+  }
+
+  getMeaningfulFunctionParams(params: TypeDescriptor[]): TypeDescriptor[] {
+    return params
+  }
+
+  toInternalModules(modules: ModuleWithAddress[]): InternalMoveModule[] {
+    return modules.map(({ address, module }) => toInternalModule(module, address))
+  }
+
+  getAllEventStructs(modules: InternalMoveModule[]): Map<string, InternalMoveStruct> {
+    const eventMap = new Map<string, InternalMoveStruct>()
+    for (const module of modules) {
+      const qname = moduleQname(module)
+      for (const struct of module.structs) {
+        const abilities = new Set(struct.abilities)
+        if (abilities.has('Drop') && abilities.has('Copy')) {
+          eventMap.set(qname + SPLITTER + struct.name, struct)
+        }
+      }
+    }
+    return eventMap
+  }
+
+  getType(base: SuiEventInput | SuiMoveObjectInput): string {
+    // Unified SuiClientTypes: Event has `eventType`, Object has `type`.
+    const v = base as any
+    return v.eventType ?? v.type ?? ''
+  }
+
+  getData(val: SuiEventInput | SuiMoveObjectInput) {
+    if (val === undefined) {
+      throw Error('val is undefined')
+    }
+    // Pass through primitives (e.g. a UID flattened to a bare string) — the
+    // decoder's per-type case handlers know how to interpret them.
+    if (val === null || typeof val !== 'object') {
+      return val as any
+    }
+    const v = val as any
+    // Unified SuiClientTypes shapes: Event.json / Object<{json:true}>.json
+    // carries the decoded Move struct content. Anything else (a nested
+    // already-flat struct value passed in during recursion) is its own data.
+    if (v.json != null) {
+      return v.json as any
+    }
+    return val as any
+  }
+}
+
+export function inferNetworkFromUrl(url: string): string {
+  if (url.includes('mainnet')) return 'mainnet'
+  if (url.includes('testnet')) return 'testnet'
+  if (url.includes('devnet')) return 'devnet'
+  if (url.includes('localnet') || url.includes('127.0.0.1') || url.includes('localhost')) return 'localnet'
+  return 'custom'
+}
+
+// gRPC counterpart of @mysten/sui/jsonRpc's `getJsonRpcFullnodeUrl`. The SDK
+// doesn't ship one under /grpc — Sui's gRPC-Web endpoint is exposed on the
+// same host as JSON-RPC over standard HTTPS, so we mirror the JSON-RPC list
+// (sans the explicit :443 since the transport speaks HTTPS by default).
+export function getGrpcFullnodeUrl(network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'): string {
+  switch (network) {
+    case 'mainnet':
+      return 'https://fullnode.mainnet.sui.io'
+    case 'testnet':
+      return 'https://fullnode.testnet.sui.io'
+    case 'devnet':
+      return 'https://fullnode.devnet.sui.io'
+    case 'localnet':
+      return 'http://127.0.0.1:9000'
+  }
+}
+
+export function getGrpcClient(endpoint: string): SuiGrpcClient {
+  const network = inferNetworkFromUrl(endpoint) as any
+  return new SuiGrpcClient({ network, baseUrl: endpoint })
+}

package/src/to-internal.ts

@@ -0,0 +1,201 @@
+import type { GrpcTypes } from '@mysten/sui/grpc'
+import {
+  accountTypeString,
+  InternalMoveEnum,
+  InternalMoveFunction,
+  InternalMoveFunctionVisibility,
+  InternalMoveModule,
+  InternalMoveStruct,
+  InternalMoveStructField,
+  SPLITTER,
+  TypeDescriptor
+} from '@typemove/move'
+
+// Re-exports for convenience: callers used to import named types from
+// '@mysten/sui/jsonRpc'; now they come from the gRPC proto namespace.
+type Module = GrpcTypes.Module
+type DatatypeDescriptor = GrpcTypes.DatatypeDescriptor
+type FieldDescriptor = GrpcTypes.FieldDescriptor
+type FunctionDescriptor = GrpcTypes.FunctionDescriptor
+type OpenSignature = GrpcTypes.OpenSignature
+type OpenSignatureBody = GrpcTypes.OpenSignatureBody
+
+// Proto enum constants kept as literals so we can compare against
+// the ordinals returned in the wire-decoded shape without importing
+// the namespaced enum at runtime.
+const DATATYPE_KIND_STRUCT = 1
+const DATATYPE_KIND_ENUM = 2
+
+const VISIBILITY_PRIVATE = 1
+const VISIBILITY_PUBLIC = 2
+const VISIBILITY_FRIEND = 3
+
+// OpenSignatureBody.Type
+const TYPE_ADDRESS = 1
+const TYPE_BOOL = 2
+const TYPE_U8 = 3
+const TYPE_U16 = 4
+const TYPE_U32 = 5
+const TYPE_U64 = 6
+const TYPE_U128 = 7
+const TYPE_U256 = 8
+const TYPE_VECTOR = 9
+const TYPE_DATATYPE = 10
+const TYPE_TYPE_PARAMETER = 11
+
+const ABILITY_NAMES: Record<number, string> = {
+  1: 'Copy',
+  2: 'Drop',
+  3: 'Store',
+  4: 'Key'
+}
+
+// Convert a proto Module (from movePackageService.getPackage().package.modules[i])
+// into typemove's InternalMoveModule. `packageAddress` is needed because the
+// proto Module doesn't repeat the package id on every module entry.
+export function toInternalModule(module: Module, packageAddress: string): InternalMoveModule {
+  packageAddress = accountTypeString(packageAddress)
+  const datatypes = module.datatypes ?? []
+  const functions = module.functions ?? []
+
+  const structs: InternalMoveStruct[] = datatypes.filter((d) => d.kind === DATATYPE_KIND_STRUCT).map(toInternalStruct)
+
+  const enums: InternalMoveEnum[] = datatypes.filter((d) => d.kind === DATATYPE_KIND_ENUM).map(toInternalEnum)
+
+  return {
+    address: packageAddress,
+    name: module.name ?? '',
+    exposedFunctions: functions.map(toInternalFunction),
+    structs,
+    enums
+  }
+}
+
+function toInternalFunction(func: FunctionDescriptor): InternalMoveFunction {
+  let visibility: InternalMoveFunctionVisibility
+  switch (func.visibility) {
+    case VISIBILITY_PRIVATE:
+      visibility = InternalMoveFunctionVisibility.PRIVATE
+      break
+    case VISIBILITY_PUBLIC:
+      visibility = InternalMoveFunctionVisibility.PUBLIC
+      break
+    case VISIBILITY_FRIEND:
+      visibility = InternalMoveFunctionVisibility.FRIEND
+      break
+    default:
+      throw Error(`No visibility for function ${func.name}`)
+  }
+  return {
+    typeParams: (func.typeParameters ?? []).map((p) => ({
+      constraints: (p.constraints ?? []).map(abilityName)
+    })),
+    isEntry: func.isEntry ?? false,
+    name: func.name ?? '',
+    params: (func.parameters ?? []).map(toTypeDescriptorFromSignature),
+    return: (func.returns ?? []).map(toTypeDescriptorFromSignature),
+    visibility
+  }
+}
+
+function toInternalStruct(d: DatatypeDescriptor): InternalMoveStruct {
+  return {
+    abilities: (d.abilities ?? []).map(abilityName),
+    fields: (d.fields ?? []).map(toInternalField),
+    typeParams: (d.typeParameters ?? []).map((p) => ({
+      constraints: (p.constraints ?? []).map(abilityName)
+    })),
+    isNative: false,
+    isEvent: false,
+    name: d.name ?? ''
+  }
+}
+
+function toInternalEnum(d: DatatypeDescriptor): InternalMoveEnum {
+  const variants: { [key: string]: InternalMoveStructField[] } = {}
+  for (const v of d.variants ?? []) {
+    variants[v.name ?? ''] = (v.fields ?? []).map(toInternalField)
+  }
+  return {
+    name: d.name ?? '',
+    abilities: (d.abilities ?? []).map(abilityName),
+    typeParams: (d.typeParameters ?? []).map((p) => ({
+      constraints: (p.constraints ?? []).map(abilityName)
+    })),
+    variants
+  }
+}
+
+function toInternalField(f: FieldDescriptor): InternalMoveStructField {
+  if (!f.type) {
+    throw Error(`Field ${f.name} has no type`)
+  }
+  return {
+    name: f.name ?? '',
+    type: toTypeDescriptorFromBody(f.type)
+  }
+}
+
+// OpenSignature wraps an OpenSignatureBody with an optional reference marker.
+// Used for function params and returns.
+function toTypeDescriptorFromSignature(sig: OpenSignature): TypeDescriptor {
+  if (!sig.body) {
+    throw Error('OpenSignature has no body')
+  }
+  const desc = toTypeDescriptorFromBody(sig.body)
+  // Reference.IMMUTABLE=1, MUTABLE=2
+  if (sig.reference === 1) {
+    desc.reference = true
+  } else if (sig.reference === 2) {
+    desc.reference = true
+    desc.mutable = true
+  }
+  return desc
+}
+
+function toTypeDescriptorFromBody(body: OpenSignatureBody): TypeDescriptor {
+  switch (body.type) {
+    case TYPE_ADDRESS:
+      return new TypeDescriptor('Address')
+    case TYPE_BOOL:
+      return new TypeDescriptor('Bool')
+    case TYPE_U8:
+      return new TypeDescriptor('U8')
+    case TYPE_U16:
+      return new TypeDescriptor('U16')
+    case TYPE_U32:
+      return new TypeDescriptor('U32')
+    case TYPE_U64:
+      return new TypeDescriptor('U64')
+    case TYPE_U128:
+      return new TypeDescriptor('U128')
+    case TYPE_U256:
+      return new TypeDescriptor('U256')
+    case TYPE_VECTOR: {
+      const inner = body.typeParameterInstantiation?.[0]
+      if (!inner) throw Error('Vector OpenSignatureBody missing type parameter')
+      return new TypeDescriptor('Vector', [toTypeDescriptorFromBody(inner)])
+    }
+    case TYPE_DATATYPE: {
+      // gRPC emits typeName as `<defining_id>::<module>::<name>` with the
+      // address in canonical long form (0x0000...0002). Normalize to the
+      // short form (0x2) so module-lookup keys match what's loaded into
+      // MoveCoder by short-form aware code paths.
+      const raw = body.typeName ?? ''
+      const parts = raw.split(SPLITTER)
+      const qname = parts.length === 3 ? [accountTypeString(parts[0]), parts[1], parts[2]].join(SPLITTER) : raw
+      const args = (body.typeParameterInstantiation ?? []).map(toTypeDescriptorFromBody)
+      return new TypeDescriptor(qname, args)
+    }
+    case TYPE_TYPE_PARAMETER:
+      return new TypeDescriptor('T' + (body.typeParameter ?? 0))
+    default:
+      throw new Error(`Unexpected OpenSignatureBody type: ${body.type}`)
+  }
+}
+
+function abilityName(a: number): string {
+  const n = ABILITY_NAMES[a]
+  if (!n) throw Error(`Unknown Ability value: ${a}`)
+  return n
+}