src: Allow uniform staleness monitoring (#8)

Author: pmerkleplant

src/IUScribe.sol

@@ -158,6 +158,12 @@ interface IUScribe {
     /// @return string The oracle's name.
     function name() external view returns (string memory);
 
+    /// @notice Returns the timestamp of the latest poke.
+    /// @dev This timestamp is updated on every poke and allows uniform
+    ///      staleness monitoring accross uscribe instances.
+    /// @return uint The timestamp of the latest poke.
+    function latestPoke() external view returns (uint);
+
     /// @notice Returns whether address `who` is a validator for Schnorr
     ///         verification.
     /// @param who The address to check.

src/UScribe.sol

@@ -28,6 +28,7 @@ abstract contract UScribe is IUScribe, Auth {
 
     bytes4 internal constant _NO_ERR = bytes4(0);
 
+    /// @inheritdoc IUScribe
     bytes32 public immutable wat;
 
     // Note that strings cannot be marked as immutable.
@@ -37,6 +38,8 @@ abstract contract UScribe is IUScribe, Auth {
     //--------------------------------------------------------------------------
     // Storage
 
+    uint48 private _latestPoke;
+
     struct SchnorrStorage {
         LibSecp256k1.Point[256] pubKeys;
         uint8 bar;
@@ -100,7 +103,9 @@ abstract contract UScribe is IUScribe, Auth {
     ///
     ///      Protections against replayability issues MAY be including a nonce
     ///      in the payload or only accepting payloads with strictly
-    ///      monotonically increasing timestamps.
+    ///      monotonically increasing timestamps. The `latestPoke()(uint)`
+    ///      function can be used by consumers to access the timestamp of the
+    ///      last poke.
     ///
     ///      To protect against cross-chain replayability issues the payload
     ///      MAY be expected to include the chain's id.
@@ -140,6 +145,9 @@ abstract contract UScribe is IUScribe, Auth {
         if (err != _NO_ERR) {
             revert PokeError_ConsumerRejectedPayload(err);
         }
+
+        // Update latest poke timestamp once poke accepted by consumer.
+        _latestPoke = uint48(block.timestamp);
     }
 
     /// @inheritdoc IUScribe
@@ -169,6 +177,9 @@ abstract contract UScribe is IUScribe, Auth {
         if (err != _NO_ERR) {
             revert PokeError_ConsumerRejectedPayload(err);
         }
+
+        // Update latest poke timestamp once poke accepted by consumer.
+        _latestPoke = uint48(block.timestamp);
     }
 
     //--------------------------------------------------------------------------
@@ -409,6 +420,14 @@ abstract contract UScribe is IUScribe, Auth {
     //--------------------------------------------------------------------------
     // Public View Functions
 
+    /// @inheritdoc IUScribe
+    ///
+    /// @dev Note that function is public to grant read-only access to
+    ///      downstream consumer.
+    function latestPoke() public view returns (uint) {
+        return _latestPoke;
+    }
+
     //----------------------------------
     // SchnorrStorage
 

test/UScribe.t.sol

@@ -184,6 +184,9 @@ contract UScribeTest is Test {
         // No validators lifted for Schnorr or ECDSA.
         assertEq(uscribe.validatorsSchnorr().length, 0);
         assertEq(uscribe.validatorsECDSA().length, 0);
+
+        // Latest poke timestamp is zero.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function test_Deployment_FailsIf_NameIsEmpty() public {
@@ -231,6 +234,9 @@ contract UScribeTest is Test {
 
         // Poke uPokeData with Schnorr musig.
         uscribe.poke(uPokeData, schnorr);
+
+        // Expect latestPoke timestamp to be updated.
+        assertEq(uscribe.latestPoke(), vm.getBlockTimestamp());
     }
 
     function testFuzz_pokeSchnorr_FailsIf_VerificationFailed_DueTo_BarNotReached(
@@ -271,6 +277,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, schnorr);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeSchnorr_FailsIf_VerificationFailed_DueTo_SignatureInvalid(
@@ -314,6 +323,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, schnorr);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeSchnorr_FailsIf_VerificationFailed_DueTo_ValidatorInvalid(
@@ -364,6 +376,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, schnorr);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeSchnorr_FailsIf_VerificationFailed_DueTo_DoubleSigningAttempted(
@@ -407,6 +422,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, schnorr);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeSchnorr_FailsIf_ConsumerRejectedPayload(
@@ -444,6 +462,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, schnorr);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     //----------------------------------
@@ -505,6 +526,9 @@ contract UScribeTest is Test {
         // Poke uPokeData with Schnorr FROST.
         uscribe.poke(uPokeData, schnorrData);
 
+        // Expect latestPoke timestamp to be updated.
+        assertEq(uscribe.latestPoke(), vm.getBlockTimestamp());
+
         // Expect poke of mutated uPokeData with Schnorr FROST to fail.
         vm.expectRevert(
             abi.encodeWithSelector(
@@ -549,6 +573,9 @@ contract UScribeTest is Test {
 
         // Poke uPokeData with list of ECDSA signatures.
         uscribe.poke(uPokeData, ecdsas);
+
+        // Expect latestPoke timestamp to be updated.
+        assertEq(uscribe.latestPoke(), vm.getBlockTimestamp());
     }
 
     function testFuzz_pokeECDSA_FailsIf_VerificationFailed_DueTo_BarNotReached(
@@ -583,6 +610,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, ecdsas);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeECDSA_FailsIf_VerificationFailed_DueTo_SignatureInvalid(
@@ -624,6 +654,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, ecdsas);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeECDSA_FailsIf_VerificationFailed_DueTo_DoubleSigningAttempted(
@@ -663,6 +696,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, ecdsas);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     function testFuzz_pokeECDSA_FailsIf_ConsumerRejectedPayload(
@@ -697,6 +733,9 @@ contract UScribeTest is Test {
             )
         );
         uscribe.poke(uPokeData, ecdsas);
+
+        // Expect latestPoke timestamp to not be updated.
+        assertEq(uscribe.latestPoke(), 0);
     }
 
     //--------------------------------------------------------------------------