Auto TopUp Application

Perform automated topping up of either RewardShareAgreementPooled, CredentialBilling, or CommercialAgreement contracts when the locked deposits fall below a configurable threshold. If sufficient amulet is available it is locked and the respective contract has its deposit amount topped up to the configured balance using these newly locked amulets.

The application is deployable as either a native kubernetes cronjob where its runs as a script or as a regular container, where it runs as a node cronjob. Configure appropriately to suit your case:

Locally, consult the README and configure /app/auto-topup/.env:

APP_EXECUTION_MODE_SCRIPT={"true"|"false"}

For a network deployment configure cluster/dev/.cronjobs-client.envrc.vars:

export APP_EXECUTION_MODE_SCRIPT={"true"|"false"}

Deployments should be configured to target either CredentialBilling, RewardShareAgreementPooled, or CommercialAgreement contracts or some desired combination:

locally, /app/auto-topup/.env:

ENABLE_CREDENTIAL_BILLING_TOPUP="true"
ENABLE_REWARD_DISTRIBUTION_TOPUP="true"
ENABLE_COMMERCIAL_AGREEMENT_TOPUP="true"

kubernetes, cluster/dev/.cronjobs-client.envrc.vars:

export CRONJOB_ENABLE_CREDENTIAL_BILLING_TOPUP="true"
export CRONJOB_ENABLE_REWARD_DISTRIBUTION_TOPUP="true"
export CRONJOB_ENABLE_COMMERCIAL_AGREEMENT_TOPUP="true"

The app works by querying all live RewardShareAgreementPooled, CredentialBilling or CommercialAgreement contracts and inspecting the respective locked amulet fields to compute the existing locked amulet amounts. This is compared with the configurable topup minima and if below these values, existing unlocked amulets are queried in anticipation of performing the topup to the configured maximum amounts. If sufficient amulet is available these are locked and the underlying contracts updated with the newly locked amounts.

export CRONJOB_REWARD_DISTRIBUTION_TOPUP_MIN_AMULET_BALANCE=1000
export CRONJOB_REWARD_DISTRIBUTION_TOPUP_MAX_AMULET_BALANCE=10000

export CRONJOB_CREDENTIAL_BILLING_TOPUP_MIN_AMULET_BALANCE=1000
export CRONJOB_CREDENTIAL_BILLING_TOPUP_MAX_AMULET_BALANCE=10000

export CRONJOB_COMMERCIAL_AGREEMENT_TOPUP_MIN_AMULET_BALANCE=1000
export CRONJOB_COMMERCIAL_AGREEMENT_TOPUP_MAX_AMULET_BALANCE=10000

locally

REWARD_DISTRIBUTION_TOPUP_MIN_AMULET_BALANCE=37100000.0
REWARD_DISTRIBUTION_TOPUP_MAX_AMULET_BALANCE=38000000.0

CREDENTIAL_BILLING_TOPUP_MIN_AMULET_BALANCE=100000.0
CREDENTIAL_BILLING_TOPUP_MAX_AMULET_BALANCE=1100000.0

COMMERCIAL_AGREEMENT_TOPUP_MIN_AMULET_BALANCE=100000.0
COMMERCIAL_AGREEMENT_TOPUP_MAX_AMULET_BALANCE=1100000.0

The app produces detailed console logging as it proceeds with the top-up. Reasons for a top-up not completing will be produced in that output.

The app interacts with the ledger as an issuer party when topping up RewardShareAgreementPooled/CommercialBilling contracts and tops up that issuer’s deposit; in the case of CredentialBilling contracts it operates on behalf of the holder party and tops up the holder’s deposit. This party is configured in the same environment file as the topup minima and maxima.

In the current configuration the app calls an OIDC (OpenID connect) provider (Auth0 by Okta) to authenticate and obtain the token for that issuer. If running locally one should mint a token. If operating as a native cronjob (running as a node cronjob) as opposed to being in a kubernetes cronjob container, the token is cached to minimize network overhead.