CTP: provide contract templates

Идея состоит в том, чтобы сервисы могли создавать контракты через вебклиент. Для этого такой сервис предоставляет минимальный REST API.

Последовательность действий такова:

  • Вебклиент читает оглавление библиотеки и предлагает пользователю выбрать темплейт
  • Вебклиент запрашивает параметры по ID темплейту
  • Вебклиент показывает форму с полями в соответствии с полученными параметрами
  • Вебклиент отправляет запрос на генерацию контракта
    • получает ответ с ошибками по полям, снова показывет форму, подсвечивает сбойные поля, позволяет ввести корректные значения
    • получает сгенерированный контракт с текстовым пояснением что с ним необходимо делать далье и со списком подписей которые требуются для его успешной регистрации.
  • Вебкоиент помещает сгенерированный контракт в криптооблако и как то запоминает данные (пояснение и требуемые подписи)
  • Пользователь подписывает контракт, передает его другим участникам для подписи, регистрирует и использует контракт.
  • Контракт содержит описание действий которые с ним можно сделать, для автоматической обработки на вебклиентах

CTP service has a base url which could be anything that us used a s a root in standard CTP requests.

_the interface here is a JSON one, it requires JSON parameters and return JSON body unless explicitely described the other format.

GET list of available templates

GET <base_path>

retuns the common response with list of templates like:

{
    providerId: "Universa Superbank",
    providerAddress: "<some universa address>",
    KISS: "Universa Superbank",
    templates: [
        {
            group: "loan contracts",
            description: "contracts that let universa lend conctracts to others",
            contracts: [
                {
                    name: "simple loan",
                    description: "allow  lend some universa contract with a given interest rate",
                    id: "simple_loan"
                },
                {
                    name: "secured loan",
                    description: "allow  lend some universa contract with a given interest rate with guaranty (pledge)",
                    id: "secured_loan"
                }
            ]
        }
    // there could be more groups
    ]
};

See KISS for more on it. The client should then show list of the templates in UI.

Get a template

use template id from a list.

GET <base_url/<template_id>

returns a common response with a template parameters like:

{
    providerId: "Universa Superbank",
    contractId: "simple_loan",
    version: "1.0.0",
    inputFields: [
{
                id: "lender",
                name: "lender",
                type: "universa_address",
                description: "address of the person who lends the asset"
            },
            {
                id: "borrower",
                name: "borrower",
                type: "universa_address",
                description: "address of the person who borrows the asset"
            },
            {
                id: "asset",
                name: "asset",
                type: "universa_contract",
                description: "asset to be lent, must be owned by owner. Any universa contract that will change ownership"
            },
            {
                id: "pledge",
                name: "a collateral contract that will b eused as a pledge. It will be blocked until borrower return the loan or will be passed to lender in the case of default",
                description: "interest is calculated depending on the day of return",
                type: "universa_contract",
            },
            {
                id: "interest_currency",
                name: "the token name of the loan payment",
                description: "the token that will be used as payment, its title",
                type: "single_selection", list: [ { id: 'UTN', name: "UTN"}, {id: 'uETH', name: 'uETH'}]
            },
            {
                id: "interest_amount",
                name: "loan payment amount",
                description: "the amount of loan payment",
                type: "decimal"
            },
            {
                id: "description",
                name: "description",
                description: "any text that could be added to the contract",
                optional: true,
                type: "text"
            },
            {
                id: "borrower_person_id",
                name: "debtor personal identification data",
                type: "text",
                description: "full name, birth date and place, document type and number, etc.",
                optional: true
            },
            {
                id: "borrower_document_scan",
                name: "debtor personal identification document scan",
                type: "image_attachment",
                description: "scanned personal ID document",
                optional: true
            }    
        ]
};

The list of parameters should be shown in a UI form to the user fo he or she could fill it in.

The filled parameters are passed to the template generation

Field types

field types are described as to use in json body. If used with BOSS, the format could differ. All text is encoded as utf-8.

type description
decmal decimal value, with the dot as a decimal point, positive or negative. like 0.000000211
universa_address string value containing either short ot long universa address
univera_conract some universa contract, as base64 string
text some text, any length, modifiers could be applied: multiline, limit=, lines=
single_selection list of values passed in list parameter with single selection. Gerat fit for a select control (dorpdown)

Template generation

POST <base_url>/<template_id>

with JSON body of the following format:

{
    lender:"<universa_address>",
    borrower: "<universa_address>",
    // and all non-optional fields and some optional fields as key-value pairs
}

The anseer in the case of errors:

{
    status: 'error',
    errors: [
        { 
            id: "lender",
            text: "invalid addres",
            details: "entered data is not a valid universa address"
        }, //...
    ]
}

In the case of success:

{
    status: "OK",
    transactionPack64: "<base64 encoded binary>",
    requiredSignatures: "lender,debtor", // field names from template
    description: "the contract should be signed by both parties and registered with Universa, then debtor will be able to use lent asset"
}

CTP info and actions

POST <base_url>/info

with parameter:

  • contract: base64 of the packed contract

retuns common response like:

{
  "ctpId": "secure_loan",
  "ctpName": "superbank",
  "contractStatus": "in_progress",
  "actions": {
    "repay": {
      "name": "repay contract",
      "description": "return the loan and the interest",
      "roles": [
        "borrower"
      ]
    }
  },
  "status": "OK"
}

Some notes

  • action.roles mean who can perform this action, e.g. must sign the revision