Cartridge Controller Node.js Integration
This guide demonstrates how to integrate the Cartridge Controller with a Node.js application.
Installation
npm
npm install @cartridge/controller starknetBasic Setup
import SessionProvider, {
ControllerError,
} from "@cartridge/controller/session/node";
import { constants } from "starknet";
import path from "path";
export const STRK_CONTRACT_ADDRESS =
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
async function main() {
// Path to store session
const storagePath =
process.env.CARTRIDGE_STORAGE_PATH ||
path.join(process.cwd(), ".cartridge");
// Create a session provider
const provider = new SessionProvider({
rpc: "https://api.cartridge.gg/x/starknet/sepolia",
chainId: constants.StarknetChainId.SN_SEPOLIA,
policies: {
contracts: {
[STRK_CONTRACT_ADDRESS]: {
methods: [
{
name: "transfer",
entrypoint: "transfer",
description: "Transfer STRK",
},
],
},
},
},
basePath: storagePath,
});
console.log("Registering a session...");
console.log("Open the URL printed below to authorize the session.");
try {
// Connect and create session
const account = await provider.connect();
if (!account) {
console.log("Session not ready yet. Complete the browser flow and rerun.");
return;
}
console.log("Session ready!");
console.log("Account address:", account.address);
// Example: Transfer STRK
const recipient = account.address; // Self transfer for demo
const amount = "0x0"; // Keep it minimal for a demo
const result = await account.execute([
{
contractAddress: STRK_CONTRACT_ADDRESS,
entrypoint: "transfer",
calldata: [recipient, amount, "0x0"],
},
]);
console.log("Transaction hash:", result.transaction_hash);
} catch (error: unknown) {
const controllerError = error as ControllerError;
if (controllerError?.code) {
console.error("Execute error:", {
code: controllerError.code,
message: controllerError.message,
data: controllerError.data,
});
} else {
console.error("Execute error:", error);
}
}
}
main().catch(console.error);Important Notes
-
The
basePathparameter specifies where session data will be stored. Make sure the directory is writable. -
When running the application for the first time, you'll need to complete the session creation in your browser. The application will provide instructions.
-
Session data is persisted between runs, so you don't need to create a new session each time.
-
The example includes proper error handling for Controller-specific errors, which include additional context through the
codeanddatafields. -
Keep your RPC endpoints and contract addresses secure, preferably in environment variables.