The database interface

A command line interface is all very well, but from the point of view of application logic it can be more convenient to execute provendb for oracle commands from within an Oracle session. ProvenDB for Oracle installs a PL/SQL package that allows you to do just that.

The database package communicates with the provendb-oracle program through the PROVENDBREQUESTS table. The provendb-oracle agent must be running in monitor mode with the. --monitorRequests flag. Eg:

✗ provendb-oracle monitor --monitorRequests
09:15:02.999 INFO  Monitoring with 120 s interval.
09:15:02.999 INFO  Looking for new requests in the provendbRequests table
09:15:03.026 INFO  Sleeping for 120 seconds
09:15:03.026 INFO  Will awake on dbms_alert

The package is called PROVENDBORACLE and is installed with public visibility in the ProvenDB for Oracle account. The package contains the following entry points:

provendboracle IS 
                FUNCTION fanchorrequest (
                    tablename    VARCHAR2,
                    columnlist   VARCHAR2 := '*',
                    whereclause  VARCHAR2 := NULL,
                    keyColumn    VARCHAR2 := 'ROWID'
                ) RETURN provendbrequests.id%TYPE;
                
               FUNCTION fvalidateRequest (
                    proofId    VARCHAR2 
                ) RETURN provendbrequests.id%TYPE;
             
            END ;

The function fanchorrequest requests that table rows be anchored. It takes the following arguments:

Argument	Optional	Description
tablename	No	Name of table to be anchored
columnlist	Yes	List of columns to be included in the anchor. Defaults to all columns
whereclause	Yes	Where clause to restrict rows to be anchored. Defaults to all rows
keyColumn	Yes	Column to be used as the key for each rows proof. Defaults to ROWID

For example, here we request that the payload table be anchored for all rows between ID 0 and 1000. The ID colu,mn will be used as the key and only the Payload column will be included in the proof:

set long 30000
var request_id NUMBER
var proof_id char
var proof clob
set pages 10000

BEGIN
  :request_id :=  PROVENDBORACLE.FANCHORREQUEST(
    TABLENAME => 'MY.PAYLOAD',
    COLUMNLIST => 'PAYLOAD ',
    WHERECLAUSE => 'ID BETWEEN 0 and 1000',
    KEYCOLUMN => 'ID'
  );
END;
/

We can retrieve information about the anchor by examining the PROVENDBREQUESTS table:

SELECT * FROM PROVENDB.PROVENDBREQUESTS WHERE ID=:request_id; 

BEGIN
     SELECT proofId into :proof_id FROM PROVENDB.PROVENDBREQUESTS WHERE ID=:request_id;
     SELECT proof into :proof from provendb.provendbcontrol where proofid=:proof_id;
end;
/
print proof_id
print proof

The proofId from the PROVENDBREQUESTS table can be used to validate the proof:

BEGIN
  :request_id := PROVENDBORACLE.FVALIDATEREQUEST(
    proofid => :proof_id
  );
END;
/

You can view the status of the request by examining the PROVENDBREQUEST table:

SELECT * FROM PROVENDB.PROVENDBREQUESTS WHERE ID=:request_id;

        ID REQUESTTYPE
---------- ------------
REQUESTJSON
-----------------------------------------------------------------------------------------------------
STATUS       STATUSDAT
------------ ---------
MESSAGES
-----------------------------------------------------------------------------------------------------
PROOFID
-----------------------------------------------------------------------------------------------------
         4 VALIDATE
{"proofId":"a42d25104d7bc3a2b631dcb45f24bc06a74aaa4ca094baad1b0be0d1ce7a7698:cev0qu2ep3oWwse2OHMyF"}
SUCCESS      12/AUG/21
["PASS: Validated all data hashes for a42d25104d7bc3a2b631dcb45f24bc06a74aaa4ca094baad1b0be0d1ce7a769
8:cev0qu2ep3oWwse2OHMyF","PASS: Proof validated with hash a42d25104d7bc3a2b631dcb45f24bc06a74aaa4ca09
4baad1b0be0d1ce7a7698 on https://rinkeby.etherscan.io/tx/0xaa2c347fb56b0e278ee8eee8eb68d007ca7d1ef55d
2512b0d888b7928e094861"]
a42d25104d7bc3a2b631dcb45f24bc06a74aaa4ca094baad1b0be0d1ce7a7698:cev0qu2ep3oWwse2OHMyF