Heidrun
This is an automation platform for Cardano to trigger various action based on detecting payment to a wallet address.
It does not require a full Cardano node and relies on Blockfrost to query & submit transactions.
Works perfectly well on Cardano testnet
as well as mainnet
(quite easy to switch between the two).
Currently, this system lets you create wallets and view contents of each wallet, and it can handle two types of jobs via the api & queue system:
TrackPaymentAndCallback
When a payment detected in a wallet, it can trigger a webhook callback.
Example api request:
curl --insecure --location --request POST 'https://localhost:8006/api/v1/job/create' \
--header 'api-access-token: YOUR_API_ACCESS_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "TrackPaymentAndCallback",
"payment_wallet_name": "MyAwesomeWallet",
"expected_lovelace": 1513147,
"callback": {
"request_url": "https://your-callback-site.com/webhook/endpoint",
"request_type": "post",
"request_params": {
"session_id": "asdasdsads",
"profile_id": "a1sdads"
}
}
}
'
TrackPaymentAndDropAsset
When a payment detected in a wallet, it can drop a native asset to a receiver's wallet address.
Example api request:
curl --insecure --location --request POST 'https://localhost:8006/api/v1/job/create' \
--header 'api-access-token: YOUR_API_ACCESS_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "TrackPaymentAndDropAsset",
"payment_wallet_name": "Gifts",
"drop_wallet_name": "MyDrops",
"expected_lovelace": 2716755,
"drop": {
"policy_id": "dcc407a706ed1fbcbc2304b340b65c970371d41c135f0bc75b2ec562",
"asset_name": "LatheesanTestCoin",
"quantity": 20,
"receiver_address": "addr_test1qp2t365a9pz4vcper0rr43vrxzeyky96rmgpxkeertyp6gt6jeraypygwzs8ymmcvgvx8cphjlwp0w2xguarthk5ta6sey2d75"
}
}
'
Example api responses
Example success response:
{
"code": 201,
"status": "Created",
"data": {
"message": "Job successfully created & scheduled",
"job_id": 11
}
}
Example error response:
{
"code": 400,
"status": "Bad Request",
"data": "Insufficient asset quantity \"dcc407a706ed1fbcbc2304b340b65c970371d41c135f0bc75b2ec562.LatheesanTestCoin\" in the drop wallet, cannot drop 2000000 because there are only 99950 left"
}
Application GUI Screenshots
Minimum Requirements
- Linux VPS with at least 1 GB RAM
- Docker
Tested well on latest Ubuntu operating system, using 1 GB RAM and 2 GB SWAP
Installation Steps
- Clone the repo with:
git clone https://github.com/adosia/Heidrun.git && cd Heidrun
- Generate new self-signed ssl certificates with:
make self-signed-ssl
- Copy
env/mysql.example
asenv/mysql
andenv/web.example
asenv/web
and modify the values as required - Build & run the app with:
make build
- Visit https://localhost:8006 to access the application and https://localhost:8006/horizon to view the queue
make
Commands
Available build
Rebuild all docker containersup
Restart all docker containersdown
Shutdown all docker containerscomposer-install
Run composer installdb-migrate
Run database migration(s)db-refresh
Drop all database tables, re-run the migration(s) with seedsadmin-account
Create a new Heidrun admin accountstatus
View the status of all running containerslogs
View the logs out of all running containersshell
Drop into an interactive shell inside heidrun-web containerstats
View the resource usage of all running containersartisan
Execute Laravelartisan
command inside heidrun-web containerself-signed-ssl
Generates new apache compatible self-signed SSL certificates
testnet
and mainnet
Switching between - Edit
env/web
and updateCARDANO_NETWORK
environment variablePossible values are
testnet
ormainnet
- Run
make up
to restart the containers with new environment
Changing mysql root and application's database password
- Edit
env/mysql
and updateMYSQL_ROOT_PASSWORD
andMYSQL_PASSWORD
environment variables
If you change
MYSQL_PASSWORD
don't forget to updateenv/web
and changeDB_PASSWORD
to match this
- Run
make down
to shut down all containers - Run
docker volume prune
and selectyes
to delete all volumes - Run
make up
to start the containers up again
Note: Sometimes laravel caches application config, so changing the env/web
and restarting the container isn't enough.
I recommend running php artisan config:clear
inside the web container using make shell
command.
Changing laravel application key
- Run
make shell
and typephp artisan key:generate --show
command - Copy the output and update
env/web
and changeAPP_KEY
environment variable - Now run
php arisan migrate:fresh --seed
(inside the web container) to drop the database and re-run the migrations and re-seed the admin account
Caveats / Notes
- Do not send more than 1 native asset to your
Drop
wallet in a single transaction, the system is not cleaver enough (yet) to deal with multiple native assets on a single UTXO - Just send one native asset at a time to your
Drop
wallet
TODO List
πΉ Authentication
πΉ Manage Wallets
πΉ Manage API Access Token (via Settings)
πΉ Track Payment And Callback
πΉ Track Payment And Drop Asset
β Manage Admins
β Manage Queue
β Migrate some of the constants as configurabe settings on the GUI
β Handle multiple native assets in a single utxo