BM-271: Add deliver and deliverBatch for "altruistic fulfillment" (#107)

- split out the ProofDelivered event
- update IProofMarket in the RFC
- rename verifyDelivery and add some basic tests
- update rfc.md

Supersedes #103
Closes github#85

Author: nategraf

contracts/src/IProofMarket.sol

@@ -99,8 +99,13 @@ interface IProofMarket {
     event RequestSubmitted(ProvingRequest request, bytes clientSignature);
     /// Event logged when a request is locked in by the given prover.
     event RequestLockedin(uint192 indexed requestId, address prover);
-    /// Event logged when a request is fulfilled, outside of a batch.
-    event RequestFulfilled(uint192 indexed requestId, bytes journal, bytes seal);
+    /// Event logged when a request is fulfilled.
+    event RequestFulfilled(uint192 indexed requestId);
+    /// @notice Event logged when a proof is delivered that satisfies the requests requirements.
+    /// @dev It is possible for this event to be logged multiple times for a single request. This
+    /// is usually logged as part of order fulfillment, however it can also be logged by a prover
+    /// sending the proof without payment.
+    event ProofDelivered(uint192 indexed requestId, bytes journal, bytes seal);
     /// Event when prover stake is burned for failing to fulfill a request by the deadline.
     event LockinStakeBurned(uint192 indexed requestId, uint96 stake);
     /// Event when a deposit is made to the proof market.
@@ -172,10 +177,24 @@ interface IProofMarket {
     /// Note that this can differ from the address of the prover that locked the
     /// request. When they differ, the locked-in prover is the one that received payment.
     function fulfill(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external;
-
     /// @notice Fulfills a batch of locked requests. See IProofMarket.fulfill for more information.
     function fulfillBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) external;
 
+    /// @notice Delivers a proof satisfying a referenced request, without modifying contract state.
+    /// In particular, calling this method will not result in payment being sent to the prover, or
+    /// marking the request as fulfilled.
+    /// @dev This method is useful for when an interested third party wants to delivery a proof for
+    /// a request even if they will not be paid for doing so.
+    /// @param fill The fulfillment information, including the journal and seal.
+    /// @param assessorSeal The seal from the Assessor guest, which is verified to confirm the
+    /// request's requirements are met.
+    /// @param prover The address of the prover that produced the fulfillment.
+    /// Note that this can differ from the address of the prover that locked the
+    /// request.
+    function deliver(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external;
+    /// @notice Delivers a batch of proofs. See IProofMarket.deliver for more information.
+    function deliverBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) external;
+
     /// @notice Combined function to submit a new merkle root to the set-verifier and call fulfillBatch.
     /// @dev Useful to reduce the transaction count for fulfillments
     function submitRootAndFulfillBatch(

contracts/src/ProofMarket.sol

@@ -241,8 +241,10 @@ contract ProofMarket is IProofMarket, EIP712 {
         emit RequestLockedin(request.id, prover);
     }
 
-    // TODO(victor): Add a path that allows a prover to fuilfill a request without first sending a lock-in.
-    function fulfill(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external {
+    /// Verify the application and assessor receipts, ensuring that the provided fulfillment
+    /// satisfies the request.
+    // TODO(#165) Return or check the request checksum here.
+    function verifyDelivery(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) public view {
         // Verify the application guest proof. We need to verify it here, even though the market
         // guest already verified that the prover has knowledge of a verifying receipt, because
         // we need to make sure the _delivered_ seal is valid.
@@ -266,13 +268,14 @@ contract ProofMarket is IProofMarket, EIP712 {
         );
         // Verification of the assessor seal does not need to comply with FULFILL_MAX_GAS_FOR_VERIFY.
         VERIFIER.verify(assessorSeal, ASSESSOR_ID, assessorJournalDigest);
-
-        _fulfillVerified(fill.id);
-
-        emit RequestFulfilled(fill.id, fill.journal, fill.seal);
     }
 
-    function fulfillBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) public {
+    /// Verify the application and assessor receipts for the batch, ensuring that the provided
+    /// fulfillments satisfy the requests.
+    function verifyBatchDelivery(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover)
+        public
+        view
+    {
         // TODO(victor): Figure out how much the memory here is costing. If it's significant, we can do some tricks to reduce memory pressure.
         bytes32[] memory claimDigests = new bytes32[](fills.length);
         uint192[] memory ids = new uint192[](fills.length);
@@ -297,14 +300,28 @@ contract ProofMarket is IProofMarket, EIP712 {
         );
         // Verification of the assessor seal does not need to comply with FULFILL_MAX_GAS_FOR_VERIFY.
         VERIFIER.verify(assessorSeal, ASSESSOR_ID, assessorJournalDigest);
+    }
+
+    function fulfill(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external {
+        verifyDelivery(fill, assessorSeal, prover);
+        _fulfillVerified(fill.id);
+
+        // TODO(victor): Potentially this should be (re)combined with RequestFulfilled. It would make
+        // the logic to watch for a proof a bit more complex, but the gas usage a little less (by
+        // about 1000 gas per fulfill based on benchmarks)
+        emit ProofDelivered(fill.id, fill.journal, fill.seal);
+    }
+
+    function fulfillBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) public {
+        verifyBatchDelivery(fills, assessorSeal, prover);
 
         // NOTE: It would be slightly more efficient to keep balances and request flags in memory until a single
         // batch update to storage. However, updating the the same storage slot twice only costs 100 gas, so
         // this savings is marginal, and will be outweighed by complicated memory management if not careful.
         for (uint256 i = 0; i < fills.length; i++) {
-            _fulfillVerified(ids[i]);
+            _fulfillVerified(fills[i].id);
 
-            emit RequestFulfilled(fills[i].id, fills[i].journal, fills[i].seal);
+            emit ProofDelivered(fills[i].id, fills[i].journal, fills[i].seal);
         }
     }
 
@@ -336,6 +353,20 @@ contract ProofMarket is IProofMarket, EIP712 {
         // Mark the request as fulfilled and pay the prover.
         accounts[client].setRequestFulfilled(idx);
         accounts[lock.prover].balance += lock.price + lock.stake;
+
+        emit RequestFulfilled(id);
+    }
+
+    function deliver(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external {
+        verifyDelivery(fill, assessorSeal, prover);
+        emit ProofDelivered(fill.id, fill.journal, fill.seal);
+    }
+
+    function deliverBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) external {
+        verifyBatchDelivery(fills, assessorSeal, prover);
+        for (uint256 i = 0; i < fills.length; i++) {
+            emit ProofDelivered(fills[i].id, fills[i].journal, fills[i].seal);
+        }
     }
 
     function slash(uint192 requestId) external {

contracts/test/ProofMarket.t.sol

@@ -430,6 +430,11 @@ contract ProofMarketTest is Test {
         vm.startPrank(PROVER_WALLET.addr);
         proofMarket.lockin(request, clientSignature);
         (Fulfillment memory fill, bytes memory assessorSeal) = fulfillRequest(request, APP_JOURNAL, PROVER_WALLET.addr);
+
+        vm.expectEmit(true, true, true, true);
+        emit IProofMarket.RequestFulfilled(request.id);
+        vm.expectEmit(true, true, true, false);
+        emit IProofMarket.ProofDelivered(request.id, hex"", hex"");
         proofMarket.fulfill(fill, assessorSeal, PROVER_WALLET.addr);
         // console2.log("fulfill - Gas used:", vm.gasUsed());
         vm.stopPrank();
@@ -526,6 +531,13 @@ contract ProofMarketTest is Test {
 
         (Fulfillment[] memory fills, bytes memory assessorSeal) =
             fulfillRequestBatch(requests, journals, PROVER_WALLET.addr);
+
+        for (uint256 i = 0; i < fills.length; i++) {
+            vm.expectEmit(true, true, true, true);
+            emit IProofMarket.RequestFulfilled(fills[i].id);
+            vm.expectEmit(true, true, true, false);
+            emit IProofMarket.ProofDelivered(fills[i].id, hex"", hex"");
+        }
         proofMarket.fulfillBatch(fills, assessorSeal, PROVER_WALLET.addr);
 
         for (uint256 i = 0; i < fills.length; i++) {
@@ -620,7 +632,7 @@ contract ProofMarketTest is Test {
         checkProofMarketBalance();
     }
 
-    function testFulfillfExpired() public {
+    function testFulfillExpired() public {
         Offer memory offer = Offer({
             minPrice: 1 ether,
             maxPrice: 2 ether,
@@ -650,6 +662,36 @@ contract ProofMarketTest is Test {
         checkProofMarketBalance();
     }
 
+    function testDeliver() public {
+        // Submit request
+        Vm.Wallet memory client = createClient(1);
+        ProvingRequest memory request = defaultRequest(client.addr, 1);
+        (Fulfillment memory fill, bytes memory assessorSeal) = fulfillRequest(request, APP_JOURNAL, PROVER_WALLET.addr);
+
+        vm.expectEmit(true, true, true, false);
+        emit IProofMarket.ProofDelivered(request.id, hex"", hex"");
+        proofMarket.deliver(fill, assessorSeal, PROVER_WALLET.addr);
+
+        // Check that the proof is still marked as unfulfilled.
+        assertFalse(proofMarket.requestIsFulfilled(fill.id), "Request should not have fulfilled status");
+    }
+
+    function testDeliverBatch() public {
+        (ProvingRequest[] memory requests, bytes[] memory journals) = newBatch(5);
+        (Fulfillment[] memory fills, bytes memory assessorSeal) =
+            fulfillRequestBatch(requests, journals, PROVER_WALLET.addr);
+
+        for (uint256 i = 0; i < fills.length; i++) {
+            vm.expectEmit(true, true, true, false);
+            emit IProofMarket.ProofDelivered(fills[i].id, hex"", hex"");
+        }
+        proofMarket.deliverBatch(fills, assessorSeal, PROVER_WALLET.addr);
+
+        for (uint256 j = 0; j < fills.length; j++) {
+            assertFalse(proofMarket.requestIsFulfilled(fills[j].id), "Request should not have fulfilled status");
+        }
+    }
+
     function testSlash() public {
         Offer memory offer = Offer({
             minPrice: 1 ether,
@@ -662,7 +704,7 @@ contract ProofMarketTest is Test {
         Vm.Wallet memory client = createClient(1);
         ProvingRequest memory request = newRequest(offer, client.addr, 1);
 
-        testFulfillfExpired();
+        testFulfillExpired();
 
         // Slash the request
         vm.expectEmit(true, true, false, true);

crates/boundless-market/src/contracts/proof_market.rs

@@ -488,7 +488,7 @@ where
             .context("Failed to get latest block number")?)
     }
 
-    /// Query the RequestFulfilled event based on request ID and block options.
+    /// Query the ProofDelivered event based on request ID and block options.
     /// For each iteration, we query a range of blocks.
     /// If the event is not found, we move the range down and repeat until we find the event.
     /// If the event is not found after the configured max iterations, we return an error.
@@ -517,7 +517,7 @@ where
             let lower_block = upper_block.saturating_sub(self.event_query_config.block_range);
 
             // Set up the event filter for the specified block range
-            let mut event_filter = self.instance.RequestFulfilled_filter();
+            let mut event_filter = self.instance.ProofDelivered_filter();
             event_filter.filter = event_filter
                 .filter
                 .topic1(request_id)

docs/src/market/rfc.md

@@ -156,8 +156,13 @@ interface IProofMarket {
     event RequestSubmitted(ProvingRequest request, bytes clientSignature);
     /// Event logged when a request is locked in by the given prover.
     event RequestLockedin(uint192 indexed requestId, address prover);
-    /// Event logged when a request is fulfilled, outside of a batch.
-    event RequestFulfilled(uint192 indexed requestId, bytes journal, bytes seal);
+    /// Event logged when a request is fulfilled.
+    event RequestFulfilled(uint192 indexed requestId);
+    /// @notice Event logged when a proof is delivered that satisfies the requests requirements.
+    /// @dev It is possible for this event to be logged multiple times for a single request. This
+    /// is usually logged as part of order fulfillment, however it can also be logged by a prover
+    /// sending the proof without payment.
+    event ProofDelivered(uint192 indexed requestId, bytes journal, bytes seal);
     /// Event when prover stake is burned for failing to fulfill a request by the deadline.
     event LockinStakeBurned(uint192 indexed requestId, uint96 stake);
     /// Event when a deposit is made to the proof market.
@@ -200,14 +205,14 @@ interface IProofMarket {
     /// @notice Submit a request such that it is publicly available for provers to evaluate and bid on.
     ///         Any `msg.value` sent with the call will be added to the balance of `msg.sender`.
     /// @dev Submitting the transaction only broadcasting it, and is not a required step.
-    function submitRequest(ProvingRequest calldata request, bytes memory clientSignature) external payable;
+    function submitRequest(ProvingRequest calldata request, bytes calldata clientSignature) external payable;
 
     /// @notice Lock the proving request to the prover, giving them exclusive rights to be paid to
     /// fulfill this request, and also making them subject to slashing penalties if they fail to
     /// deliver. At this point, the price for fulfillment is also set, based on the reverse Dutch
     /// auction parameters and the block at which this transaction is processed.
     /// @dev This method should be called from the address of the prover.
-    function lockin(ProvingRequest calldata request, bytes memory clientSignature) external;
+    function lockin(ProvingRequest calldata request, bytes calldata clientSignature) external;
 
     /// @notice Lock the proving request to the prover, giving them exclusive rights to be paid to
     /// fulfill this request, and also making them subject to slashing penalties if they fail to
@@ -216,16 +221,46 @@ interface IProofMarket {
     /// @dev This method uses the provided signature to authenticate the prover.
     function lockinWithSig(
         ProvingRequest calldata request,
-        bytes memory clientSignature,
+        bytes calldata clientSignature,
         bytes calldata proverSignature
     ) external;
 
-    /// Fulfill a locked request by delivering the proof for the application.
-    /// Upon proof verification, the prover will be paid.
-    function fulfill(Fulfillment calldata fill, bytes calldata assessorSeal) external;
-
-    /// Fulfills a batch of locked requests
-    function fulfillBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal) external;
+    /// @notice Fulfill a locked request by delivering the proof for the application.
+    /// Upon proof verification, the prover that locked the request will be paid.
+    /// @param fill The fulfillment information, including the journal and seal.
+    /// @param assessorSeal The seal from the Assessor guest, which is verified to confirm the
+    /// request's requirements are met.
+    /// @param prover The address of the prover that produced the fulfillment.
+    /// Note that this can differ from the address of the prover that locked the
+    /// request. When they differ, the locked-in prover is the one that received payment.
+    function fulfill(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external;
+    /// @notice Fulfills a batch of locked requests. See IProofMarket.fulfill for more information.
+    function fulfillBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) external;
+
+    /// @notice Delivers a proof satisfying a referenced request, without modifying contract state.
+    /// In particular, calling this method will not result in payment being sent to the prover, or
+    /// marking the request as fulfilled.
+    /// @dev This method is useful for when an interested third party wants to delivery a proof for
+    /// a request even if they will not be paid for doing so.
+    /// @param fill The fulfillment information, including the journal and seal.
+    /// @param assessorSeal The seal from the Assessor guest, which is verified to confirm the
+    /// request's requirements are met.
+    /// @param prover The address of the prover that produced the fulfillment.
+    /// Note that this can differ from the address of the prover that locked the
+    /// request.
+    function deliver(Fulfillment calldata fill, bytes calldata assessorSeal, address prover) external;
+    /// @notice Delivers a batch of proofs. See IProofMarket.deliver for more information.
+    function deliverBatch(Fulfillment[] calldata fills, bytes calldata assessorSeal, address prover) external;
+
+    /// @notice Combined function to submit a new merkle root to the set-verifier and call fulfillBatch.
+    /// @dev Useful to reduce the transaction count for fulfillments
+    function submitRootAndFulfillBatch(
+        bytes32 root,
+        bytes calldata seal,
+        Fulfillment[] calldata fills,
+        bytes calldata assessorSeal,
+        address prover
+    ) external;
 
     /// When a prover fails to fulfill a request by the deadline, this method can be used to burn
     /// the associated prover stake.