JSON

Overview

The IJson.sol precompile enables EVM smart contracts to manipulate JSON data.

In this article, you'll find a full list of available methods, allowing you to handle different value types:

• All value types
• Basic types and numbers
• Arrays and nested objects

To learn how to use this precompile, refer to Use the JSON precompile.

Code

You can find the JSON precompile code on GitHub: IJson.sol

Precompile address

To reference the IJson precompile in your code, use the following precompile address:

0x0000000000000000000000000000000000000904

All value types

Create a new root object

• Method: newJson()
• Description: Creates an empty root JSON object.
• Code:

  function newJson() external view returns (bytes memory);
• Output:

  @return The created JSON as bytes.
• Usage example: Create a new root object

Get a value

• Method: get()
• Description: Returns a value by key.
• Code:

  function get(
      bytes memory input,
      string memory key
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The value as bytes.
• Usage example: Get a value

Remove a pair

• Method: remove()
• Description: Removes a key-value pair from the root object.
• Code:

  function remove(
      bytes memory input,
      string memory key
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to remove.
• Output:

  @return The modified JSON as bytes.
• Usage example: Remove a pair

Get multiple values

• Method: read()
• Description: Returns multiple values by their keys. Requires passing an array of keys: see the ReadKeyValue struct.
• Code:

  function read(
      bytes memory input,
      ReadKeyValue[] memory keyValues
  ) external view returns (bytes[] memory);
• Parameters:

  @param input The JSON input as bytes.
  @param keyValues The key-value pairs to read.
• Output:

  @return The array of key-value pairs as bytes.
• Usage example: Get multiple pairs

Set multiple pairs

• Method: write()
• Description: Sets multiple key-value pairs. Requires passing an array of pairs: seee the SetKeyValue struct.
• Code:

  function write(
      bytes memory input,
      SetKeyValue[] memory keyValues
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param keyValues The key-value pairs to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set multiple pairs

Basic types and numbers

Get a string value

• Method: getString()
• Description: Returns a string value by key.
• Code:

  function getString(
      bytes memory input,
      string memory key
  ) external view returns (string memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The string value.
• Usage example: Get a string value

Get a boolean value

• Method: getBool()
• Description: Returns a boolean value by key.
• Code:

  function getBool(
      bytes memory input,
      string memory key
  ) external view returns (bool);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The boolean value.
• Usage example: Get a boolean value

Get an address value

• Method: getAddress()
• Description: Returns an address value by key.
• Code:

  function getAddress(
      bytes memory input,
      string memory key
  ) external view returns (address);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The address value.
• Usage example: Get an address value

Get a uint256 value

• Method: getUint256()
• Description: Returns a uint256 value by key.
• Code:

  function getUint256(
      bytes memory input,
      string memory key
  ) external view returns (uint256);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The uint256 value
• Usage example: Get a uint256 value

Get an int256 value

• Method: getInt256()
• Description: Returns an int256 value by key.
• Code:

  function getInt256(
      bytes memory input,
      string memory key
  ) external view returns (int256);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The int256 value.
• Usage example: Get an int256 value

Get a float value

• Method: getFloat()
• Description: Returns a float value by key.
• Code:

  function getFloat(
      bytes memory input,
      string memory key,
      int64 decimals
  ) external view returns (int256);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
  @param decimals The number of decimal places.
• Output:

  @return The float value as int256.
• Usage example: Get a float value

Set a string pair

• Method: setString()
• Description: Sets a string key-value pair.
• Code:

  function setString(
      bytes memory input,
      string memory key,
      string memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The string value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a string pair

Set a boolean pair

• Method: setBool()
• Description: Sets a boolean key-value pair.
• Code:

  function setBool(
      bytes memory input,
      string memory key,
      bool value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The boolean value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a boolean pair

Set an address pair

• Method: setAddress()
• Description: Sets an address key-value pair.
• Code:

  function setAddress(
      bytes memory input,
      string memory key,
      address value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The address value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set an address pair

Set a bytes pair

• Method: setBytes()
• Description: Set a bytes key-value pair.
• Code:

  function setBytes(
      bytes memory input,
      string memory key,
      bytes memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The bytes value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a bytes pair

Set a uint256 pair

• Method: setUint256()
• Description: Set a uint256 key-value pair.
• Code:

  function setUint256(
      bytes memory input,
      string memory key,
      uint256 value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The uint256 value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a uint256 pair

Set an int256 pair

• Method: setInt256()
• Description: Set an int256 key-value pair.
• Code:

  function setInt256(
      bytes memory input,
      string memory key,
      int256 value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The int256 value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set an int256 pair

Set a float pair

• Method: setFloat()
• Description: Set a float key-value pair.
• Code:

  function setFloat(
      bytes memory input,
      string memory key,
      int256 value,
      int64 decimals
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The int256 value to set.
  @param decimals The number of decimal places.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a float pair

Arrays and nested objects

Get a string array

• Method: getStringArray()
• Description: Returns a string array value by key.
• Code:

  function getStringArray(
      bytes memory input,
      string memory key
  ) external view returns (string[] memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The string array value.
• Usage example: Get a string array

Get a boolean array

• Method: getBoolArray()
• Description: Returns a boolean array value by key.
• Code:

  function getBoolArray(
      bytes memory input,
      string memory key
  ) external view returns (bool[] memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The boolean array value.
• Usage example: Get a boolean array

Get an address array

• Method: getAddressArray()
• Description: Returns an address array value by key.
• Code:

  function getAddressArray(
      bytes memory input,
      string memory key
  ) external view returns (address[] memory);
• Parameters:

   @param input The JSON input as bytes.
   @param key The key to look up.
• Output:

  @return The address array value.
• Usage example: Get an address array

Get a uint256 array

• Method: getUintArray()
• Description: Returns a uint256 array value by key.
• Code:

  function getUintArray(
      bytes memory input,
      string memory key
  ) external view returns (uint256[] memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The uint256 array value.
• Usage example: Get a uint256 array

Get an int256 array

• Method: getIntArray()
• Description: Returns an int256 array value by key.
• Code:

  function getIntArray(
      bytes memory input,
      string memory key
  ) external view returns (int256[] memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The int256 array value.
• Usage example: Get an int256 array

Get a float array

• Method: getFloatArray()
• Description: Returns a float array value by key.
• Code:

  function getFloatArray(
      bytes memory input,
      string memory key,
      int64 decimals
  ) external view returns (int256[] memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The float array value.
• Usage example: Get a float array

Get an object array

• Method: getObjectsArray()
• Description: Returns an object array value by key.
• Code:

  function getObjectsArray(
      bytes memory input,
      string memory key
  ) external view returns (bytes[] memory);
  • Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The nested object value as bytes.
• Usage example: Get an object array

Get a nested object

• Method: getObject()
• Description: Returns a nest object value by key.
• Code:

  function getObject(
      bytes memory input,
      string memory key
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to look up.
• Output:

  @return The nested object value as bytes.
• Usage example: Get a nested object

Set a string array pair

• Method: setStringArray()
• Description: Set a string array key-value pair.
• Code:

  function setStringArray(
      bytes memory input,
      string memory key,
      string[] memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The string array value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a string array pair

Set an address array pair

• Method: setAddressArray()
• Description: Set an address array key-value pair.
• Code:

  function setAddressArray(
      bytes memory input,
      string memory key,
      address[] memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The address array value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set an address array pair

Set a boolean array pair

• Method: setBoolArray()
• Description: Set a boolean array key-value pair.
• Code:

  function setBoolArray(
      bytes memory input,
      string memory key,
      bool[] memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The boolean array value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a boolean array pair

Set a uint256 array pair

• Method: setUintArray()
• Description: Set a uint256 array key-value pair.
• Code:

  function setUintArray(
      bytes memory input,
      string memory key,
      uint256[] memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The uint256 array value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a uint256 array pair

Set an int256 array pair

• Method: setIntArray()
• Description: Set an int256 array key-value pair.
• Code:

  function setIntArray(
      bytes memory input,
      string memory key,
      int256[] memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The int256 array value to set.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set an int256 array pair

Set a float array pair

• Method: setFloatArray()
• Description: Set a float array key-value pair.
• Code:

  function setFloatArray(
      bytes memory input,
      string memory key,
      int256[] memory value,
      int64 decimals
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The int256 array value to set.
  @param decimals The number of decimal places.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a float array pair

Set an object array pair

• Method: setObjectsArray()
• Description: Set an object array key-value pair.
• Code:

  function setObjectsArray(
      bytes memory input,
      string memory key,
      bytes[] memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The nested objects values as bytes.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set an object array pair

Set a nested object pair

• Method: setObject()
• Description: Set a nested object key-value pair.
• Code:

  function setObject(
      bytes memory input,
      string memory key,
      bytes memory value
  ) external view returns (bytes memory);
• Parameters:

  @param input The JSON input as bytes.
  @param key The key to set.
  @param value The nested object value as bytes.
• Output:

  @return The modified JSON as bytes.
• Usage example: Set a nested object pair

Structs

SetKeyValue

• Description: A struct representing a key and its value type. It's used for getting multiple values.

struct ReadKeyValue {
    string key;
    string valueType;
    int64 decimals;
}

ReadKeyValue

• Description: A struct representing a key-value pair. It's used for setting multiple pairs.

struct SetKeyValue {
    string key;
    string valueType;
    bytes value;
    int64 decimals;
}