Add pause state readonly function

.gitattributes

@@ -1,3 +1,4 @@
 tests/** linguist-vendored
 vitest.config.js linguist-vendored
 * text=lf
+docs/PAUSE_STATE_*.md linguist-documentation

CHANGELOG.md

@@ -8,6 +8,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- Direct read-only function for contract pause state (Issue #345):
+  - New `get-is-paused` read-only function provides direct access to pause state
+  - Returns simple boolean response: `(ok true)` for paused, `(ok false)` for running
+  - Eliminates need to infer pause state from other contract responses
+  - Frontend helpers updated to use new function for improved clarity
+  - Comprehensive contract tests for both v2 and legacy contracts
+  - Frontend integration tests verify correct API usage
+  - Example scripts for querying and monitoring pause state
+  - Migration guide for integrators
+  - Documentation updates across PAUSE_API_REFERENCE, PAUSE_OPERATIONS, and ADMIN_OPERATIONS
+
 - Cancel-pause-change functionality for contract pause operations:
   - New `cancel-pause-change` function allows admins to cancel pending pause proposals
   - Provides operational symmetry with existing `cancel-fee-change` function

README.md

@@ -155,6 +155,7 @@ constants instead of hard-coding path strings.
 | `get-pending-owner` | Pending ownership transfer target |
 | `get-pending-fee-change` | Pending fee proposal and execution height |
 | `get-pending-pause-change` | Pending pause proposal and execution height |
+| `get-is-paused` | Current contract pause state (true = paused, false = running) |
 | `get-multisig` | Authorized multisig contract address |
 | `get-contract-version` | Contract version and name |
 
@@ -184,7 +185,7 @@ constants instead of hard-coding path strings.
 | `blocked-users` | Privacy blocking |
 | `total-tips-sent` | Global counter (also tip ID) |
 | `total-volume` / `platform-fees` | Running totals |
-| `is-paused` | Emergency pause |
+| `is-paused` | Emergency pause state (accessible via `get-is-paused` read-only function) |
 | `current-fee-basis-points` | Fee rate (default 50 = 0.5%) |
 
 ### Testing

contracts/tipstream-v2.clar

@@ -540,6 +540,13 @@
     }
 )
 
+;; Returns the current pause state of the contract.
+;; When paused, tip operations are disabled.
+;; Returns (ok true) if paused, (ok false) if running.
+(define-read-only (get-is-paused)
+    (ok (var-get is-paused))
+)
+
 (define-read-only (get-multisig)
     (ok (var-get authorized-multisig))
 )

contracts/tipstream.clar

@@ -532,6 +532,13 @@
     }
 )
 
+;; Returns the current pause state of the contract.
+;; When paused, tip operations are disabled.
+;; Returns (ok true) if paused, (ok false) if running.
+(define-read-only (get-is-paused)
+    (ok (var-get is-paused))
+)
+
 (define-read-only (get-multisig)
     (ok (var-get authorized-multisig))
 )

docs/ADMIN_OPERATIONS.md

@@ -12,7 +12,7 @@ Quick reference guide for common administrative tasks on TipStream.
 | Emergency Pause | `set-paused` (direct) | None | Owner | Seconds |
 | Change Owner | `propose-new-owner` → `accept-ownership` | 2-step | Owner → New Owner | 10 min |
 | View Fee Rate | `get-current-fee-basis-points` | None (read) | Anyone | Instant |
-| View Contract Status | `get-contract-owner` / `is-paused` | None (read) | Anyone | Instant |
+| View Contract Status | `get-contract-owner` / `get-is-paused` | None (read) | Anyone | Instant |
 
 ## Pre-Administration Checklist
 
@@ -315,7 +315,7 @@ Result should be: SP1234...ABC
 fetch('https://api.hiro.so/.../get-contract-owner')
 // Should return owner address
 
-fetch('https://api.hiro.so/.../is-paused')
+fetch('https://api.hiro.so/.../get-is-paused')
 // Should return boolean (false = operational)
 
 // 2. Recent Transactions

docs/MIGRATION_GUIDE_PAUSE_STATE.md

@@ -0,0 +1,168 @@
+# Migration Guide: Pause State Read-Only Function
+
+## Overview
+
+This guide covers the addition of the `get-is-paused` read-only function to the TipStream contract, which provides direct access to the current pause state.
+
+## What Changed
+
+### Contract Changes
+
+**Added Function:**
+```clarity
+(define-read-only (get-is-paused)
+    (ok (var-get is-paused))
+)
+```
+
+This function provides a direct way to query the current pause state of the contract without having to infer it from other responses.
+
+### Frontend Changes
+
+**Updated Files:**
+- `frontend/src/lib/admin-contract.js` - Now calls `get-is-paused` instead of attempting to call non-existent `is-paused`
+- `frontend/src/lib/pauseOperations.js` - Updated constant from `IS_PAUSED` to `GET_IS_PAUSED`
+
+## Migration Steps
+
+### For Contract Integrators
+
+If you're integrating with the TipStream contract and need to check the pause state:
+
+**Before:**
+```javascript
+// Had to infer pause state from get-pending-pause-change or other methods
+const pendingData = await callReadOnly('get-pending-pause-change');
+// Parse and extract current state from complex response
+```
+
+**After:**
+```javascript
+// Direct pause state query
+const pauseData = await callReadOnly('get-is-paused');
+const isPaused = parseClarityValue(pauseData.result); // Returns boolean
+```
+
+### For Frontend Developers
+
+The `fetchPauseState()` function in `admin-contract.js` now uses the new read-only function internally. No changes needed to your code if you're using this helper.
+
+**Example Usage:**
+```javascript
+import { fetchPauseState } from '../lib/admin-contract';
+
+const state = await fetchPauseState();
+console.log(state.isPaused); // true or false
+console.log(state.pendingPause); // Pending proposal value (if any)
+console.log(state.effectiveHeight); // When pending proposal becomes executable
+```
+
+### For Admin Dashboard Users
+
+No changes required. The admin dashboard automatically uses the new function.
+
+## Response Format
+
+### get-is-paused Response
+
+```clarity
+(ok true)   // Contract is paused
+(ok false)  // Contract is running
+```
+
+### Clarity Hex Examples
+
+**Paused (true):**
+```
+0x0703
+```
+
+**Running (false):**
+```
+0x0704
+```
+
+## Benefits
+
+1. **Simpler API**: Direct access to pause state without parsing complex tuples
+2. **Better Performance**: Single function call instead of inferring from other data
+3. **Clearer Intent**: Explicit function name makes code more readable
+4. **Consistency**: Follows naming convention of other read-only functions
+
+## Backward Compatibility
+
+This is a **non-breaking change**. The addition of a new read-only function does not affect existing functionality:
+
+- All existing functions continue to work as before
+- The `is-paused` data variable remains unchanged
+- The `get-pending-pause-change` function still returns current state in its response
+- Frontend code that doesn't use the new function will continue to work
+
+## Testing
+
+### Contract Tests
+
+New tests have been added to verify the function works correctly:
+
+```bash
+npm test -- tests/tipstream-v2.test.ts
+npm test -- tests/tipstream.test.ts
+```
+
+### Frontend Tests
+
+Tests verify the integration with the frontend helpers:
+
+```bash
+cd frontend
+npm test -- pause-state.test.js
+npm test -- admin-contract.test.js
+```
+
+## Documentation Updates
+
+The following documentation has been updated:
+
+- `README.md` - Added `get-is-paused` to read-only functions table
+- `docs/PAUSE_API_REFERENCE.md` - Full API documentation for the new function
+- `docs/PAUSE_OPERATIONS.md` - Updated function availability table
+- `docs/PAUSE_CONTROL_RUNBOOK.md` - Updated operational procedures
+- `docs/ADMIN_OPERATIONS.md` - Updated admin dashboard examples
+
+## Troubleshooting
+
+### Issue: Function not found
+
+**Symptom:** Contract call fails with "function not found" error
+
+**Solution:** Ensure you're calling the correct function name: `get-is-paused` (not `is-paused`)
+
+### Issue: Unexpected response format
+
+**Symptom:** Response doesn't match expected format
+
+**Solution:** The function returns `(ok bool)`, not a raw boolean. Use `parseClarityValue()` to extract the boolean value.
+
+### Issue: Old code still works
+
+**Symptom:** Code using old inference method still works
+
+**Explanation:** This is expected. The old method of inferring pause state from `get-pending-pause-change` still works. The new function is an addition, not a replacement.
+
+## Support
+
+For questions or issues related to this change:
+
+1. Check the [PAUSE_API_REFERENCE.md](./PAUSE_API_REFERENCE.md) for detailed API documentation
+2. Review the [PAUSE_OPERATIONS.md](./PAUSE_OPERATIONS.md) for operational guidance
+3. Open an issue on GitHub with the `pause-control` label
+
+## Related Changes
+
+This change is part of issue #345: "Add a direct read-only contract function for the current pause state"
+
+**Related Documentation:**
+- [PAUSE_API_REFERENCE.md](./PAUSE_API_REFERENCE.md)
+- [PAUSE_OPERATIONS.md](./PAUSE_OPERATIONS.md)
+- [PAUSE_CONTROL_RUNBOOK.md](./PAUSE_CONTROL_RUNBOOK.md)
+- [ADMIN_OPERATIONS.md](./ADMIN_OPERATIONS.md)

docs/PAUSE_API_REFERENCE.md

@@ -138,13 +138,13 @@ Pause proposal pending:
 
 ---
 
-### is-paused
+### get-is-paused
 
 Returns current contract pause state.
 
 **Function Signature:**
 ```clarity
-(define-read-only (is-paused) ...)
+(define-read-only (get-is-paused) ...)
 ```
 
 **Parameters:** None
@@ -169,7 +169,7 @@ PAUSE_OPERATIONS = {
   EXECUTE_PAUSE: 'execute-pause-change',
   CANCEL_PAUSE: 'cancel-pause-change',
   GET_PENDING: 'get-pending-pause-change',
-  IS_PAUSED: 'is-paused'
+  GET_IS_PAUSED: 'get-is-paused'
 }
 
 TIMELOCK_BLOCKS = 144  // ~24 hours

docs/PAUSE_CONTROL_RUNBOOK.md

@@ -117,7 +117,7 @@ Before executing any pause change:
 
 ### If Pause Executed Unexpectedly
 
-1. Verify pause state: Check `is-paused` returns true
+1. Verify pause state: Check `get-is-paused` returns true
 2. Determine if intentional
 3. If unintentional:
    - Call `set-paused(false)` immediately (direct bypass)
@@ -138,7 +138,7 @@ Before executing any pause change:
 ### If Unpause Fails
 
 1. Call `set-paused(false)` directly (bypasses timelock)
-2. Verify `is-paused` returns false
+2. Verify `get-is-paused` returns false
 3. Monitor system for issues
 4. Investigate failure cause
 

docs/PAUSE_OPERATIONS.md

@@ -123,7 +123,7 @@ Need to pause?
 | cancel-pause-change | ✓ | ✗ |
 | set-paused (direct) | ✓ | ✗ |
 | get-pending-pause-change | ✓ | ✓ |
-| is-paused | ✓ | ✓ |
+| get-is-paused | ✓ | ✓ |
 
 ## Events