{"id":21529208,"url":"https://github.com/everx-labs/ever-appkit-js","last_synced_at":"2025-04-09T23:51:10.576Z","repository":{"id":43041037,"uuid":"349405192","full_name":"everx-labs/ever-appkit-js","owner":"everx-labs","description":"Free TON Javascript Application Kit","archived":false,"fork":false,"pushed_at":"2023-05-12T14:51:14.000Z","size":527,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-09T23:51:05.116Z","etag":null,"topics":["everscale","free","javascript","js","sdk","ton","tonos","typescript","web3"],"latest_commit_sha":null,"homepage":"https://docs.everos.dev/appkit-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/everx-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2021-03-19T11:50:07.000Z","updated_at":"2023-07-25T14:44:28.000Z","dependencies_parsed_at":"2024-04-16T15:33:05.731Z","dependency_job_id":"c889b9dd-3056-441c-a69f-0abafd801bac","html_url":"https://github.com/everx-labs/ever-appkit-js","commit_stats":null,"previous_names":["everx-labs/ever-appkit-js"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everx-labs%2Fever-appkit-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everx-labs%2Fever-appkit-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everx-labs%2Fever-appkit-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everx-labs%2Fever-appkit-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/everx-labs","download_url":"https://codeload.github.com/everx-labs/ever-appkit-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131455,"owners_count":21052819,"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":["everscale","free","javascript","js","sdk","ton","tonos","typescript","web3"],"created_at":"2024-11-24T01:56:14.198Z","updated_at":"2025-04-09T23:51:10.552Z","avatar_url":"https://github.com/everx-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Everscale JS Application Kit\n\nThis library is a part of Everscale SDK for JavaScript.\n\nAppKit is built over the [@eversdk/core](https://github.com/tonlabs/ever-sdk-js) package and purposed to simplify writing applications on Everscale.\n\nFull API reference: [https://tonlabs.github.io/ever-appkit-js/](https://tonlabs.github.io/ever-appkit-js/)\n\nIf this package helped you, please give it a star:)\n\n**Have a question? Get quick help in our channel:**\n\n[![Chat on Telegram](https://img.shields.io/badge/chat-on%20telegram-9cf.svg)](https://t.me/ton\\_sdk)\n\n## Table of Contents\n\n* [Useful links](./#useful-links)\n* [Before You Start](./#before-you-start)\n* [Installation](./#installation)\n* [Setup Client Library](./#setup-client-library)\n  * [NodeJs:](./#nodejs)\n  * [Web:](./#web)\n  * [React Native:](./#react-native)\n* [Create Client Instance](./#create-client-instance)\n* [A Few Words about the Code](./#a-few-words-about-the-code)\n* [Use Account Object](./#use-account-object)\n  * [Sample source code](./#sample-source-code)\n* [Subscribe for Changes](./#subscribe-for-changes)\n* [Executing Contract on TVM](./#executing-contract-on-tvm)\n* [Interacting with Core SDK](./#interacting-with-core-sdk)\n\n## Useful links\n\n* [Full API reference](https://tonlabs.github.io/ever-appkit-js/)\n* [Appkit samples](https://github.com/tonlabs/sdk-samples/tree/master/appkit-examples)\n* [SDK guides](https://docs.everos.dev/ever-sdk/quick\\_start) - to get a deeper understanding dive into our sdk guides where you can find extensive explanations and descriptions of each step of DApp development on Everscale.\n\n## Before You Start\n\nWe strongly recommend installing [EverDev](https://docs.everos.dev/everdev/) utility before you start playing with AppKit. This utility will help you manage your tools for Everscale development.\n\n## Installation\n\n```shell\n# Install core package\nnpm i --save @eversdk/core\n\n# Install lib-node bridge if you write node js application\nnpm i --save @eversdk/lib-node\n\n# Or install lib-web bridge if you write web/browser application\nnpm i --save @eversdk/lib-web\n\n# Or install lib-react-native if you write react-native mobile application\nnpm i --save @eversdk/lib-react-native\n\n# And finally install appkit itself\nnpm i --save @eversdk/appkit\n```\n\n## Setup Client Library\n\nYou must initialize the core library before the first use. The best place to do it is in the initialization code of your application.\n\n### NodeJs:\n\n```javascript\nconst { TonClient } = require(\"@eversdk/core\");\nconst { libNode } = require(\"@eversdk/lib-node\");\n\n// Application initialization\n\nTonClient.useBinaryLibrary(libNode)\n```\n\n### Web:\n\n```javascript\nimport { TonClient } from \"@eversdk/core\";\nimport { libWeb } from \"@eversdk/lib-web\";\n\n// Application initialization\n\nTonClient.useBinaryLibrary(libWeb);\n```\n\nBy default, the library loads wasm module from relative URL `/tonclient.wasm`.\n\nYou can specify alternative URL if you want to place (or rename) wasm module.\n\n```javascript\nimport { TonClient } from \"@eversdk/core\";\nimport { libWeb, libWebSetup } from \"@eversdk/lib-web\";\n\n// Application initialization.\n\n// You have to setup libWeb if the `tonclient.wasm`\n// isn't located at root of your web site.\n// Otherwise you havn't to call `libWebSetup`.\nlibWebSetup({\n    binaryURL: \"/assets/tonclient_1_2_3.wasm\",\n});\n\nTonClient.useBinaryLibrary(libWeb);\n```\n\n### React Native:\n\n```javascript\nimport { TonClient } from \"@eversdk/core\";\nimport { libReactNative } from \"@eversdk/lib-react-native\";\n\n// Application initialization\n\nTonClient.useBinaryLibrary(libReactNative);\n```\n\n## Create Client Instance\n\nAppKit is built over [core JS library](https://github.com/tonlabs/ever-sdk-js/tree/master/packages/core). So you have to create an instance of `TonClient` to use it later with AppKit objects.\n\n```javascript\nconst client = new TonClient({\n    network: { endpoints: [\"http://localhost\"] }\n});\n```\n\nIn this sample we create a client instance configured to use local blockchain [Evernode SE](https://github.com/tonlabs/evernode-se) instance.\n\nIf you want to work with Developer Network or Everscale main network, please use the [list of endpoints, listed here](https://docs.everos.dev/ever-sdk/reference/ever-os-api/networks). **Attention** You must specify all the endpoints as an array in `endpoints` parameter, because each endpoint does not guarantee its availability, but we guarantee that at least one endpoint is operational at the moment.\n\n## A Few Words about the Code\n\nBelow we use a code snippets to illustrate `AppKit` usage.\\\nIn this code we omit an initialization part because it is the same.\\\nWe suppose that we are using lib-node bridge (NodeJs) to write examples. Also, we use the library to deal with local [Evernode SE](https://github.com/tonlabs/evernode-se) instance.\n\nSo the full code of each example can look like this:\n\n```javascript\nconst { TonClient } = require(\"@eversdk/core\");\nconst { libNode } = require(\"@eversdk/lib-node\");\nconst { Account } = require(\"@eversdk/appkit\");\n\nTonClient.useBinaryLibrary(libNode);\n\n(async () =\u003e {\n    const endpoint = process.env.TON_NETWORK_ADDRESS || \"http://localhost\";\n    const client = new TonClient({ network: { endpoints: [endpoint] } });\n    try {\n        await main(client);\n    } catch (err) {\n        console.error(err);\n    } finally {\n        client.close();\n    }\n})();\n\nasync function main(client) {\n    // Snippet code is here\n}\n```\n\n## Use Account Object\n\nAt the moment the key point of `AppKit` is an Account object (class). Application uses an Account instance to deal with specific blockchain account using specific owner ( signer in terms of TonClient library).\n\nEach Account instance must use an ABI compliant contract. So we have to define the `Contract` object with an ABI and optionally tvc fields. This object must be provided to the Account constructor.\n\nIn the example below we use predefined giver already included in AppKit and predeployed in Evernode SE.\n\n```javascript\n// Define Contract object.\nconst AccContract = {\n    abi: { /* ABI declarations */ },\n    tvc: \"... base64 encoded string ...\",\n};\n\n// Generate new keys pair for new account.\nconst keys = await client.crypto.generate_random_sign_keys();\n\n// Create owner (signer) instance for new account.\nconst signer = signerKeys(keys);\n\n// Construct Account instance.\n//\n// Note that this account is not deployed in the blockchain yet.\n// We just create an object to deal with this account.\nconst acc = new Account(AccContract, { signer, client });\n\n// We can determine the future addres of the account \n// and print it to the user before deploying.\nconsole.log(`New account future address: ${await acc.getAddress()}`);\n\n// Deploy account to the blockchain.\n// Here we use TONOS SE giver to create a positive balance\n// before deploying.\nawait acc.deploy({ useGiver: true });\n\n// Send external inbound message to our new account\n// and receives result from external outboud message.\nconst response = await acc.run(\"someFunction\", { someParam: 1 });\n\n// Print decoded response message\nconsole.log(\"Account has responded to someFunction with\", response.decoded.output);\n\n// Print current balance.\n// Note that balance returned as a string in decimal representation.\n// This is because of a value measure is a nano.\n// So its value may not be representable using JS Number.\nconsole.log(\"Account balance now is\", await acc.getBalance());\n```\n\nIn the example above we demonstrated typical basic usage of the Account object.\n\n### Sample source code\n\nFind the sample that demonstrates AppKit usage source code here: [https://github.com/tonlabs/sdk-samples/tree/master/demo/hello-wallet](https://github.com/tonlabs/sdk-samples/tree/master/demo/hello-wallet)\u0026#x20;\n\n## Subscribe for Changes\n\nSometimes it is required to listen for events related to an account in realtime.\n\nIt is easy: just call one of the `subscribe` methods of an account instance.\n\nFor example, if we need to track all changes in the account state on the blockchain we can use `subscribeAccount`:\n\n```ts\nconst hello = new Account(Hello, { signer });\nawait hello.deploy();\n\nawait hello.subscribeAccount(\"balance\", (acc) =\u003e {\n    // This callback triggers every time the account data \n    // is changed on the blockchain \n    console.log(\"Account has updated. Current balance is \", parseInt(acc.balance));\n});\n\nawait hello.subscribeMessages(\"boc\", async (msg) =\u003e {\n    // This callback triggers every time the message related to this account \n    // is appeared on the blockchain.\n    // Releated messages include inbound and outbound messages.  \n    console.log(\"Message is appeared \", msg);\n});\n\n// ...... do something with hello account ...........\n\n// In addition to other cleanup stuff the `free` method \n// unsubscribes all active subscriptions for this account instance.\nawait hello.free();\n```\n\n## Executing Contract on TVM\n\nThere are some situations where running the contract on the blockchain is not acceptable:\n\n* Writing a tests for developing contract.\n* Emulating execution for an existing account to detect failure reason or to calculate estimated fees.\n* Getting information from an existing account by running its get methods.\n\nIn these cases we can play with an account on the TVM included in EVER SDK client library:\n\n```ts\nconst hello = new Account(Hello, { signer });\n\n// We don't deploy contract on real network.\n// We just emulate it. After this call the hello instance\n// will have an account boc that can be used in consequent \n// calls.\nawait hello.deployLocal();\n\n// We execute contract locally.\n// But exactly the same way as it executes on the real blockchain.\nconst result = await hello.runLocal(\"touch\", {});\nconsole.log('Touch output', result);\n```\n\nWe can call get method on accounts in the blockchain:\n\n```ts\nconst acc = new Account(MyAccount, { address: someAddress });\n\n// Contracts code and data will be downloaded from the blockchain\n// and used to execute on the local TVM.\n// Without any fees.\nconst lastBid = (await acc.runLocal(\"getLastBid\", {})).decoded.output.lastBid;\nconsole.log('Last bid is', lastBid);\n\n// As laways we need to cleanup resources associated with insdtance.\nawait acc.free();\n```\n\nThere are some situations where running the contract on the blockchain is not acceptable:\n\n* Writing a tests for developing contract.\n* Emulating execution for an existing account to detect failure reason or to calculate estimated fees.\n* Getting information from an existing account by running its get methods.\n\nIn these cases we can play with an account on the TVM included in EVER SDK client library:\n\n```ts\nconst hello = new Account(Hello, { signer });\n\n// We don't deploy contract on real network.\n// We just emulate it. After this call the hello instance\n// will have an account boc that can be used in consequent \n// calls.\nawait hello.deployLocal();\n\n// We execute contract locally.\n// But exactly the same way as it executes on the real blockchain.\nconst result = await hello.runLocal(\"touch\", {});\nconsole.log('Touch output', result);\n```\n\nWe can call get method on accounts in the blockchain:\n\n```ts\nconst acc = new Account(MyAccount, { address: someAddress });\n\n// Contracts code and data will be downloaded from the blockchain\n// and used to execute on the local TVM.\n// Without any fees.\nconst lastBid = (await acc.runLocal(\"getLastBid\", {})).decoded.output.lastBid;\nconsole.log('Last bid is', lastBid);\n\n// As laways we need to cleanup resources associated with insdtance.\nawait acc.free();\n```\n\n## Interacting with Core SDK\n\nAppKit is a convenient library built over the EVER SDK core library. Of course the AppKit doesn't cover a lot of tasks the core SDK do.\n\nSo you have to easily interact with low level SDK functions. It is really easy.\n\nEach `Account` instance has a reference to the EVER SDK client instance. So you can use this reference.\n\n```ts\nasync function test(wallet: Account) {\n    const rnd = (await wallet.client.crypto.generate_random_bytes({\n        length: 100\n    })).bytes;\n}\n```\n\nEach account instance has an `abi` field with ABI this account belongs to.\n\n```ts\nasync function test(wallet: Account) {\n    const decoded = (await wallet.client.abi.decode_message_body({\n        abi: wallet.abi,\n        body: someMessageBody,\n        is_internal: false,\n    })).value;\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feverx-labs%2Fever-appkit-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feverx-labs%2Fever-appkit-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feverx-labs%2Fever-appkit-js/lists"}