@subsquid/evm-codec 0.2.1 → 1.0.0

package/src/codecs/primitives.ts

@@ -1,185 +1,93 @@
-import { decodeHex, isHex, toHex } from '@subsquid/util-internal-hex'
-import { Codec } from '../codec'
-import { Sink } from '../sink'
-import { Src } from '../src'
-import { ArrayCodec, FixedSizeArrayCodec } from './array'
-import { StructCodec } from './struct'
-import { safeToNumber } from '../safeToNumber'
+import type {Codec, Sink, Src} from '../codec'
 
-type Numberish = number | bigint
-
-export const bool: Codec<boolean> = {
-  encode: function (sink: Sink, val: boolean) {
-    sink.bool(val)
-  },
-  decode(src: Src): boolean {
-    return src.bool()
-  },
-  isDynamic: false,
-}
-
-export const uint8: Codec<Numberish, number> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.u8(safeToNumber(val))
-  },
-  decode(src: Src): number {
-    return src.u8()
-  },
-  isDynamic: false,
-}
-
-export const int8: Codec<Numberish, number> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.i8(safeToNumber(val))
-  },
-  decode(src: Src): number {
-    return src.i8()
-  },
-  isDynamic: false,
-}
-
-export const uint16: Codec<Numberish, number> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.u16(safeToNumber(val))
-  },
-  decode(src: Src): number {
-    return src.u16()
-  },
-  isDynamic: false,
+function safeToNumber(value: number | bigint): number {
+    if (value < Number.MIN_SAFE_INTEGER || value > Number.MAX_SAFE_INTEGER) {
+        throw new Error(`${value} is not a safe integer`)
+    }
+    return Number(value)
 }
 
-export const int16: Codec<Numberish, number> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.i16(safeToNumber(val))
-  },
-  decode(src: Src): number {
-    return src.i16()
-  },
-  isDynamic: false,
-}
-
-export const uint32: Codec<Numberish, number> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.u32(safeToNumber(val))
-  },
-  decode(src: Src): number {
-    return src.u32()
-  },
-  isDynamic: false,
-}
-
-export const int32: Codec<Numberish, number> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.i32(safeToNumber(val))
-  },
-  decode(src: Src): number {
-    return src.i32()
-  },
-  isDynamic: false,
-}
-
-export const uint64: Codec<Numberish, bigint> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.u64(BigInt(val))
-  },
-  decode(src: Src): bigint {
-    return src.u64()
-  },
-  isDynamic: false,
-}
-
-export const int64: Codec<Numberish, bigint> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.i64(BigInt(val))
-  },
-  decode(src: Src): bigint {
-    return src.i64()
-  },
-  isDynamic: false,
-}
-
-export const uint128: Codec<Numberish, bigint> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.u128(BigInt(val))
-  },
-  decode(src: Src): bigint {
-    return src.u128()
-  },
-  isDynamic: false,
-}
-
-export const int128: Codec<Numberish, bigint> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.i128(BigInt(val))
-  },
-  decode(src: Src): bigint {
-    return src.i128()
-  },
-  isDynamic: false,
-}
-
-export const uint256: Codec<Numberish, bigint> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.u256(BigInt(val))
-  },
-  decode(src: Src): bigint {
-    return src.u256()
-  },
-  isDynamic: false,
-}
-
-export const int256: Codec<Numberish, bigint> = {
-  encode(sink: Sink, val: Numberish) {
-    sink.i256(BigInt(val))
-  },
-  decode(src: Src): bigint {
-    return src.i256()
-  },
-  isDynamic: false,
-}
+type Numberish = number | bigint
+type NumberType = 'u8' | 'i8' | 'u16' | 'i16' | 'u32' | 'i32'
+type BigIntType = 'u64' | 'i64' | 'u128' | 'i128' | 'u256' | 'i256'
 
-export const string = <const>{
-  encode(sink: Sink, val: string) {
-    sink.newStaticDataArea()
-    sink.string(val)
-    sink.endCurrentDataArea()
-  },
-  decode(src: Src): string {
-    return src.string()
-  },
-  isDynamic: true,
+function numberCodec(method: NumberType): Codec<Numberish, number> {
+    return {
+        encode: (sink, val) => sink[method](safeToNumber(val)),
+        decode: (src) => src[method](),
+        isDynamic: false,
+        baseType: 'int',
+    }
 }
 
-function toBuffer(val: Uint8Array | string): Uint8Array {
-  if (val instanceof Uint8Array) {
-    return val
-  }
-  if (!isHex(val)) {
-    throw new Error(`Expected hex string or buffer, got: ${val}`)
-  }
-  return decodeHex(val)
+function bigintCodec(method: BigIntType): Codec<Numberish, bigint> {
+    return {
+        encode: (sink, val) => sink[method](BigInt(val)),
+        decode: (src) => src[method](),
+        isDynamic: false,
+        baseType: 'int',
+    }
 }
 
-export const bytes: Codec<Uint8Array | string, string>  = <const>{
-  encode(sink: Sink, val: Uint8Array | string) {
-    sink.newStaticDataArea()
-    sink.bytes(toBuffer(val))
-    sink.endCurrentDataArea()
-  },
-  decode(src: Src): string {
-    return toHex(src.bytes())
-  },
-  isDynamic: true,
+export const bool: Codec<boolean> = {
+    encode(sink: Sink, val: boolean) {
+        sink.bool(val)
+    },
+    decode(src: Src): boolean {
+        return src.bool()
+    },
+    isDynamic: false,
+    baseType: 'bool',
+}
+
+export const uint8 = numberCodec('u8')
+export const int8 = numberCodec('i8')
+export const uint16 = numberCodec('u16')
+export const int16 = numberCodec('i16')
+export const uint32 = numberCodec('u32')
+export const int32 = numberCodec('i32')
+export const uint64 = bigintCodec('u64')
+export const int64 = bigintCodec('i64')
+export const uint128 = bigintCodec('u128')
+export const int128 = bigintCodec('i128')
+export const uint256 = bigintCodec('u256')
+export const int256 = bigintCodec('i256')
+
+export const string: Codec<string> = {
+    encode(sink: Sink, val: string) {
+        sink.openTail()
+        sink.string(val)
+        sink.closeTail()
+    },
+    decode(src: Src): string {
+        return src.string()
+    },
+    isDynamic: true,
+    baseType: 'string',
+}
+
+export const bytes: Codec<Uint8Array | string, string> = {
+    encode(sink: Sink, val: Uint8Array | string) {
+        sink.openTail()
+        sink.bytes(val)
+        sink.closeTail()
+    },
+    decode(src: Src): string {
+        return src.bytesHex()
+    },
+    isDynamic: true,
+    baseType: 'bytes',
 }
 
 const bytesN = (size: number): Codec<Uint8Array | string, string> => ({
-  encode(sink: Sink, val: Uint8Array | string) {
-    sink.staticBytes(size, toBuffer(val))
-  },
-  decode(src: Src): string {
-    return toHex(src.staticBytes(size))
-  },
-  isDynamic: false,
+    encode(sink: Sink, val: Uint8Array | string) {
+        sink.staticBytes(size, val)
+    },
+    decode(src: Src): string {
+        return src.staticBytesHex(size)
+    },
+    isDynamic: false,
+    baseType: 'bytes',
 })
 
 export const bytes0 = bytesN(0)
@@ -217,27 +125,16 @@ export const bytes31 = bytesN(31)
 export const bytes32 = bytesN(32)
 
 export const address: Codec<string> = {
-  encode(sink: Sink, val: string) {
-    sink.address(val)
-  },
-  decode(src: Src): string {
-    return src.address()
-  },
-  isDynamic: false,
-}
-
-export const fixedSizeArray = <TIn, TOut>(item: Codec<TIn, TOut>, size: number): Codec<TIn[], TOut[]> => new FixedSizeArrayCodec(item, size)
-
-export const array = <TIn, TOut>(item: Codec<TIn, TOut>): Codec<TIn[], TOut[]> => new ArrayCodec(item)
-
-type Struct = {
-  [key: string]: Codec<any>
+    encode(sink: Sink, val: string) {
+        sink.address(val)
+    },
+    decode(src: Src): string {
+        return src.address()
+    },
+    isDynamic: false,
+    baseType: 'address',
 }
 
-export const struct = <const T extends Struct>(components: T) => new StructCodec<T>(components)
-
-export const tuple = struct
-
 export const uint24 = uint32
 export const int24 = int32
 export const uint40 = uint64
@@ -290,4 +187,3 @@ export const uint240 = uint256
 export const int240 = int256
 export const uint248 = uint256
 export const int248 = int256
-

package/src/codecs/struct.test.ts

@@ -0,0 +1,69 @@
+import {describe, expect, it} from 'vitest'
+import {address, array, bytes4, int8, BytesSink, BytesSrc, struct, uint256} from '..'
+
+function roundtrip<T>(codec: {encode: (s: BytesSink, v: T) => void; decode: (s: BytesSrc) => T; slotsCount?: number}, value: T) {
+  const sink = new BytesSink(codec.slotsCount ?? 1)
+  codec.encode(sink, value)
+  expect(codec.decode(new BytesSrc(sink.result()))).toStrictEqual(value)
+}
+
+describe('StructCodec', () => {
+  it('static tuple', () => {
+    roundtrip(
+      struct({
+        a: int8,
+        b: uint256,
+        c: struct({e: address}),
+      }),
+      {
+        a: 1,
+        b: 2n,
+        c: {e: '0x1234567890123456789012345678901234567890'},
+      },
+    )
+  })
+
+  it('dynamic tuple', () => {
+    roundtrip(
+      struct({
+        a: array(uint256),
+        b: uint256,
+        c: struct({d: array(uint256), e: address}),
+      }),
+      {
+        a: [100n, 1n, 123n],
+        b: 2n,
+        c: {
+          d: [3n, 4n],
+          e: '0x1234567890123456789012345678901234567890',
+        },
+      },
+    )
+  })
+
+  it('dynamic tuple with bytes4', () => {
+    const s = struct({
+      foo: uint256,
+      bar: array(uint256),
+      str: struct({foo: uint256, bar: bytes4}),
+    })
+    const value = {
+      foo: 100n,
+      bar: [1n, 2n, 3n],
+      str: {
+        foo: 123n,
+        bar: '0x12345678',
+      },
+    }
+    const sink = new BytesSink(1)
+    // `bytes4` accepts either `Uint8Array` or the `0x…`-prefixed hex form
+    // on the encode side but always returns the hex form on decode — check
+    // both input paths explicitly.
+    s.encode(sink, {
+      ...value,
+      str: {...value.str, bar: Uint8Array.from([0x12, 0x34, 0x56, 0x78])},
+    })
+    expect(s.decode(new BytesSrc(sink.result()))).toStrictEqual(value)
+    roundtrip(s, value)
+  })
+})

package/src/codecs/struct.ts

@@ -1,74 +1,94 @@
-import {Codec, Struct, DecodedStruct, EncodedStruct} from '../codec'
-import { Sink } from '../sink'
-import { Src } from '../src'
+import type {Codec, Sink, Src, Struct} from '../codec'
+import {type Pretty, propAccess, propName} from '../util'
+
+export type DecodedStruct<T extends Struct> = Pretty<{
+    [K in keyof T]: T[K] extends Codec<any, infer U> ? U : never
+}>
+
+export type EncodedStruct<T extends Struct> = Pretty<{
+    [K in keyof T]: T[K] extends Codec<infer U, any> ? U : never
+}>
 
 function slotsCount(codecs: readonly Codec<any>[]) {
-  let count = 0
-  for (const codec of codecs) {
-    count += codec.slotsCount ?? 1
-  }
-  return count
+    let count = 0
+    for (const codec of codecs) {
+        count += codec.slotsCount ?? 1
+    }
+    return count
 }
 
 export class StructCodec<const T extends Struct> implements Codec<EncodedStruct<T>, DecodedStruct<T>> {
-  public readonly isDynamic: boolean
-  public readonly slotsCount: number
-  private readonly childrenSlotsCount: number
-  private readonly components: T
+    public readonly baseType = 'struct'
+    public readonly isDynamic: boolean
+    public readonly slotsCount: number
+    public readonly childrenSlotsCount: number
+    public readonly components: T
 
-  constructor(components: T) {
-    this.components = components
-    const codecs = Object.values(components)
-    this.isDynamic = codecs.some((codec) => codec.isDynamic)
-    this.childrenSlotsCount = slotsCount(codecs)
-    if (this.isDynamic) {
-      this.slotsCount = 1
-    } else {
-      this.slotsCount = this.childrenSlotsCount
-    }
-  }
+    readonly encodeInline: (sink: Sink, val: EncodedStruct<T>) => void
+    readonly decodeInline: (src: Src) => DecodedStruct<T>
 
-  public encode(sink: Sink, val: EncodedStruct<T>): void {
-    if (this.isDynamic) {
-      this.encodeDynamic(sink, val)
-      return
-    }
-    for (let i in this.components) {
-      let prop = this.components[i]
-      prop.encode(sink, val[i])
-    }
-  }
+    readonly encode: (sink: Sink, val: EncodedStruct<T>) => void
+    readonly decode: (src: Src) => DecodedStruct<T>
 
-  private encodeDynamic(sink: Sink, val: EncodedStruct<T>): void {
-    sink.newStaticDataArea(this.childrenSlotsCount)
-    for (let i in this.components) {
-      let prop = this.components[i]
-      prop.encode(sink, val[i])
-    }
-    sink.endCurrentDataArea()
-  }
+    constructor(components: T) {
+        this.components = components
+        const entries = Object.entries(components) as Array<[string, Codec<any>]>
+        const codecs = entries.map(([, c]) => c)
+        this.isDynamic = codecs.some((codec) => codec.isDynamic)
+        this.childrenSlotsCount = slotsCount(codecs)
+        this.slotsCount = this.isDynamic ? 1 : this.childrenSlotsCount
 
-  public decode(src: Src): DecodedStruct<T> {
-    if (this.isDynamic) {
-      return this.decodeDynamic(src)
+        this.encodeInline = this.createEncode(entries, false)
+        this.decodeInline = this.createDecode(entries, false)
+        this.encode = this.isDynamic ? this.createEncode(entries, true) : this.encodeInline
+        this.decode = this.isDynamic ? this.createDecode(entries, true) : this.decodeInline
     }
-    let result: any = {}
-    for (let i in this.components) {
-      let prop = this.components[i]
-      result[i] = prop.decode(src)
-    }
-    return result
-  }
 
-  private decodeDynamic(src: Src): DecodedStruct<T> {
-    let result: any = {}
+    // JIT-generates a straight-line encode function. Each child's encode is bound once
+    // at construction time to avoid property lookups on the hot path. When wrap=true
+    // and the struct is dynamic, openTail/closeTail bracket the field writes so the
+    // function can be used as a nested ABI field.
+    private createEncode(
+        entries: Array<[string, Codec<any>]>,
+        wrap: boolean,
+    ): (sink: Sink, val: EncodedStruct<T>) => void {
+        const closureNames: string[] = []
+        const closureValues: any[] = []
+        let body = ''
+        if (wrap && this.isDynamic) {
+            body += `sink.openTail(${this.childrenSlotsCount});`
+        }
+        for (let i = 0; i < entries.length; i++) {
+            const [key, child] = entries[i]
+            const name = `__e${i}`
+            closureNames.push(name)
+            closureValues.push(child.encode.bind(child))
+            body += `${name}(sink, val${propAccess(key)});`
+        }
+        if (wrap && this.isDynamic) {
+            body += 'sink.closeTail();'
+        }
+        const fn = new Function(...closureNames, 'sink', 'val', body)
+        return fn.bind(null, ...closureValues)
+    }
 
-    const offset = src.u32()
-    const tmpSrc = src.slice(offset)
-    for (let i in this.components) {
-      let prop = this.components[i]
-      result[i] = prop.decode(tmpSrc)
+    private createDecode(entries: Array<[string, Codec<any>]>, wrap: boolean): (src: Src) => DecodedStruct<T> {
+        const closureNames: string[] = []
+        const closureValues: any[] = []
+        let body = ''
+        if (wrap && this.isDynamic) {
+            body += 'src = src.slice(src.u32());'
+        }
+        const fields: string[] = []
+        for (let i = 0; i < entries.length; i++) {
+            const [key, child] = entries[i]
+            const name = `__d${i}`
+            closureNames.push(name)
+            closureValues.push(child.decode.bind(child))
+            fields.push(`${propName(key)}:${name}(src)`)
+        }
+        body += `return {${fields.join(',')}};`
+        const fn = new Function(...closureNames, 'src', body)
+        return fn.bind(null, ...closureValues)
     }
-    return result
-  }
 }

package/src/dsl.ts

@@ -0,0 +1,16 @@
+import type {Codec, Struct} from './codec'
+import {ArrayCodec, FixedSizeArrayCodec} from './codecs/array'
+import {StructCodec} from './codecs/struct'
+
+export * from './codecs/primitives'
+export {ArrayCodec, FixedSizeArrayCodec} from './codecs/array'
+export {StructCodec, type DecodedStruct, type EncodedStruct} from './codecs/struct'
+
+export const fixedSizeArray = <TIn, TOut>(item: Codec<TIn, TOut>, size: number): FixedSizeArrayCodec<TIn, TOut> =>
+    new FixedSizeArrayCodec(item, size)
+
+export const array = <TIn, TOut>(item: Codec<TIn, TOut>): ArrayCodec<TIn, TOut> => new ArrayCodec(item)
+
+export const struct = <const T extends Struct>(components: T): StructCodec<T> => new StructCodec<T>(components)
+
+export const tuple = struct

package/src/index.ts

@@ -1,4 +1,7 @@
-export { Src } from './src'
-export { Sink } from './sink'
-export type { Codec, Struct, DecodedStruct, EncodedStruct } from './codec'
-export * from './codecs/primitives'
+export * from './codec'
+export * from './dsl'
+export * from './sink/bytes'
+export * from './sink/hex'
+export * from './src/bytes'
+export * from './src/hex'
+export * from './util'

package/src/sink/bounds.ts

@@ -0,0 +1,26 @@
+export const TEXT_ENCODER = new TextEncoder()
+
+export const U256_BASE = 1n << 256n
+
+export const U8_MAX = 0xff
+export const U16_MAX = 0xffff
+export const U32_MAX = 0xffffffff
+
+export const I8_MIN = -0x80
+export const I8_MAX = 0x7f
+export const I16_MIN = -0x8000
+export const I16_MAX = 0x7fff
+export const I32_MIN = -0x80000000
+export const I32_MAX = 0x7fffffff
+
+export const U64_MAX_BI = 0xffffffffffffffffn
+export const I64_MIN_BI = -0x8000000000000000n
+export const I64_MAX_BI = 0x7ffffffffffffffen
+
+export const U128_MAX_BI = 0xffffffffffffffffffffffffffffffffn
+export const I128_MIN_BI = -0x80000000000000000000000000000000n
+export const I128_MAX_BI = 0x7fffffffffffffffffffffffffffffffn
+
+export const U256_MAX_BI = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn
+export const I256_MIN_BI = -0x8000000000000000000000000000000000000000000000000000000000000000n
+export const I256_MAX_BI = 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn

package/src/sink/bytes.test.ts

@@ -0,0 +1,92 @@
+import {describe, expect, it} from 'vitest'
+import {BytesSink, BytesSrc} from '..'
+
+describe('sink', () => {
+  it('negative numbers round-trip through Src', () => {
+    const sink = new BytesSink(6)
+    sink.i8(-1)
+    sink.i16(-123)
+    sink.i32(-123456)
+    sink.i64(-1234567890n)
+    sink.i128(-12345678901234567890n)
+    sink.i256(-1234567890123456789012345678901234567890n)
+
+    const src = new BytesSrc(sink.result())
+    expect(src.i8()).toBe(-1)
+    expect(src.i16()).toBe(-123)
+    expect(src.i32()).toBe(-123456)
+    expect(src.i64()).toBe(-1234567890n)
+    expect(src.i128()).toBe(-12345678901234567890n)
+    expect(src.i256()).toBe(-1234567890123456789012345678901234567890n)
+  })
+
+  it('number overflow', () => {
+    const sink = new BytesSink(1)
+    expect(() => sink.u8(0x1234567890)).toThrowError('78187493520 is out of bounds for uint8[0, 255]')
+    expect(() => sink.i8(0x1234567890)).toThrowError('78187493520 is out of bounds for int8[-128, 127]')
+    expect(() => sink.u16(0x1234567890)).toThrowError('78187493520 is out of bounds for uint16[0, 65535]')
+    expect(() => sink.i16(0x1234567890)).toThrowError('78187493520 is out of bounds for int16[-32768, 32767]')
+    expect(() => sink.u32(0x1234567890)).toThrowError('78187493520 is out of bounds for uint32[0, 4294967295]')
+    expect(() => sink.i32(0x1234567890)).toThrowError('78187493520 is out of bounds for int32[-2147483648, 2147483647]')
+  })
+
+  it('mixed static types round-trip through Src', () => {
+    const sink = new BytesSink(5)
+    sink.u8(1)
+    sink.i8(-2)
+    sink.address('0x1234567890123456789012345678901234567890')
+    sink.u256(3n)
+    sink.staticBytes(7, Buffer.from('1234567890abcd', 'hex'))
+
+    const src = new BytesSrc(sink.result())
+    expect(src.u8()).toBe(1)
+    expect(src.i8()).toBe(-2)
+    expect(src.address()).toBe('0x1234567890123456789012345678901234567890')
+    expect(src.u256()).toBe(3n)
+    expect(src.staticBytes(7)).toStrictEqual(new Uint8Array(Buffer.from('1234567890abcd', 'hex')))
+  })
+
+  describe('string', () => {
+    function testString(value: string) {
+      const sink = new BytesSink(1)
+      sink.openTail()
+      sink.string(value)
+      sink.closeTail()
+      expect(new BytesSrc(sink.result()).string()).toBe(value)
+    }
+
+    it('short string', () => testString('hello'))
+    it('32 byte string', () => testString('this string length is 32 bytes!!'))
+    it('longer string', () => testString('this string length is 33 bytes!!!'))
+    it('UTF', () => testString('привет 👍'))
+  })
+
+  it('bytes', () => {
+    const sink = new BytesSink(1)
+    sink.openTail()
+    const buffer = Buffer.alloc(150)
+    buffer.fill('xd')
+    sink.bytes(buffer)
+    sink.closeTail()
+    expect(new BytesSrc(sink.result()).bytes()).toStrictEqual(new Uint8Array(buffer))
+  })
+
+  it('string encodes to canonical 32-byte-aligned ABI layout', () => {
+    // Pin the exact on-wire layout for one value so we catch regressions
+    // in the offset/length word without needing an external reference
+    // implementation on the hot path.
+    const sink = new BytesSink(1)
+    sink.openTail()
+    sink.string('hello')
+    sink.closeTail()
+    expect(sink.toString()).toBe(
+      '0x' +
+        // offset to the dynamic region (0x20)
+        '0000000000000000000000000000000000000000000000000000000000000020' +
+        // length (5)
+        '0000000000000000000000000000000000000000000000000000000000000005' +
+        // "hello" left-aligned, zero-padded to 32 bytes
+        '68656c6c6f000000000000000000000000000000000000000000000000000000',
+    )
+  })
+})