The Spheron Protocol SDK for Node.js provides a comprehensive set of modules to interact with the Spheron decentralized infrastructure. This includes modules for lease management, deployment operations, and escrow functionality.
- Node.js: Version 14 or higher.
- npm: Version 6 or higher.
- Docker: If you plan to run the Provider Proxy Server using Docker.
- Git: For cloning the repository if running the Provider Proxy Server from source.
Install the Spheron SDK for Node.js using npm:
npm install @spheron/protocol-sdkOr using yarn:
yarn add @spheron/protocol-sdkTo use the Spheron SDK, first import it and initialize it with the desired network type:
const { SpheronSDK } = require('@spheron/protocol-sdk');
const sdk = new SpheronSDK('testnet');Note: Chain type can be testnet or mainnet. But currently, only testnet is supported.
If you want to perform write operations, you'll need to provide a private key:
const sdk = new SpheronSDK('testnet', 'your-private-key');Note: Never hardcode your private key; use environment variables or secure key management systems.
networkType: Specifies the environment. Possible values are'testnet'or'mainnet'.privateKey(optional): Private key for signing transactions.
The SDK provides several modules for different functionalities:
- Escrow Module: Handles escrow-related operations, such as user balance management, deposits, withdrawals, and earnings management.
- Deployment Module: Facilitates the creation, updating, and closing of deployments.
- Lease Module: Manages compute leases, including retrieving lease details and managing active leases.
The Escrow Module handles operations related to the escrow system, allowing users to manage their token balances within the Spheron ecosystem.
Fetches the user's balance from the escrow contract for a given token and wallet address.
const balance = await sdk.escrow.getUserBalance('USDT', '0xYourWalletAddress');
console.log('Your USDT balance in escrow is:', balance);token(string): The token symbol. Supported tokens areUSDT,USDC,DAI, andWETH.walletAddress(string, optional): The wallet address to query. If not provided, the wallet associated with the provided private key will be used.
Promise<object>: An object containing the user's balance information:lockedBalance(string): The locked balance of the specified token in the escrow.unlockedBalance(string): The unlocked balance of the specified token in the escrow.token(object): Details about the token:name(string): The name of the token.symbol(string): The symbol of the token.decimal(number): The number of decimal places for the token.
Deposits a specified amount of tokens into the escrow contract.
const depositReceipt = await sdk.escrow.depositBalance({
token: 'USDC',
amount: 100,
});
console.log('Deposit transaction receipt:', depositReceipt);token(string): The token symbol to deposit (USDT,USDC,DAI,WETH).amount(number): The amount to deposit.
Promise<object>: The transaction receipt of the deposit operation.
Withdraws a specified amount of tokens from the escrow contract.
const withdrawReceipt = await sdk.escrow.withdrawBalance({
token: 'DAI',
amount: 50,
});
console.log('Withdrawal transaction receipt:', withdrawReceipt);token(string): The token symbol to withdraw (USDT,USDC,DAI,WETH).amount(number): The amount to withdraw.
Promise<object>: The transaction receipt of the withdrawal operation.
Retrieves the earnings information for a provider.
const providerAddress = '0xProviderAddress';
const tokenAddress = '0xTokenAddress';
const earnings = await sdk.escrow.getProviderEarnings(providerAddress, tokenAddress);
console.log('Provider earnings:', earnings);providerAddress(string): The address of the provider.tokenAddress(string): The address of the token.
Promise<object>: An object containing the provider's earnings information:earned(string): The total amount earned.withdrawn(string): The amount withdrawn.balance(string): The current balance.
Retrieves the earnings information for a Fizz node.
const fizzAddress = '0xFizzNodeAddress';
const tokenAddress = '0xTokenAddress';
const earnings = await sdk.escrow.getFizzEarnings(fizzAddress, tokenAddress);
console.log('Fizz node earnings:', earnings);fizzAddress(string): The address of the Fizz node.tokenAddress(string): The address of the token.
Promise<object>: An object containing the Fizz node's earnings information:earned(string): The total amount earned.withdrawn(string): The amount withdrawn.balance(string): The current balance.
Withdraws earnings for a provider.
const withdrawalData = {
rewardWallet: '0xRewardWalletAddress',
tokenAddress: '0xTokenAddress',
amount: 100,
decimals: 18,
};
const withdrawalReceipt = await sdk.escrow.withdrawProviderEarnings(withdrawalData);
console.log('Provider earnings withdrawal receipt:', withdrawalReceipt);rewardWallet(string): The address of the reward wallet.tokenAddress(string): The address of the token to withdraw.amount(number): The amount to withdraw.decimals(number): The number of decimals for the token.onSuccessCallback(function, optional): Callback function for successful withdrawal.onFailureCallback(function, optional): Callback function for failed withdrawal.
Promise<object>: The transaction receipt of the withdrawal operation.
Withdraws earnings for a Fizz node.
const withdrawalData = {
rewardWallet: '0xRewardWalletAddress',
tokenAddress: '0xTokenAddress',
amount: 100,
decimals: 18,
};
const withdrawalReceipt = await sdk.escrow.withdrawFizzEarnings(withdrawalData);
console.log('Fizz node earnings withdrawal receipt:', withdrawalReceipt);rewardWallet(string): The address of the reward wallet.tokenAddress(string): The address of the token to withdraw.amount(number): The amount to withdraw.decimals(number): The number of decimals for the token.onSuccessCallback(function, optional): Callback function for successful withdrawal.onFailureCallback(function, optional): Callback function for failed withdrawal.
Promise<object>: The transaction receipt of the withdrawal operation.
The Deployment Module streamlines the process of creating, updating, retrieving, and closing deployments on the Spheron network.
Creates a new deployment using the ICL (Infrastructure Configuration Language) YAML configuration.
const iclYaml = `
version: "1.0"
services:
py-cuda:
image: quay.io/jupyter/pytorch-notebook:cuda12-pytorch-2.4.1
expose:
- port: 8888
as: 8888
to:
- global: true
env:
- JUPYTER_TOKEN=sentient
profiles:
name: py-cuda
duration: 2h
mode: provider
tier:
- community
compute:
py-cuda:
resources:
cpu:
units: 8
memory:
size: 16Gi
storage:
- size: 200Gi
gpu:
units: 1
attributes:
vendor:
nvidia:
- model: rtx4090
placement:
westcoast:
attributes:
region: us-central
pricing:
py-cuda:
token: USDT
amount: 10
deployment:
py-cuda:
westcoast:
profile: py-cuda
count: 1
`;
const providerProxyUrl = 'http://your-provider-proxy-url'; // run the provider proxy server using the code from the provider proxy server repo and the readme instructions in the repo
const deploymentResult = await sdk.deployment.createDeployment(iclYaml, providerProxyUrl);
console.log('Deployment result:', deploymentResult);iclYaml(string): The deployment configuration in YAML format.providerProxyUrl(string): URL of the provider proxy server.
Promise<object>: An object containing:leaseId(string): The ID of the newly created lease.transaction(object): The transaction details of the deployment creation.
Updates an existing deployment using the Lease ID and ICL YAML configuration.
const updatedIclYaml = `
version: "1.0"
services:
py-cuda:
image: quay.io/jupyter/pytorch-notebook:cuda12-pytorch-2.4.1
expose:
- port: 8888
as: 8888
to:
- global: true
env:
- JUPYTER_TOKEN=sentient
profiles:
name: py-cuda
duration: 2h
mode: provider
tier:
- community
compute:
py-cuda:
resources:
cpu:
units: 4
memory:
size: 8Gi
storage:
- size: 100Gi
gpu:
units: 1
attributes:
vendor:
nvidia:
- model: rtx4090
placement:
westcoast:
attributes:
region: us-central
pricing:
py-cuda:
token: USDT
amount: 10
deployment:
py-cuda:
westcoast:
profile: py-cuda
count: 1
`;
const leaseId = 'your-lease-id';
const updateResult = await sdk.deployment.updateDeployment(
leaseId,
updatedIclYaml,
providerProxyUrl
);
console.log('Update result:', updateResult);leaseId(string): Lease ID of the deployment to update.iclYaml(string): The updated deployment configuration in YAML format.providerProxyUrl(string): URL of the provider proxy server.
Promise<object>: An object containing:orderId(string): The ID of the updated order.providerAddress(string): The address of the provider handling the deployment.
Retrieves the details of an existing deployment based on the provided Lease ID.
const leaseId = 'your-lease-id';
const deploymentDetails = await sdk.deployment.getDeployment(leaseId, providerProxyUrl);
console.log('Deployment details:', deploymentDetails);leaseId(string): Lease ID of the deployment.providerProxyUrl(string): URL of the provider proxy server.
Promise<object>: An object containing the deployment details, including:services(object): Information about the deployed services, where each key is the service name:name(string): The name of the service.available(number): The number of available instances.total(number): The total number of instances.observed_generation(number): The observed generation of the service.replicas(number): The number of replicas.updated_replicas(number): The number of updated replicas.ready_replicas(number): The number of ready replicas.available_replicas(number): The number of available replicas.container_statuses(array): Status information for the containers.creationTimestamp(string): The timestamp when the service was created.
forwarded_ports(object): Information about forwarded ports for each service:[service_name](array): An array of port forwarding objects:host(string): The hostname for accessing the service.port(number): The original port of the service.externalPort(number): The external port mapped to the service.proto(string): The protocol used (e.g., 'TCP').name(string): The name of the service.
ips(null | object): IP information (if available).
Closes an existing deployment using the Lease ID.
const leaseId = 'your-lease-id';
const closeDeploymentResult = await sdk.deployment.closeDeployment(leaseId);
console.log('Deployment closed:', closeDeploymentResult);leaseId(string): Lease ID of the deployment to close.
Promise<object>: The transaction receipt of the close operation, including:hash(string): The hash of the transaction.blockNumber(number): The block number in which the transaction was included.gasUsed(BigNumber): The amount of gas used for the transaction.- Other standard Ethereum transaction receipt fields.
Note: To submit manifests to a provider, a proxy server needs to be set up by the SDK consumer. You can find the proxy server code and instructions here.
The Lease Module provides functionality for managing and interacting with compute leases.
Retrieves detailed information about a specific lease.
const leaseId = 'your-lease-id';
const leaseDetails = await sdk.leases.getLeaseDetails(leaseId);
console.log('Lease details:', leaseDetails);leaseId(string): Lease ID to retrieve details for.
Promise<object>: An object containing the details of the lease:leaseId(string): The ID of the lease.fizzId(string): The ID of the associated Fizz node.requestId(string): The ID of the request associated with this lease.resourceAttribute(object): Details about the resources allocated:cpuUnits(number): Number of CPU units.cpuAttributes(array): Additional CPU attributes.ramUnits(number): Amount of RAM allocated.ramAttributes(array): Additional RAM attributes.gpuUnits(number): Number of GPU units.gpuAttributes(array): Additional GPU attributes.endpointsKind(number): Type of endpoints.endpointsSequenceNumber(number): Sequence number for endpoints.
acceptedPrice(string): The accepted price for the lease.providerAddress(string): The address of the provider.tenantAddress(string): The address of the tenant.startBlock(string): The block number when the lease started.startTime(number): The timestamp when the lease started.endTime(number): The timestamp when the lease ended (0 if still active).state(string): The current state of the lease (e.g., 'active').
Retrieves active, terminated, and all lease IDs for a given address.
const walletAddress = '0xYourWalletAddress';
const { activeLeaseIds, terminatedLeaseIds, allLeaseIds } = await sdk.leases.getLeaseIds(
walletAddress
);
console.log('Active Leases:', activeLeaseIds);
console.log('Terminated Leases:', terminatedLeaseIds);
console.log('All Leases:', allLeaseIds);walletAddress(string): Address to retrieve lease IDs for.
Promise<object>: An object containing arrays of lease IDs:activeLeaseIds(string[]): Active lease IDs.terminatedLeaseIds(string[]): Terminated lease IDs.allLeaseIds(string[]): All lease IDs.
Retrieves leases filtered by state (ACTIVE or TERMINATED) with pagination support.
const walletAddress = '0xYourWalletAddress';
const options = {
state: 'ACTIVE',
page: 1,
pageSize: 10,
};
const leases = await sdk.leases.getLeasesByState(walletAddress, options);
console.log('Leases:', leases);walletAddress(string): Address to retrieve leases for.options(object, optional):state(string): State of the leases to retrieve (ACTIVEorTERMINATED).page(number): Page number for pagination.pageSize(number): Number of items per page.
Promise<object>: An object containing:leases(LeaseWithOrderDetails[]): An array of lease objects with additional order details:- All properties from the lease object
name(string): The name of the order- `tier (string): The tier of the order
region(string | undefined): The region of the provider or Fizz nodetoken(object): Token detailssymbol(string | undefined): The symbol of the tokendecimal(number | undefined): The number of decimal places for the token
activeCount(number): The number of active leasesterminatedCount(number): The number of terminated leasestotalCount(number): The total number of leases
Closes an active lease. You can do it using closeDeployment method of deployment module as well. Both of them are idempotent.
const leaseId = 'your-lease-id';
const closeLeaseReceipt = await sdk.leases.closeLease(leaseId);
console.log('Lease closed:', closeLeaseReceipt);leaseId(string): Lease ID to close.
Promise<object>: Transaction receipt of the close operation.
Sets up a listener for the LeaseClosed event.
sdk.leases.listenToLeaseClosedEvent(
({ orderId, providerAddress, tenantAddress }) => {
console.log('Lease closed:', orderId);
},
() => {
console.error('Listening failed or timed out');
},
60000 // Timeout in milliseconds
);onSuccessCallback(function): Function called when aLeaseClosedevent is detected.onFailureCallback(function): Function called if listening fails or times out.timeout(number, optional): Time in milliseconds before the listener times out.
For detailed examples of how to use each module, please refer to the Examples Directory.
It's recommended to wrap your SDK calls in try-catch blocks to handle any potential errors:
try {
const result = await sdk.someModule.someMethod();
// Handle successful result
} catch (error) {
console.error('An error occurred:', error);
// Handle error
}Feel free to contribute by submitting pull requests or issues. Ensure you follow the coding standards set in the repository.
This project is licensed under the Apache License 2.0.