;; Hold-to-Earn Engine
;;
;; This contract implements the core energy generation mechanism of the Charisma protocol
;; as an interaction-compatible component. It calculates energy output based on users'
;; token balance history, utilizing integral calculus for accurate and fair representation
;; of token holding over time. The contract incorporates dynamic multipliers to adjust
;; energy generation based on token-specific factors and protocol incentives.
;;
;; Key Components:
;; 1. Interaction Trait Implementation: Allows the engine to be used within the
;; interaction-based system of the Charisma protocol.
;; 2. Balance Integral Calculation: Uses trapezoidal rule to approximate the integral
;; of user's token balance over time, providing a time-weighted measure of token holding.
;; 3. Dynamic Sample Point Generation: Adapts the number of sample points based on the
;; time period, managed by the Meme Engine Manager for consistency across all engines.
;; 4. Energy Output Calculation: Combines balance integral with quality and incentive
;; scores, normalized by circulating supply.
;; 5. Interaction with Charisma Ecosystem: Integrates with Arcana for quality scores,
;; Aura for incentive scores, and the Dungeon Keeper for energy minting.
;;
;; Core Functions:
;; - execute: Main entry point for interaction-based energy generation.
;; - tap: Calculates and requests energy generation based on token holding.
;; - calculate-balance-integral: Computes the balance integral using appropriate sample points.
;; - get-balance: Retrieves token balance at specific blocks, handling historical data.
;;
;; Integration with Charisma Protocol:
;; - Implements the interaction-trait defined in dao-traits-v7.
;; - Utilizes the Meme Engine Manager for shared parameters and sample point generation.
;; - Interacts with token-specific contracts (e.g., .charisma-token) for balance checks.
;; - Calls Arcana and Aura contracts for dynamic multipliers.
;; - Requests energy minting through the Dungeon Keeper contract.
;;
;; Security and Efficiency:
;; - Non-custodial: Users retain control of their tokens while participating.
;; - Retroactive Calculation: Fairly rewards users based on historical holding patterns.
;; - Scalable: Can be adapted for various tokens in the Charisma ecosystem.
;; - Interaction-based: Allows for seamless integration with the broader Charisma exploration system.
;;
;; This contract is a crucial component of the Charisma protocol, enabling
;; a novel approach to "stake-less staking" and forming the foundation for
;; diverse applications in DeFi, GameFi, and beyond. Its interaction-compatible
;; design allows for flexible integration within the Charisma ecosystem,
;; potentially allowing users to include energy generation as part of their
;; exploration activities.
;; Traits
(impl-trait .dao-traits-v9.interaction-trait)
(use-trait rulebook-trait .dao-traits-v9.rulebook-trait)
;; Constants
(define-constant ERR_UNAUTHORIZED (err u401))
(define-constant CONTRACT_OWNER tx-sender)
;; Data Variables
(define-data-var first-start-block uint block-height)
(define-data-var contract-uri (optional (string-utf8 256))
(some u"https://charisma.rocks/api/v0/interactions/engines/cha"))
;; Maps
(define-map last-tap-block principal uint)
;; Hold-to-Earn functions
(define-private (get-balance (data { address: principal, block: uint }))
(let ((target-block (get block data)))
(if (< target-block block-height)
(let ((block-hash (unwrap-panic (get-block-info? id-header-hash target-block))))
(at-block block-hash (unwrap-panic (contract-call? .charisma-token get-balance (get address data)))))
(unwrap-panic (contract-call? .charisma-token get-balance (get address data))))))
(define-private (calculate-trapezoid-areas-39 (balances (list 39 uint)) (dx uint))
(list
(/ (* (+ (unwrap-panic (element-at balances u0)) (unwrap-panic (element-at balances u1))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u1)) (unwrap-panic (element-at balances u2))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u2)) (unwrap-panic (element-at balances u3))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u3)) (unwrap-panic (element-at balances u4))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u4)) (unwrap-panic (element-at balances u5))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u5)) (unwrap-panic (element-at balances u6))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u6)) (unwrap-panic (element-at balances u7))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u7)) (unwrap-panic (element-at balances u8))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u8)) (unwrap-panic (element-at balances u9))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u9)) (unwrap-panic (element-at balances u10))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u10)) (unwrap-panic (element-at balances u11))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u11)) (unwrap-panic (element-at balances u12))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u12)) (unwrap-panic (element-at balances u13))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u13)) (unwrap-panic (element-at balances u14))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u14)) (unwrap-panic (element-at balances u15))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u15)) (unwrap-panic (element-at balances u16))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u16)) (unwrap-panic (element-at balances u17))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u17)) (unwrap-panic (element-at balances u18))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u18)) (unwrap-panic (element-at balances u19))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u19)) (unwrap-panic (element-at balances u20))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u20)) (unwrap-panic (element-at balances u21))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u21)) (unwrap-panic (element-at balances u22))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u22)) (unwrap-panic (element-at balances u23))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u23)) (unwrap-panic (element-at balances u24))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u24)) (unwrap-panic (element-at balances u25))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u25)) (unwrap-panic (element-at balances u26))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u26)) (unwrap-panic (element-at balances u27))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u27)) (unwrap-panic (element-at balances u28))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u28)) (unwrap-panic (element-at balances u29))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u29)) (unwrap-panic (element-at balances u30))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u30)) (unwrap-panic (element-at balances u31))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u31)) (unwrap-panic (element-at balances u32))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u32)) (unwrap-panic (element-at balances u33))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u33)) (unwrap-panic (element-at balances u34))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u34)) (unwrap-panic (element-at balances u35))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u35)) (unwrap-panic (element-at balances u36))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u36)) (unwrap-panic (element-at balances u37))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u37)) (unwrap-panic (element-at balances u38))) dx) u2)))
(define-private (calculate-trapezoid-areas-19 (balances (list 19 uint)) (dx uint))
(list
(/ (* (+ (unwrap-panic (element-at balances u0)) (unwrap-panic (element-at balances u1))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u1)) (unwrap-panic (element-at balances u2))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u2)) (unwrap-panic (element-at balances u3))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u3)) (unwrap-panic (element-at balances u4))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u4)) (unwrap-panic (element-at balances u5))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u5)) (unwrap-panic (element-at balances u6))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u6)) (unwrap-panic (element-at balances u7))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u7)) (unwrap-panic (element-at balances u8))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u8)) (unwrap-panic (element-at balances u9))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u9)) (unwrap-panic (element-at balances u10))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u10)) (unwrap-panic (element-at balances u11))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u11)) (unwrap-panic (element-at balances u12))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u12)) (unwrap-panic (element-at balances u13))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u13)) (unwrap-panic (element-at balances u14))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u14)) (unwrap-panic (element-at balances u15))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u15)) (unwrap-panic (element-at balances u16))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u16)) (unwrap-panic (element-at balances u17))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u17)) (unwrap-panic (element-at balances u18))) dx) u2)))
(define-private (calculate-trapezoid-areas-9 (balances (list 9 uint)) (dx uint))
(list
(/ (* (+ (unwrap-panic (element-at balances u0)) (unwrap-panic (element-at balances u1))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u1)) (unwrap-panic (element-at balances u2))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u2)) (unwrap-panic (element-at balances u3))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u3)) (unwrap-panic (element-at balances u4))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u4)) (unwrap-panic (element-at balances u5))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u5)) (unwrap-panic (element-at balances u6))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u6)) (unwrap-panic (element-at balances u7))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u7)) (unwrap-panic (element-at balances u8))) dx) u2)))
(define-private (calculate-trapezoid-areas-5 (balances (list 5 uint)) (dx uint))
(list
(/ (* (+ (unwrap-panic (element-at balances u0)) (unwrap-panic (element-at balances u1))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u1)) (unwrap-panic (element-at balances u2))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u2)) (unwrap-panic (element-at balances u3))) dx) u2)
(/ (* (+ (unwrap-panic (element-at balances u3)) (unwrap-panic (element-at balances u4))) dx) u2)))
(define-private (calculate-trapezoid-areas-2 (balances (list 2 uint)) (dx uint))
(list
(/ (* (+ (unwrap-panic (element-at balances u0)) (unwrap-panic (element-at balances u1))) dx) u2)))
(define-private (calculate-balance-integral-39 (address principal) (start-block uint) (end-block uint))
(let (
(sample-points (contract-call? .meme-engine-manager-rc2 generate-sample-points-39 address start-block end-block))
(balances (map get-balance sample-points))
(dx (/ (- end-block start-block) u38))
(areas (calculate-trapezoid-areas-39 balances dx)))
(fold + areas u0)))
(define-private (calculate-balance-integral-19 (address principal) (start-block uint) (end-block uint))
(let (
(sample-points (contract-call? .meme-engine-manager-rc2 generate-sample-points-19 address start-block end-block))
(balances (map get-balance sample-points))
(dx (/ (- end-block start-block) u18))
(areas (calculate-trapezoid-areas-19 balances dx)))
(fold + areas u0)))
(define-private (calculate-balance-integral-9 (address principal) (start-block uint) (end-block uint))
(let (
(sample-points (contract-call? .meme-engine-manager-rc2 generate-sample-points-9 address start-block end-block))
(balances (map get-balance sample-points))
(dx (/ (- end-block start-block) u8))
(areas (calculate-trapezoid-areas-9 balances dx)))
(fold + areas u0)))
(define-private (calculate-balance-integral-5 (address principal) (start-block uint) (end-block uint))
(let (
(sample-points (contract-call? .meme-engine-manager-rc2 generate-sample-points-5 address start-block end-block))
(balances (map get-balance sample-points))
(dx (/ (- end-block start-block) u4))
(areas (calculate-trapezoid-areas-5 balances dx)))
(fold + areas u0)))
(define-private (calculate-balance-integral-2 (address principal) (start-block uint) (end-block uint))
(let (
(sample-points (contract-call? .meme-engine-manager-rc2 generate-sample-points-2 address start-block end-block))
(balances (map get-balance sample-points))
(dx (/ (- end-block start-block) u1))
(areas (calculate-trapezoid-areas-2 balances dx)))
(fold + areas u0)))
(define-private (calculate-balance-integral (address principal) (start-block uint) (end-block uint))
(let (
(block-difference (- end-block start-block))
(thresholds (unwrap-panic (contract-call? .meme-engine-manager-rc2 get-thresholds))))
(if (>= block-difference (get threshold-39-point thresholds)) (calculate-balance-integral-39 address start-block end-block)
(if (>= block-difference (get threshold-19-point thresholds)) (calculate-balance-integral-19 address start-block end-block)
(if (>= block-difference (get threshold-9-point thresholds)) (calculate-balance-integral-9 address start-block end-block)
(if (>= block-difference (get threshold-5-point thresholds)) (calculate-balance-integral-5 address start-block end-block)
(calculate-balance-integral-2 address start-block end-block)))))))
;; Read-only functions
(define-read-only (get-interaction-uri)
(ok (var-get contract-uri)))
(define-read-only (get-last-tap-block (address principal))
(default-to (var-get first-start-block) (map-get? last-tap-block address)))
;; Public functions
(define-public (execute (rulebook <rulebook-trait>) (action (string-ascii 32)))
(if (is-eq action "TAP") (tap-action rulebook)
(err "INVALID_ACTION")))
;; Meme Engine Action Handler
(define-private (tap-action (rulebook <rulebook-trait>))
(let (
(sender tx-sender)
(end-block block-height)
(start-block (get-last-tap-block sender))
(balance-integral (calculate-balance-integral sender start-block end-block))
(quality-score (contract-call? .arcana get-quality-score .charisma-token))
(incentive-score (contract-call? .aura get-incentive-score .charisma-token))
(circulating-supply (contract-call? .arcana get-circulating-supply .charisma-token))
(potential-energy (/ (* (* balance-integral quality-score) incentive-score) circulating-supply)))
(map-set last-tap-block sender end-block)
(match (contract-call? rulebook energize potential-energy sender)
success (handle-tap-success sender potential-energy balance-integral)
error (if (is-eq error u1) (handle-tap-insufficient-balance sender)
(if (is-eq error u405) (handle-tap-limit-exceeded sender)
(if (is-eq error u403) (handle-tap-unverified sender)
(handle-tap-unknown-error sender)))))))
;; Meme Engine Response Handlers
(define-private (handle-tap-success (sender principal) (energy uint) (integral uint))
(let ((op "ENERGY_GENERATED"))
(print {op: op, sender: sender, energy: energy, integral: integral,
message: "The tokens resonate with power, and produce energy for their holder."})
(ok op)))
(define-private (handle-tap-insufficient-balance (sender principal))
(let ((op "ENERGY_NOT_GENERATED"))
(print {op: op, sender: sender,
message: "The holder's tokens balances are too low to generate any energy."})
(ok op)))
(define-private (handle-tap-limit-exceeded (sender principal))
(let ((op "ENERGY_NOT_GENERATED"))
(print {op: op, sender: sender,
message: "Charisma energy capacity exceeded, please contact a protocol administrator."})
(ok op)))
(define-private (handle-tap-unverified (sender principal))
(let ((op "ENERGY_NOT_GENERATED"))
(print {op: op, sender: sender,
message: "This contract has not been verified, please contact a protocol administrator."})
(ok op)))
(define-private (handle-tap-unknown-error (sender principal))
(let ((op "ENERGY_NOT_GENERATED"))
(print {op: op, sender: sender,
message: "An unknown disturbance prevents the tokens from generating energy."})
(ok op)))
;; Admin functions
(define-public (set-contract-uri (new-uri (optional (string-utf8 256))))
(begin
(asserts! (is-eq tx-sender CONTRACT_OWNER) ERR_UNAUTHORIZED)
(ok (var-set contract-uri new-uri))))