croncat

croncat JS & CLI

croncat CLI is a Node.js application that relies on near-api-js to generate secure keys, connect to the NEAR platform and send transactions to the network on your behalf.

note that Node.js version 10+ is required to run croncat CLI

CLI Installation

npm install -g croncat

Commands

For a list of up-to-date commands, run croncat --help in your terminal.

Usage: croncat <command> [options]

Commands:
  croncat register <account_id> [payable_account_id]  Add your agent to cron known agents
  croncat update <account_id> [payable_account_id]    Update your agent to cron known agents
  croncat unregister <account_id>                     Account to remove from list of active agents.
  croncat withdraw [account_id]                       Withdraw all rewards earned for this account
  croncat status [account_id]                         Check agent status and balance for this account
  croncat tasks                                       Check tasks list
  croncat triggers                                    Check how many triggers are currently available
  croncat go [account_id]                             Run tasks that are available, if agent is registered and has balance
  croncat daemon [near_env]                           Generate a network specific croncat daemon service

Docker Installation & Setup

Before running the image make sure you are logged in with near:

near login

This should create the following directory (if it doesn't exist already):

ls ~/.near-credentials
default testnet

Build the image:

yarn docker:build

Run docker in detached mode and set the agent account id:

docker run --rm -d --env AGENT_ACCOUNT_ID=your_agent.testnet -v ~/.near-credentials:/root/.near-credentials croncat

Run the cli:

docker run --rm -it croncat ./croncat-cli

Add an alias for convenience:

alias croncat="docker run --rm -it croncat ./croncat-cli"

This will allow you to run the commands as seen below.

Customization & Environment Variables

Sometimes you want to run croncat with notifications and uptime monitoring, or configure the different settings. To do this, you need to run the following command:

cp .env.example .env

You can then configure the following:

NODE_ENV=production
NEAR_ENV=mainnet
LOG_LEVEL=info
BETA_FEATURES=false

# The account registered as an agent
AGENT_ACCOUNT_ID=YOUR_ACCOUNT.near
# the NEAR amount to trigger a notification (example here: 1 Near)
AGENT_MIN_TASK_BALANCE=1
# When balance is empty, will auto-withdraw rewards to cover signing txns, withdraws the payout account.
AGENT_AUTO_REFILL=true
# Helpful if your agent gets kicked after being inactive for any reason. Will attempt to re-register and become a pending agent upon next start.
AGENT_AUTO_RE_REGISTER=false

# The interval to wait between checking for tasks. Good intervals are below 60 seconds and above 10 seconds.
WAIT_INTERVAL_MS=450000

# Period between checking triggers, needs to be less than 10 seconds to be effective
# Period will need to be consistent with RPC rate limits to ensure query goes through
TRIGGER_INTERVAL_MS=10000

## Notify slack when events happen
SLACK_TOKEN=YOUR_WEBHOOK_TOKEN
SLACK_CHANNEL=general

# If you have an external heartbeat service that just needs a ping (GET request)
HEARTBEAT=false
HEARTBEAT_URL=GET_REQUEST_URL_FOR_STATUS_SERVICE

## -------------------------------------------------------------------
## RPC Providers
## Configure the following as CSV, in priority order, for RPC Failover
## -------------------------------------------------------------------
# Example: RPC_MAINNET_PROVIDERS="https://rpc.mainnet.near.org,http://localhost:3030"
RPC_MAINNET_PROVIDERS="https://mainnet-rpc.openshards.io,https://rpc.mainnet.near.org"
RPC_TESTNET_PROVIDERS="https://rpc.testnet.near.org,https://testnet-rpc.openshards.io"
RPC_GUILDNET_PROVIDERS="https://rpc.openshards.io"
RPC_BETANET_PROVIDERS="https://rpc.betanet.near.org"

## RPC API KEY for providers that require it
RPC_API_KEY=

Croncat Agent DAEMON

To setup an agent that has auto reboot capability, do the following steps:

# 1. create a service file via daemon command: Example for guildnet, use your desired network
croncat daemon guildnet

# 2. create the service symlink and then enable the service
sudo systemctl link ~/croncat/testnet/croncat_testnet.service
sudo systemctl enable croncat_testnet.service

# 3. reload systemctl
sudo systemctl daemon-reload

# 4. start the service
sudo systemctl start croncat_testnet.service

# 5. for accessing logs, you can use these commands, just make sure to use the right network name
journalctl -f -u croncat_testnet.service
tail -f /var/log/croncat_testnet.log
tail -f /var/log/croncat_testneterror.log

Development & Local Testing

To develop, you will need to:

1. npm i or yarn
2. npm run dev or yarn dev

For local testing: npm start or yarn start

You can also test against other networks: NODE_ENV=production yarn start which is the same as NODE_ENV=mainnet yarn start

Local CLI testing

To test methods, utilize local execution with the command syntax:

node bin/croncat COMMAND ARGS

Examples:

node bin/croncat tasks
node bin/croncat triggers
node bin/croncat register agent.in.testnet agent.in.testnet
node bin/croncat status agent.in.testnet
node bin/croncat go agent.in.testnet
node bin/croncat withdraw agent.in.testnet

Deploy

Croncat CLI is available via npm, which auto-publishes every update to master.

For deploying docker, simply do the following commands:

npm run build:cli
npm publish
npm run docker:build
docker tag croncat/agent:latest croncat/agent:1.4.1
docker push croncat/agent:latest
docker push croncat/agent:1.4.1