SuiJSON

SuiJSON is a JSON-based format with restrictions that allow Sui to align JSON inputs more closely with Move call arguments.

This table shows the restrictions placed on JSON types to make them SuiJSON compatible:

JSONSuiJSON RestrictionsMove Type Mapping
NumberMust be unsigned integerU8
U16
U32
U64
(U128 is encoded as String)
(U256 is encoded as String)
StringNo restrictionsVector<U8>
Address
ObjectID
TypeTag
Identifier
Unsigned Integer (256 bit max)
BooleanNo restrictionsBool
ArrayMust be homogeneous JSON and of SuiJSON typeVector
NullNot allowed
ObjectNot allowed

Type coercion reasoning

Due to the loosely typed nature of JSON/SuiJSON and the strongly typed nature of Move types, we sometimes need to overload SuiJSON types to represent multiple Move types.

For example SuiJSON::Number can represent both U8 and U64. This means we have to coerce and sometimes convert types.

Which type we coerce depends on the expected Move type. For example, if the Move function expects a U8, we must have received a SuiJSON::Number with a value less than 256. More importantly, we have no way to easily express Move addresses in JSON, so we encode them as hex strings prefixed by 0x.

Additionally, Move supports U128 and U256 but JSON doesn't. As a result we allow encoding numbers as strings.

Type coercion rules

Move TypeSuiJSON RepresentationsValid ExamplesInvalid Examples
BoolBooltrue, false
U8Supports 3 formats:
  • Unsigned number < 256.
  • Decimal string with value < 256.
  • One byte hex string prefixed with 0x.
7
"70"
"0x43"
-5: negative not allowed
3.9: float not allowed
NaN: not allowed
300: U8 must be less than 256
" 9": Spaces not allowed in string
"9A": Hex num must be prefixed with 0x
"0x09CD": Too large for U8
U16Three formats are supported
  • Unsigned number < 65536.
  • Decimal string with value < 65536.
  • Two byte hex string prefixed with 0x.
712
"570"
"0x423"
-5: negative not allowed
3.9: float not allowed
NaN: not allowed
98342300: U16 must be less than 65536
" 19": Spaces not allowed in string
"9EA": Hex num must be prefixed with 0x
"0x049C1D": Too large for U16
U32Three formats are supported
  • Unsigned number < 4294967296.
  • Decimal string with value < 4294967296.
  • One byte hex string prefixed with 0x.
9823247
"987120"
"0x4BADE93"
-5: negative not allowed
3.9: float not allowed
NaN: not allowed
123456789123456: U32 must be less than 4294967296
" 9": Spaces not allowed in string
"9A": Hex num must be prefixed with 0x
"0x3FF1FF9FFDEFF": Too large for U32
U64Supports 3 formats:
  • Unsigned number < U64::MAX.
  • Decimal string with value < U64::MAX.
  • Up to 8 byte hex string prefixed with 0x.
Extrapolate above examplesExtrapolate above examples
U128Two formats are supported
  • Decimal string with value < U128::MAX.
  • Up to 16 byte hex string prefixed with 0x.
"74794734937420002470"
"0x2B1A39A1514E1D8A7CE"
34: Although this is a valid U128 number, it must be encoded as a string
U256Two formats are supported
  • Decimal string with value < U256::MAX.
  • Up to 32 byte hex string prefixed with 0x.
"747947349374200024707479473493742000247"
"0x2B1762FECADA39753FCAB2A1514E1D8A7CE"
123434: Although this is a valid U256 number, it must be encoded as a string
Address20 byte hex string prefixed with 0x"0x2B1A39A1514E1D8A7CE45919CFEB4FEE70B4E011"0x2B1A39: string too short
2B1A39A1514E1D8A7CE45919CFEB4FEE70B4E011: missing 0x prefix
0xG2B1A39A1514E1D8A7CE45919CFEB4FEE70B4E01: invalid hex char G
ObjectID16 byte hex string prefixed with 0x"0x2B1A39A1514E1D8A7CE45919CFEB4FEE"Similar to above
IdentifierTypically used for module and function names. Encoded as one of the following:
  1. A String whose first character is a letter and the remaining characters are letters, digits or underscore.
  2. A String whose first character is an underscore, and there is at least one further letter, digit or underscore
"function",
"_function",
"some_name",
"\___\_some_name",
"Another"
"_": missing trailing underscore, digit or letter,
"8name": cannot start with digit,
".function": cannot start with period,
" ": cannot be empty space,
"func name": cannot have spaces
Vector<Move Type>Homogeneous vector of aforementioned types including nested vectors of primitive types (only "flat" vectors of ObjectIDs are allowed)[1,2,3,4]: simple U8 vector
[[3,600],[],[0,7,4]]: nested U64 vector ["0x2B1A39A1514E1D8A7CE45919CFEB4FEE", "0x2B1A39A1514E1D8A7CE45919CFEB4FEF"]: ObjectID vector
[1,2,3,false]: not homogeneous JSON
[1,2,null,4]: invalid elements
[1,2,"7"]: although we allow encoding numbers as strings meaning this array can evaluate to [1,2,7], the array is still ambiguous so it fails the homogeneity check.
Vector<U8>For convenience, we allow:
U8 vectors represented as UTF-8 (and ASCII) strings.
"√®ˆbo72 √∂†∆˚–œ∑π2ie": UTF-8
"abcdE738-2 _=?": ASCII
Last update 10/31/2022, 4:13:00 PM

Contributor(s)