JavaScript/TypeScript SDK
This page contains details related to a few JavaScript (JS) clients and the Casper JS SDK.
Usage of JavaScript Clients
The Casper team has implemented specific JS clients to support interaction with the Casper contracts.
Repository & Client Packages
We provide repositories to create clients for Casper contracts and usage examples of such clients dedicated to interacting with smart contracts on Casper:
These packages give you an easy way to install and interact with the corresponding Casper contract.
Casper SDK for JavaScript
The TypeScript/JavaScript SDK allows developers to interact with a Casper network using TypeScript or JavaScript. Version 5.0 represents a complete rewrite of the SDK with full compatibility for Casper 2.0, introducing new types, improved RPC capabilities, and support for both Transactions (Casper 2.0) and Deploys (legacy).
Installation
To install this library using Node.js, run the following command:
npm install casper-js-sdk --save
Note: The @next flag is no longer needed as v5.0 is now the stable release.
Migration from v2.x
If you're upgrading from v2.x, please refer to the v2 to v5 Migration Guide for detailed information about breaking changes and how to update your code.
Tests
You can find basic examples for how to use this library in the test directory. To run the tests, use this command:
npm run test
Usage Examples
In this section, we outline essential tasks you can accomplish with the JavaScript SDK:
- Generating account keys
- Sending a native transfer (Casper 2.0 Transaction)
- Sending a legacy deploy (backward compatibility)
- Creating CSPR, CEP-18, and NFT transfers
- Working with the RPC client
- Subscribing to SSE events
Generating Account Keys
This example shows you how to use the SDK to generate account keys using the new v5 API:
import { KeyAlgorithm, PrivateKey, PublicKey } from "casper-js-sdk";
const generateKeys = async () => {
// Choose algorithm: KeyAlgorithm.ED25519 or KeyAlgorithm.SECP256K1
const privateKeyAlgorithm = KeyAlgorithm.ED25519;
// Generate new private key
const privateKey = await PrivateKey.generate(privateKeyAlgorithm);
// Get public key from private key
const publicKey = privateKey.publicKey;
// Export keys as hex strings
const privateKeyHex = privateKey.toHex();
const publicKeyHex = publicKey.toHex();
console.log("Private Key (hex):", privateKeyHex);
console.log("Public Key (hex):", publicKeyHex);
return { privateKey, publicKey };
};
// Recreate private key from hex string
const loadPrivateKey = async (privateKeyHex, algorithm) => {
const privateKey = await PrivateKey.fromHex(privateKeyHex, algorithm);
return privateKey;
};
// Recreate public key from hex string
const loadPublicKey = (publicKeyHex) => {
const publicKey = PublicKey.fromHex(publicKeyHex);
return publicKey;
};
Note: In v5, the key generation API has changed significantly. The old Keys.Ed25519.new() pattern is replaced with PrivateKey.generate() and related methods.
Sending a Native Transfer (Casper 2.0)
This example shows how to create and send a native CSPR transfer using the new Transaction API (Casper 2.0):
import {
HttpHandler,
RpcClient,
NativeTransferBuilder,
PrivateKey,
KeyAlgorithm,
PublicKey,
} from "casper-js-sdk";
const sendNativeTransfer = async () => {
// Initialize RPC client
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
// Load or generate private key
const privateKey = await PrivateKey.generate(KeyAlgorithm.ED25519);
// Create a native transfer transaction
const transaction = new NativeTransferBuilder()
.from(privateKey.publicKey)
.target(
PublicKey.fromHex(
"0202f5a92ab6da536e7b1a351406f3744224bec85d7acbab1497b65de48a1a707b64"
)
)
.amount("2500000000") // Amount in motes (2.5 CSPR)
.id(Date.now()) // Transfer ID for tracking
.chainName("casper-net-1") // Or 'casper-test' for testnet
.payment(100_000_000) // Payment amount in motes
.build();
// Sign the transaction
transaction.sign(privateKey);
try {
// Submit transaction to the network
const result = await rpcClient.putTransaction(transaction);
console.log("Transaction Hash:", result.transactionHash);
// You can check the transaction status on the block explorer:
// Testnet: https://testnet.cspr.live/transaction/<transaction-hash>
// Mainnet: https://cspr.live/transaction/<transaction-hash>
console.log(
`View on explorer: https://testnet.cspr.live/transaction/${result.transactionHash}`
);
return result.transactionHash;
} catch (error) {
console.error("Transaction failed:", error);
throw error;
}
};
Sending a Legacy Deploy
For backward compatibility with Casper 1.5, you can still create and send deploys:
import {
Deploy,
DeployHeader,
ExecutableDeployItem,
HttpHandler,
PublicKey,
KeyAlgorithm,
PrivateKey,
RpcClient,
TransferDeployItem,
} from "casper-js-sdk";
const sendLegacyDeploy = async () => {
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
const senderKey = await PrivateKey.generate(KeyAlgorithm.ED25519);
const recipientKey = PublicKey.fromHex(
"010068920746ecf5870e18911EE1fC5db975E0e97fFFcBBF52f5045Ad6C9838D2F"
);
const paymentAmount = "10000000000000";
const transferAmount = "10";
const transferId = 35;
// Create session (transfer)
const session = new ExecutableDeployItem();
session.transfer = TransferDeployItem.newTransfer(
transferAmount,
recipientKey,
undefined,
transferId
);
// Create payment
const payment = ExecutableDeployItem.standardPayment(paymentAmount);
// Create deploy header
const deployHeader = DeployHeader.default();
deployHeader.account = senderKey.publicKey;
deployHeader.chainName = "casper-test";
// Make deploy
const deploy = Deploy.makeDeploy(deployHeader, payment, session);
// Sign deploy
deploy.sign(senderKey);
// Submit deploy
const result = await rpcClient.putDeploy(deploy);
console.log("Deploy Hash:", result.deployHash);
// You can check the deploy status on the block explorer:
// Testnet: https://testnet.cspr.live/transaction/<deploy-hash>
// Mainnet: https://cspr.live/transaction/<deploy-hash>
console.log(
`View on explorer: https://testnet.cspr.live/transaction/${result.deployHash}`
);
return result.deployHash;
};
Serializing and Deserializing Transactions
You can serialize transactions to JSON for storage, transmission, or later processing:
import { Transaction } from "casper-js-sdk";
// Serialize a transaction to JSON
const serializeTransaction = (transaction) => {
const jsonString = JSON.stringify(transaction.toJSON());
console.log("Serialized Transaction:", jsonString);
// Store it, send it over network, etc.
return jsonString;
};
// Deserialize a transaction from JSON
const deserializeTransaction = (json) => {
const transaction = Transaction.fromJSON(json);
console.log("Deserialized Transaction:", transaction);
return transaction;
};
// Example usage
const transaction = new NativeTransferBuilder()
.from(privateKey.publicKey)
.target(recipientPublicKey)
.amount("2500000000")
.chainName("casper-test")
.payment(100_000_000)
.build();
transaction.sign(privateKey);
// Serialize
const serialized = serializeTransaction(transaction);
// Later, deserialize
const restoredTransaction = deserializeTransaction(serialized);
// The restored transaction can now be submitted
await rpcClient.putTransaction(restoredTransaction);
Serializing and Deserializing Deploys
Similarly, you can serialize and deserialize legacy deploys:
import { Deploy } from "casper-js-sdk";
// Serialize a deploy to JSON
const serializeDeploy = (deploy) => {
const jsonObject = Deploy.toJSON(deploy);
const jsonString = JSON.stringify(jsonObject);
console.log("Serialized Deploy:", jsonString);
// Store it, send it over network, etc.
return jsonString;
};
// Deserialize a deploy from JSON
const deserializeDeploy = (json) => {
const deploy = Deploy.fromJSON(json);
console.log("Deserialized Deploy:", deploy);
return deploy;
};
// Example usage
const deploy = makeCsprTransferDeploy({
senderPublicKeyHex: privateKey.publicKey.toHex(),
recipientPublicKeyHex: "0123456789abcdef...",
transferAmount: "2500000000",
});
deploy.sign(privateKey);
// Serialize
const serialized = serializeDeploy(deploy);
// Later, deserialize
const restoredDeploy = deserializeDeploy(serialized);
// The restored deploy can now be submitted
await rpcClient.putDeploy(restoredDeploy);
Use Cases for Serialization:
- Store transactions/deploys in a database
- Send transactions/deploys between different parts of your application
- Create transaction/deploy templates for later signing
- Implement offline transaction signing workflows
- Debug and inspect transaction/deploy structure
Using Helper Functions for CSPR Transfers
The SDK provides convenient helper functions for common operations:
import {
HttpHandler,
RpcClient,
KeyAlgorithm,
PrivateKey,
makeCsprTransferDeploy,
} from "casper-js-sdk";
const sendCsprTransfer = async () => {
// Load private key
const privateKey = await PrivateKey.fromHex(
"your-private-key-hex",
KeyAlgorithm.ED25519
);
// Create transfer deploy using helper function
const deploy = makeCsprTransferDeploy({
senderPublicKeyHex: privateKey.publicKey.toHex(),
recipientPublicKeyHex: "0123456789abcdef...",
transferAmount: "2500000000", // 2.5 CSPR in motes
});
// Sign deploy
deploy.sign(privateKey);
// Initialize RPC client and submit
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
const result = await rpcClient.putDeploy(deploy);
console.log("Deploy Hash:", result.deployHash);
// Check deploy status on block explorer
console.log(
`View on explorer: https://testnet.cspr.live/transaction/${result.deployHash}`
);
return result.deployHash;
};
Auction Manager Operations
Delegate, undelegate, or redelegate CSPR using the auction manager:
import {
HttpHandler,
RpcClient,
KeyAlgorithm,
PrivateKey,
makeAuctionManagerDeploy,
AuctionManagerEntryPoint,
} from "casper-js-sdk";
const delegateStake = async () => {
const privateKey = await PrivateKey.fromHex(
"your-private-key-hex",
KeyAlgorithm.ED25519
);
const deploy = makeAuctionManagerDeploy({
contractEntryPoint: AuctionManagerEntryPoint.delegate,
delegatorPublicKeyHex: privateKey.publicKey.toHex(),
validatorPublicKeyHex: "0123456789abcdef...",
amount: "500000000000", // 500 CSPR in motes
});
deploy.sign(privateKey);
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
const result = await rpcClient.putDeploy(deploy);
console.log("Deploy Hash:", result.deployHash);
return result.deployHash;
};
CEP-18 Token Transfers
Transfer CEP-18 tokens using the SDK:
import {
HttpHandler,
RpcClient,
KeyAlgorithm,
PrivateKey,
makeCep18TransferDeploy,
} from "casper-js-sdk";
const transferCep18Token = async () => {
const privateKey = await PrivateKey.fromHex(
"your-private-key-hex",
KeyAlgorithm.ED25519
);
const deploy = await makeCep18TransferDeploy({
contractHash: "hash-of-cep18-contract...",
senderPublicKeyHex: privateKey.publicKey.toHex(),
recipientPublicKeyHex: "0123456789abcdef...",
transferAmount: "25000000000", // Amount with decimals
paymentAmount: "3000000000", // 3 CSPR in motes
});
deploy.sign(privateKey);
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
const result = await rpcClient.putDeploy(deploy);
console.log("Deploy Hash:", result.deployHash);
return result.deployHash;
};
NFT Transfers
Transfer NFTs using CEP-47 or CEP-78 standards:
import {
HttpHandler,
RpcClient,
KeyAlgorithm,
PrivateKey,
makeNftTransferDeploy,
NFTTokenStandard,
} from "casper-js-sdk";
const transferNft = async () => {
const privateKey = await PrivateKey.fromHex(
"your-private-key-hex",
KeyAlgorithm.ED25519
);
const deploy = await makeNftTransferDeploy({
nftStandard: NFTTokenStandard.CEP78, // or NFTTokenStandard.CEP47
contractPackageHash: "hash-of-nft-contract...",
senderPublicKeyHex: privateKey.publicKey.toHex(),
recipientPublicKeyHex: "0123456789abcdef...",
paymentAmount: "3000000000", // 3 CSPR in motes
tokenId: 234, // NFT token ID
});
deploy.sign(privateKey);
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
const result = await rpcClient.putDeploy(deploy);
console.log("Deploy Hash:", result.deployHash);
return result.deployHash;
};
Using the RPC Client
The RPC client provides access to all Casper network RPC methods:
import { HttpHandler, RpcClient } from "casper-js-sdk";
const queryNetwork = async () => {
const rpcHandler = new HttpHandler("http://<Node Address>:7777/rpc");
const rpcClient = new RpcClient(rpcHandler);
// Get deploy information
const deployHash =
"3facbc4133e722c5c5630b6ad2331383ba849ef719da582cc026e9dd85e72ac9";
const deployResult = await rpcClient.getDeploy(deployHash);
console.log("Deploy Result:", deployResult);
// Get transaction information (Casper 2.0)
const txHash =
"ef6a3f8f6c6412b9b2a6eb392d1ca6822e32b791ed7da3236dd0d062b2759bb5";
const txResult = await rpcClient.getTransactionByTransactionHash(txHash);
console.log("Transaction Result:", txResult);
// Get network status
const status = await rpcClient.getStatus();
console.log("Network Status:", status);
// Get account balance
const publicKey = "01ab..."; // Account public key hex
const balance = await rpcClient.queryBalance(publicKey);
console.log("Account Balance:", balance);
};
Subscribing to SSE Events
Listen to blockchain events using Server-Sent Events:
import { SseClient, EventName } from "casper-js-sdk";
const subscribeToEvents = () => {
const sseClient = new SseClient("http://<Node Address>:9999/events");
// Subscribe to block added events
sseClient.subscribe(EventName.BlockAddedEventType, (rawEvent) => {
try {
const parsedEvent = rawEvent.parseAsBlockAddedEvent();
console.log("New Block Hash:", parsedEvent.BlockAdded.blockHash);
console.log("Block Height:", parsedEvent.BlockAdded.blockHeader.height);
} catch (error) {
console.error("Error processing event:", error);
}
});
// Subscribe to transaction processed events (Casper 2.0)
sseClient.subscribe(EventName.TransactionProcessedEventType, (rawEvent) => {
try {
const parsedEvent = rawEvent.parseAsTransactionProcessedEvent();
console.log(
"Transaction Hash:",
parsedEvent.TransactionProcessed.transactionHash
);
} catch (error) {
console.error("Error processing event:", error);
}
});
// Start the client (optionally with last known event ID)
const lastEventID = 1234; // Optional: resume from specific event
sseClient.start(lastEventID);
};
Key Changes in v5
- New Key Management API:
PrivateKeyandPublicKeyclasses replace the oldKeysAPI - Transaction Support: New
Transactionand builder classes for Casper 2.0 - Improved Type System: Complete TypeScript rewrite with better type safety
- RPC Client Updates: New methods supporting both Casper 1.5 and 2.0
- Helper Functions: More utility functions like
makeCsprTransferDeploy,makeAuctionManagerDeploy - SSE Improvements: Enhanced event handling and parsing
- Backward Compatibility: Continued support for legacy Deploy system
For comprehensive information about all changes, please refer to the official migration guide and full documentation.