Skip to main content

Technical Specification

This document is a draft

Introduction​

The Internet Computer Toolkit Standard (ICTS) provides a structured and consistent approach to developing tools on the Internet Computer. This standard defines a set of methods that toolkit canisters should implement to facilitate interaction, enhance maintainability, and ensure a seamless user experience. ICTS aims to create a uniform interface for tools, making it easier for developers and users to work with them.

Objectives​

  1. Consistency: Ensure that all tools on the Internet Computer follow a consistent interface.
  2. Maintainability: Simplify the process of maintaining and updating tools by standardizing common methods.
  3. Usability: Facilitate easier interaction with tools through well-defined methods that can be leveraged by user interfaces and other automated systems.

Method Specifications​

1. icts_name​

Description: Returns the name of the tool. This method is essential for identifying the tool within user interfaces and logs.

Signature: fn icts_name() -> String

Example:

fn icts_name() -> String {
    "MyTool".to_string()
}

2. icts_methods​

Description: Returns a JSON that should be exposed for handling through a user interface. This ensures that all necessary interactions are available to the end-users.

Signature: fn icts_methods() -> String

Example:

#[export_icts_methods]
pub fn icts_methods() -> String {
    _icts_methods()
}

3. icts_version​

Description: Returns the current version of the tool. This method is crucial for version management and ensuring compatibility.

Signature: fn icts_version() -> String

Example:

fn icts_version() -> String {
    "1.0.0".to_string()
}

4. icts_root​

Description: Returns the controller of the tool. This method identifies the primary entity responsible for managing the tool.

Signature: fn icts1_root() -> Principal

Example:

fn icts1_root() -> Principal {
    Principal::from_text("aaaaa-aa")
}

5. icts_status​

Description: Returns the current status of the tool. This method can be used for monitoring and ensuring that the tool is functioning as expected.

Signature: fn icts_status() -> String

Example:

fn icts_status() -> String {
    "Running".to_string()
}

Custom Methods​

To expose custom methods for handling through a user interface, use the icts_register attribute macro. This macro registers the method with metadata, making it accessible for querying or updating purposes.

Examples:

#[icts_register(query)]
fn custom_query_method(arg1: String, arg2: u64) -> Result<(), String> {
    // Function implementation
}

#[icts_register(update)]
fn custom_update_method(arg1: String, arg2: u64) -> Result<(), String> {
    // Function implementation
}

Generated JSON:

{
  "custom_query_method": {
    "function_name": "custom_query_method",
    "arguments": ["arg1: String", "arg2: u64"],
    "return_type": "Result<(), String>",
    "type": "query"
  }
},
{
  "custom_update_method": {
    "function_name": "custom_update_method",
    "arguments": ["arg1: String", "arg2: u64"],
    "return_type": "Result<(), String>",
    "type": "update"
  }
},

Typescript interfaces:

interface ICTSMethod {
  function_name: string;
  arguments: string[];
  return_type: string;
  type: string;
}

interface ICTSMethodsJSON {
  [key: string]: ICTSMethod;
}

Implementation Guidelines​

  1. Environment Variable: The ICTS_GENERATE environment variable should be set to enable the registration of these methods. This allows flexibility in toggling the registration feature during development and deployment.
  2. Attribute Macros: Use the icts_register attribute macro to register custom methods with the ICTS. The macro handles the serialization of method metadata into a JSON file, ensuring consistent and automated registration.
  3. Metadata Storage: Method metadata is stored in a JSON file (icts_methods.json). This file should be included and managed as part of the tool's resources to maintain accurate and up-to-date method information.

Conclusion​

The Internet Computer Tooling Standard (ICTS) provides a robust framework for developing and maintaining tools on the Internet Computer. By adhering to this standard, developers can create consistent, maintainable, and user-friendly tools. This technical specification outlines the required methods and implementation guidelines to ensure compliance with the ICTS. As the Internet Computer ecosystem evolves, this standard will be updated to incorporate new requirements and best practices.