{"id":21550499,"url":"https://github.com/ThomasConstantinBity/ICP-Kotlin-Kit","last_synced_at":"2025-07-16T14:30:53.767Z","repository":{"id":258527039,"uuid":"824624205","full_name":"ThomasConstantinBity/ICP-Kotlin-Kit","owner":"ThomasConstantinBity","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-27T13:23:13.000Z","size":1496,"stargazers_count":0,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-27T21:31:46.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThomasConstantinBity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-05T14:35:34.000Z","updated_at":"2024-10-27T13:23:19.000Z","dependencies_parsed_at":"2024-10-26T19:07:52.181Z","dependency_job_id":null,"html_url":"https://github.com/ThomasConstantinBity/ICP-Kotlin-Kit","commit_stats":null,"previous_names":["thomasconstantinbity/icp-kotlin-kit"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasConstantinBity%2FICP-Kotlin-Kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasConstantinBity%2FICP-Kotlin-Kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasConstantinBity%2FICP-Kotlin-Kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasConstantinBity%2FICP-Kotlin-Kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThomasConstantinBity","download_url":"https://codeload.github.com/ThomasConstantinBity/ICP-Kotlin-Kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226134310,"owners_count":17578780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T07:01:49.168Z","updated_at":"2025-07-16T14:30:53.748Z","avatar_url":"https://github.com/ThomasConstantinBity.png","language":"Kotlin","funding_links":[],"categories":["Client Libraries (Agents)"],"sub_categories":["Java/Kotlin"],"readme":"![IcpKit](readme_utils/IcpKit.png)\n\nA comprehensive kotlin package for writing applications that interact with the Internet Computer Protocol (ICP).\nIcp Kotlin Kit aims at facilitating the interaction with the ICP blockchain.\n\nFor more information about ICP Development, we recommend starting from https://internetcomputer.org/docs/current/references/\n\n## Contributors\nThis package has been developed by [Thomas Constantin](https://github.com/0xTommy). All code and functionality are the result of his work.\n\n## Acknowledgments\nI would like to express my gratitude to [Konstantinos Gaitanis](https://github.com/kgaitanis) for his support during the initial project study and other contributions that helped shape this library.\n\nThis Package has been built by [Bity SA](https://bity.com) with the help of the [DFinity Foundation Developer Grant Program](https://dfinity.org/grants).\n\n## License\n**MIT License** is applicable for all Kotlin Code (see [LICENSE](LICENSE)).\n\nBLS12381 Rust Library is licensed by Levi Feldman (see [LICENSE](readme_utils/bls12381_LICENSE)).\n\n## Library Overview\nIcpKit will take care of all the encoding, serialisation and cryptography required to communicate with ICP allowing\ndevelopers to focus on the real functionality of their app and bootstrapping their development cycle.\n### Main functionalities\n- Cryptographic methods applicable to ICP such as signing and signature verification.\n- CBOR serialisation\n- Basic ICP Models for transactions, accounts, self-authenticating principals etc.\n- `CandidEncoder` and `CandidDecoder` for converting any kotlin class/values to a CandidValue\n- This library provides a set of pre-generated files inside `data/generated_file`\n\nThis files can be directly used to interact with canisters. These files include the most \ncommonly needed functionality for operations such as fetching balances, sending ICP or ICP tokens, \nand retrieving NFT information.\n\nIf you need to interact with other canisters using custom candid files, you can easily add a Gradle task to \ngenerate the necessary bindings from your own candid files. For more details, see the [Installation](#Installation) \nsection.\n\n## Installation\n\n### Use pre generated files\n#### Add the JitPack repository to your build file\n\nAdd in your `settings.gradle.kts` file:\n\n```kotlin\ndependencyResolutionManagement {\n    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)\n    repositories {\n        mavenCentral()\n        maven{ url = uri(\"https://jitpack.io\") }\n    }\n}\n```\n\n#### Add the dependency\nAdd in your application `build.gradle.kts` file:\n```kotlin\ndependencies {\n    implementation(\"com.github.ThomasConstantinBity:ICP-Kotlin-Kit:Tag\")\n}\n```\n\n#### Add BLS12381 rust library\n\n### Generate custom files with gradle task\nAdd in your app `build.gradle.kts` file:\n```kotlin\nbuildscript {\n    repositories {\n        maven { url = uri(\"https://jitpack.io\") }\n    }\n    dependencies {\n        classpath(\"com.github.ThomasConstantinBity:ICP-Kotlin-Kit:Tag\")\n    }\n}\n```\n\n## Usage\nTo enable signature verification, this library requires the BLS12381 Rust library. You’ll need to compile the Rust project located in the `rust/bls12381` folder. \n\n### Steps:\n\n1. Navigate to the `rust/bls12381` directory.\n2. Compile the Rust project according to your target platform.\n\n\u003e **Note:** You must provide separate libraries for each platform or device you want to support (e.g., Android, iOS).\n\n### Android Support\n\nFor Android projects, you can use [cargo-ndk-android-gradle](https://github.com/willir/cargo-ndk-android-gradle) to simplify the process of building Rust libraries for Android. This tool helps compile Rust libraries into native code that can be used within Android applications.\n\nMake sure to configure the build process for each platform and link the resulting native libraries accordingly.\n\n### Use pre generated files\nFor this example, we’ll use the `ICRC1.kt` file to demonstrate how to interact with the service.\n#### Service Initialization\nFirst, initialize the service with your canister principal:\n\n```kotlin\nval canister: ICPPrincipal = // Define your principal\nval service = ICRC1.ICRC1Service(canister)\n```\nYou can initialize `ICPPrincipal` by using the principal string \n(e.g., `ryjl3-tyaaa-aaaaa-aaaba-cai` for the ICP Ledger canister). \nAlternatively, check the `ICPSystemCanisters` enum class for predefined canisters.\n\nOnce the service is initialized, you can call **any** of the available functions.\n\n#### Performing a Simple Query\nTo perform a query, you can use `service.query_name`. The service will call the corresponding method on the canister, retrieve the response, and parse it into a Kotlin value or class according to the function’s definition.\nFor query methods, there are some optional parameters you can pass:\n- **Certification**: Use `ICPRequestCertification.Certified` if you want to verify the response’s signature. \nBe aware that this process involves JNI and will be slower due to the additional verification step. Default value: ICPRequestCertification.Unertified.\n- **Sender**: An interface to implement if the query requires a signature.\n- Polling values: This is relevant for certified requests, as the service needs to poll the canister while awaiting a response.\nDefault values: \n  - Polling interval: 2 seconds\n  - Polling timeout: 2 minutes\n\n#### Calling a Function That Requires a Signature\nHere’s an example of how to call a function that requires a signature:\n\nImplement `ICPSigningPrincipal`\n```kotlin\nval sender = object : ICPSigningPrincipal {\n    override val principal: ICPPrincipal = this@TmpTest.principal\n    override val rawPublicKey: ByteArray = publicKey\n    override suspend fun sign(message: ByteArray): ByteArray {\n        val hashedMessage = SHA256.sha256(message)\n        val signature = EllipticSign(\n            messageToSign = hashedMessage,\n            privateKey = BigInteger(privateKey)\n        )\n        signature[64] = (signature[64] + 0x1b).toByte()\n        return signature.dropLast(1).toByteArray()\n    }\n}\n```\nNow, you can make a transfer using the service:\n```kotlin\nval transferArgs = ICRC1.TransferArgs(\n    ...\n)\nval transferResult = service.icrc1_transfer(\n    transferArgs = transferArgs,\n    sender = sender\n)\n\nval blockIndex = when (transferResult) {\n    is ICRC1.TransferResult.Err -\u003e throw transferResult.transferError.toDataModel()\n    is ICRC1.TransferResult.Ok -\u003e transferResult.bigInteger\n}\n```\n\n### Generate custom files with gradle task\nYou can use `KotlinFileGenerator` class inside gradle tasks. Here is a **demo** example\n```kotlin\ntasks.register(\"parseCandidFiles\") {\n    val inputFolder = file(\"./candid/files/path\")\n    require(inputFolder.isDirectory)\n    inputFolder.listFiles { it -\u003e it.extension == \"did\" }?.forEach { file -\u003e\n        val fileName = file.name.removeSuffix(\".did\")\n        val kotlinFile = KotlinFileGeneratorService.parseAndGetKotlinFile(\n            candidFileText = file.readText(Charsets.UTF_8),\n            fileName = fileName,\n            packageName = \"com.your.package.name\"\n        )\n        val outputFile = file(\"./src/main/path/to/your/folder/${fileName}.kt\")\n        outputFile.writeText(kotlinFile)\n    }\n}\n```\n\n### NFT Support\nThe library, in the `DataModule` file, provides an `nftRepository` object that implements the `NFTRepository` interface. The interface implementation can be used to fetch all the required NFT information. If you want to handle a collection with a custom implementation, you can call `NFTServiceUtil.setNFTService`. You can check `ChainFusionToonisNFTService` for an example.\n\n### Logger\n\nTo enhance tracking and debugging, you can set a custom logger by calling `ICPKitLogger.setLogger`. Simply provide an implementation of `ICPKitLogHandler` and override only the necessary functions. All methods with custom behavior have an empty body by default, allowing for flexible customization.  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FThomasConstantinBity%2FICP-Kotlin-Kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FThomasConstantinBity%2FICP-Kotlin-Kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FThomasConstantinBity%2FICP-Kotlin-Kit/lists"}