Takt Protocol — takt-contract

Decentralized task scheduling and bounty-incentivized keeper execution primitive on Stellar Soroban.

---

Overview

Soroban smart contracts cannot self-execute on a scheduled basis, nor can they react autonomously to time without external invocation. Additionally, idle state data in Soroban risks being archived if storage time-to-live (TTL) thresholds lapse.

Takt Protocol provides on-chain infrastructure for automated contract execution on Stellar (admin-governed in alpha):

• Task Scheduling (Admin-Governed in Alpha): Register repetitive or one-off tasks with custom intervals and execution constraints.
• Dynamic Cross-Contract Invocations: Invocations pass arbitrary contract targets, function symbols, and argument vectors via env.invoke_contract.
• SEP-41 Escrow & Bounty Settlement: Users fund per-job escrows in any SEP-41 token, rewarding keepers while deducting a protocol fee into the treasury.
• Keeper Economic Security (Admin-Governed in Alpha): Keepers stake tokens with mandatory unbonding cooldown periods and are subject to admin slashing for malicious behavior.

---

Repository Architecture & Dependency Order

The protocol is partitioned into 3 isolated Soroban contracts within a single Cargo workspace, deployed in strict dependency order:

keeper-registry (1) <---+
                        |
bounty-vault    (2) <---+--- job-engine (3)

Order	Contract	Path	Role & Responsibilities
1	keeper-registry	contracts/keeper-registry	Manages keeper stakes, unbonding cooldown timers, keeper status tracking, execution counters, and admin slashing.
2	bounty-vault	contracts/bounty-vault	Custodies SEP-41 deposit balances, locks per-job bounty escrows, calculates basis-point fee splits, executes payouts to keepers, and refunds unspent escrows.
3	job-engine	contracts/job-engine	Orchestrates job registration, interval and cadence enforcement, dynamic target contract invocations, lifecycle transitions (active, paused, completed, cancelled), and execution receipt storage.

---

Deployed Stellar Testnet Contracts

• Network: Stellar Testnet (Test SDF Network ; September 2015)
• Admin / Treasury: GBKGRYZZEELD6POCG5E3MNMA3CT7OKF45CUX3FUDSJH6NJXAMTPXIYRS

Contract	Address	Explorer
keeper-registry	CDSBDXYELFFHM7XMG4D4BXEVETOHQDWPQOTQLPRHGTTVW7DTNODHIIZN	Stellar.Expert
bounty-vault	CDDIJAZCXR7TWSTI4B2FSE7MCXFKH2JVOBT4WELSSJLZHV5XQ4PKHEGO	Stellar.Expert
job-engine	CC6ZSDYSGFAZDJ2FP2RT2ZV6NUZN4OFEWYNIS3CYOG2CBG7DIJDCWYOT	Stellar.Expert
token (Wrapped Native XLM)	CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC	Stellar.Expert

Testnet Deployment Log

From the maintainer's testnet deployment log:

Operation	Transaction Hash	Explorer
keeper-registry deploy and init	00f576872aee9a7ac6332174cdec8c659ac4400d4ce36f1b00c843e67958f8af	Stellar.Expert
bounty-vault deploy and init	b9a9b1be24970b636905ac9015428c1d9763017798018a226e27ba398c6fd8fc	Stellar.Expert
job-engine deploy and init	d2401b75adda5f36e1d8a1396cacffbba5d1bd013e085e36d423f10b7d5adaab	Stellar.Expert
set_engine in registry	981ca837efcaaa93f462075fc5801d3d4b307b1bbb30502d920799e02e73cd48	Stellar.Expert
set_engine in vault	d698300e25a812389cd3c7c2b6057cdbe8c9f1f5238101b446318f6cb2d6122d	Stellar.Expert
register keeper (stake 100 XLM)	b2d2a818bf3a099e38e366f2891c495ff701cb07bebed10fb81b8a26f0756adf	Stellar.Expert
vault deposit	e04408446bb6063f4328dcdb2c48f79d6b12061d9f84733a88d1f5d01c295e7a	Stellar.Expert
create_job #1 (revert test case)	94aac3b86a2637538de46574e4050492c244e7d4921359897239cfe29fb8458a	Stellar.Expert
create_job #2	a266c3c9ce3a9603e413497ee6fffa9fb661288516e8ff26ba6e92951bca0bbd	Stellar.Expert
execute_job #2 (keeper paid 9,500,000 stroops, protocol fee 500,000)	d7e6b7284b7e1ac8ef297b994bb387aaffafae4fff518647435e07450044e4b5	Stellar.Expert

From the maintainer's testnet deployment log, Job #2 is a live example (target keeper-registry::get_total_keepers, 60 s interval, 1 XLM bounty, 20 XLM escrow).

---

Project Status & Current Limitations

• Stage: Alpha / Stellar Testnet Only (Test SDF Network ; September 2015).
• Audit Status: Unaudited. Do not deploy with mainnet funds until formal security review is completed.
• Trust Assumptions & Roadmap:
  • initialize, set_engine, and slash_keeper are currently governed by a single configured admin address (GBKGRYZZEELD6POCG5E3MNMA3CT7OKF45CUX3FUDSJH6NJXAMTPXIYRS on Testnet). Migrating admin controls to a multi-sig / timelock contract is planned on the roadmap.
  • Target contract execution (execute_job) verifies keeper and interval eligibility, records execution in keeper-registry, dispatches the cross-contract call (env.invoke_contract), and triggers bounty payout via bounty-vault.

---

Contract Entrypoints Reference

KeeperRegistry

Function	Access	Description
initialize(admin, stake_token, min_stake, unbond_period)	Admin	Sets initial governance parameters and staking token address.
set_engine(engine)	Admin	Authorizes the JobEngine contract to call internal registry methods.
register_keeper(keeper, amount)	Keeper	Stakes tokens to register as an active keeper.
top_up_stake(keeper, amount)	Keeper	Adds additional stake to an existing active registration.
request_unbond(keeper)	Keeper	Initiates the unbonding cooldown period.
withdraw_stake(keeper)	Keeper	Withdraws staked tokens once the cooldown period has elapsed.
record_execution(keeper)	Engine Only	Increments keeper execution count and updates last active timestamp.
slash_keeper(keeper, penalty, recipient)	Admin	Slashes a keeper's stake for misconduct and transfers penalty tokens.
get_keeper(keeper)	Public Read	Returns keeper profile struct (stake, status, execution count, cooldowns).
is_active_keeper(keeper)	Public Read	Checks whether an address is currently an authorized active keeper.
get_total_keepers()	Public Read	Returns the total count of registered keepers.

BountyVault

Function	Access	Description
initialize(admin, token, fee_bps, treasury)	Admin	Initializes vault with supported token, fee basis points, and treasury address.
set_engine(engine)	Admin	Authorizes JobEngine to lock and payout job escrows.
deposit(from, amount)	User	Deposits SEP-41 tokens into the user's vault balance.
withdraw(to, amount)	User	Withdraws available (unlocked) tokens back to the user's wallet.
fund_job_from_engine(owner, job_id, amount)	Engine Only	Moves user's deposit balance into an escrow dedicated to a specific job.
payout_execution(job_id, keeper, bounty)	Engine Only	Deducts bounty from job escrow, sends protocol fee to treasury, and pays keeper reward.
refund_job(job_id, recipient)	Engine Only	Returns all unspent job escrow back to the owner's vault balance upon cancellation.
get_user_balance(user)	Public Read	Returns free, unallocated balance of a user.
get_job_escrow(job_id)	Public Read	Returns current escrow balance locked for a job.

JobEngine

Function	Access	Description
initialize(admin, keeper_registry, bounty_vault)	Admin	Configures linked registry and vault addresses and initializes ID counters.
create_job(...)	Job Owner	Locks initial escrow and registers a job with recurrence intervals and target call args.
execute_job(keeper, job_id)	Active Keeper	Verifies keeper and intervals, triggers target execution, updates receipt, and triggers payout.
pause_job(owner, job_id)	Job Owner	Pauses an active job to halt executions temporarily.
resume_job(owner, job_id)	Job Owner	Resumes execution eligibility for a paused job.
cancel_job(owner, job_id)	Job Owner	Permanently cancels a job and triggers full refund of unspent escrow.
is_executable(job_id)	Public Read	Evaluates whether a job is eligible for immediate execution (timing, status, escrow).
get_job(job_id)	Public Read	Retrieves full job configuration and current lifecycle state.
get_last_receipt(job_id)	Public Read	Retrieves the most recent execution receipt for a job.
get_total_jobs()	Public Read	Returns total number of jobs created to date.

---

Quick Start

Build Contracts

Compile all contracts into Soroban WASM targets:

stellar contract build

Run Tests

Run all unit tests and end-to-end integration tests across the workspace:

cargo test --workspace

Run Linter & Formatter

Verify code formatting and clippy rules without warnings:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

Deploy to Stellar Testnet

Run the automated testnet deployment script to deploy and link all contracts in sequence:

./scripts/deploy_testnet.sh

---

Related Repositories

• takt-protocol/takt-app: Web dashboard, TypeScript SDK, and autonomous keeper node client for the Takt Protocol (event indexer planned).

---

Maintainers

Maintainer	Role	Contact
webdevayo	Core Maintainer	@dev_ayo

---

Community

• Community Chat

---

Contributors

Thank you to everyone contributing to Takt Protocol!

---

License

This project is licensed under the MIT License.