first draft stacks executor contract

Author: connorstake

stacks/.gitattributes

@@ -0,0 +1,3 @@
+tests/** linguist-vendored
+vitest.config.js linguist-vendored
+* text=lf

stacks/.gitignore

@@ -0,0 +1,13 @@
+
+**/settings/Mainnet.toml
+**/settings/Testnet.toml
+.cache/**
+history.txt
+
+logs
+*.log
+npm-debug.log*
+coverage
+*.info
+costs-reports.json
+node_modules

stacks/.vscode/settings.json

@@ -0,0 +1,4 @@
+
+{
+    "files.eol": "\n"
+}

stacks/.vscode/tasks.json

@@ -0,0 +1,19 @@
+
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "check contracts",
+      "group": "test",
+      "type": "shell",
+      "command": "clarinet check"
+    },
+    {
+      "type": "npm",
+      "script": "test",
+      "group": "test",
+      "problemMatcher": [],
+      "label": "npm test"
+    }
+  ]
+}

stacks/Clarinet.toml

@@ -0,0 +1,31 @@
+[project]
+name = 'stacks'
+description = ''
+authors = []
+telemetry = false
+cache_dir = './.cache'
+
+[[project.requirements]]
+contract_id = 'SP1E0XBN9T4B10E9QMR7XMFJPMA19D77WY3KP2QKC.self-listing-helper-v3'
+[contracts.executor-state]
+path = 'contracts/executor-state.clar'
+clarity_version = 3
+epoch = 'latest'
+
+[contracts.executor]
+path = 'contracts/executor.clar'
+clarity_version = 3
+epoch = '3.2'
+depends_on = ['executor-state']
+[repl.analysis]
+passes = ['check_checker']
+
+[repl.analysis.check_checker]
+strict = false
+trusted_sender = false
+trusted_caller = false
+callee_filter = false
+
+[repl.remote_data]
+enabled = false
+api_url = 'https://api.hiro.so'

stacks/contracts/executor-state.clar

@@ -0,0 +1,94 @@
+;; title: executor-state
+;; version: 0.0.1
+;; summary: State contract for cross-chain executor relayer registry
+;; description: Simple relayer address mapping for the executor system
+
+;;;; Constants
+
+;; State contract errors
+(define-constant ERR_STATE_RELAYER_EXISTS (err u20001))
+
+;;;; Data maps
+
+;; Map to track relayer addresses for payments
+;; Universal address is keccak256(stacks-principal-as-string)
+(define-map relayer-to-stacks
+  (buff 32)  ;; Universal address (32-byte hash)
+  principal  ;; Stacks principal for STX payments
+)
+
+;;;; Public functions
+
+;; @desc Register a relayer's Stacks address for their universal address
+;;       Anyone can call this to register themselves as a relayer
+(define-public (register-relayer (stacks-addr principal))
+  (let ((p-as-string (principal-to-string stacks-addr))
+        (universal-addr (keccak256 (string-ascii-to-buff p-as-string))))
+    
+    ;; Check if relayer already exists
+    (asserts! (is-none (relayer-to-stacks-get universal-addr)) ERR_STATE_RELAYER_EXISTS)
+    
+    ;; Register the mapping
+    (map-set relayer-to-stacks universal-addr stacks-addr)
+    
+    ;; Return the universal address for confirmation
+    (ok universal-addr)))
+
+;;;; Read-only functions
+
+;; @desc Convert universal address to Stacks principal
+(define-read-only (universal-addr-to-principal (universal-addr (buff 32)))
+  (relayer-to-stacks-get universal-addr))
+
+;; @desc Helper function to convert string to buffer for hashing
+;;       Matches the exact implementation from Wormhole Core
+(define-read-only (string-ascii-to-buff (s (string-ascii 256)))
+  (let ((cb (unwrap-panic (to-consensus-buff? s))))
+    ;; Consensus buff format for string:
+    ;;   bytes[0]:     Consensus Buff Type
+    ;;   bytes[1..4]:  String length
+    ;;   bytes[5..]:   String data
+    (unwrap-panic (slice? cb u5 (len cb)))))
+
+;; principle to string conversion from https://explorer.hiro.so/txid/0xa0988bb5f2aa6179e61e7735b91f7276cf70106f05781a0c1c7dee663be5dc7c?chain=mainnet
+;; @desc Convert principal to string representation (C32 encoding)
+(define-read-only (principal-to-string (p principal))
+  (let ((destructed (unwrap-panic (principal-destruct? p)))
+        (checksum (unwrap-panic (slice? (sha256 (sha256 (concat (get version destructed) (get hash-bytes destructed)))) u0 u4)))
+        (data (unwrap-panic (as-max-len? (concat (get hash-bytes destructed) checksum) u24)))
+        (result (concat (concat "S" (unwrap-panic (element-at? C32 (buff-to-uint-be (get version destructed))))) (append-leading-0 data (trim-leading-0 (hash-bytes-to-string data))))))
+    (match (get name destructed) n (concat (concat result ".") n) result)))
+
+;; Constants and helpers for C32 encoding
+(define-constant C32 "0123456789ABCDEFGHJKMNPQRSTVWXYZ")
+(define-constant LIST_15 (list 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0))
+(define-constant LIST_24 (list 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0))
+(define-constant LIST_39 (concat LIST_24 LIST_15))
+
+(define-read-only (c32-to-string-iter (idx int) (it { s: (string-ascii 39), r: uint }))
+  { s: (unwrap-panic (as-max-len? (concat (unwrap-panic (element-at? C32 (mod (get r it) u32))) (get s it)) u39)), r: (/ (get r it) u32) })
+
+(define-read-only (hash-bytes-to-string (data (buff 24)))
+  (let ((low-part (get s (fold c32-to-string-iter LIST_24 { s: "", r: (buff-to-uint-be (unwrap-panic (as-max-len? (unwrap-panic (slice? data u9 u24)) u16)))})))
+        (high-part (get s (fold c32-to-string-iter LIST_15 { s: "", r: (buff-to-uint-be (unwrap-panic (as-max-len? (unwrap-panic (slice? data u0 u9)) u16)))}))))
+    (unwrap-panic (as-max-len? (concat high-part low-part) u39))))
+
+(define-read-only (trim-leading-0-iter (idx int) (it (string-ascii 39)))
+  (if (is-eq (element-at? it u0) (some "0")) (unwrap-panic (slice? it u1 (len it))) it))
+
+(define-read-only (trim-leading-0 (s (string-ascii 39)))
+  (fold trim-leading-0-iter LIST_39 s))
+
+(define-read-only (append-leading-0-iter (idx int) (it { hash-bytes: (buff 24), address: (string-ascii 39)}))
+  (if (is-eq (element-at? (get hash-bytes it) u0) (some 0x00))
+    { hash-bytes: (unwrap-panic (slice? (get hash-bytes it) u1 (len (get hash-bytes it)))), address: (unwrap-panic (as-max-len? (concat "0" (get address it)) u39)) }
+    it))
+
+(define-read-only (append-leading-0 (hash-bytes (buff 24)) (s (string-ascii 39)))
+  (get address (fold append-leading-0-iter LIST_24 { hash-bytes: hash-bytes, address: s })))
+
+;;;; Map getters
+
+(define-read-only (relayer-to-stacks-get (universal-addr (buff 32)))
+  (map-get? relayer-to-stacks universal-addr))
+

stacks/contracts/executor.clar

@@ -0,0 +1,162 @@
+;; title: executor
+;; version:
+;; summary:
+;; description:
+
+;; traits
+;;
+
+;; token definitions
+;;
+
+;; constants
+(define-constant EXECUTOR-VERSION "Executor-0.0.1")
+(define-constant OUR-CHAIN u1) ;; Must be manually updated before deployment. Worth doing it this way or an initialize call?
+
+;; errors
+(define-constant ERR-QUOTE-SRC-CHAIN-MISMATCH (err u1001))
+(define-constant ERR-QUOTE-DST-CHAIN-MISMATCH (err u1002))
+(define-constant ERR-QUOTE-EXPIRED (err u1003))
+(define-constant ERR-UNREGISTERED-RELAYER (err u1004))
+(define-constant ERR-INVALID-PAYEE-ADDRESS (err u1005))
+(define-constant ERR-BUFFER-PARSE-ERROR (err u1006))
+;;
+
+;; data vars
+;;
+
+;; data maps
+;;
+
+;; public functions
+(define-public (request-execution
+    (dst-chain uint)
+    (dst-addr (buff 32))
+    (refund-addr principal)
+    (signed-quote-bytes (buff 8192))
+    (request-bytes (buff 8192))
+    (relay-instructions (buff 8192))
+    (payment uint)) ;; STX amount in microSTX
+
+  (begin
+    ;; Validate quote header
+    (try! (validate-quote-header signed-quote-bytes dst-chain))
+    
+    ;; Extract quoter and payee info  
+    (match (extract-quote-addresses signed-quote-bytes)
+      quote-addresses 
+        (let ((payee-universal-addr (get payee quote-addresses)))
+          ;; 1. Verify universal address is properly formatted (32 bytes, non-zero)
+          (asserts! (is-eq (len payee-universal-addr) u32) ERR-INVALID-PAYEE-ADDRESS)
+          (asserts! (not (is-eq payee-universal-addr 0x0000000000000000000000000000000000000000000000000000000000000000)) ERR-INVALID-PAYEE-ADDRESS)
+          
+          ;; 2. Verify relayer is registered and get principal
+          (let ((payee-lookup-result (contract-call? .executor-state relayer-to-stacks-get payee-universal-addr)))
+            (asserts! (is-some payee-lookup-result) ERR-UNREGISTERED-RELAYER)
+            
+            ;; 3. Extract the principal and validate it's not contract address
+            (let ((payee-principal (unwrap-panic payee-lookup-result)))
+              (asserts! (not (is-eq payee-principal (as-contract tx-sender))) ERR-INVALID-PAYEE-ADDRESS)
+              
+              ;; 4. Perform the payment after all validations pass
+              (try! (stx-transfer? payment tx-sender payee-principal))
+
+              ;; Emit event for off-chain relayers
+              (print {
+                event: "RequestForExecution",
+                quoter-address: (get quoter quote-addresses),
+                amount-paid: payment,
+                dst-chain: dst-chain,
+                dst-addr: dst-addr,
+                refund-addr: refund-addr,
+                signed-quote: signed-quote-bytes,
+                request-bytes: request-bytes,
+                relay-instructions: relay-instructions,
+                block-height: stacks-block-height,
+                tx-sender: tx-sender
+              })
+
+              (ok true))))
+      err-case 
+        ERR-BUFFER-PARSE-ERROR)))
+;;
+
+;; read only functions
+;; Extract uint16 from buffer at specific offset (big-endian) using efficient slice operation
+(define-read-only (extract-uint16-be (data (buff 8192)) (offset uint))
+  (let ((extracted (slice? data offset (+ offset u2))))
+    (match extracted
+      result (if (is-eq (len result) u2)
+        (ok (buff-to-uint-be (unwrap-panic (as-max-len? result u2))))
+        (err ERR-BUFFER-PARSE-ERROR))
+      (err ERR-BUFFER-PARSE-ERROR))))
+
+;; Extract uint64 from buffer at specific offset (big-endian) using efficient slice operation
+(define-read-only (extract-uint64-be (data (buff 8192)) (offset uint))
+  (let ((extracted (slice? data offset (+ offset u8))))
+    (match extracted
+      result (if (is-eq (len result) u8)
+        (ok (buff-to-uint-be (unwrap-panic (as-max-len? result u8))))
+        (err ERR-BUFFER-PARSE-ERROR))
+      (err ERR-BUFFER-PARSE-ERROR))))
+
+;; Extract bytes32 from buffer at specific offset
+;; Returns a properly sized 32-byte buffer using efficient slice operation
+(define-read-only (extract-bytes32 (data (buff 8192)) (offset uint))
+  (let ((extracted (slice? data offset (+ offset u32))))
+    (match extracted
+      result (if (is-eq (len result) u32)
+        (ok (unwrap-panic (as-max-len? result u32)))
+        (err ERR-BUFFER-PARSE-ERROR))
+      (err ERR-BUFFER-PARSE-ERROR))))
+
+;; Extract address (20 bytes) from buffer at specific offset
+(define-read-only (extract-address (data (buff 8192)) (offset uint))
+  (slice? data offset (+ offset u20)))
+
+;; Validate quote header
+(define-read-only (validate-quote-header (signed-quote-bytes (buff 8192)) (dst-chain uint))
+  (match (extract-uint16-be signed-quote-bytes u56)
+    quote-src-chain (match (extract-uint16-be signed-quote-bytes u58)
+      quote-dst-chain (match (extract-uint64-be signed-quote-bytes u60)
+        expiry-time (if (is-eq quote-src-chain OUR-CHAIN)
+          (if (is-eq quote-dst-chain dst-chain)
+            ;; Currently comparing Unix timestamp (expiry-time) with block height (stacks-block-height)
+            ;; Correct way is likely to do: (get-stacks-block-info? time stacks-block-height) which should return Unix timestamp
+            ;; Unable to write tests for it though as of now. 
+            (if (> expiry-time stacks-block-height)
+              (ok true)
+              ERR-QUOTE-EXPIRED)
+            ERR-QUOTE-DST-CHAIN-MISMATCH)
+          ERR-QUOTE-SRC-CHAIN-MISMATCH)
+        err3 ERR-BUFFER-PARSE-ERROR)
+      err2 ERR-BUFFER-PARSE-ERROR)
+    err1 ERR-BUFFER-PARSE-ERROR))
+
+;; Extract quoter and payee addresses from quote
+(define-read-only (extract-quote-addresses (signed-quote-bytes (buff 8192)))
+  (match (extract-address signed-quote-bytes u4)
+    quoter-addr (match (extract-bytes32 signed-quote-bytes u24)
+      payee-addr-32 (ok {
+        quoter: quoter-addr,
+        payee: payee-addr-32
+      })
+      err (err ERR-BUFFER-PARSE-ERROR))
+    (err ERR-BUFFER-PARSE-ERROR)))
+
+
+;; Convert 32-byte universal address hash back to a Stacks principal
+;; Uses the executor-state contract's relayer registry
+(define-read-only (universal-addr-to-principal (universal-addr (buff 32)))
+  (contract-call? .executor-state universal-addr-to-principal universal-addr))
+
+;; Read-only functions for external access
+(define-read-only (get-executor-version)
+  EXECUTOR-VERSION)
+
+(define-read-only (get-our-chain)
+  OUR-CHAIN)
+;;
+
+;; private functions
+;;