Merge branch 'master' of git+ssh://git.taler.net/docs

5 files changed, 111 insertions, 8 deletions

diff --git a/Makefile b/Makefile
index e15550e5..60745923 100644
--- a/Makefile
+++ b/Makefile
@@ -60,7 +60,8 @@ diagrams: arch-api.png
 # The html-linked builder does not support caching, so we
 # remove all cached state first.
 html: diagrams
-	$(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	# -W = exit 1 on warning; --keep-going = complete build anyway; write log to ~/warnings.log
+	$(SPHINXBUILD) -W --keep-going -w /home/docbuilder/sphinx-warnings.log -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -121,7 +122,8 @@ latex:
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	# -W = exit 1 on warning; --keep-going = complete build anyway
+	$(SPHINXBUILD) -W --keep-going  -w /home/docbuilder/sphinx-warnings.log -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
diff --git a/developers-manual.rst b/developers-manual.rst
index 19825122..b67ceeb6 100644
--- a/developers-manual.rst
+++ b/developers-manual.rst
@@ -315,6 +315,34 @@ run the following script from ``deployment/bin``:
 Environments and Builders on taler.net
 ======================================
 
+Buildbot implementation
+-----------------------
+
+GNU Taler uses a buildbot implementation (front end at https://buildbot.taler.net) to manage continuous integration.  Buildbot documentation is at https://docs.buildbot.net/.
+
+Here are some highlights:
+
+- The WORKER is the config that that lives on a shell account on a localhost (taler.net), where this host has buildbot-worker installed.  The WORKER executes the commands that perform all end-functions of buildbot.
+
+- The WORKER running buildbot-worker receives these commands by authenticating and communicating with the buildbot server using parameters that were specified when the worker was created in that shell account with the `buildbot-worker` command.
+
+- The buildbot server's master.cfg file contains FACTORY declarations which specify the commands that the WORKER will run on localhost.
+
+- The FACTORY is tied to the WORKER in master.cfg by a BUILDER.
+
+- The master.cfg also allows for SCHEDULER that defines how and when the BUILDER is executed.
+
+- Our master.cfg file is checked into git, and then periodically updated on a particular account on taler.net (ask Christian for access if needed).  Do not edit this file directly/locally on taler.net, but check changes into Git.
+
+
+Best Practices:
+
+- When creating a new WORKER in the `master.cfg` file, leave a comment specifying the server and user account that this WORKER is called from.  (At this time, taler.net is the only server used by this implementation, but it's still good practice.)
+
+- Create a worker from a shell account with this command: `buildbot-worker create-worker <workername> localhost <username> <password>`
+
+Then make sure there is a WORKER defined in master.cfg like: `worker.Worker("<username>", "<password>")``
+
 Documentation Builder
 ---------------------
 
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 3d5781bf..1e713fd9 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -87,7 +87,7 @@ Bank Account Management
        holder: string;
      }
 
-.. http:post:: {nexusBase}/bank-accounts/{acctid}/prepared-payments/{pmtid}/submit
+.. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit
 
   Ask nexus to submit one prepare payment at the bank.
 
@@ -95,7 +95,7 @@ Bank Account Management
     the bank connection could not be found in the system
 
 
-.. http:get:: {nexus}/bank-accounts/{my-acct}/prepared-payments/{uuid}
+.. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}
    
    Ask the status of payment ``$uuid``.
 
@@ -133,7 +133,7 @@ Bank Account Management
         preparationDate: string;
       }
 
-.. http:post:: {nexusBase}/bank-accounts/{my-acct}/prepared-payments
+.. http:post:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations
   
   Ask nexus to prepare instructions for a new payment.
   Note that ``my-acct`` is the bank account that will be
@@ -327,15 +327,73 @@ to the real bank.
 
    Make a passphrase-encrypted backup of this connection.
 
+..
+  not implemented.
+
 .. http:post:: {nexusBase}/bank-connections/{connid}/accounts/fetch
 
    Update accounts that are accessible via this bank connection.
 
 .. http:get:: {nexusBase}/bank-connections/{connid}/accounts
 
-   list accounts that are accessible via this bank connection and what
-   LibEuFin accounts they are connected to.
+   List the bank accounts that are downloaded into this bank connection
+   but aren't imported yet:
+
+  .. ts:def:: BankAccount
+
+     interface BankAccount {
+       
+       // iban
+       iban: string;
+
+       // bic
+       bic: string;
+
+       // account holder
+       holder: string;
+
+       // account label as given by the bank
+       account: string;
+     }
+
+.. http:get:: {nexusBase}/bank-connections/{connid}/accounts/imported
+
+   List the bank accounts that were imported under this bank connection:
+
+  .. ts:def:: BankAccount
+
+     interface BankAccount {
+       
+       // iban
+       iban: string;
+
+       // bic
+       bic: string;
+
+       // account holder
+       holder: string;
+
+       // custom account label as given by the user
+       account: string;
+     }
+
+
+.. http:post:: {nexusBase}/bank-connections/{connid}/accounts/import
+
+   Import one bank account, allowing the user to name it.
 
+  .. ts:def:: ImportBankAccount
+
+     interface ImportBankAccount {
+
+       // alphanumeric identifier given by the bank to
+       // the bank account to import.
+       accountId: string;
+
+       // alphanumeric name chosen by the user to identify
+       // locally such imported bank account.
+       localName: string;
+     }
 
 Facades
 -------
diff --git a/libeufin/banking-protocols.rst b/libeufin/banking-protocols.rst
index f2dee9e4..6c3fd037 100644
--- a/libeufin/banking-protocols.rst
+++ b/libeufin/banking-protocols.rst
@@ -113,3 +113,14 @@ The `Open Bank Project <https://www.openbankproject.com/>`__ provides a free sof
 banking middleware that supports various APIs, including PSD2-compatible APIs (based on Berlin Group).
 
 API Docs: https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture
+
+
+UK Open Banking
+===============
+
+Open Banking is the (quite confusing!) name of a UK-based open banking initiative.
+
+What's nice about Open Banking is that their APIs are really close to ISO 20022, unlike many
+similar HTTP+JSON APIs.
+
+https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index 82b206ec..f5cca273 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -59,7 +59,11 @@ to other parties.
 
 To perform this duty, you will need at least (read-only) access to the bank
 transactions of the exchange, as well as a continuously synchronized replica
-of the exchange's database.
+of the exchange's database.  The general assumption for running the auditor
+is that this is done on a separate system controlled by the auditor. After
+all, the goal is to detect nerfarious activity of the exchange operator,
+which cannot be effectively done on a machine controlled by the exchange
+operator.
 
 For this, every auditor needs to operate a Postgres database.  The data
 collected will include sensitive information about Taler users, including