Skip to main content

Connecting To The Node

In order to connect to the node you must have one running. We assume that you have a newly booted local Shinkai Node running before starting (reference the Getting Started page for starting your own node), and that you will be creating a service that will be making the connection/interacting with Shinkai.

There are a few of ways to connect to your running Shinkai Node, depending on your chosen stack:

High-level Registration Flow

At a high level, when a new Shinkai node is started (aka. it is "pristine", with no other client device connected to it yet), the overall flow to connect a client device is as such:

  1. Generate a set of keys on your client device (your service)
  2. Generate a message using ShinkaiMessageBuilder to register your client device
  3. Send the message to the Node REST API endpoint use_registration_code
  4. The node will register your client device if it is available
  5. Once registered, we can verify if the freshly booted node processed the registration by calling /shinkai_health GET endpoint. In the response we should see property is_pristine set to false, meaning at least one client device has been registered. If there are none registered, is_pristine will return true.

Of note, the set of keys you generate are required to be kept safe & persist over sessions. Your client device's ability/permission to interact with the node (by creating/sending ShinkaiMessages) always require using these keys and they allow your client device (service) to have its own sub-identity underneath your Node's global identity.

Registering In Practice

Now that we've laid down the overall approach of how to connect to the node, let's look at the specific details of how this is done in practice. We will start by enabling our service to auto-connect to the Shinkai Node.

As mentioned in the previous section, there is one endpoint we are specifically interested in: /v1/use_registration_code. This endpoint requires us to pass a Shinkai message that holds needed registration info about your client device (service), which the node uses to register it officially as a sub-identity under the node (ie. @@node.shinkai/profile/myService).

Generating payload for registration

In order to register, your service must start by generating encryption and signing keys, creating a registration message, and then sending this message to the node. Here's are the steps to perform this action using the Javascript/Typescript Shinkai library (process is nearly identical using libraries in other languages):

  1. Generate Encryption and Signature Keys: First, you need to generate two sets of keys - encryption keys and signature keys. These keys are crucial for securing the communication between your client device(service) and the Shinkai Node. These functions are available in the Shinkai library (inside the typescript lib as: generateEncryptionKeys and generateSignatureKeys)
const encryptionKeys = await generateEncryptionKeys();
const signatureKeys = await generateSignatureKeys();
  1. Prepare Your Device Keys: With the keys generated, we will encode them in an easily-readable format for the node using Uint8Array.
const my_device_encryption_sk = new Uint8Array(Buffer.from(encryptionKeys.my_encryption_sk_string, "hex"));
const my_device_signature_sk = new Uint8Array(Buffer.from(signatureKeys.my_identity_sk_string, "hex"));
const profile_encryption_sk = new Uint8Array(Buffer.from(encryptionKeys.my_encryption_sk_string, "hex"));
const profile_signature_sk = new Uint8Array(Buffer.from(signatureKeys.my_identity_sk_string, "hex"));
  1. Create a Registration Message: With your keys ready, use the ShinkaiMessageBuilder to create a registration message. This message will include your client device's encryption and signature keys, along with the name of the profile you want this device to be registered under (profiles are like accounts, usually one per person/use case), and the name for your client device that you wish to register it as. Of note, while registering if you input a profile name that does not already exist in your node, it will be auto-generated.
const registrationMessage = await ShinkaiMessageBuilder.initialRegistrationWithNoCodeForDevice(
my_device_encryption_sk,
my_device_signature_sk,
profile_encryption_sk,
profile_signature_sk,
"my_device_name",
"my_profile_name",
"@@localhost.shinkai"
"@@localhost.shinkai"
);
  1. Send the Registration Message: Finally, with the Shinkai message in hand, you simply take the registration message you've created and send it to the Shinkai Node. This is done by making a POST request to the /v1/use_registration_code endpoint on the node.
const response = await axios.post('http://localhost:9550/v1/use_registration_code', registrationMessage);

The node will process this message and thus register your client device. You are now ready to interact with the node itself.

Retaining Connectivity

As mentioned previously, the keypairs you generated when registering your client device (service) are required to be used whenever you create and send Shinkai messages post-registration. These keypairs uniquely identify your client device (and allow encryption to be possible), and thus must be saved into persistent storage and used every time your service interacts with the Shinkai node.

The one endpoint which does not require keys however is the simple /shinkai_health GET endpoint. It allows you to check if the node is online, and specifically returns JSON with the is_pristine field which identifies whether the node has a device registered for it or not. If the node is pristine (meaning no client devices registered) then it will be true, which can be checked by your service and thus trigger the key generation/registration process. When it is false, you must use existing keypairs from an already registered client device (or register a new one by generating a registration code from your previously registered device, only first device can be registered with no registration code).