Improved Invoice Submission Process and Protocol

[allancto]

Benefit to RChain

Currently in our bounty system invoices are required but are time consuming to prepare and error prone. We propose a process and protocol with similar security properties, better accuracy and reliability than manual preparation, and improved ease of use.

Budget and Objective

What is the purpose of an invoice? It’s fundamentally a simple agreement between the Contributor and our Cooperative acknowledging the correctness of certain data and that completion of payment completes the voted rewards process. Since all of the data that goes into an invoice is known already in the rewardsApp and ram_registry, it makes sense that we should use our technology to assemble the data to the contributor, and have a simple action such as “Confirm/Dispute” finalize the invoice.

The proposed system relies on a simple 3 step protocol between Contributor and InvoiceApp.

1. InvoiceApp offers to Contributor partially invoice including all invoice_data but not signed.
2. Contributor agrees (or disagrees) and indicates that by “signing”, which will be represented by a field “signed_by_contributor”
3. InvoiceApp reports to Contributor that the invoice has been paid, by including a transactionId, and notifies Contributor.

The detailed implementation of this protocol are described below. In fact we propose two implementations, the one discussed here (meant to be implemented immediately) and another to follow, a rholang based upgrade which we plan to release at the same time as Mercury. Blockchain implementation will require both stable mainnet AND signing key, aka Self Sovereign ID or Cooperative voting ID or rchain wallet.

For the current implementation we will continue to rely on email authentication. Step 1 will implemented as an email message containing a private link to the InvoiceApp which is private to the Contributor and specific to the pay_period. Step 2 will be implemented as a click (agree/disagree) on the secure link to InvoiceApp. Step 3 will be implemented by email.

For full details see updated Usage and Code Overview or the original InvoiceApp Specification

source: https://github.com/whereyouatwimm/rchain-invoice

Estimated Budget of Task: $[11,400] 92 story points
September management of system and design improvements: 34 story points ($5100)
Notes: goal is an InvoiceApp WORKING PROTOTYPE which may be used fop September invoices by any Contributor who does not want to use the current manual system.
Estimated Timeline Required to Complete the Task: [23 days Working Prototype]
How will we measure completion? [Tested by team, Available for trial in Sep Voting, Agreed to by Finance]

Team:
@kovmargo, @golovach-ivan, @azazime , @allancto, @help_wanted

Legal

Task Submitter shall not submit Tasks that will involve RHOC being transacted in any manner that (i) jeopardizes RHOC’s status as a software access token or other relevant and applicable description of the RHOC as an “asset”—not a security— or (2) violates, in any manner, applicable U.S. Securities laws.

[allancto]

@jimscarver suggested the possibility of using discord oauth. That could either replace "private link" in email, or be required in addition, or allow Contributor to access InvoiceApp directly without private link. I have no objection to any of these if for instance CoLab wants to implement, with the caveat that fewer features seems better at least for the first iteration. Similar thinking about integrating InvoiceApp with RewardsApp, that could be considered but imo would likely both apps more complex.

[tucsonblockchain]

i support this initiative

[allancto]

@Ojimadu will help with preparing documentation for Finance explaining why the proposed system should still qualify as an invoicing system from a financial accounting perspective. (@BelovedAquila you're studying law, @owans you're in finance, let @Ojimadu or me know if you may be able to help as well)

[ghost]

Some more discussion on issues #904, #910 and #912: https://rchaincommunity.xyz/t/principle-of-the-matter-and-common-law/350/9

[allancto]

@ICA3DaR5, @tucsonblockchain , thanks for the article and the discussion! Awesome use of the community forum :)

[allancto]

@dckc I'm hoping you'll participate at a minimum in code reviews and a security audit of the code and the overall process.

Thanks in advance!
-@allancto

[owans]

@allancto I'm available to help in whatever way possible.

[dckc]

OK; when there's code to review, let me know.

I read/skimmed the InvoiceApp Specification. The two biggest risks I see are:

• spending a whole bunch of time / effort / money and not getting anybody paid much sooner
• managing sensitive data such as postal addresses and and ETH addresses

Time Saving Expectations

I'm having trouble spotting where the big time saver is. This spec still includes the most labor-intensive parts of the process that I'm aware of... the parts where contributors are waiting with no visibility into the process:

• Finance double checks that the invoice hasn’t been tampered with or being submitted twice ...
• Finance transfers rhoc and manually records TransactionID in spreadsheet

This estimate is coherent... who knows if it's accurate; it's a reasonable guess; time will tell...

15 minutes * 60 invoices- 15 hours of time translating to $1000 a month. Thus we expect this project to amortize itself over 10 months.

... but is it consistent with expectations set in #910 and such? This system doesn't seem designed to get invoices paid multiple calendar-days sooner than the existing system.

The RHOC to REV conversion is scheduled for less than 10 months from now, at which point any number of details may need to change. For example, I hope that REV transactions will have transaction IDs, but that isn't in any of the plans or specs or code that I have seen so far.

Managing sensitive data

Note that rewards.rchain.coop handles no sensitive data.

In particular, #548 invoice support in rewards.rchain.coop is closed wontfix, based on conversation around March 29:

In that case we don't have to ask for the public ETH address. That would be only in the spreadsheet. I think it's not a good idea to connect real names to public ETH addresses.

It's not explicit in the InvoiceApp spec that it's on a totally separate host, but that's my strong preference.

Using Google Apps Script seems like the shortest path to the target that I can see.

[allancto]

@dckc thanks for your feedback in this.

• Yes: "InvoiceApp on a totally separate host", thanks for pointing this out
• Yes: "Google sheets api seems shortest path to the target". Current plan is to generate pdf using existing template (@lapin7) at the core. Also file management since that's what we currently run on.
• Partially: "not designed to get invoices paid multiple calendar-days sooner". There are two bottlenecks in the system,
  • ours
    • submission by Contributors and admin in the system currently experiences delays because some contributors find the template difficult to use (or delete it or whatever)
    • errors are frequent
    • review is time consuming
    • errors we make propagate and slow processing by Finance
  • processing by Finance
    • takes place in batches, along with other payments Cooperative must make
    • requires individual review and multisig
    • the way to address this would be to eliminate invoices altogether and replace by rholang smart contracts
      • cannot happen until platform is stable and proper auth/id
      • can be considered in the Mercury time frame (@golovach-ivan)

Updates made in spec working doc (recently created and linked to in the draft spec, thanks @kovmargo and @azazime)
https://docs.google.com/document/d/1e4uMmCsElk7IcvDo-MygzX9j3c1gPB_eAav_MpOoyO0/

Thanks! -@allancto

[BelovedAquila]

@Allanto I am also willing to help in ways possible. On going through the doc on this,here

Some of the details will depend on whether we choose to use database technology or simple flat files

I think using database technology would be more effective , organized and data managing than the simple flat files which tends not to be relational and is limited as regards the amount of files(or let's say tables)it can contain i.e its single directory functioning system ,unlike the database technology . although the simple flat file system is a simple way to store files,but i think if we are to be using the system ,it would become increasingly inefficient as more data is added.

[dckc]

@David405 writes on behalf of @allancto:

Plan to run in parallel with existing system (Aug pay_period)

Care to elaborate? Be sure to keep this issue up to date.

[allancto]

@ALL, i am attaching the DVG for this issue here. The fact is that I'd hoped to be able to also attach a working demo, but we ran into a couple of significant issues and I delayed in order to shorten the explanation process and focus on the work. I do hope to add more direct visibility into the work product this evening, which I'll also attach in the DVG for #912.

We do still believe we'll be able to release this product in time to provide an alternative for August invoices. We've made some nuanced but important improvements in terms of better privacy for contributors. We've implemented triple checking of eth_address. We have modularized and further simplified for security audit the portion of the process that will operate unattended on a secure server. We've been in contact with @Kateag010 who is pleased from the Treasury perspective with certain aspects and I hope she'll be able to give her approval on behalf of Finance for adoption of the improved system. But the primary beneficiaries of the new system will be you, contributors and Trustmetric voters, I hope you will find the new system saves you time and protects your privacy.

As I indicated in the DVG, @whereyouatwimm is the hero of this project, I hope you support him and the whole team in your voting.

Thanks! -@allancto

[whereyouatwimm]

Hi all,

My names Scott, I go by wimm. I've been spearheading a lot of the development on this issue. My goal has been to create a better process surrounding invoicing, both for contributors and finance. I've built a small web app in nodejs for users to verify their invoices before getting paid, and a series of google scripts to handle the data necessary for exporting invoices to a PDF for each user.

The web app should assist contributors in confirming the coops records are in line with what the user expects to be paid (in USD) before transactions are processed by finance, and automate a lot of tasks for finances side, in regards to the previous process of handling invoices and paying contributors out.

I hope it will help ease a lot of these issues, and look forward to helping ease the process of handling contributor bounty rewards.

If anyone wants to test the current system we have and provide feedback, please hit me up on discord. Username is wimm.

attached is a copy of an exported sample invoice, in pdf form.

-wimm.

sample-invoice.pdf

[dckc]

A nodejs app? Where will that run? What's the plan for security review and deployment? I thought the code would be shared here as it was developed. Though I also thought the system would stay inside google apps script.

…

On Fri, Sep 7, 2018, 1:41 AM wimm. ***@***.***> wrote: Hi all, My names Scott, I go by wimm. I've been spearheading a lot of the development on this issue. My goal has been to create a better process surrounding invoicing, both for contributors and finance. I've built a small web app in nodejs for users to verify their invoices before getting paid, and a series of google scripts to handle the data necessary for exporting invoices to a PDF for each user. The web app should assist contributors in confirming the coops records are in line with what the user expects to be paid (in USD) before transactions are processed by finance, and automate a lot of tasks for finances side, in regards to the previous process of handling invoices and paying contributors out. I hope it will help ease a lot of these issues, and look forward to helping ease the process of handling contributor bounty rewards. If anyone wants to test the current system we have and provide feedback, please hit me up on discord. Username is wimm. attached is a copy of an exported sample invoice, in pdf form. - wimm. invoice-sample.pdf <https://github.com/rchain/bounties/files/2359828/invoice-sample.pdf> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#912 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAJNyhLWmKuaKjafb1zB4g6yPZHLZYI2ks5uYhULgaJpZM4WCtxK> .

[allancto]

@BelovedAquila i just wanted to let you know that i didn't miss your database question. We wanted to keep the code as simple as possible to read and also have as little data on the continuously running server as possible. Your suggestion will be very appropriate in other cases.

Thanks! -@allanc

[dckc]

The documentation for invoicing, linked from https://github.com/rchain/bounties/blob/master/CONTRIBUTING.md , is https://github.com/rchain/bounties/wiki/Creating-an-Invoice . Please keep it up to date as things evolve.

[dckc]

@allancto writes Aug 20:

@dckc I'm hoping you'll participate at a minimum in code reviews and a security audit of the code and the overall process.

Is that still the case, @allancto ? @whereyouatwimm ? If so, please respond to my Sep 8 comment above.

@whereyouatwimm pointed me to https://github.com/whereyouatwimm/rchain-invoice . I started to take a quick look, but before I dive into a full code review, please confirm that you don't have other plans for security review.

[allancto]

@dckc, plans are still the same. We do still plan to have a full code review documentation and security audit, just that's not complete yet. Thanks.

For context, the code you are looking at is to sit on a dedicated server run by colab. It should contain no private data. The input is one csv file which allows for confirming eth address and amount and signing, the output is the same file updated with signing information. Producing the input is done in a separate environment by RamAdmin and uses .gs (google scripts) as you anticipated. Merging the output for processing by Finance is also done in the RamAdmin environment.

[dckc]

@dckc, plans are still the same. We do still plan to have a full code review documentation and security audit, just that's not complete yet.

Got it.

For context, the code you are looking at is to sit on a dedicated server run by colab. It should contain no private data.

Good, but...

The input is one csv file which allows for confirming eth address and amount and signing, the output is the same file updated with signing information.

Isn't eth address sensitive / private? I suppose if it's not connected to a name and postal address, it's no more information than goes on the public blockchain eventually anyway. But please do confirm that you're saying that eth address is not private or otherwise clarify.

[allancto]

The server gets to contain only a hash of the eth address, and is compared for the protection of the contributor. That in fact was the source of our serious bug (used text representation of eth address without tolower() before hash, ouch).

[dckc]

I'm supporting this work with a vote of $2K for design / development this month and adding $3K for the related work of invoice processing.

We all know @allancto stepped in for @lapin7 to process invoices early this summer. While @lapin7 was compensated for that work, @allancto hadn't arrange for that. I think that's worth fixing, at least for the 201809 pay period. I learned from @kennyrowe that the coop does have a budget for operating the bounty system, and this seems in line with that budget.

@allancto and I also discussed the $11K that was rewarded in 201808. He tweaked the InvoiceApp Usage and Code Overview doc to be more explicit about what it's for:

Story Points

Design data handling: 13 story points
Create invoice_summaries from pasted data: 8 story points
Write invoices as pdf: 21 story points (including gsheets workaround)
Email notification: 8 story points
Design UI for signing: 21 story points
Create “purple sheet”: 13 story points (data goes to e-signServer and comes back signed)
Create spreadsheet invoices_summary for Finance use 5 story points
Explain and Interface with Finance: 3 story points

[kitblake]

I followed @dckc's lead and voted. The issue is provisioned.

[dckc]

Code Review

@allancto wrote Sep 24:

We do still plan to have a full code review documentation and security audit, just that's not complete yet.

Today @whereyouatwimm tells me:

feel free to review it whenever, i've no major changes planned as of right now

So I'm assigning myself.

About the Google Apps Script code... @whereyouatwimm says he doesn't have rights to grant me access. So I guess I need you to do that, @allancto .

Redundancy in administration

@allancto , I gather you asked @whereyouatwimm to make an account for me; he asked me for an ssh public key. I'm not interested in administering the service.

But it really should have redundancy in the administrator role.

Critical path to completion

I see what @Ojimadu and @allancto are expected to do.

Are @golovach-ivan, @azazime azazime, and @kovmargo still in the critical path? Has "Tested by team" happened? Is there something else they are expected to do?

[allancto]

@dckc yes, ready for review at any time. Tested by team yes happened. @Ojimadu and @azazime helped with our approach to Finance and that worked fine. @golovach-ivan and @kovmargo helped with the early design, those documents are still around but in fact we kept simplifying as we went. @dckc you're now sudo on the e-sign server, meaning you shouldn't have to do anything at all except for give rw access if @whereyouatwimm is unavailable. For anyone else interested in the e-sign implementation please look at the e-sign repo.

For the invoice generation and admin side (gscripts), @dckc you now have access. For implementation questions that's largely @whereyouatwimm and design questions mostly me. @whereyouatwimm can fill you in as to where the skeletons are (nasty issues from gsuite throttling, and a persistent off by 1 error in invoice generation). Other than that the key on the admin side just seems to be to take on as much responsibility as possible in order to reduce external dependencies. Also the Contributor Dashboard will make it easier for Contributors to self register, and on the processing side will enable us to better classify status and error codes and reduce the number of errors from bad data or unexpected state. It's my hope over time that every member will become a Contributor, and our systems will be simple to use and in position to handle as many members as we have making inspired contributions.

[dckc]

I'm still not clear whether @golovach-ivan, @azazime azazime, and @kovmargo are still in the critical path. It looks like you're saying no, their part is done; it would be clearer, to me, if you un-assigned them.

[allancto]

@dckc no one left on critical path except for you (code review) @whereyouatwimm and me, changing assignments to reflect that. Also consider closing this issue unless you see anything missing for now, will re-open if future changes are required.