⏰ AF-Clock

A cron-based timeout service for AO processes on Arweave

Built by Autonomous Finance

---

Caution

This project is archived and no longer maintained.

This repository has been open-sourced for educational and reference purposes. No support, updates, or bug fixes will be provided. Use at your own risk.

---

📖 Overview

AF-Clock is a specialized AO process that provides timeout/scheduling functionality for other AO processes on the Arweave permaweb. It acts as a shared cron service that can respond to "Ping" requests after a specified timeout period has elapsed.

The service uses a whitelist mechanism to control which processes can request timeouts, with factory processes able to register their spawned processes as authorized pingers.

Key Features

• ⏱️ Cron-based scheduling — Leverages AO's native cron mechanism for reliable timeout execution
• 🔐 Whitelist access control — Only authorized processes can request timeouts
• 🏭 Factory integration — Whitelister processes can programmatically authorize new pingers
• 📡 Simple message protocol — Clean Ping/Pong interface for timeout requests

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AF-Clock Process                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│   │  Whitelisters │───▶│  Whitelist   │◀───│   Pingers    │      │
│   │  (Factories)  │    │   Registry   │    │ (Authorized) │      │
│   └──────────────┘    └──────────────┘    └──────────────┘      │
│                              │                    │              │
│                              ▼                    ▼              │
│                       ┌─────────────┐     ┌─────────────┐       │
│                       │   Pending   │     │    Cron     │       │
│                       │    Pings    │◀────│    Tick     │       │
│                       └─────────────┘     └─────────────┘       │
│                              │                                   │
│                              ▼                                   │
│                       ┌─────────────┐                           │
│                       │    Pong     │                           │
│                       │  Response   │                           │
│                       └─────────────┘                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Message Handlers

Handler	Action	Description
Info	Info	Returns process configuration and whitelist info
Ping	Ping	Request a timeout callback (whitelisted processes only)
Cron	Cron-Tick	Internal handler that processes pending timeouts
Whitelist-Pinger	Whitelist-Pinger	Register a process as authorized pinger
Is-Whitelisted-Pinger	Is-Whitelisted-Pinger	Check if a process is whitelisted
Add-Whitelister	Add-Whitelister	Add a factory/whitelister (owner only)

---

🚀 Getting Started

Prerequisites

• Lua 5.4
• LuaRocks
• Teal — Typed Lua compiler
• Cyan — Teal build system
• amalg — Lua module bundler
• Node.js (for aoform deployment)

Installation

# Install Teal and build tools
luarocks install tl 0.15.3-1
luarocks install cyan 0.3.1-2
luarocks install amalg

# Clone the repository
git clone https://github.com/autonomous-finance/af-clock.git
cd af-clock

# Install Node.js dependencies
npm install

Building

npm run build
# or directly:
bash ./scripts/build.sh

This compiles the Teal source to Lua and bundles all modules into a single build/af-clock.lua file ready for deployment.

Deployment

1. Copy aoform.example.yaml to processes.yaml
2. Fill in your Arweave addresses (scheduler, module, operator, authority)
3. Set your wallet JSON:

   export WALLET_JSON="$(cat your-wallet.json)"

4. Deploy using aoform:

   npx aoform apply -f processes.yaml

---

📁 Project Structure

af-clock/
├── src/
│   ├── main.tl              # Main process handlers
│   ├── globals.tl           # Global state definitions
│   ├── typedefs/            # Type definitions
│   │   ├── ao.d.tl          # AO platform types
│   │   └── json.d.tl        # JSON module types
│   └── utils/               # Utility modules
│       ├── assertions.tl    # Input validation
│       ├── bint-strings.tl  # BigInt string operations
│       ├── forward-tags.tl  # Tag forwarding utilities
│       ├── output.tl        # Output formatting
│       ├── quantities.tl    # Quantity operations
│       ├── responses.tl     # Response helpers
│       ├── tl-bint.tl       # BigInteger implementation
│       └── tl-utils.tl      # General utilities
├── test/
│   ├── setup.lua            # Test configuration
│   └── mocked-env/          # Mocked AO environment
├── scripts/
│   └── build.sh             # Build script
├── aoform.example.yaml      # Example deployment config
├── tlconfig.lua             # Teal compiler configuration
└── package.json             # Node.js dependencies

---

💬 Message Protocol

Requesting a Timeout (Ping)

Send a message with Action: Ping to the AF-Clock process. The process must be whitelisted.

ao.send({
  Target = "<AF_CLOCK_PROCESS_ID>",
  Action = "Ping"
})

When the timeout expires, AF-Clock responds with:

{
  Action = "Pong"
}

Whitelisting a Process

Whitelister processes can authorize new pingers:

ao.send({
  Target = "<AF_CLOCK_PROCESS_ID>",
  Action = "Whitelist-Pinger",
  ["Process-Id"] = "<PROCESS_TO_WHITELIST>"
})

---

🛠️ Technology Stack

• Teal — Typed dialect of Lua
• AO — Hyper-parallel computing on Arweave
• Arweave — Permanent data storage
• aoform — AO process deployment tool

---

📜 License

This project is licensed under the MIT License — see the LICENSE.md file for details.

---

🙏 Attribution

Originally developed by
Autonomous Finance

_{Building autonomous financial infrastructure on Arweave}

---

_{⚠️ This repository is archived. No issues or pull requests will be addressed.}