Overview

You can embed the ADAPT toolkit into any system that supports native Node.js or any WebAssembly (Wasm) JavaScript runtime environment and modify your JavaScript/TypeScript code to access ADAPT’s JavaScript API. The API provides comprehensive management of ADAPT packets from JavaScript/TypeScript code and includes methods for creating packets, creating MUFL values, executing transactions within packets, and more.

For a comprehensive list of functions, refer to the ADAPT JavaScript API Reference.

For a detailed practical introduction to embedding ADAPT into a web application, please see the Messenger Tutorial Part 1 and Messenger Tutorial Part 2.

The ADAPT JS API does not reveal the contents of the managed packet. Instead, it offers developers a means of invoking transactions within an ADAPT packet through the packet’s interface. To access specific data, you define a packet interface containing transactions. Without a transaction, that data cannot be accessed through API.

For instance, even though it is possible to set a variable in your MUFL code by executing the set_some_value transaction via the JavaScript API, if you haven’t defined a corresponding get_some_value transaction in the packet interface, it is not possible for JavaScript code to retrieve the value of the variable.

Example:

application test_app uses transactions
{
    value = 0.

    trn set_value new_value: int
    {
        value -> new_value.

        return ::transaction::success [].
    } 
}

And we can invoke this transaction using TypeScript:

let packet: AdaptPacketContext // suppose we have already loaded the packet
const transaction_envelope = object_to_adapt_value({name: "::test_app::set_value", targ: 10});
const transaction_result = packet.ExecuteTransaction(transaction_envelope)
packet = transaction_result.GetPacket(); // update the packet state after transaction

// At this point, there is no way to extract the "::test_app::value" from the packet because there is no corresponding transaction

The ADAPT JS API is available in these forms:

• Native
• Nitro
• Wasm

Each ADAPT node contains an ADAPT wrapper that uses the API that corresponds to the platform on which the node resides. All the APIs implement the same set of endpoints. The key distinction among these three versions lies in the underlying MUFL evaluator, each of which is compiled targeting a different platform: native, AWS Nitro Enclaves, and Wasm.

To use the correct version, simply import the adapt_js_api module and access the endpoints using the module name as a prefix on the API calls in your TypeScript code:

import { adapt_js_api } from 'adapt_utilities' 

adapt_js_api.AdaptEnvironment.Initialize(); 

One of the primary differences among these targets lies in the method of generating secure random bytes. Both the WASM and native versions utilize libsodium, whereas the nitro version employs the nsm library, which is only available within AWS Nitro Enclaves.

Another significant difference is in the method of attestation document generation. It’s important to note that each version of the MUFL evaluator can validate an attestation document from any other target, but it can only generate an attestation for the platform it is compiled for.

The typical use case for the native ADAPT JS API involves the message broker and the data storage utilities. These utilities use the native ADAPT JS API to invoke transactions in the protocol packet, enabling, validating, and creating network protocol messages.

For a detailed description of the API, refer to the ADAPT JavaScript API Reference.

Native

The native Node.js ADAPT JS API is constructed using Node-API, as specified in the Node.js documentation.

Use the native ADAPT JS API when running ADAPT in native environments, such as Linux servers, Docker, etc.

Nitro

The Nitro Node.js ADAPT JS API is constructed the same way as the native ADAPT JS API, that is, using Node-API, as specified in the Node.js documentation.

The only differences are:

• It uses the Nitro MUFL build instead of the native build.
• It links Nitro-related libraries, such as libnsm.

Wasm

ADAPT’s Wasm JavaScript API is C++ code compiled into a Wasm module using the emscripten toolkit. It uses WebIDL binder to generate JavaScript bindings.