The @ic-reactor/core
package provides a streamlined way to interact with the Internet Computer (IC). It simplifies agent and actor management, ensuring type-safe communication with canisters. This package offers utilities for creating and managing IC agents, enabling seamless interaction through a friendly API.
To get started with @ic-reactor/core
, you can install the package using npm or Yarn:
Using npm:
npm install @ic-reactor/core
Using Yarn:
yarn add @ic-reactor/core
or you can use the UMD version:
<script src="https://github.com/B3Pay/ic-reactor/releases/download/v1.12.0/ic-reactor-core.min.js"></script>
createReactorCore
For ease of use, the createReactorCore
factory function automatically sets up a new Reactor instance, managing the agent and its state internally, and providing a simple API for authenticating, querying, and updating actors.
Example:
import { createReactorCore } from "@ic-reactor/core"
import { candid, canisterId, idlFactory } from "./declarations/candid"
type Candid = typeof candid
const { queryCall, updateCall, getPrincipal, login } =
createReactorCore<Candid>({
canisterId,
idlFactory,
withProcessEnv: true, // will use process.env.DFX_NETWORK
})
You can find All available methods are returned from the createReactorCore
function here.
// later in your code
await login({
onSuccess: () => {
console.log("Logged in successfully")
},
onError: (error) => {
console.error("Failed to login:", error)
},
})
// queryCall, will automatically call and return a promise with the result
const { dataPromise, call } = queryCall({
functionName: "icrc1_balance_of",
args: [{ owner: getPrincipal(), subaccount: [] }],
})
console.log(await dataPromise)
// updateCall
const { call, subscribe } = updateCall({
functionName: "icrc1_transfer",
args: [
{
to: { owner: getPrincipal(), subaccount: [] },
amount: BigInt(10000000000),
fee: [],
memo: [],
created_at_time: [],
from_subaccount: [],
},
],
})
// subscribe to the update call
subscribe(({ loading, error, data }) => {
console.log({ loading, error, data })
})
const result = await call()
console.log(result)
When interacting with multiple canisters using @ic-reactor/core
, you need one agent manager for each canister. This way, you can create separate reactor for each canister. This enables modular interaction with different services on the Internet Computer,
and allows you to manage the state of each actor independently.
Here's how to adjust the example to handle methods that require multiple arguments:
Fist you need to create a agent manager:
// agent.ts
import { createAgentManager } from "@ic-reactor/core"
export const agentManager = createAgentManager() // Connects to IC network by default
Then you can create a Actor for each canister:
// Assuming you've already set up `candidA`, `candidB`, and `agentManager`
import { createActorManager } from "@ic-reactor/core"
import * as candidA from "./declarations/candidA"
import * as candidB from "./declarations/candidB"
import { agentManager } from "./agent"
type CandidA = typeof candidA.candidA
type CandidB = typeof candidB.candidB
const actorA = createActorManager<CandidA>({
agentManager,
canisterId: candidA.canisterId,
idlFactory: candidA.idlFactory,
})
const actorB = createActorManager<CandidB>({
agentManager,
canisterId: candidB.canisterId,
idlFactory: candidB.idlFactory,
})
You can now use the actorA
and actorB
instances to interact with their respective canisters:
const { dataPromise: version } = actorA.queryCall({
functionName: "version",
})
console.log("Response from CanisterA method:", await version)
const { dataPromise: balance } = actorB.queryCall({
functionName: "balance",
args: [principal, []],
})
console.log("Response from CanisterB method:", await balance)
The CandidAdapter
class is used to interact with a canister and retrieve its Candid interface definition. It provides methods to fetch the Candid definition either from the canister's metadata or by using a temporary hack method.
If both methods fail, it throws an error.
import { createCandidAdapter } from "@ic-reactor/core"
import { agentManager } from "./agent"
const candidAdapter = createCandidAdapter({ agentManager })
const canisterId = "ryjl3-tyaaa-aaaaa-aaaba-cai"
// Usage example
try {
const definition = await candidAdapter.getCandidDefinition(canisterId)
console.log(definition)
} catch (error) {
console.error(error)
}
createReactorCore
with CandidAdapter
You can use the candidAdapter
to fetch the Candid definition and then pass it to the createReactorCore
function.
import { createReactorCore, createCandidAdapter } from "@ic-reactor/core"
import { agentManager } from "./agent"
const candidAdapter = createCandidAdapter({ agentManager })
const canisterId = "ryjl3-tyaaa-aaaaa-aaaba-cai" // NNS ICP Ledger Canister
// Usage example
try {
const { idlFactory } = await candidAdapter.getCandidDefinition(canisterId)
const { callMethod } = createReactorCore({
agentManager,
canisterId,
idlFactory,
})
const name = await callMethod("name")
console.log(name) // { name: 'Internet Computer' }
} catch (error) {
console.error(error)
}
If you require more control over the state management, you can use the createReactorStore
function to create a store that provides methods for querying and updating actors.
import { createReactorStore } from "@ic-reactor/core"
import { candid, canisterId, idlFactory } from "./declarations/candid"
type Candid = typeof candid
const { agentManager, callMethod } = createReactorStore<Candid>({
canisterId,
idlFactory,
})
// Usage example
await agentManager.authenticate()
const authClient = agentManager.getAuth()
authClient?.login({
onSuccess: () => {
console.log("Logged in successfully")
},
onError: (error) => {
console.error("Failed to login:", error)
},
})
// Call a method
const version = callMethod("version")
console.log("Response from version method:", await version)
IC Agent Example:
// agent.ts
import { createAgentManager } from "@ic-reactor/core"
export const agentManager = createAgentManager() // Connects to IC network by default
Local Agent Example:
For development purposes, you might want to connect to a local instance of the IC network:
// agent.ts
import { createAgentManager } from "@ic-reactor/core"
export const agentManager = createAgentManager({
withLocalEnv: true,
port: 8000, // Default port is 4943
})
Alternatively, you can specify a host directly:
// agent.ts
import { createAgentManager } from "@ic-reactor/core"
export const agentManager = createAgentManager({
host: "http://localhost:8000",
})
You can use Actor Managers to create your implementation of an actor. This allows you to manage the actor's lifecycle and state, as well as interact with the actor's methods.
// actor.ts
import { createActorManager } from "@ic-reactor/core"
import { candid, canisterId, idlFactory } from "./declarations/candid"
import { agentManager } from "./agent"
type Candid = typeof candid
const candidActor = createActorManager<Candid>({
agentManager,
canisterId,
idlFactory,
})
// Usage example
const data = await candidActor.callMethod("version")
console.log(data)