Skip to content

Latest commit

 

History

History
337 lines (173 loc) · 15.2 KB

README.md

File metadata and controls

337 lines (173 loc) · 15.2 KB
Raw

Lucchetto :: an Armadietto (Node.js) RemoteStorage Compatible Server w/IAPs CircleCI

This repository contains resources relating to use of the Armadietto (Node.js) RemoteStorage compatible server extended with pay2my.app for ledger-based authorizations and in-app purchases (IAPs) — hereby known as the Lucchetto extended Armadietto.

New to RemoteStorage? Please go through this how-to tutorial guide.

A RemoteStorage veteran that wants to leverage IAPs in your apps? Rest assured your current app will work just fine with any Lucchetto extended RS server. To leverage the Luchetto value-add check out the last section of the how-to tutorial guide or the "Getting Started" example (the ./index.html in this repo).

Have a moment? Check out this video of both examples.

Introduction / About

A RemoteStorage Provider for any RemoteStorage App

The Luchetto extended server itself is a regular RemoteStorage server but with a modified oauth login flow — modified to use ledger-based authorizations.

It provides:

  • social login
  • Ethereum wallet login
  • regular passphrase login

This new flow is streamlined for your apps' users.

This new flow enables a proliferation of RemoteStorage providers: no custom code needed to charge for the service of providing RemoteStorage storage to the world. All of the bits to enable this are in FOSS communities' hands:

With all this in mind, consider yourself — the RS enabled app developer — and your users:

Also consider the third persona — the RS storage provider (perhaps also you) — that hosts storage for your users as a Lucchetto enabled cluster and is remunerated for it.

Lucchetto Client Library For In-App Purchases

As an existing RS app developer there is nothing more for you to do to support users that come to your app with storage from a Lucchetto enabled server. You can keep your current apps unchanged.

However, you could easily add in-app purchases and make some money off of upsells ("appsells"?), by extending your application with lucchetto.js and onboarding a couple SKUs into your own Lucchetto storage.

You will continue to support all users coming to your apps with regular RS storage — not from a Lucchetto enabled RS server — and even offer them the same in-app purchases. However, users who log into your app with Luchetto RS storage will simply have a smoother experience (fewer prompts).

The integration sequence — combined with the previous sequence above — would become:

Don't fret if the above looks overwhelming, just skip over to the example code starting in the next section.

The main take away should be that lucchetto.js (red box) leverages special handling of the GET pay2myapp endpoint in a Lucchetto extended server — to enable IAPs in end-user apps (also red box):

  • offer paid features to your users
  • paid features download your own defined content from the pay2my.app scope

Again, there is quite a bit to unwind in the above diagram.

But don't worry about any of it unless you're familiar with Lucchetto already.

For now know, that as you read the sections below, you can refer to the above model to make sense of what you're reading.

Quick Links

Getting Started — Writing an App with In-App Purchases

The steps for writing your own app are as per https://remotestorage.io. After all, you're writing a RemoteStorage app.

There are some additional steps needed to have your app leverage Lucchetto for in-app purchases. The main steps are outlined below.

All of this is also covered, step by step, in our how-to tutorial guide.

Onboard to US Dollars Ledger — as the Dev Receiving $

The payments integration for IAPs uses Ledger-Based Authorizations as per https://pay2my.app.

Dollars payments are verified against a receipts ledger where the receipts are actually made out to your (the developer's) public Ethereum address: an Ethereum address is used for all currencies in this setup.

As such we must tell the US dollars ledger what public Ethereum address to associate with your (the developer's) https://stripe.com account — all value transfers via credit cards occurs through https://stripe.com. If you don't have a Stripe.com account, the ledger onboarding process will guide you to create one.

⚠ You do not need an actual Stripe.com account when testing with fake money and testnets. You can play around with all of this and develop your application without onboarding to Stripe.com.

When onboarding your Ethereum address to the testnet simply skip the Stripe.com account setup:

If you connect your in-browser Ethereum web3.js enabled wallet to the onboarding page, you'll be able to use your wallet's address for the onboarding.

⚠ Connecting your in-browser Ethereum web3.js enabled wallet to the dollars onboarding page is by far the preferred way to go.

If you do not have an public Ethereum address yet, the onboarding process will guide you to generate one. Make sure to note down the generated public address and private secret key.

To onboard:

Take note of your onboarded Ethereum address.

Onboard to Ethereum Ledger — as the Dev Receiving eth

Cryptos do not need onboarding — you do not need to register as a payee with any entity (i.e. Stripe) like you do for dollars processing (which is also simple enough).

To start using Ethereum simply get an Ethereum wallet such as MetaMask and generate the public Ethereum address you want to use.

Add SKUs

Consider the upsells (app-sells?) you'll want in your application.

For each such in-app purchase item — a SKU — you'll need to upload a piece of data to your Lucchetto extended RS server (e.g. https://rs.overhide.io).

Use the SKU setup RS app to do this.

For production make sure to use @rs.overhide.io or a Lucchetto extended RS provider of your choice.

For testing you can use @test.rs.overhide.io.

The app has all the necessary instructions.

Add pay2my.app In-App Purchase Buttons Against Above SKU Data

When your users make an IAP purchase you need to validate their payment — en perpetuity — and get the data backing your SKU (what you added in the previous section to your RS server).

The pay2my.app IAP buttons wire up all the necessary information:

<pay2myapp-appsell 
  ...
  sku="boost"
  priceDollars="1.50"
  withinMinutes="2"
  ...
  ethereumAddress="0xd6106c445a07a6a1caf02fc8050f1fde30d7ce8b"
  overhideAddress="0xd6106c445a07a6a1caf02fc8050f1fde30d7ce8b">
  ...
</pay2myapp-appsell>

Notice that the SKU dimensions asked for in the SKU setup RS app are also expected in the button:

  • sku
  • priceDollars
  • withinMinutes

These must match as SKU configured with the app as per the previous section.

The overhideAddress is your US dollars Ethereum linked address as per the US dollars ledger onboarding section above. Similarly the ethereumAddress is the Ethereum address you wish to receive ethers on.

The Code

Study the "Getting Started — Example App" in the next section for the rest of the code needed to hook up IAPs.

Pay attention to the use of <pay2myapp-* /> Web components.

Note how <pay2myapp-hub> has an ID which is provided to the <pay2myapp-appsell> components.

Pay attention to the use of var userRemoteStorage in conjunction with var lucchetto.

Getting Started — Example App

The "Getting Started" example app is just the ./index.html in this same folder as this README.md you're reading.

This application is hosted on GitHub for convenience.

You can connect any RS server — Lucchetto enabled or not — to this application. The application helps your correlate some console logs (displayed in upper right) to the source code (displayed in lower right), in a very similar fashion as the original Armadietto example application.

To use this application please read the text in the lower-right pane of the application.

The same text is available here: ignore/welcome.txt.

Create a User

The example app shows the remotestorage-widget / remotestorage.js integration.

Create a user using the widget. To create user click on the widget and enter:

@localhost:8000

⚠ notice we skipped adding a user in front of the @ as per standard RemoteStorage logins. The user will be determined subsequently in the flow, based on ledger-based authorization choices.

Click Connect. You'll be taken to an on-boarding site served by your localhost Armadietto + Lucchetto.

⚠ notice that there is no sign-up, just a pay2my.app login widget to authenticate and authorize with.

You'll be automatically redirected back to your application, regardless of login outcome.

Getting Started — Hosting a Lucchetto Extended Server

This folder with the README.md you're reading also has the sample code to start a Lucchetto RS as ./server.js.

This ./server.js is a bootstrapping piece of JavaScript that starts an Armadietto server (Node RS server), which, in this case, happens to be Lucchetto extended.

For non-Lucchetto settings factoring into ./server.js refer to the standard Armadietto README.md.

Reading ./server.js, the Lucchetto extension is enabled in the extnesions > pay2myapp descriptor. You will want to edit the following configuration points:

const server = new Armadietto({
  ...
  extensions: {
    ...
    pay2myapp: {
      enabled: true,
      is_test: true,
      api_key: '0x___API_KEY_ONLY_FOR_DEMOS_AND_TESTS___',
      price_dollars: 2,
      within_days: 7,
      address: '0x046c88317b23dc57F6945Bf4140140f73c8FC80F',
      retention_policy_text: 'Your data ...',
      salt: 'p1n34ppl3',
      ...

  • enabled flags whether this extension is enabled

  • is_test flags whether this server connects to pay2my.app/overhide testnets...

    ... or mainnets...

  • api_key is the API key for your new RS server's (cluster's) connection to overhide cluster

  • price_dollars is the cost in dollars you charge for storage, fake dollars if testnets

  • within_days is the number of days you provide storage for price_dollars

  • address is your ledger address for all ledgers — overhide and Ethereum — where you receive payments

  • retention_policy_text is some verbiage that shows up on the payment modal that gives your commitment statement to your users' data

  • salt is used to salt token metadata we don't want bad actors to adjust in transit

Note that you may want to further configure the storage_allowance extension to limit the number of bytes of storage per user. See the standard Armadietto README.md.

Let's get to running this Lucchetto extended server.

Starting in this README.md's folder, namely ./lucchetto/ subfolder of this distro.

In a terminal:

$ cd $ARMADIETTO_REPO/lucchetto
$ npm install

Where $ARMADIETTO_REPO is the root where you synced the armadietto repo.

To run the example server:

$ npm run start

This server is already configured with the lucchetto extensions.

The Armadietto server starts on port 8000.

Leave the terminal running the server as is.

In a new terminal host the example application:

$ npm run serve

The example application is now available on port 8080.

Now open the example app. You may need to dismiss browser warnings about the self-signed certificate for localhost before the clients will connect properly.

open http://localhost:8080

The "Getting Started" example application renders ready to be played with.

Running a Lucchetto Extended RS Server?

You may have noticed that the regular remotestorage-widget is amended by lucchetto.js with a dropdown of available servers.

Let's add your server to the list.