improve docs; +simulation spreadsheet

doc/Flow.md

@@ -1,54 +1,36 @@
 # Flow of transactions
 
-A combination of off-chain and on-chain transactions define the interaction of the client with the system.
+A service instance is represented by a smart contract on a blockchain. The contract's state changes with transactions on it by the user and the service provider.
 
-* a fiat on-ramp sells service tokens in the sense of a gift card to the client who's on-chain account will be credited with the corresponding amount
-  * alternative: accepting crypto currencies might trigger the same
-* the client exposes a fraction of her balance to the service
-  * this is an on-chain transaction of transferring tokens from a client's account back to the service account
-  * in return the client is credited with internal service tokens (GEEZ)
-* the client starts and uses services
-  * which then debit their usage from the client's GEEZ account
+* at first, the contract is created by the service manager with references to the provider's and the user's addresses so to allow only interaction from these accounts
+* the user deposits a small amount to start the contract
+* both the user and the provider can intermittently withdraw funds from the contract
+* the user may deposit more funds to extend the duration of the contract
+* either the user or the provider call "stop" on the contract, or the contract runs out of funds
+* after this point, the contract cannot be started again, the balances don't change anymore
 
-This approach has some
 
-### CONS
-- it is a bit laborous for the client
-  - fiat payment, then on-chain transfer of tokens
-- there are some parts which depend on "trust" like the account of GEEZ which is presumably held in an internal and opaque database
+## On-ramp, off-ramp
 
-### PROS
-- only a fraction of the client's holding are at stake, the rest is kept in an on-chain account
-- a fiat on-ramp process allows more users to use the system
-  - not everybody can, wants, or is allowed to use cryptocurrencies
-- low transaction fees
-  - fiat on-ramp: \<5% charged to the service
-  - on-chain transfer: $0.05 or lower charged to the client
+All services on this platform are payable in a token, named BCA1, that represents the value of one Euro per token.
+Such tokens can be purchased using fiat money in our on-ramp service. And, token holders can request a payout to a bank account by returning the tokens.
 
-## Transactions
+### The user buys service tokens using fiat and gets credited
 
-Let's have a closer look at the transactions involved.
-
-### The client buys service tokens using fiat and gets credited
-
-The client buys in a conventional fiat transaction some tokens. This is reflected by minting new tokens to the client's on-chain account.
+The user buys in a conventional fiat transaction some tokens. This is reflected by minting new tokens to the user's on-chain account.
 
 ![Fiat on-ramp](./img/tx0-1.png)
 
 
-### The client charges her account
-
-Using an on-chain transaction, the client transfers a number of tokens to the _serviceAccount_.
-
-This is reflected in crediting the client's off-chain account with "Geez" tokens of the same amount. 
+### The user deposits tokens for service micro-payments
 
-![Charge client account](./img/tx2.png)
+Using an on-chain transaction, the user transfers a number of tokens to a smart contract representing a service instance.
 
+![User deposit](./img/tx2.png)
 
-### Services debit the client's account for micropayments
 
-In an off-chain setup, or on a private blockchain with minimal transaction fees, services can debit client accounts for their service usage.
+### Balances of both parties are managed in the smart contract
 
-This is immediately reflected in an updated balance in the client's account.
+After the contract is started, the user's and the provider's balances are maintained. These balances determine how much each party can withdraw from the contract. While the user's balance diminishes with time, the provider's balance will increase.
 
 ![Service usage debit](./img/tx3.png)

doc/Services.md

@@ -1,55 +1,56 @@
 # Service Management
 
+Contract [Solidity](../bca-token-solidity/contracts/BCA_Service.sol) code
+
 There are three parties involved:
-- the user which initiates the requests
-- the service manager which manages the user's account and communicates with both the user and the service providers
+- the service account that owns the contract
+- the user who requests and funds the service
 - the service provider which provides services and manages them
+  - represented by the service controller which reacts to events of the contract
 
 ![Use case services](./img/UC2.png)
 
 
-## Starting a service
+## Setting up a new service instance
 
 The user requests a new service with the service manager.
 
-The service manager invokes the setup process with the service provider.
+The service manager invokes the setup process with the service provider and deploys a new smart contract for this service instance.
 
-After the process ends successfully, the service providers hands over the credentials in a secure way to the user via the service manager.
+To progress in the setup, the user must first deposit enough funds in the contract.
 
-At this time, the user can use the service.
+After the setup process ends successfully, the service provider hands over, in a secure way, the access credentials to the user via the service manager.
 
 ![Sequence diagram start service](./img/Seq-Service-Start.png)
 
 
 ## Stopping a service
 
-The user requests a service he has subscribed to be shutdown.
-
-The service manager invokes the shutdown process with the service provider.
+The user requests a subscribed service to be shutdown with a call to the "stop" method of the contract. Or, the user's deposit on the contract is exhausted.
 
-At the end of the process, the service provider acknowledges the sunsetting of the service and send this via the service manager to the user.
+The service controller reacts to the Stop event and invokes the shutdown process of the service.
 
 ![Sequence diagram stop service](./img/Seq-Service-Stop.png)
 
 
 ## Billing of services
 
-The service manager debits the user's account periodically for the services in use.
+The contract is effectively calculating the user's and the provider's balances on arrival of a transaction.
 
-The time periods of a tick are per hour: from one up to 24 hours.
+Since the parameters of the contract are known, these balances can also be deterministically calculated off-chain.
 
-A service is in use after it has been started. The usage ends with the stopping of the service.
-If the user's account runs out of credits, then the service is stopped immediately and the usage ends.
+This has the same effect as micro-payments. Users only pay for their usage and service providers earn a revenue stream. If the calculated balance is reasonably high, then a provider might withdraw their balance.
+
+A service is in use after it has been started with a first deposit by the user. The usage ends with the stopping of the service, or if the user's balance runs out of funds.
 
 At start of a service an initial setup fee can be charged. This fee also includes a potential tear down fee when the service is shut down; there is no extra fee due when the servicing ends.
 
-At the end of the time period, the user's account is charged.
+### Contract simulation
 
-### Process of billing 
-![Charging for service usage](./img/Seq-Service-Billing.png)
+The [spreadsheet](./img/Tokenized_Service_Contract_Simulation.ods) contains simulations for a short lived and a long-running service contract and the calculation of the user's and the provider's balances.
 
-### Details of the accounting class
-![ServerManager debits the user](./img/Iface-Billing.png)
+![long-running service contract simulation](./img/sim_contract.png)
+This shows the balances of the user and the provider over the lifespan of the service contract. The user regularly deposits coins to fund the service. Also, the provider withdraws funds as soon as they reach a certain amount.
 
 ## Registering a service controller
 
@@ -60,4 +61,3 @@ The service controller runs on the service provider's infrastructure.
 Between the two there is a secure VPN connection installed such that either party is assured to only communicate with the other and nobody else is listening.
 
 ![Interface Service Controller](./img/Iface-Service-Controller.png)
-

doc/Tokenization.md

@@ -3,9 +3,9 @@
 
 ## ERC20 Service Contract
 
-
 ![Contract interactions](./img/UC1.png)
 
+Contract [Solidity](../bca-token-solidity/contracts/BCA_ERC20_nf.sol) code
 
 ### public methods
 The ERC20 contract allows the following methods:
@@ -24,17 +24,10 @@ These methods can only be called from the _serviceAccount_
 ### supply methods
 
 - mint
-> only allowed from the _minter_
+> only allowed from the _minter_ account
 
 - burn
-> only allowed from the _burner_
+> only allowed from the _burner_ account
 
 > will burn tokens in the _serviceAccount_
 
-
-### transfer method
-
-This method only allows to transfer tokens from a user's account to the _serviceAccount_
-
-Users cannot transfer tokens to their addresses.
-

doc/img/UC2.puml

@@ -46,14 +46,22 @@ skinparam backgroundColor #ffffff
 
 actor "User" as user order 1
 participant "Service Manager" as sm order 2
-participant "Service Controller" as sc order 3
-participant "Service" as sv order 4
+participant "Service Smart Contract" as co order 3
+participant "Service Controller" as sc order 4
+participant "Service" as sv order 5
 
 user -> sm : request service
 
-sm -> sc : start service
+sm -> co : deploy
+activate co
+
+co --> sc : event Create
 
+user -> co : deposit
+
+co --> sc : event Deposit
 sc -> sv : setup
+activate sv
 sc <-- sv : credentials
 sc -> sv : start
 
@@ -71,49 +79,22 @@ Stopping a service:
 skinparam backgroundColor #ffffff
 
 actor "User" as user order 1
-participant "Service Manager" as sm order 2
+participant "Service Smart Contract" as sm order 2
 participant "Service Controller" as sc order 3
 participant "Service" as sv order 4
 
-user -> sm : shutdown service
+activate sm
+activate sv
+user -> sm : stop
 
-sm -> sc : stop service
+sm --> sc : stop event
+' deactivate sm
 
 sc -> sv : stop
-
-sm <-- sc : acknowledgement
-
-user <-- sm : acknowledgement
+deactivate sv
 
 @enduml
 
-Charging for services:
-@startuml Seq-Service-Billing
-
-!theme mars
-
-skinparam backgroundColor #ffffff
-
-actor "User" as user order 1
-participant "Accounting" as accounting order 2
-participant "Service Manager" as sm order 3
-
-user -> accounting :  credit
-
-user -> sm : request service
-
-accounting <-- sm : charge setup fee
-
-group "repeat: after each time period"
-accounting <-- sm : charge tick fee
-end
-
-user -> sm : shutdown service
-accounting <-- sm : charge last tick fee
-
-@enduml
-
-
 The interface a service controller needs to provide:
 @startuml Iface-Service-Controller
 

doc/img/tx0-1.mmd

@@ -1,27 +1,27 @@
 graph LR
 
-    style Client0 fill:#444
-    style Client1 fill:#444
+    style User0 fill:#444
+    style User1 fill:#444
     style ServiceAccount0 fill:#559
     style Minter fill:#559
     style tx0 fill:#484
     style tx1 fill:#844
 
     subgraph fiat
     direction TB
-    %% tx0 - client charges account
+    %% tx0 - user funds token account
     tx0("tx0")
-    Client0("Client: $25") --> tx0 --> ServiceAccount0(Service Account: $25)
+    User0("User: €25") --> tx0 --> ServiceAccount0(Service Account: €25)
     end
 
-    %% tx1 - mint tokens to client's account
+    %% tx1 - mint tokens to user's account
     tx1("tx1")
     %% inputs
     subgraph on-chain
     direction BT
     Minter --> tx1
     %% outputs
-    tx1 --> Client1("Client: BCA1 25")
+    tx1 --> User1("User: BCA1 25")
     end
 
     fiat -.-> on-chain

doc/img/tx2.mmd

@@ -1,26 +1,19 @@
 graph LR
 
     style tx2 fill:#844
-    style Client0 fill:#444
-    style Client1 fill:#444
-    style Client2 fill:#444
-    style ServiceAccount0 fill:#559
-    style ServiceAccount1 fill:#559
+    style User0 fill:#444
+    style User1 fill:#444
+    style ServiceContract0 fill:#559
+    style ServiceContract1 fill:#559
 
     subgraph on-chain
-    %% tx2 - client reserves tokens for service charge
+    %% tx2 - user reserves tokens for service charge
     tx2("tx2")
     %% inputs
-    Client0("Client: BCA1 25") -->|"transfer 5"| tx2
-    ServiceAccount0("Service Account: BCA1 0") --> tx2
+    User0("User: BCA1 25") -->|"deposit 5"| tx2
+    ServiceContract0("Service Contract: BCA1 0") --> tx2
 
     %% outputs
-    tx2 --> Client1("Client: BCA1 20")
-    tx2 --> ServiceAccount1("Service Account: BCA1 5")
+    tx2 --> User1("User: BCA1 20")
+    tx2 --> ServiceContract1("Service Contract: BCA1 5")
     end
-    subgraph off-chain
-    direction LR
-    Client2("Client: Geez 5")
-    end
-
-    on-chain -.-> off-chain

doc/img/tx3.mmd

@@ -1,16 +1,29 @@
 graph TD 
 
-    style tx3 fill:#626
-    style Client0 fill:#444
-    style Client1 fill:#444
+    style tx3 fill:#844
+    style µpay fill:#626
+    style User0 fill:#444
+    style User1 fill:#444
+    style User2 fill:#444
     style Service0 fill:#559
     style Service1 fill:#559
+    style Service2 fill:#559
+    style Service3 fill:#559
 
-    subgraph off-chain
-    %% tx3 - services debit the client account for usage
+    subgraph service smart contract
+    %% µpay - services debit the user account for usage
+    µpay("micro-payment")
+    User0(User: BCA1 4.8) -.->|dt = -0.1| µpay
+    Service0(Provider: BCA1 0) -.->|dt = +0.1| µpay
+    µpay -.-> User1(User: BCA1 4.7)
+    µpay -.-> Service1(Provider: BCA1 0.1)
+    end
+
+    subgraph withdrawal
     tx3("tx3")
-    Client0(Client: Geez 5) -.-> tx3
-    Service0(Service) -.->|debit .1| tx3
-    tx3 -.-> Client1(Client: Geez 4.9)
-    tx3 -.-> Service1(Service: Geez 0.1)
+    User1(User: BCA1 4.7) -.-> tx3
+    Service1(Provider: BCA1 0.1) -.-> tx3
+    tx3 -.-> User2(User: BCA1 4.7)
+    tx3 -.-> Service2(Provider: BCA1 0)
+    tx3 -.->|withdrawal| Service3(Provider': BCA1 0.1)
     end