Welsh Faucet Audit

;; Welsh Street Faucet
 
;; SIP-010 trait for token transfers — transformer accepts trait parameter but is private
(use-trait sip-010 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait)
 
;; errors
;; 2 unique error codes with u99x prefix — testnet-only contract
(define-constant ERR_NOT_CONTRACT_OWNER (err u991))
(define-constant ERR_COOLDOWN (err u992))
 
;; constants
;; u1000000000000 = 1 million WELSH at 6 decimals — immutable (see I-03)
(define-constant AMOUNT u1000000000000)
 
;; variables
 
;; initialized to deployer at deployment — transferable via set-contract-owner (see I-01)
(define-data-var contract-owner principal tx-sender)
 
;; minimum blocks between claims — default 10, adjustable by owner with no bounds (see I-04)
(define-data-var cooldown uint u10)
 
;; tracks last claim block for each user — prevents cooldown bypass
(define-map last-request
  { user: principal }
  { block: uint }
)
 
;; permissionless claim function — dispenses AMOUNT tokens per call subject to cooldown
;; uses tx-sender for recipient identity — prevents contracts from claiming for users (see I-02)
(define-public (request)
  (let (
    ;; recipient is tx-sender (not contract-caller) — see I-02 for anti-abuse rationale
    (recipient tx-sender)
  )
    ;; check if user has claimed before
    (match (map-get? last-request { user: recipient })
      last-entry
        (begin
          ;; repeat claim — enforce cooldown period
          ;; blocks-since-last-claim must be >= cooldown
          (asserts! (>= (- stacks-block-height (get block last-entry)) (var-get cooldown)) ERR_COOLDOWN)
          
          ;; update last-request block to current height — prevents double-claim in same block
          (map-set last-request { user: recipient } { block: stacks-block-height })
          
          ;; transfer AMOUNT tokens from faucet to recipient
          (try! (transformer .welshcorgicoin AMOUNT recipient))
          (ok true)
        )
      ;; first-time claim — no cooldown check, create map entry
      (begin
        ;; initialize last-request tracking for new user
        (map-set last-request { user: recipient } { block: stacks-block-height })
        
        ;; transfer AMOUNT tokens
        (try! (transformer .welshcorgicoin AMOUNT recipient))
        (ok true)
      )
    )
  )
)
 
;; single-step ownership transfer — no two-step confirmation pattern (see I-01)
(define-public (set-contract-owner (new-owner principal))
  (begin
    ;; contract-caller check — consistent with all protocol contracts
    (asserts! (is-eq contract-caller (var-get contract-owner)) ERR_NOT_CONTRACT_OWNER)
    
    ;; irreversible if transferred to wrong address — owner controls only metadata, not funds
    (var-set contract-owner new-owner)
    (ok true)
  )
)
 
;; adjust cooldown period — no bounds validation (see I-04)
;; owner can set to u0 (instant claims) or extremely high value (disable faucet)
(define-public (set-cooldown (blocks uint))
  (begin
    ;; contract-caller check — same pattern as set-contract-owner
    (asserts! (is-eq contract-caller (var-get contract-owner)) ERR_NOT_CONTRACT_OWNER)
    
    ;; update cooldown — no minimum or maximum bounds enforced (see I-04)
    (var-set cooldown blocks)
    (ok { cooldown: blocks })
  )
)
 
;; private function for token transfers from faucet contract to user
;; uses as-contract? and with-ft pattern for post-condition compliance
(define-private (transformer
    (token <sip-010>)
    (amount uint)
    (recipient principal)
  )
  ;; as-contract? changes execution context — tx-sender becomes contract principal
  ;; with-ft adds post-condition: contract can spend up to `amount` of `token`
  ;; "*" is wildcard for asset name (resolved to token contract at runtime)
  (as-contract? ((with-ft (contract-of token) "*" amount))
    ;; transfer from faucet (tx-sender = contract) to recipient
    ;; amount is bounded by with-ft post-condition — prevents over-spending
    (try! (contract-call? token transfer amount tx-sender recipient none))
  )
)
 
;; === READ-ONLY FUNCTIONS — no access control needed ===
 
;; returns faucet's welshcorgicoin balance — uses unwrap-panic (see I-06)
(define-read-only (get-balance)
  ;; as-contract? to check contract's own balance (not caller's)
  (as-contract? ()
    ;; unwrap-panic: assumes get-balance always returns (ok uint) — see I-06
    ;; if welshcorgicoin.get-balance returns error, this read-only function will panic
    (unwrap-panic (contract-call? .welshcorgicoin get-balance tx-sender))
  )
)
 
;; returns current contract owner
(define-read-only (get-contract-owner)
  (ok (var-get contract-owner)))
 
;; returns current cooldown period in blocks
(define-read-only (get-cooldown)
  (ok (var-get cooldown)))
 
;; returns user's last claim block height — (some uint) if claimed before, none otherwise
(define-read-only (get-last-request (user principal))
  (ok (map-get? last-request { user: user })))
 
;; returns blocks remaining until user can claim again — u0 if ready now
(define-read-only (get-next-request (user principal))
  (match (map-get? last-request { user: user })
    last-entry
      (let ((blocks-since-request (- stacks-block-height (get block last-entry))))
        ;; if cooldown period has passed, user can claim now (u0 blocks remaining)
        ;; otherwise, return blocks remaining
        (if (>= blocks-since-request (var-get cooldown))
          (ok u0)
          (ok (- (var-get cooldown) blocks-since-request))
        )
      )
    ;; no prior request — user can claim immediately
    (ok u0)
  )
)
 
;; composite function — returns all faucet state for a user
(define-read-only (get-faucet-info (user principal))
  (let (
    (cooldown-period (var-get cooldown))
    (last-req (map-get? last-request { user: user }))
  )
    (match last-req
      last-entry
        (let ((blocks-since-request (- stacks-block-height (get block last-entry))))
          (ok {
            ;; blocks until next claim (0 if ready now)
            blocks-remaining: (if (>= blocks-since-request cooldown-period)
              u0
              (- cooldown-period blocks-since-request)
            ),
            ;; current cooldown setting
            cooldown: cooldown-period,
            ;; when user last claimed
            last-request: (some (get block last-entry)),
          })
        )
      ;; first-time user — no claim history
      (ok {
        blocks-remaining: u0,
        cooldown: cooldown-period,
        last-request: none,
      })
    )
  )
)