Security News
The Push to Ban Ransom Payments Is Gaining Momentum
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
@radixdlt/babylon-core-api-sdk
Advanced tools
Readme
This SDK is a thin wrapper around the Babylon Core API.
The Core API SDK code is released under an Apache 2.0 license. The executable components are licensed under the Radix Software EULA.
The CoreApiClient
is the main exported object. It includes high-level wrappers around every sub-API:
LTS
/ lts
- For long term support/backward compatible endpoints aimed at integrators such as exchanges.Status
- For status and configuration details for the node / engine.Mempool
- For information on the contents of the node's mempool.State
- For reading the state of entities.Stream
- For reading the committed transactions.Transaction
- For transaction construction, preview, submission, and monitoring the status of an individual transaction.All high level wrappers internally instantiate classes generated from OpenAPI specification. In order to query automatically generated code, you can either use innerClient
property on each of high level APIs or access them through coreApiClient.lowLevel.X
where X
is each of the different sub-APIs.
See here for a full end-to-end example working with the TypeScript Radix Engine Toolkit.
You can instantiate a Core API Client with CoreApiClient.initialize({ ... })
and various configuration options.
The options you provide will depend on how your node is configured, and how you're connecting to it.
The client checks that it can connect to the Core API at initialize
time.
If running against RCnet-V2, with a full node running on localhost (such as running testnet-node/run.sh
in local development), with its Core API bound to 3333, you can use:
import { CoreApiClient } from "@radixdlt/babylon-core-api-sdk";
const coreApiClient = await CoreApiClient.initialize({
basePath: "http://127.0.0.1:3333/core", // Note: 127.0.0.1 works better than localhost on Node.JS
logicalNetworkName: "zabanet",
// Further options - explained below...
});
If this doesn't work, please see further options below.
Behind the scenes, this library uses the fetch API:
fetch
is provided natively, so you don't need add a fetch
parameter.node-fetch
version ^2.6.13
(as 3.x
can only be imported as an ESModule).@types/node-fetch
version ^2.6.3
import fetch from "node-fetch"
import { CoreApiClient } from "@radixdlt/babylon-core-api-sdk";
const coreApiClient = await CoreApiClient.initialize({
// ...
fetch,
});
If you have set up your node using the Radix Node CLI, then the node will likely be configured with its APIs exposed via nginx, and bound to the standard https port.
You will have set up some custom basic authentication for this API, and by default, nginx will use a self-signed certificate.
To work with this set-up you will need to:
basePath
is set up to connect to the correct host and port, on which nginx is bound.Authorization
header on your request, configured with your basic auth credentials for the Core API.agent
/ dispatcher
configuration, include the self-signed certificate by using the ca
parameter, or if you understand the implications and have precautions against MITM, use rejectUnauthorized: false
with the https agent.node-fetch
An example, with the rejectUnauthorized: false
line, assuming you are EG on localhost, or a private network where MITM attacks are mitigated.
import fetch from "node-fetch"
import https from "node:https";
import { CoreApiClient } from "@radixdlt/babylon-core-api-sdk";
const basicAuthUsername = "admin";
const basicAuthPassword = "????"; // From your node set-up - provide this securely to your application
const coreApiClient = await CoreApiClient.initialize({
basePath: "https://127.0.0.1/core",
logicalNetworkName: "zabanet",
advanced: {
agent: new https.Agent({
keepAlive: true,
// NOTE - Only add the below line if you've taken precautions to avoid MITM attacks between you and the node
rejectUnauthorized: false,
}),
headers: {
"Authorization": `Basic ${Buffer.from(`${basicAuthUsername}:${basicAuthPassword}`).toString("base64")}`
}
}
});
fetch
If wanting to customise the certificate settings on the request, you will need install undici
(as per this comment):
The below includes the rejectUnauthorized: false
line, assuming you are EG on localhost, or a private network where MITM attacks are mitigated.
import { CoreApiClient } from "@radixdlt/babylon-core-api-sdk";
import { Agent } from 'undici';
const basicAuthUsername = "admin";
const basicAuthPassword = "????"; // From your node set-up - provide this securely to your application
const coreApiClient = await CoreApiClient.initialize({
basePath: "https://127.0.0.1/core",
logicalNetworkName: "zabanet",
advanced: {
dispatcher: new Agent({
connect: {
// NOTE - Only add the below line if you've taken precautions to avoid MITM attacks between you and the node
rejectUnauthorized: false,
},
}),
headers: {
"Authorization": `Basic ${Buffer.from(`${basicAuthUsername}:${basicAuthPassword}`).toString("base64")}`
}
}
});
The Core API has a "Long Term Support" sub-API. This is documented in the API specification.
The client has a high-level LTS
API, which includes the following features:
getConstructionMetadata
includes a node synced-up checksubmitTransaction
handles different submit transaction errorsConstruction and submission looks something like this:
import { LtsCommittedTransactionStatus } from "@radixdlt/babylon-core-api-sdk";
const constructionMetadata = await coreApiClient.lts.getConstructionMetadata();
const currentEpoch = constructionMetadata.current_epoch;
const { notarizedTransactionHex, intentHash } = buildTransaction(currentEpoch, ...);
/**
* By testing `submitResponse.result`, you can distinguish different possible results
* Some of these possible results will need to be handled.
* See the integrators guide for more information.
*/
const submitResponse = await coreApiClient.lts.submitTransaction({
notarized_transaction_hex: notarizedTransactionHex
});
console.log(submitResponse);
/**
* By testing `statusResponse.intent_status`, you can see different intent statuses.
*
* You may wish to poll this endpoint until it is one of:
* - LtsTransactionIntentStatus.CommittedSuccess
* - LtsTransactionIntentStatus.CommittedFailure
* - LtsTransactionIntentStatus.PermanentRejection
*
* See the integrators guide for more information.
*/
const statusResponse = await coreApiClient.lts.getTransactionStatus({
intent_hash: intentHash
});
console.log(statusResponse);
if (statusResponse.committed_state_version) {
const committedOutcomeResponse = await coreApiClient.lts.getTransactionOutcome({
state_version: statusResponse.committed_state_version
});
if (committedOutcomeResponse?.status == LtsCommittedTransactionStatus.Success) {
console.log("Committed success");
} else if (committedOutcomeResponse?.status == LtsCommittedTransactionStatus.Failure) {
console.log("Committed failure");
}
}
Account balance queries look like this:
const accountAddress = "..";
const resourceAddress = "..";
const balanceResponse = await coreApiClient.lts.getAccountFungibleResourceBalance({
account_address: accountAddress,
resource_address: resourceAddress,
});
const allBalancesResponse = await coreApiClient.lts.getAccountAllFungibleResourceBalances({
account_address: accountAddress,
});
You can get transaction outcomes in ledger order with these endpoints.
You can sum the fungible_entity_balance_changes
from the transaction outcomes to track balance changes in components including accounts.
const accountAddress = "..";
const transactionsBatch = await coreApiClient.lts.getTransactionOutcomes({
from_state_version: 1,
limit: 100,
});
const accountTransactionsBatch = await coreApiClient.lts.getAccountTransactionOutcomes({
account_address: accountAddress,
from_state_version: 1,
limit: 100,
});
FAQs
A client for the RadixDLT Babylon Core API
We found that @radixdlt/babylon-core-api-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
Application Security
New SEC disclosure rules aim to enforce timely cyber incident reporting, but fear of job loss and inadequate resources lead to significant underreporting.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).