Decoding Kernel Responses in Solidity

Prerequisites

• Supported OpenAPI Specifications

---

This page is dedicated for explaining how to decode the responses from kernel(s) in your Solidity smart contract. The decoding part of Solidity plays a crucial role in both your smart contract and Token Authority. Following methods from this page would allow your smart contract and/or Token Authority to see the responses from kernels.

It is worth mentioning that the decoding part can be used in both TA and registered smart contract.

---

On-chain Kernel Responses

The method of decoding on-chain kernel responses is similar to simple object in off-chain kernels.

We will use kernel 337 as an example.

As we can see from the figure above, the return type of this on-chain kernel is uint256 type.

The decoding part of Solidity would be in the snippet.

Solidity

// ...
foo = abi.decode(kernelResponses[i].result, (int256));
// ...

---

Below this line, this page would be focusing entirely on off-chain kernel responses.

---

Off-chain Kernel Responses

It is also recommended to visit Supported OpenAPI Specifications page (click here) to understand more on how to decode off-chain kernels.

1. Variable Names Matter

The names of variables from the off-chain response matter.

Click here to read more

2. Float and Number

The number value from off-chain kernels can be decoded using int256.

The output after decoding on Solidity would give the value in 18 decimal places.

For example, value of 12.34 from off-chain kernel will be 12340000000000000000.

This includes float value as well.

---

Example

The below table shows the line of code which might be helpful in order to decode the responses from off-chain kernel(s).

Example Endpoint: https://api.mock.com/submit-passport

Method: GET

Response:

{

"name": "John"

}

This example would fall into the first case of the below table.

It is worth mentioning that the decoding part can be used in both TA and registered smart contract.

The variable names in your smart contract do not have to match those in the kernel response.

However, aligning them can make tracking easier.

Element	Response	Solidity
string	{ "hello": "world" }	foo = abi.decode(kernelResponses[i].result, (string));
boolean	{ "allowed": true }	foo = abi.decode(kernelResponses[i].result, (bool));
number (no decimal places)	{ "number": 123 }	foo = abi.decode(kernelResponses[i].result, (int256));
float	{ "number": 123.456 }	foo = abi.decode(kernelResponses[i].result, (int256));
null	{ "hello": null }	Null values require a precise decoding method Click here to read more
array	{ "group": [123,456,789] }	foo = abi.decode(kernelResponses[i].result, (int256[]));
simple response	"hello"	Simple responses such as in the example can also be decoded Click here to read more
multiple fields object	{ "allowed": true, "hello": "world" }	struct FooStruct { bool foo1 string foo2 } // ... foo = abi.decode(kernelResponses[i].result, (FooStruct));
multiple fields object 2	{ "group": [123,456,789], "hello": "world" }	struct FooStruct { int256[] foo1 string foo2 } // ... foo = abi.decode(kernelResponses[i].result, (FooStruct));
nested object	{ "alpha": { "allowed": true, "hello": "world" }, "group": [123,456,789] }	struct FooStruct { Alpha foo1 int256[] foo2 } struct Alpha { bool alp string beta } // ... foo = abi.decode(kernelResponses[i].result, (FooStruct));

---

Variable Names

What?

The decoding part of off-chain kernels will have to be sorted by alphabetical order.

Why?

The reason why variable names from off-chain kernels matter is because when KRNL node will pack the responses from off-chain kernel altogether.

Even though the API response does not return with the alphabetical order, the decoding part on Solidity smart contract still requires to decode alphabetically.

How?

Let's use the mock off-chain response as in the below example.

Response

{
  "zebra": "text",
  "apple": true,
  "krnl": "text"
}

The decoding part in Solidity should be in the below snippet.

Solidity

struct Foo {
  bool apple
  string krnl
  string zebra
}
// ...

---

Null

What?

When it comes to null value responses, it is important to handle the response precisely.

The responses from off-chain kernels might not show up if null gets handled poorly and/or the transactions might not be completed as well.

Why?

Solidity language itself does not fundamentally have "null" value.

How?

The kernel ID of ABC will be used as a simple off-chain kernel example here.

When the value is null, it will return the default value of the actual type from the OpenAPI schema.

We have to observe the response data type when it does not come back with null value.

Let's hypothetically say that this kernel ABC can give us either string value or null value.

Response 1

Response

{
  "kernelabcresponseexample": null
}

Response 2

Response

{
  "kernelabcresponseexample": "This is a simple sentence."
}

This means that the response can be either "null" or "string".

The decoding part in Solidity smart contract would have to be string.

Decoding

Solidity

// ...
foo = abi.decode(kernelResponses[i].result, (string));
// ...

---

Simple Responses

What?

When it comes to simple responses from off-chain kernels such as in the below code snippet, KRNL nodes can also handle and send them to the Solidity smart contract.

Fundamentally, this is a rare case from calling a request to an API, but it does not mean that it cannot happen.

string

"hello"

boolean

true

number

123456

In the code-base of KRNL node, it will handle these types of responses similar to the object responses.

See below for simpler explanation.

string

{
  "text": "hello"
}

boolean

{
  "allowed": true
}

number

{
  "text": 123456
}

How?

What this means is the during the decoding part in Solidity smart contract would be straightforward.

string

foo = abi.decode(kernelResponses[i].result, (string));

boolean

foo = abi.decode(kernelResponses[i].result, (bool));

number

foo = abi.decode(kernelResponses[i].result, (int256));

The reason why the node can handle the simple responses, like in this scenario, is not because it automatically happens but because our team already handle this type of responses.

---