Reporter Demo

Please post comments at Prowl-Users Group Discussion

Table of Contents


Prowl is a short-hand term for Publisher-Reporter Oriented Web Ledgers. Prowl is a collection of web ledger standards that covers the scope described in the table below. Although not covered by Prowl, transaction agreements and transactor notation are described to clearly delineate where the protocol applies. The online demo illustrates how technical details are hidden from the end-user through the use of capable devices and/or customized routines. Since record publication, verification and reporting could occur instantaneously using networked devices, Prowl may also be used as a payment confirmation protocol.

Prowl Scope

All currency activity in Prowl must be published according to the syntax in 1.1. The record may be published cleanly or with unrelated text in a blog post or web page. The Publisher must support either the standard "?prowl=get+" query-string or equivalent alternatives as described in 2.2. Record publication in Prowl is equivalent to a bookkeeping journal entry.
An inter-entity transaction or currency activity is considered completed in Prowl when copies of the same record are published at the domain(s) indicated in that record. This process resembles the double-entry standard in bookkeping systems, with the important difference that matching inflow/outflow entries are made by independent entities at separate domains. Verification may be requested as a reporter "observer" service using the see-query string in 2.3. When querying for the existence of a published record within a Publisher site, a reporter should use the get-query string or its equivalent as described in 2.2.
Once a record is verified, it is posted in an itemized report as described in 1.3. This process is equivalent to a ledger posting. Optional parameters may be prepended or appended to a record as explained in 1.2. Carryover of account balance form one period to the next is considered valid when the initial parameters in a new report matches the ending tally of the previous report.
Pending and completed reports are audited as described in 3.3. This process is equivalent to periodic account reconciliation, with the important feature that consistency checks within and between independent ledgers are performed, and that anyone with internet access can request and view the results of an on-demand web ledger audit. An audit may be requested from a reporter using the audit-query string as described in 2.3.
Pending and completed reports are evaluated as described in 3.4. This process is equivalent to periodic market performance reviews. A report evaluation may be requested from a reporter using the eval-query string as described in 2.3.


Transaction Agreement and Controls:
Prowl does NOT specify transaction prerequisites or transactor eligibility. It is agnostic to which parties could enter into transactions based on community affiliations, transaction limits, currency boundaries, etc. Prowl expects that independent accounting and administrative systems will control what is published within their respective domains. The advisability and basis for transaction agreements is not a core feature in Prowl, but should be specified and may be accomodated through accounting models as derived from payment systems and/or currency frameworks.
Namespaces and Registries:
Prowl does NOT have its own namespace convention or user registries for identifying and/or locating transactor accounts. Prowl simply locates published copies of a record through the internet domain name(s) indicated in it, which is considered valid as long as an active web page is reached through HTTP. The Prowl core is also agnostic to what the domain names represent. "Domain.ext", "subdomain.domain.ext", "domain.ext/directory", "sub.domain.ext/directory" and similar formats are all valid transactor notations for Prowl to locate records per 2.2.

1 Publishing Syntax, Structure and Semantics

This section specifies Publisher standards to ensure interoperability between different publisher platforms and the reporter applications that interpret and process published records and reports. Prowl uses keywords, the relative positions or sequence of terms within a record and very few symbols to guide parsing applications.

1.1 Published Records

There are five types of published Prowl records, not including the tally-record which is expected to be included only as part of completed reports. In Prowl, record publication is equivalent to a journal entry. It should be emphasized that the record date should be interpreted as any date that the affected Publisher(s) agree to report the record in, which may not necessarily be the transaction or posting date. The general syntax is:

  • date keyword1 ... keyword2 ... period_character
  • words are separated by a single space
  • The record is terminated with a period character immediately after the record units or record id when provided. The units or id must not include the period character for this reason.
  • Within a web page or blog post, a Prowl record is not required to be delimited by newline characters as long as the record is published intact in its complete form.
  • A published record may also be marked-up with tags as long as the stripped record is equivalent to the plain text format.

An accounting model or currency specification will specify which record types are recognized in audits, what parameters to track and what each record's impact should be to account balances, reconciliation procedures, tallied parameters and recommended evaluation metrics.

Flow: A flow-record indicates a transaction between two accounts or two currency brands. The flow-keywords are: from ... to.

Format: yyyy-mm-dd " from " originator.ext " to " recipient.ext amount units [#record_id] "."
mybrand Inflow: 2008-01-03 from buyer.com to mybrand.org 200.00 dollar #01029.
mybrand Outflow: 2008-01-03 from mybrand.org to seller.com 300.00 dollar.

Set: A set-record indicates the initialization of a parameter to a new value, such as when ending balances are carried over to the next period to start a new period report. The set-keywords are: set ... to.

Format: yyyy-mm-dd " set " brand_domain parameter[.subparameter] " to " value [units] [#record_id] "."
Example: 2008-01-01 set mybrand.com interestRate to 5.0 APR.
Example: 2008-01-01 set mybrand.com lastReport.SHA1 to 1a029476b37dffa4fd61ade3c84e9bec7068f379.

Add: An add-record indicates an increase to a parameter's current value. The add-keywords are: add ... to.

Format: yyyy-mm-dd " add " amount units " to " brand_domain parameter[. #record_id] "."
Example: 2008-01-01 add 1000.00 dollar to mybrand.com unusedBudget.

Cut: A cut-record indicates a decrease from a parameter's current value. The cut-keywords are: cut ... from.

Format: yyyy-mm-dd " cut " amount units " from " brand_domain parameter [#record_id] "."
Example: 2008-01-01 cut 100.00 dollar from mybrand.com unusedBudget.

Reverse: The accounting model should specify which records are allowed to be reversed.

Format: yyyy-mm-dd " reverse " mm-dd processed_record [#record_id] "."
Correct Example: 2008-01-02 reverse 01-01 from mybrand.org to seller.com 300.00 dollars.
Incorrect Example: 2008-01-02 reverse 2008-01-01 from mybrand.org to seller.com 300.00 dollars.

Note: The incorrect example contains two complete records - the original record inside the reversed record, so that the same published record might conceivably be used to verify two distinct records. The correct example, which indicates the original record but without the year, would not require a Reporter application to check for a preceding "reverse" keyword when performing a substring-in-a-published-string verification.

Tally: A tally record is not likely to be published independently and is expected be found only in completed reports. A collection of tallies indicates the cumulative currency activity for a given year or year-month period; or if a year-month-day is specified, then the tally is calculated from the beginning of a report period to that date. The brand_domain is not needed as tallies are calculated from data within the report.

Format: yyyy[-mm[-dd]] " tally " param[.subparameter] calculated_value units "."
Example 1: 2008-12-31 tally netBalance -100.00 dollar.
Example 2: 2008-12-31 tally unusedBudget.revenueBal 100.00 dollar.

Published Record Syntax Guidelines:

The record syntax was based on the following guidelines, listed in the order of higher to lower priority:

  • Record Applicability - The record syntax should contain information to clearly indicate which entities are responsible for publishing the record and which reports it should be included in. For example, the record "2008-01-01 from brand1.org to brand2.com 100.00 dollar #01." would be considered valid for processing only when independently published in brand1 and brand2's respective domains, and the same record would be considered valid for inclusion in report periods that include the date 2008-01-01.
  • Record Completeness - The record syntax should facilitate the cross-verification of published copies of the same record between two entities. In order to simplify the expectations from this requirement, copies of the same record must be published in the same exact form by the corresponding entities. For example, brand1 should NOT truncate "2008-01-01 from brand1.org to brand2.com 100.00 dollars #01." to the published copy of "2008-01-01 to brand2.com 100.00 dollar #01."
  • Record Readability - As much as possible, the record should avoid the use of special symbols.
  • Record Writability - The record should not be difficult to enter using text-entry systems such as those found in mobile devices for SMS-type applications. Wherever possible, automated pre-filled forms should be presented to the user.

1.2 Posted Records

Records are verified using a substring-in-a-published-string approach. Once a published record copy has been verified and is ready to be posted, additional parameters may be prepended and/or appended to the record in order to assist auditor and evaluator service applications.

Notary Parameter: If a reporter independently maintains a copy of an entity's currency activity and active reports, the reporter should be appended to the record as a notary parameter value. If there are more than one notary that witnessed a published transaction, the notary values must be comma-separated.

Format: record " [" notary1.ext[,notary2.ext] "] "
Example: 2008-11-07 from food2go.com to myuniversity.edu 100.00 hours #abc123. [acctfirm.com]
Example: 2008-11-07 from business.com to sfcity.gov 100.00 hours #abc123. [reporterA.org,reporterB.org]

Posting Time: The current Unix Time at the instance of posting a record may be prepended on the line before the posted record. The Unix Time is indicated by a colon at the beginning of the line. This parameter is likely to be used for generating charts in evaluator routines.

Format: [:Unix_Time]
record [notary]
Example: :1230530817
2008-12-28 from food2go.com to myuniversity.edu 100.00 hours #abc123. [acctfirm.com]

1.3 Report Structure

A sequence of verified, posted records in plain text comprises an itemized report for a given accounting period. Within a report, a Prowl record must be delimited by newline-characters. A Prowl Reporter will be expected to accommodate generally accepted new line characters, such as "\n", "<p>", "<br>", and to ignore unrelated texts when parsing a published record or report. Posted records must not have HTML markups.

Note that reporter applications should offer a service for generating a report file in the above format, so the user would not need to write up the report itself but would simply need to understand it. The reporter demo supports audits and evaluations of plain text reports (.txt).

General Structure Example

Prowl/version number
Accounting Model: model_name
mybrand.ext period accounting_units report: status //period is either yyyy, yyyy-QQ, yyyy-mm

//Initialize information for new period; in this example, the netBalance is a tracked parameter
yyyy-mm-dd set lastReport.period to 2007.
yyyy-mm-dd set lastReport.SHA1 to 0123456789abcdef0123456789abcdef01234567.
yyyy-mm-dd set lastReport.filesize to 1234 byte.
yyyy-mm-dd set netBalance to 0.00 unit.

//Currency Activity Examples
yyyy-mm-dd from mybrand.ext to seller.com 100.00 unit. [reporterA.org]
yyyy-mm-dd from buyer.com to mybrand.ext 50.00 unit. [reporterA.org]

//Tallies at the end of the report period;
yyyy-12-31 tally inflow 50.00 unit.
yyyy-12-31 tally outflow 100.00 unit.
yyyy-12-31 tally netBalance -50.00 unit.

//Auditors are declared to validate the report
yyyy-12-31 set mybrand.ext auditor1 to reporterA.org.
yyyy-12-31 set mybrand.ext auditor2 to reporterB.org.


1.4 Prowl Dictionary

While Prowl is designed to support different accounting models, there must not be any collision or ambiguity in how a term is used, if and when a model uses that term. For example, the netBalance in a CC or LETS accounting model must have the same meaning and calculation formula as a netBalance in the ocaup model. The question is whether or not to use a parameter in an accounting model, and whether a definition is suitable or if a new term should instead be added to the dictionary to avoid ambiguity in interpretation.

The following are example parameters and definitions, some of which are used in the demo:

certificate.issuer When an entity is starting its very first Prowl report, this parameter may be set instead of the lastReport. Not yet implemented in the demo, as this parameter requires a link to an optional registry service and a yet-to-be developed standard for querying such service.
certificate.SHA1 See explanation for certificate.issuer
headCount: The number of unique members in an entity
headCount = set - .adds + .cuts
interest.rate: A parameter that might be required in certain accounting models. Not implemented in the demo.
interest.type: A parameter that might be required in certain accounting models. Values might include simple, compound, adjustable, etc. Not implemented in the demo.
lastReport.filesize: See explanation for lastReport.period
lastReport.period When carrying values from one accounting period to the next, the sha1 digest and file size of the source file is used to verify that its contents has not been modified from the audited form. The verified contents are then used to check for the accuracy of carried-over values. A period is formatted as yyyy, yyyy-QQ or yyyy-mm.
lastReport.SHA1: See explanation for lastReport.period
netBalance: The difference in inflow minus outflow
netBalance = set - outflow + inflow
netBalance.negLimit: An accounting model may prescribe a negative limit on the accrued net balance amount.
netBalance.posLimit: An accounting model may prescribe a positive limit on the accrued net balance amount.
reporter.units An entity may use an independent reporter site or simply declare itself to witness its transactions with other entities that are published in the indicated accounting units. This declaration indicates which site to notify for completing a pending transaction and will be appended as a notary field to a posted record. The current reporter is also expected to support standard Prowl query strings for retrieving an entity's records and reports.
unusedBudget: A short-hand term that is used when adding or cutting the same amount on both unused revenue and expense budgets.
unusedBudget.expenseBal: The amount of expense budget that has not been spent
unusedBudget.expenseBal = set + .adds - .cuts - outflow
unusedBudget.revenueBal: The amount of revenue budget that has not been met
unusedBudget.revenueBal = set + .adds - .cuts - inflow

Evaluation Metrics:

Percent Recovery = inflow /unusedBudget.revenueBal

Flow Ratio = inflow/outflow

Units Issued Per Member Per Week = unusedBudget.adds/(headCount*52)

2 Search-Assist and Query Strings

Prowl queries are formatted as a single-parameter HTTP GET or POST query strings. Like the record syntax, queries rely heavily on the use of keywords and the sequence of terms in a string to indicate semantics. This approach avoids explicit breakdown of submitted values into separate parameters and expects a service provider to have an effective parsing routine similar to those used in processing reports.

2.1 Search-Assist Declaration String

In order to facilitate interoperability between web publishing platforms and reporter applications, a publisher must declare a search-assist string that is always visible within the home page source code. A search-assist indicates how or where a reporter should look for records that are not visible from the home page and any reporter that needs to be notified when completing transactions. The search-assist may indicate an internal search convention that could return any matching records, or it may indicate a text file where a user logs previously submitted transaction records, or anything similar that either has the record cleanly by itself or published with other text. By using resources that already exists within a site, Prowl avoids the need for middleware or knowledge of exact physical URL links for locating a published record.

A search-assist string is published in the following form:

http://mybrand.com/search_assist "set+" mybrand.com "+reporter." units "+to+" myreporter.org[%2F][path]
Standard Format per 2.3:
Blogger Example:
Wordpress Example:
Simple Path to File Example:
Directory or Category-Based Example:

The URL portion before the "set+mybrand.com+reporter.hour+to+" should be used when attempting to locate a record; the tailend portion, "myreporter.org%F", should be used when querying a reporter for reports or witnessed records. If an entity is self-reporting, then "myreporter.org" should be set to the entity's domain name.

To minimize its profile, the search-assist string may be hidden inside a listed link within a gadget or widget feature. Alternatively, it may be included in a meta or hidden input tag for sites that can be customized. Although the search convention may be inferred based on the meta "generator" tag within the HTML head section, a published search-assist declaration string is a simpler and more definite indicator of a site's search capabilities and any reporter that needs to be notified when completing transactions.

2.2 Publisher Query Strings

Once a publisher has declared a search-assist string as described above in 2.1, it should ensure that the contents returned using the search-assist string is up-to-date. Most blogs should satisfy this requirement when records are published as part of blog posts, in which case the home page would display recently submitted records. Accounting systems with customizable output should also be relatively easy to program to log prowl-format records onto a simple file that is web accessible. Relatively simple applications could also be developed to return records cleanly over HTTP. With the preceding options just described, a publisher is free to process or ignore the standard prowl get-string.

Standard Get-Query String: Servers that do not support the standard get-query string should ignore it. The get-string format is:

Standard Format: "?prowl=get+" record

Alternate Get-Query String: In order to accomodate publisher platforms that do not support the "?prowl=get" standard, a reporter should use the search conventions that are declared through a search-assist string as described in 2.1.

Blogger get-string alternative:
Wordpress get-string alternative:
NOTE: A blog's search results might include the original query string and could lead to a false verification. For this reason, a record must be truncated, such as by omitting the date, when it is used in a query.
File-based get-string alternative:

2.3 Reporter Query Strings

There are four Reporter query strings. The general syntax is:

  • http://reporter.ext/?prowl=query_keyword ...
  • the query string is URL encoded where necessary (e.g., whitespace => +)

See: When a query keyword is not specified in a standard string, the default is for a reporter to verify that a copy or copies of the submitted record have been published at the domain(s) indicated in a record. A see-query string acts as a trigger for a reporter to pull web pages or records from other sites, if the reporter does not already have matching journal or ledger entries. Once a record is verified as published within the visited domain(s), it should be posted in the appropriate ledgers. More details on reporter observer service are provided in 3.2.

Format: "?prowl=" URL_encoded_record
Example: ?prowl=2008-01-02+from+mybrand.org+to+seller.com+300.00+dollars.
Response: Response codes have not been assigned. Additional response parameters to be developed - feel free to make suggestions.
"Both originator.ext and recipient.ext have not published the record yet."
"Originator.ext has not published the record yet."
"Recipient.ext has not published the record yet." //reporter does not maintain corresponding report(s)
"Record posted." //reporter maintains the corresponding report(s)

Get: The get query string is used to retrieve a specific record, any wildcard-matching record(s), a report or a calculated parameter value from within a reporter site. This is in contrast with the see-query which triggers a reporter service to pull record copies from other sites. The get-string is not the default query since it restricts a reporter search to within its own records, whereas users will generally be more interested in verifying whether a record has been published or not on the web. In other words, transactor domain copies should be more up-to-date than reporter copies, so the see-string behavior should return more up-to-date results.

The wildcard character "~" tilde should be inserted anywhere in the record string to indicate a search for any and all matching records.

Format: "?prowl=get+" record/~record/yyyy[-QQ/mm] "+" units "+" report/parameter_value
Example: ?prowl=get+2008-01-02+from+mybrand.org+to+seller.com+300.00+dollar.
Example: ?prowl=get+2008-01-~+to+ngo.org~
Example: ?prowl=get+mybrand.org+2008-Q3+dollar+report
Example: ?prowl=get+mybrand.org+unusedBudget
Response: Response codes have not been assigned. Additional response parameters to be developed - feel free to make suggestions.
Any and all matching record should be returned. Applicable verification time should be prepended on a separate line before a record. Because of the substring-in-a-published-string verification approach, care should be taken to prevent false confirmations.
Reports should be returned as plain text in its entirety and without any additionas or modifications.

Audit: A reporter may provide audits of completed or pending reports as described in 3.3.

Format: "?prowl=audit+"brand.ext "+" units "+report+" [ for+yyyy[-QQ/-mm] / period+between+yyyy-mm-dd "+and+" yyyy-mm-dd]
Alternate: "?prowl=audit+" URL
Example: ?prowl=audit+mybrand.org+dollar+report+for+2008-01
Example: ?prowl=audit+mybrand.org+dollar+period+between+2008-01-01+and+2008-03-15
Response: Response codes have not been assigned. Additional response parameters to be developed - feel free to make suggestions.
The demo is currently limited to web-browser oriented response formats.
Once defined, standard response format options should be appended to the audit-query string.

Evaluate: A reporter may provide evaluations of completed or pending reports as described in 3.4.

Format: "?prowl=eval+" brand.ext "+" units "+report+" [ for+yyyy[-QQ/-mm] / period+between+yyyy-mm-dd "+and+" yyyy-mm-dd]
Alternate: "?prowl=eval+" URL
Example: ?prowl=eval+mybrand.org+dollar+report+for+2008-01
Example: ?prowl=eval+mybrand.org+dollar+period+between+2008-01-01+and+2008-03-15
Response: Response codes have not been assigned. Additional response parameters to be developed - feel free to make suggestions.
The demo is currently limited to web-browser oriented response formats.
Once defined, standard response format options should be appended to the eval-query string.

3 Reporter Services

Prowl was designed to take advantage of free blog hosting platforms, such as Blogger and Wordpress.com, to minimize the need for custom accounting and publishing solutions early in the currency development cycle. Essentially, a user or organization would simply establish and use a site or blog to publish accurate transaction record copies, and an offsite Reporter would do the rest for serving client requests: performing on-demand balance calculations, generating itemized reports and auditing data for reconcilability and validity.

The following are examples of services that a user may expect from a Reporter application. The list is not meant to be exhaustive, but is given as a guide for independent development of Reporter features. Specific functionalities and capabilities should be programmed into a Reporter application as the need arises.

3.1 Optional Registration with a Reporter

In order to take full advantage of offsite services, a Publisher should register with a Reporter in order to have independently verified and maintained copies of its records and reports. Even if an entity's web site could provide the services that are typically expected from a Reporter, the presence of an independent auditor should help an entity establish its reputation. There might even be compelling reasons to use the Reporter's copy of published records, such as when the Reporter is more reputable or when query-response performance is a concern.

An entity declares a new or replacement reporter by using a set-record, such as:

2008-01-01 set tyaga.org reporter.units to reporterA.org.

In addition to the preceding set-record, it is recommended that a search-assist string be declared per 2.3. An entity must not have more than one reporter for each accounting unit that it uses. When an entity changes to a new reporter, current and archived reports must be transferred to the new reporter.

3.2 Observer or Notary Service

The Reporter acts as an observer mainly by:

  1. Verifying that a copy of the same record string is found in the published contents of corresponding URL links, and
  2. Creating and maintaining an independent copy of a currency or entity record once the record has been cross-verified. This service helps minimize potential concerns from mismanaged records. For example, if a previously published but missing (Error 404) or tampered record is discovered when following a link from site_1 to site_2, the Reporter would be able to provide a witnessed copy to back-up the accuracy of site_1's record copy. The Reporter could also observe and provide additional information to a real-time, near simultaneous publication of a transaction, thereby facilitating the completion of a transaction between two unacquainted parties. This service would likely require a publisher to subscribe to a Reporter site.

To improve user experience, record publication should automatically trigger a see-query for a reporter to verify and post records in real time. For example, Blogger's mail-to-blog and sendBlog features offer a simple way for triggering a reporter to visit the publisher domains and verify the existence of matching record copies. If only one flow-record copy is published, a reporter should notify the appropriate publisher or reporter, also through a see-query, to help complete a pending transaction. A sequence of notification pathways are illustrated here.

A Reporter is not expected to maintain a market listing service, although the observer service could present newsfeeds of member's product announcements.

3.3 Auditor Service

The Reporter audits and validates the published itemized report of an entity by independently:

  1. Reconciling tally amounts against published amounts, including verifying the carried over values from an audited copy of the last reporting period
  2. Checking the existence of corresponding record copies as maintained by the reporter indicated in the notary parameter
  3. Verifying the identity and existence of members and entities that are referenced by a published record

In essence, the Reporter screens the data in an itemized report for further evaluation. Otherwise, unvalidated data might yield misleading evaluation results (junk in = junk out). It might be useful to think of the auditor functions listed above as Level 0 (simple balance check), Level 1 (with notary check), Level 2 (check original publisher sites also), Level 3 (check for complaints re: unreported or missing records), etc.

In order to calculate balance and tally amounts, the Reporter must understand the particular accounting model that was followed in preparing an itemized report. For example, in the ocaup accounting model, a currency brand's unused revenue and expense budgets are tracked and independently managed by a market entity. In a CC or LETS system, an account's net balance will be tracked instead, calculated as the difference between the inflow and outflow in a period, and compare it to a static negative net balance limit.

3.4 Evaluator Service

The Reporter evaluates the market performance of a currency brand or account as calculated from the validated data in its itemized report. There are three general types of evaluation metrics:

  1. Market Demand: An example metric in an ICB system would be the calculated percent recovery, which is the inflow over the currency units issued in a given period. In a CC or LETS system, market demand might be indicated simply as total inflow to an account.
  2. Self-Regulation: An example metric in an ICB framework would be the ratio between inflow and outflow as it fluctuates in a period. In a CC or LETS system, self-regulation might be indicated by how close an account is to zero net balance over time.
  3. Fairness: An example metric might be how much limit was issued per person over a given period compared to other entities or accounts.

4 Record Retention

It is expected that reports and the record copies in it will have the longest retention period. Original physical copies, published copies and notary copies should be purged as soon as applicable refutation periods have expired.