Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Plugin Automation Upkeep -Ui Guide

Developer Guide (Registry 2.3 / OCR3)

Purpose of this document

This document is for the developer building the front-end / user interface that lets external DApp teams register their own Upkeep contract with Plugin Automation on XDC.

In scope: everything needed to build the UI — wallet connection, the registration form, the on-chain calls the UI makes, the events it listens to, and what to display back to the user.

Out of scope: how to write, deploy, or configure an Automation-compatible smart contract. The DApp team brings their own already-deployed Upkeep contract; we are not teaching them (or building) that part.

Background — what is “Automation”, in plain terms?

Read this section fully before the rest of the doc. It has no jargon assumed.

The problem it solves

Smart contracts can't act on their own — nothing on a blockchain runs automatically. A contract only does something when someone sends a transaction that calls it.

So if a DApp needs some function on their contract to run periodically (e.g. “check every hour if a loan is undercollateralized and liquidate it if so”) or in response to a condition (e.g. “as soon as price crosses $X, do Y”), somebody has to keep watching and keep sending those transactions manually, forever.

That's tedious, easy to forget, and doesn't scale.

What Plugin Automation does

It's a service, run by us using a network of off-chain nodes, that watches contracts on behalf of DApp teams and automatically sends the transaction that triggers their contract's logic whenever the conditions are met.

The DApp team never has to babysit it themselves.

Key terms

  • Upkeep contract — The DApp team's own smart contract that needs to be triggered automatically. It's not written by us and not written by our UI; the DApp team writes and deploys it themselves before they ever come to our site. It just needs two specific functions in it: a “can this run now?” check function and a “do the thing” function, so our system knows how to talk to it.

  • Registering an upkeep — The one-time action of telling our system “here's my contract's address, please start watching/triggering it.” This is the whole purpose of the UI we're building: it's the front door where a DApp team registers their contract with us.

  • The Registry — Our core on-chain contract that keeps the official list of every registered upkeep, their funding balance, and their settings. Think of it like a database, except it lives on-chain and our automation nodes read from it to know what to check and run.

  • Funding an upkeep — Running an upkeep costs gas (transaction fees) every time it's triggered. The DApp team deposits tokens up front into the Registry as a balance for their upkeep, and that balance is drawn down each time it runs. If the balance runs out, the upkeep stops being triggered.

  • The automation node network — The off-chain software that our infrastructure runs, invisible to the DApp team, which continuously checks all registered upkeeps and submits the trigger transaction when needed. This part already exists and works; it's not something the UI or the DApp team touches at all.

What the UI we're building actually is

It's a web page where a DApp developer connects their wallet, tells us the address of a contract they already deployed, puts some funding behind it, and clicks “Register.”

From that point on, our node network takes over and keeps calling that contract automatically.

Everything after registration — checking, funding, and pausing — is just reading and writing values on the Registry contract; there is no custom logic to build beyond calling its functions.

Actors and contracts involved

Actor / Contract
Role

DApp developer (end user of our UI)

Owns/admins an already-deployed Upkeep contract. Brings the address, doesn't write any code on our site.

Upkeep contract

Provided by the DApp developer. Must implement checkUpkeep(bytes) and performUpkeep(bytes). Our UI never generates or edits this.

Registry contract (OCR3 / 2.3)

Plugin's core contract. Holds registered upkeeps, their balances, and triggers performUpkeep calls via the keeper/OCR3 node network.

Registrar contract (if used)

Optional front door that validates registration params and forwards to the Registry — used so registration can be a single approve + register call rather than requiring Registry admin whitelisting. Confirm with Karthick whether our deployment registers directly against the Registry or via a Registrar.

PLI token (or native funding token)

Used to fund the upkeep so the keeper network gets paid for performing it.

UI flow

1

Connect wallet

Connect the DApp developer's wallet.

This wallet will become the upkeep's admin.

2

Complete the input form

Collect:

  • Upkeep contract address — the contract they already deployed

  • Upkeep name/label — display only, stored off-chain or in registry metadata

  • Gas limit — maximum gas to reserve for performUpkeep

  • Admin address — defaults to the connected wallet, editable

  • Initial funding amount

  • Optional checkData / trigger config bytes, if the upkeep needs custom check parameters

3

Validate the contract

Before submitting, optionally call checkUpkeep as a view/simulated call against the pasted address to confirm it responds like a valid Automation-compatible contract.

This catches a wrong address early instead of failing on-chain.

4

Approve token spend

Call the standard ERC-20 approve() function on the PLI, or other funding token, for the Registry or Registrar contract.

Approve at least the initial funding amount.

5

Submit registration

Call registerUpkeep(...) on the Registrar, or the equivalent Registry function, passing the form values.

6

Capture the Upkeep ID

The registration transaction emits an event, such as UpkeepRegistered, containing the new upkeepId.

Parse the ID from the transaction receipt logs. This ID is how the upkeep is referenced everywhere after this point.

7

Show confirmation

Show:

  • Upkeep ID

  • Funded balance

  • Status: active

Post-registration dashboard

Once registered, the DApp developer should be able to come back and see and manage their upkeep(s).

Action
Contract call
Notes

View upkeep details

getUpkeep(upkeepId) (view)

Returns target contract, balance, admin, gas limit, paused state

Add funds

addFunds(upkeepId, amount)

Requires prior approve()

Withdraw funds

withdrawFunds(upkeepId, amount)

Only callable by admin; typically only after cancellation delay, depending on registry rules

Pause

pauseUpkeep(upkeepId)

Stops performs without removing registration

Unpause

unpauseUpkeep(upkeepId)

Resumes

Cancel

cancelUpkeep(upkeepId)

Starts/executes cancellation; remaining balance becomes withdrawable

Change admin

transferUpkeepAdmin(upkeepId, newAdmin)

Two-step in most Registry versions: propose + accept

Events to listen for

Reflect the following events in the UI:

  • UpkeepRegistered

  • UpkeepPerformed

  • UpkeepPaused

  • UpkeepUnpaused

  • UpkeepCanceled

  • FundsAdded

  • FundsWithdrawn

Exact function signatures and the deployed Registry/Registrar addresses on XDC mainnet should be pulled from the actual OCR3 (2.3) contract ABI/artifacts we're running. Plug those in before the developer starts building against a testnet, rather than relying on generic Chainlink 2.3 signatures.

What the UI should show per upkeep

  • Upkeep ID

  • Target contract address

  • Status: Active / Paused / Canceled

  • Current balance + low-balance warning threshold

  • Last performed (block/time), if available from UpkeepPerformed event history

  • Admin address

Explicitly not part of this UI

  • No code editor or contract deployment for the Upkeep contract itself

  • No guidance/help for writing checkUpkeep / performUpkeep logic

  • No OCR3 node configuration — that's our infrastructure, invisible to the DApp developer

Open items for the requirements doc author

PreviousPlugin Validators
NextIntroduction