Protocol SDK

The Spheron Protocol SDK provides developers with tools to interact with the Spheron decentralized infrastructure. It includes modules for managing compute leases, deployments, escrow operations, and more.

How It Works

The Spheron Protocol SDK comprises two main components that work together to provide a seamless experience for interacting with the Spheron decentralized infrastructure:

Protocol SDK

The Protocol SDK handles all deployment and escrow-specific operations, including:

• Creating Deployment Orders: Initiate new deployments on the network.
• Updating Deployments: Modify existing deployments with new configurations.
• Closing Deployments: Terminate deployments when they are no longer needed.
• Managing Escrow Balances: Track and manage your account balance within the network’s escrow system.
• Wallet Transactions: Deposit and withdraw funds securely.

This component manages the blockchain transactions and smart contract interactions required for these operations.

Provider Proxy Server

The Provider Proxy Server is essential for interacting with provider-specific functions, such as:

• Fetching Deployment Details: Retrieve information about your deployments.
• Retrieving Exposed Ports: Get details about network ports exposed by your services.
• Getting Service Details: Access information about running services.
• Checking Service Statuses: Monitor the status of your deployed applications.

The Provider Proxy Server acts as an intermediary between your application and the Spheron provider, handling both HTTP and WebSocket requests.

Working Together

These components work hand in hand, allowing you to interact with the Spheron infrastructure without needing to build additional components:

1. Run the Provider Proxy Server: This server communicates with the Spheron provider on your behalf.
2. Or you can use the default proxy server provided by Spheron https://provider-proxy.sphn.xyz
3. Pass the Provider Proxy Server URL to the Protocol SDK: This allows the SDK to route requests appropriately.
4. Use the SDK Functions: Manage deployments and interact with the Spheron infrastructure through the SDK.

By following the guide below, you’ll be able to perform all necessary interactions for deployments on Spheron.

Components

Node.js SDK

The Node.js SDK offers a comprehensive set of functionalities to interact with the Spheron Protocol via Node.js applications.

Key features include:

• Escrow Module: Manage user balances, deposits, and withdrawals.
• Deployment Module: Create, update, retrieve, and close deployments.
• Lease Module: Manage compute leases, including retrieving lease details and managing active leases.

Provider Proxy Server

The Provider Proxy Server acts as an intermediary for fetching data related to deployments from the Spheron Provider. It handles both HTTP and WebSocket requests to communicate with the Spheron provider.

Installation and Setup

Installing the SDK

To install the Spheron SDK in your Node.js project, use npm or yarn or bun:

npm install @spheron/protocol-sdk

yarn add @spheron/protocol-sdk

bun add @spheron/protocol-sdk

Setting Up the Provider Proxy Server

To submit manifests to a provider, you need to set up a proxy server. You can run the provider proxy server using Docker or from source code.

Refer to the Provider Proxy Server for detailed instructions.

Option 1: Use the Docker Image

Pull and run the Docker image:

docker pull spheronnetwork/provider-proxy-server:latest
docker run -p 3040:3040 spheronnetwork/provider-proxy-server:latest

Option 2: Run from Source Code

Clone the repository and run the server:

git clone https://github.com/spheronFdn/protocol-sdk.git
cd protocol-sdk/provider-proxy-server
npm install
npm run start

Make sure to set any necessary environment variables as described in the Provider Proxy Server README.

Usage

Initializing the SDK

To use the Spheron SDK, import it and initialize it with the desired configuration:

const { SpheronSDK } = require('@spheron/protocol-sdk');
 
// Basic initialization
const sdk = new SpheronSDK({
  networkType: 'mainnet' // 'mainnet' (default) or 'testnet'
});
 
// Initialization with private key for write operations
const sdk = new SpheronSDK({
  networkType: 'mainnet',
  privateKey: 'your-private-key'
});
 
// Full initialization with all optional parameters
const sdk = new SpheronSDK({
  networkType: 'mainnet',
  privateKey: 'your-private-key',
  rpcUrls: {
    http: 'your-http-rpc-url',
    websocket: 'your-websocket-rpc-url'
  },
  gaslessOptions: {
    type: 'coinbase', // or 'biconomy'
    bundlerUrl: 'your-bundler-url',
    paymasterUrl: 'your-paymaster-url'
  }
});

Configuration Parameters:

• networkType (optional): Specifies the environment - ‘mainnet’ (default) or ‘testnet’
• privateKey (optional): Your private key for signing transactions
• rpcUrls (optional): Custom RPC URLs for the network
  • http: HTTP RPC endpoint
  • websocket: WebSocket RPC endpoint
• gaslessOptions (optional): Configuration for gasless transactions
  • type: ‘coinbase’ or ‘biconomy’
  • bundlerUrl: URL for the bundler service
  • paymasterUrl: URL for the paymaster service

Using Gasless Transactions

When using gasless transactions, follow these steps:

1. First, get your smart wallet details:

const smartWalletDetails = await sdk.escrow.getSmartWalletDetails();
console.log('Smart Wallet Address:', smartWalletDetails.address);
console.log('Smart Wallet Balance:', smartWalletDetails.balance);

2. Before making any deposits using depositBalance, ensure you have deposited funds into your smart wallet.

Examples

Example: Creating a Deployment

const { SpheronSDK } = require("@spheron/protocol-sdk");
 
const sdk = new SpheronSDK("testnet", "your-private-key");
 
const iclYaml = `
// Your YAML file here
`;
 
const providerProxyUrl = "http://localhost:3040";
 
(async () => {
  try {
    const deploymentTxn = await sdk.deployment.createDeployment(
      iclYaml,
      providerProxyUrl
    );
    console.log("Deployment created:", deploymentTxn);
  } catch (error) {
    console.error("Error creating deployment:", error);
  }
})();

Security Best Practices

• Private Key Management: Store your private key securely using environment variables or secret management services like AWS Secrets Manager, Azure Key Vault, etc.
• Avoid Hardcoding Sensitive Data: Never commit sensitive information like private keys or API keys to version control.

Contributing

1. Fork the Repository: Click the “Fork” button at the top of the repository page.
2. Create a Feature Branch: Use a descriptive name, e.g., feature/add-new-module.
3. Make Changes: Commit your changes with clear and concise commit messages.
4. Run Tests: Ensure all tests pass by running npm test.
5. Submit a Pull Request: Open a pull request against the main branch with a detailed description of your changes.

Coding Standards

• Code Style: Follow the established coding style in the project.
• Linting: Run npm run lint to check for linting errors.
• Testing: Include unit tests for new features and ensure existing tests pass.