Cheetah

Stacks blockchain reads and writes on steroids.

Maintenance & Support

This internal package is currently undergoing development, and we continuously make changes as deemed necessary. As a result, this documentation may be outdated, and please note that we do not offer any support at this time.

Installation

Install the NPM package:

npm  i  @nieldeckx/stacks-cheetah

Features

API

When utilizing Stacks API calls, an RPC is required. Most RPCs, such as Hiro's, come with a rate limit, which can be easily exceeded when making numerous API calls. Additionally, calls may fail due to various reasons.

To address this issue, Cheetah is equipped with call queuing and a retry mechanism, alleviating concerns about call failures.

cheetah.callApi('/extended/v1/block?limit=1')

You have the option to override the parameters as shown below:

cheetah.setupApi({
  maxSimultaneousRequests: 40,
  retrySecondsToWait: 70,
  retrySecondsToIncrease: 30,
  retryMax: 10
})

Contract Reads

Just like with API calls, contract reads are performed via an RPC, which is prone to failure. By employing a combination of queuing and a retry mechanism, you can ensure receipt of the accurate result.

await cheetah.callReadOnlyFunction({
  contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
  contractName: "usda-token",
  functionName: "get-decimals",
  functionArgs: [],
  senderAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
})

You have the option to override the parameters as shown below:

cheetah.setupReadOnly({
  maxSimultaneousRequests: 40,
  retrySecondsToWait: 70,
  retrySecondsToIncrease: 30,
  retryMax: 10
})

Contract Calls

Ensuring the correct nonce is crucial when making contract calls. Although the Stacks API offers an endpoint to fetch the next nonce, it may not always consider transactions in the mempool. Cheetah incorporates an advanced mechanism to determine the accurate nonce for an account, or users can manually provide one.

Similarly, obtaining the correct fee for a contract call is essential. Cheetah dynamically fetches the optimal fee based on user input.

Below is an example of a contract call with essential parameters. Additional parameters from the Stacks transaction package can also be utilized.

 cheetah.contractCall({
   contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
   contractName: "contract-name",
   functionName: "function-call,
   functionArgs: [],
   senderAddress: process.env.ADDR!,
   senderKey: process.env.PK!,
 })

If you prefer not to utilize Cheetah's advanced mechanisms, you can still directly broadcast a transaction in the following manner:

cheetah.broadcastTransaction({
  contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
  contractName: "contract-name",
  functionName: "function-call,
  functionArgs: [],
  senderAddress: process.env.ADDR!,
  senderKey: process.env.PK!,
});

You can choose to override the parameters for contract settings as depicted below:

cheetah.setupContractCall({
  mempoolPollInterval: 15,
  monitorInterval: 70,
})

Nonce

You can obtain an account's nonce in the following manner:

cheetah.getNonce("ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM");

Fee

You can acquire the fee required to make a contract call as follows:

cheetah.getFee();
cheetah.getFee(TransactionFeePriority.medium);

Monitor

When utilizing cheetah.contractCall, the transaction will be automatically monitored. The monitor will only return the transaction result once it is mined.

Alternatively, you can initiate a monitor for an existing transaction as shown below:

cheetah.monitorTransaction("0xb28...93b");

If you wish to monitor an existing transaction while also implementing an RBF (Replace-By-Fee) strategy, you can achieve this as demonstrated below:

cheetah.monitorContractCall(
  "0xb28...93b",
  {
    contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
    contractName: "contract-name",
    functionName: "function-call,
    functionArgs: [],
    senderAddress: process.env.ADDR!,
    senderKey: process.env.PK!,
  }
  {
    rbfInterval: 60 * 20,  // 20 mins
    rbfIncrease: 0.2,      // 20%
    maxFee: 5000000        // 5 STX
  }
);

RBF

A transaction can be replaced using RBF (Replace-By-Fee). Cheetah incorporates an automatic RBF mechanism, whereby if a transaction remains in the mempool for an extended period, the fee is automatically incremented until reaching the specified maximum.

Here is an example of how to configure the RBF strategy for a contract call:

cheetah.contractCall(
  {
    contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
    contractName: "contract-name",
    functionName: "function-call,
    functionArgs: [],
    senderAddress: process.env.ADDR!,
    senderKey: process.env.PK!,
  },
  {
    rbfInterval: 60 * 20,  // 20 mins
    rbfIncrease: 0.2,      // 20%
    maxFee: 5000000        // 5 STX
  }
)

Notifications

With Cheetah, sending notifications to your Telegram bot is straightforward. Once the bot information is configured, Cheetah will handle the notification sending process seamlessly.

cheetah.sendNotification("Notification Text");

For notifications to function correctly, you must configure the Telegram botId and chatId:

cheetah.setupNotifications({
  botId: "",
  chatId: "",
})

Utils

Cheetah offers several handy utility functions.

You can effortlessly retrieve the current Stacks Network information:

cheetah.getStacksNetwork();
cheetah.getNetworkInfo();

To obtain a link to the Stacks explorer:

cheetah.getExplorerLink(ExplorerType.address, "ST1...GM");

Verify whether a specific transaction is present in the mempool and get the transaction ID if so:

cheetah.getTransactionMempool({
  contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
  contractName: "contract-name",
  functionName: "function-call,
  functionArgs: [],
  senderAddress: process.env.ADDR!,
  senderKey: process.env.PK!,
});

Parser

When invoking the Stacks API or a read-only function, the response may include a Clarity value in JSON or string format. The parser ensures that Clarity values are returned in a more structured format.

Parse Contract Events

Below is an example demonstrating how the Stacks API can be utilized to retrieve contract events.

[{
  "tx_id": "0x67a...f18",
  "event_type": "smart_contract_log",
  "contract_log": {
    "contract_id": "STTB1X9XAM3CHTXVDWWY5YYN23PZ7TK16XPEX9Y4.arkadiko-dao",
    "topic": "print",
    "value": {
      "hex": "0x0c000000...",
      "repr": "(tuple (action \"minted\") (data (tuple (amount u18562500000) (recipient 'STWKDKPZ3QDPQGDADWJ3EWPAP14CB1N1HCF7JZNN))) (type \"token\"))"
    }
  }
}]

The parsed result below:

 [{
   "tx_id": "0x67a...f18",
   "event_type":"smart_contract_log",
   "contract_log":{
     "contract_id": "STTB1X9XAM3CHTXVDWWY5YYN23PZ7TK16XPEX9Y4.arkadiko-dao",
     "action":"minted",
     "data": {
       "amount":18562500000,
       "recipient":"STWKDKPZ3QDPQGDADWJ3EWPAP14CB1N1HCF7JZNN"
     },
     "type":"token"
   },
 }]

Parse Function Arguments

The function arguments for fetching information for a contract call will be in the following format.

 function_args: [
   {
     "hex": "0x0d000000086e616b616d6f746f",
     "repr": "\"nakamoto\"",
     "name": "tick",
     "type": "(string-ascii 16)"
    },
    {
      "hex": "0x01000000000000000000000004e3b29200",
      "repr": "u21000000000",
      "name": "amt",
      "type": "uint"
    }
 ]

The function arguments will be parsed to get:

function_args: [
  'nakamoto',
  21000000000
]

Parse Read Only Calls

The result of a read-only call will be in the following format:

{
  "type": "(response ... UnknownType)",
  "value": {
    "type": "(tuple ...)",
      "value": {
        "stability-fee": {
          "type": "uint",
          "value": "400"
        },
        "token-name": {
          "type": "(string-ascii 3)",
          "value": "STX"
        },
      }
  }
}

This will be parsed to the following output:

{
  'stability-fee': 400,
  'token-name': 'STX',
}