croncats / cron-spec Goto Github PK

Requirements

• Home (Similar to: crontab.guru), CTA to try it
• Problem/solution section
• Key features section (time, etc)
• Key use cases
• CTA to top tasks/runners
• CTA to try it

Requirements

• Create interface spec (functions & arguments) for all task methods
• Create interface annotations about arguments and types

References:

• https://github.com/Cron-Near/Cron-Spec#cron-reference

Requirements

• Getting task list
  • Request task list at every block or every few blocks to make sure upcoming tasks need execution
  • Cron manager will reply with a short list of available tasks (not all) so agent knows to sign and execute for this range
  • Task list can be requested for future/upcoming time slots
• Task Execution
  • Sign a transaction with highest gas amount to execute the next task on cron manager
  • Needs to only occur if this account is registered with cron manager
• Retry logic:
  • TBD: Need to test best approach on this!

References:

• https://github.com/Cron-Near/Cron-Spec/blob/main/user_stories.md#cron-task-runners

Requirements

• UI List of tasks executed (transactions: contract id, fee, timestamp, tx link)
• Should return the recent 50-100 tasks, both success and fail
• Create new task button CTA, for easy onboarding

Requirements

• Create interface spec (functions & arguments) for all cross contract methods
• Create interface annotations about arguments and types

References:

• https://github.com/Cron-Near/Cron-Spec#for-contract-developers

Requirements & Implementation

• Schedule a task
  • allow contract or user to submit a task
  • Required data: contract account id, function, time spec, is recurring, args (optional)
  • Payable: TBD Amount
  • Returns: task id
• Cancel a task
  • allow task owner (contract or user) to call method
  • Required data: task id, beneficiary (optional)
  • Returns: --
• Funding a task
  • Initial task creation doesnt need this, only when task runs out of funds
  • allow contract or user to update balance for a given task

References:

• https://github.com/Cron-Near/Cron-Spec#cron-usage-guide

---

Use Cases

Schedule A new task

As a contract developer, I want to schedule a cron task to allow my code to be called one or many times in the future by paying fees up front and allowing an actor to execute my code. My contract code will give permission to the cron protocol to execute my pre-defined function using NEAR access keys. I will provide data on how to call my contract code, how often or when to call the code and any special configurations pertaining to inclusion or fee allotment. I understand that I need to pay for my tasks to execute or the scheduled task will be removed.

Paying for future and recurring tasks

As a contract developer, I want to ensure my tasks get run at some point in the future. To ensure this happens, I allocate funds to be used to execute this task and include a little extra to pay for the protocol to trigger my task. I will provide payment to the protocol directly, paying up front for single function tasks or keeping an available balance for my account on the protocol contract. I expect to manage how my funds are allocated with a simple tool or SDK so that I don't need to understand the underlying payment system of Cron. Upon removing a recurring task, I expect to have any unused balance returned to me. I understand that all payments for task execution will be based on protocol definition and can fluctuate depending on my task configuration, market changes and protocol upgrades. Failed payments will result in cancelled task execution or task removal.

Cancelling tasks

As a contract developer, I want to remove any task that I had previously scheduled that has a pending or future execution status. I expect a cancellation to stop all parties from calling my contract as defined in the task. I expect any already submitted and/or executed tasks to be final and un-cancelable. I expect to cancel a job by submitting a request to the Cron protocol by task ID and get a response whether the cancellation was successful or not. Cancellation timing is based on how tasks are executed within the parameters of blockchain block times and can be difficult to know an exact cancellation time; if a cancellation request is submitted within a same block range as the task pre-allocation window, Cron cannot guarantee a cancellation transaction.

Tasks without arguments

As a contract developer, I want to configure Cron to execute a function within my code that does not require any arguments. This will allow my code to do any/all logic necessary to complete some logic utilizing local state and logic. I hope to utilize this functionality to do tasks pertaining to UX (I.E. bulk reward payouts), state management (I.E. data migrations), logical finalizations (I.E. auction or voting outcomes) or time locking (I.E. Contracts with a start or EOL date).

Tasks with arguments

NOTE: For purposes of MVP, tasks with arguments will need further research and development. The following is the initial pass at a user story and should be considered as incomplete.

As a contract developer, I want to configure Cron tasks that contain external arguments (outside my contract state) to be provided at time of task execution to my contract code. Arguments provided to my code must match the pre-defined types as specified by the task configuration, and must be able to be verified upon and after execution. I expect the function in my code to have a baseline verification of argument data and will cover edge cases not established by the Cron protocol safety checks. External arguments can come from other contracts state, blockchain or core protocol and possibly from the outside global context of any internet enabled task runner. I expect tasks that require external arguments to incur a separate fee schedule to cover computation costs.

Tasks timing needs

As a contract developer, I want to configure specific time parameters that match my contract outcome requirements. I expect to be able to configure a task to run only once at a future date. I expect to configure a task to run at a recurring interval over a span of time until I cancel or stop the task. I expect to be able to pay extra for a more finite window of execution. I expect to have a minimum execution time guarantee for the base task fees. Time is based on network speed and consensus between blockchain nodes, I expect to see fluctuations in exact execution time that are determined by the network and blockchain protocol.

Requirements

• Runner onboarding:
  • User starts runner server
  • Server checks if there is a local NEAR key pair or not
  • If no keys, create them, log the output to user: account id (generated), public key
  • check to make sure account has funds for gas fees
  • If no funds, prompt user to fill account id with gas funds (and suggest amount), exit process
  • If funds, proceed to register flow
• Register flow:
  • Check if account is registered, if so exit process
  • If not registered, create a transaction to submit account as new task runner on core cron manager
  • submit signed transaction and wait for confirmations
  • upon complete, store local txt file that has: txn hash, task runner id, etc -- for faster registration checks in the future
• Unregister flow:
  • Check if this account is registered
  • If registered, create a transaction to submit this account and optional beneficiary of any rewards to core cron manager
  • submit signed transaction and wait for confirmations
  • upon complete, remove local txt file about the register success info

References:

• https://github.com/Cron-Near/Cron-Spec/blob/main/user_stories.md#cron-task-runners

Requirements

• Create a simple contract that can be called by cron.near
• Contract can take ideas from near.dev
• Example idea: Allow a cron task to update example contact internal counter, incrementing by 1 every 1000 blocks

References:

• https://github.com/Cron-Near/Cron-Spec#motivation

Requirements

• UI List of all registered task runners
• Item data: account id, active/inactive, task runner id
• Register CTA Button - link to docs on how to setup your own task runner server

GOAL: Show an easy UI for managing cron tasks you own.

Requirements

• User must login account -- via web wallet
• View All Tasks
  • Query chain for transactions of this account
  • Filter to only cron tasks
  • show data: contract account id, task id, fee, balance remaining(?), Cancel task button
• Create Task
  • Opens modal to create task
  • Input fields for all cron manager schedule function
  • sign transaction and send to chain
  • upon confirmations, add new scheduled task to All Tasks list
• Update Balance Button
  • Open modal
  • allow user to select or input an amount of NEAR to refill their task
  • sign and send to chain
• Cancel task button
  • Allow user to add beneficiary
  • confirm details, sign and send to chain

Requirements

• Setup documentation site from a markdown based generator & basic documentation structure (files, navigation)
• Document:
  • Cross Contract integration
  • Task Runner: Setup, Registration, Unregistration and rewards
  • Example usage

References:

• https://www.gitbook.com/
• https://docc-theme.netlify.app/

Reward:

TBD: Pitch requests in comments

Requirements

• Create interface spec (functions & arguments) for all task runner methods
• Create interface annotations about arguments and types
• Create examples for registering/unregistering

References:

• https://github.com/Cron-Near/Cron-Spec#for-cron-task-runners

Requirements & Implementation

• These requirements work in conjunction with task runner server issues.
• Register
  • account can submit to gain access to run tasks
  • account must have a minimum balance to cover transaction fees
  • Required data: env:: data, reward beneficiary (optional)
  • Payable: No
  • Returns: task runner id
• Un-Register
  • Required data: task runner id, env:: data, reward beneficiary (optional)
  • Payable: No
  • Returns: --
• Get Tasks
  • Required data: --
  • Returns: Array of task ids
• Execute Task
  • Required data: task id
  • Payable: Yes (gas fees)
  • Returns: Boolean status
• Claiming Rewards
  • Required data: task runner id, env:: data, reward beneficiary (optional)
  • Payable: No
  • Returns: --
• Viewing Rewards
  • Required data: task runner id
  • Payable: No
  • Returns: Balance sums for single task runner

References:

• https://github.com/Cron-Near/Cron-Spec#for-cron-task-runners

---

Use Cases

Register as a task runner

As a task runner, I want to provide Cron with a reliable ongoing triggering mechanism by registering my server as an official Cron agent. I expect to create a special wallet my server can utilize to sign transactions for the NEAR blockchain. I expect to keep my server 100% accessible to the internet and to NEAR blockchain. I expect to register my server as a participant in the Cron service by submitting my server wallet account ID, account public key, reward account id and possibly a graffiti tag for friendly runner leaderboards. I expect the registration process to take some small window of block times, and potentially need to stake some NEAR tokens to help secure my place as a Cron agent. I also expect to incur fees or total stake loss upon acting maliciously toward the Cron protocol.

Unregister as a task runner

As a task runner, I want to remove my agent from running any further cron tasks. I expect to cancel any upcoming tasks that may have been pre-assigned, but do not expect any tasks that are pending / submitted to be cancelled. For a successful unregister, I expect to withdraw any / all rewards accrued by my agent for running tasks. I expect to not be able to withdraw some or all rewards in the event my agent was deemed malicious. I expect that I can re-register at a future date if my account is deemed acceptable again in the future.

Viewing available tasks

As a task runner, I want to view all tasks that my agent can run. I expect to be able to view this list or paginate through a list of available tasks to make sure my agent has tasks available to run. In most cases this list will be how my agent knows if it should be signing a transaction or maintaining an idle but active status.

Executing an available task or task batch

As a task runner, I want to claim a task from the Cron queue. To claim a task, I expect my agent to autonomously request an item from Cron that I can sign as a transaction and submit to the network. Upon successful execution, I expect my agent to become available to process another task, repeating this cycle until there are no further tasks or my agent is un-registering.

Accruing & claiming rewards

As a task runner, I want to profit for running tasks by accruing small fees per task. My rewards will be automatically paid out directly to my configured beneficiary account ID at time of execution or in batches. To participate in being an agent, I understand that I may be required to lock an amount of NEAR within Cron as a security for upholding my agents goodwill and reputation.

Requirements

• Create an RPC connection to near RPC, based on environment variables
• RPC methods should include:
  • Cron manager contract methods (get task list, registration, execution, etc)
  • Send signed txn for executing new task: https://docs.near.org/docs/api/rpc#send-transaction-await

References:

• https://github.com/near/near-indexer-for-wallet

Requirements

• Create a rust contract that can hold a couple options of queue types.
• We have talked about:
  • Linked list with keys at certain block ranges
  • mapping that checks when previous occurred and calculate if next / when.
  • Time based (min, hour, day) execution sample
  • Block based (block, epoch) execution sample
• Find solution that:
  • Is the cheapest for large lists
  • Simple to perform per transaction

References:

• https://github.com/Cron-Near/Cron-Spec#how-does-cronnear-work
• https://github.com/Cron-Near/Cron-Spec#unresolved-questions

Requirements

• TBD: Needs a docker container, build scripts for rust task runner

References:

• https://github.com/Cron-Near/Cron-Spec/blob/main/user_stories.md#cron-task-runners