TheProtocols Docs

Current Version: 3.0

Test Suite: Not available yet

Implementation report: Not available yet

Author: Cagan Mert ISLEK


Abstract

TheProtocols is a federated protocol for decentralizing super apps by letting people choose a network and a client they want. TheProtocols is designed to provide most functionality a standard user needs in a daily life.

State of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

All interested parties are invited to provide implementation and bug reports and other comments through email, TheProtocols, HereUS, or issue tracker. These will be considered in any future versions of this specification.

Overview

Objects

**Resource Pointer** Used for pointing to any resource on web. 
{
  "title": "Example",
  "url": "https://example.com/index.html",
  "description": "Lorem ipsum dolor sit amet"
}
**Feed Post** A post listed in feed.
`content` is in HTML format and an optional key if this object is in list.
`id` must follow FAT32 filename limitation except space is not allowed.
 
{
  "title": "Post Title",
  "datetime": "YYYY-MM-DD HH:mm",
  "id": "post01",
  "content": "HTML"
}
**Contact** Extensible object to keep extra data about a person.
Addition to key value pairs on right key value pairs available in a standard user ID can be added to replace hidden ones.
Value of `Relation` must be `"Self"` if the contact is the current user and empty string if relation is not unique. 
{
  "Relation": "",
  "SMTP": {
    "Label": "username@example.com"
  },
  "Socials": {
    "App": "@username"
  }
}
**Reminder** Standard reminder object.
`deadline` and `last_update_status` must be in "YYYY-MM-DD HH:mm" format.
`last_update_status` is the most recent time the reminder toggled.
`subs` is a list of sub-reminder object. `repeat` must be an interval object. 
{
  "deadline": "",
  "last_update_status": "2024-01-24 11:28",
  "repeat": "",
  "status": true,
  "subs": [],
  "title": "Demo Task"
}
**Sub-Reminder** Sub-reminder object.
`deadline` must be in "YYYY-MM-DD HH:mm" format. 
{
  "deadline": "",
  "status": true,
  "title": "Demo Task"
}
**Chat** Two form object to keep information about two party and multiple party chats.
Two party chats only have `last_index` key, other keys are only for multiple party chats.
`image` must be an URL.
`participants` is a list of TheProtocols addresses of participants. 
{
    "last_index": 0,
    "image": "",
    "title": "",
    "participants": []
}
**Message** An object to keep information about a message.
`date_received` must be in `YYYY-MM-DD HH:mm` format.
`body` must be in Markdown format. 
{
  "from": "",
  "body": "",
  "date_received": ""
}
**Mail** An object to keep information about a mail.
`date_received` must be in `YYYY-MM-DD HH:mm` format.
`body` must be in HTML format.
`sender` must be the address of sender.
`to` and `cc` must be lists of addresses stringified with `;` as deliminator.
`hashtag` must only contain lowercase, uppercase, and numbers. 
{
  "subject": "",
  "date_received": "",
  "sender": "",
  "to": "",
  "cc": "",
  "hashtag": "",
  "body": ""
}
**Deleted** Used to inform network to delete a remote object. 
</deleted>

Network Information

To learn about a network, an HTTPS POST request to /protocols/version is used.

Server must not expect any data to be in body for this request.

Example Response Client Must Expect:

{
  "help": "",
  "os": {
    "arch": "",
    "family": "",
    "name": "",
    "version": ""
  },
  "rules": {
    "new_accounts_allowed": true
  },
  "software": {
    "build": 1,
    "channel": "",
    "developer": "",
    "name": "",
    "source": "",
    "version": ""
  },
  "users": [],
  "version": "3.0"
}
String: Username of the account users must contact for help
Dictionary: Information about OS of the server of the network
     String: Architecture of OS *(look below)*
     String: OS Family
     String: OS Name
     String: OS Version

Dictionary: Rule configuration of the network
     Bool: If network accepts new users to create account using TheProtocols

Dictionary: Information about the server software
     Integer: Build number of the server software
     String: Release channel of the server software *(look below)*
     String: TheProtocols address of the developer
     String: Name of the server software
     String: `"Closed"` or URL of the repository of the server software
     String: Version of the server software

List: List of usernames of the users
String: TheProtocol version server configured

Architecture of OS must be in official format like: x86, x86_64, AArch64

Account Creation & Terms of Service

To create an account on a network these steps must be followed in the order:

  1. HTTPS POST request to /protocols/terms_of_service to view Terms of Service of the network in HTML format. Account creation will assume you accepted.
  2. HTTPS POST request to /protocols/signup with a JSON with these keys:
{
    "birthday": "YYYY-MM-DD",
    "country": "US",
    "gender": "Male",
    "name": "Given Name",
    "password": "Raw Password",
    "phone_number": "+1 000 000 0000",
    "postcode": "54050",
    "timezone": -8,
    "surname": "FAMILY",
    "username": "username",
    "biography": "Bio"
}
String: Birthday in `YYYY-MM-DD` format
String: 2-letter Country Code
String: Gender
String: Given Name
String: Raw Password of User
String: Phone Number, "+1 000 000 0000" format without spaces
String: Postcode of the user
Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00")
String: Surname in all uppercase
String: Username with only using ASCII lowercase and `-` symbol
String: Social media biography with `` as line breaker

+ symbol can also be used in usernames as alternative accounts of the main account. For instance, user@example.com can use user+untrustedapp@example.com for privacy and prevent spam if the server software supports as TheProtocols specification highly recommends.

Client must not expect anything except a status code to learn about is the server was able to create the account.

Identity of The Current User

To get identity (including personal information and hidden information) of the current user, an HTTPS POST request to /protocols/current_user_info is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

current_user_username must be the username of the user and current_user_password must be the password of the user.

Example Response Client Must Expect:

{
  "birthday": "",
  "chamychain_private_key": "",
  "chamychain_public_key": "",
  "rsa_private_key": "",
  "rsa_public_key": "",
  "country": "",
  "gender": "",
  "name": "",
  "phone_number": "",
  "plus": false,
  "postcode": "00000",
  "profile_photo": "",
  "settings": {
    "apps": [],
    "plus_until": 20321108,
    "theme_color": "blue"
  },
  "social": {
    "biography": "",
    "emoji": "",
    "story": {
      "content": "",
      "datetime": 202401011200
    }
  },
  "surname": "SURNAME",
  "timezone": -8
}
String: Birthday in `YYYY-MM-DD` format
String: ChamyChain Private Key
String: ChamyChain Public Key
String: RSA Private Key
String: RSA Public Key
String: 2-letter Country Code
String: Gender
String: Given Name
String: Phone Number, "+1 000 000 0000" format without spaces
Integer: `0` is free plan, `1` is plus, `2` is pro, and `3` is ultra
String: Postcode of the user
String: URL of the profile photo of the user
Dictionary: Settings of user which not owned by an app
     List: List of package names keeping data in library of user
     Integer: When membership of the user ends in YYYYMMDD format
     String: Theme color preference of user

Dictionary: Required keys to create a complete social media profile
     String: Social media biography with `` as line breaker
     String: Emoji to show next to the username
     Dictionary: Story data for social media
          String: HTML Content of Story
          Integer: When story updated in YYYYMMDDHHmm format


String: Surname in all uppercase.
Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00")

Standard theme_color values are red, orange, yellow, green, blue, pink, purple, and blank. blank value means for client to not color the UI.

If a server software implementor wants to create a feature like email aliases with privacy feature, the server must hide the data while respecting the standards above. For instance, while user_info can hide timezone by replacing with "**" but current_user_info can only hide by replacing with 0 or other standard compatible placeholder.

Servers can modify count of memberships (plus key) available up to 4. That means servers can disable 1, 2, 3, 1 & 2, 1 & 3, 2 & 3, or all. The reason why TheProtocols has standard of memberships is these memberships are considered as TheProtocols Network membership by clients and names must be generated from an integer. Extraction of membership plan names from Network Info is planned.

social key can be removed to disable social media integrations. But if server sends this key included, value must follow the standard.

User ID Modifications

To modify a value in user id, HTTPS POST request to /protocols/set_user_data is used.

Networks can be configured to set immutable some of the keys. Client must not expect success everytime.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "key": "",
  "data": ""
}

key must be in file path format. For instance, if client wants to edit biography, key must be social/biography. If the value placed directly in the root, key must be the key directly. For instance, if client wants to edit country, key must be country.

Client must not expect anything except a status code to learn about is the server was able to save.

To search for an object or a website from index of server, an HTTPS POST request to /protocols/search is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "key": ""
}

key is the query string. Network will return every object matching with the key.

Response will be a JSON with a single key value pair. Key is results and contains a list of resource pointer objects matching with the query.

Feed

TheProtocols allows networks to serve a feed. To get the feed, an HTTPS POST request to /protocols/get_feed is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Response will be a JSON with a single key value pair. Key is feed and contains a list of feed post objects matching with the query.

To get a feed post, an HTTPS POST request to /protocols/get_feed_post is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "id": ""
}

id must be the id of the post.

Response will be a feed post object.

Cloud Storage Status

To check status of cloud storage allocated for the user, an HTTPS POST request to /protocols/storage_status is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Example Response Client Must Expect:

{
  "total": 0,
  "used": {}
}

used can contain unlimited number of key value pairs to address what uses how much space. Values must be size in byte as integer. Recommended keys to have in used dictionary are size of user id as id, size of folder contains library data as library_data, size of folder contains mails as mails, size of folder contains notes as notes, size of folder contains reminders as reminders, and size of folder contains cold wallet as token.

total is total space allocated for the user in byte as integer.

Notes

To pull all notes from the network, an HTTPS POST request to /protocols/pull_notes is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Response client must expect is a plain JSON. If the value of a key is dictionary, the pair is a folder. If the value of a key is string, the pair is a note. For instance, if there notes folder of a user is /Users/user/Notes, and user has a note in /Users/user/Notes/path/to/note.html, response should be

{
  "path": {
    "to": {
      "note": "<p>Hello, World!</p>"
    }
  }
}

To edit a note, an HTTPS POST request to /protocols/edit_note is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "path": "",
  "value": ""
}

path must be the path of the note to edit.

value must be text in HTML format.

Client must not expect anything except a status code to learn about is the server was able to save.

To delete a note, send deleted object as the new value of the note.

Reminders

To pull reminders from the network, an HTTPS POST request to /protocols/get_reminders is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Response client must expect is JSON key value pairs, task list titles as keys and lists of reminder objects as values.

To toggle a reminder, reversing status value, an HTTPS POST request to /protocols/toggle_reminder is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "list": "",
  "id": 0
}

list must be the name of the list.

id must be the index of the reminder in the list. Note that id is not unique and can change, best to pull reminders before editing, toggling, deleting a reminder.

Client must not expect anything except a status code to learn about is the server was able to save.

To edit a reminder, an HTTPS POST request to /protocols/edit_reminder is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "list": "",
  "id": 0,
  "data": ""
}

data must be a reminder object that dumped to JSON.

Client must not expect anything except a status code to learn about is the server was able to save.

To delete a reminder, an HTTPS POST request to /protocols/delete_reminder is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "list": "",
  "id": 0
}

Client must not expect anything except a status code to learn about is the server was able to delete.

To create a new list, an HTTPS POST request to /protocols/create_reminder_list is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "list": ""
}

Value of list must follow FAT32 filename limitations.

Client must not expect anything except a status code to learn about is the server was able to create.

To create a new reminder, an HTTPS POST request to /protocols/create_reminder is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "list": "",
  "title": "",
  "deadline": "",
  "repeat": ""
}

Value of title must be string. deadline must be in "YYYY-MM-DD HH:mm" format. 'repeat` must be an interval object.

Client must not expect anything except a status code to learn about is the server was able to create.

To create a new sub-reminder, an HTTPS POST request to /protocols/create_sub_reminder is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "list": "",
  "reminder": "",
  "title": "",
  "deadline": ""
}

Value of title must be string. deadline must be in "YYYY-MM-DD HH:mm" format.

Client must not expect anything except a status code to learn about is the server was able to create.

Tokens

While interacting with tokens, requests must be done to a relay in the token's network which supports TheProtocols.

To learn about a token, an HTTPS POST request to /protocols/token/about is used.

Server must not expect any data to be in body for this request.

Example Response Client Must Except:

{
  "exchange": 1,
  "name": "",
  "os": {
    "arch":"",
    "family":"",
    "name":"",
    "version":""
  },
  "software": {
    "build": 0,
    "channel": "",
    "developer": "",
    "name": "",
    "source": "",
    "version": ""
  },
  "version":"3.0"
}
Float: Exchange Rate Recommended by The Server Software
String: Token Name
Dictionary: Server OS Information
     String: Architecture of OS *(in official format)*
     String: OS Family
     String: OS Name
     String: OS Version

Dictionary: Server Software Information
     Integer: Build number of the server software
     String: Release channel of the server software (look below)
     String: TheProtocols address of the developer
     String: Name of the server software
     String: `"Closed"` or URL of the repository of the server software
     String: Version of the server software

String: TheProtocols Version

To check balance of a public key, an HTTPS POST request to /protocols/token/balance is used.

Example Body Server Must Expect:

{
  "public_key": ""
}

Value of public_key must be a ChamyChain Public Key.

Client must expect a number as plain/text.

To transfer token, an HTTPS POST request to /protocols/token/transfer is used.

Example Body Server Must Expect:

{
  "private_key": "",
  "receiver": "",
  "amount": 0
}

Value of private_key must be the ChamyChain Private Key of sender.

Value of receiver must be the ChamyChain Public Key of receiver.

Value of amount must be the amount of token to transfer as float or integer.

Client must not expect anything except a status code to learn about is the server was able to transfer.

Identity of Others in Federalized Web

To get identity (excluding personal information, hidden information is censored) of others in federalized web, an HTTPS POST request to /protocols/user_info is used.

For this time, unlikely to other requests, we must make the request to the network of the person we want to learn about.

Example Body Server Must Expect:

{
  "username": "Username"
}

username must be the username of the person we want to learn about.

Example Response Client Must Expect:

{
  "birthday": "",
  "chamychain_public_key": "",
  "rsa_public_key": "",
  "country": "",
  "gender": "",
  "name": "",
  "phone_number": "",
  "plus": false,
  "postcode": "00000",
  "profile_photo": "",
  "social": {
    "biography": "",
    "emoji": "",
    "story": {
      "content": "",
      "datetime": 202401011200
    }
  },
  "surname": "SURNAME",
  "timezone": -8
}
String: Birthday in `YYYY-MM-DD` format
String: ChamyChain Public Key
String: RSA Public Key
String: 2-letter Country Code
String: Gender
String: Given Name
String: Phone Number, "+1 000 000 0000" format without spaces
Integer: `0` is free plan, `1` is plus, `2` is pro, and `3` is ultra
String: Postcode of the user
String: URL of the profile photo of the user
Dictionary: Required keys to create a complete social media profile
     String: Social media biography with `` as line breaker
     String: Emoji to show next to the username
     Dictionary: Story data for social media
          String: HTML Content of Story
          Integer: When story updated in YYYYMMDDHHmm format


String: Surname in all uppercase.
Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00")

If a user wants to hide information or a network configured to not collect the data, value must contain censored version of the data. To censor data, replace value with multiple * symbol to mimic length of the original value or any value following standard.

Servers can modify count of memberships (plus key) available up to 4. That means servers can disable 1, 2, 3, 1 & 2, 1 & 3, 2 & 3, or all. The reason why TheProtocols has standard of memberships is these memberships are considered as TheProtocols Network membership by clients and names must be generated from an integer. Extraction of membership plan names from Network Info is planned.

social key can be removed to disable social media integrations. But if server sends this key included, value must follow the standard.

Contacts

Since some value can be hidden from public identity, this can block some functionality of clients. To solve this problem TheProtocols has contacts feature enabling users to fill hidden information of the people they know, changes only visible to them.

To get contacts, an HTTPS POST request to /protocols/list_contacts is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Response will be the JSON with TheProtocols address of the contact as key and contact object as value.

To add someone as contact, an HTTPS POST request to /protocols/add_contact is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "email": "username@example.com",
  "relation": "",
  "smtp": "{}",
  "socials": "{}"
}

Value of smtp must be string JSON of key value pairs of SMTP addresses of the contact, see contact object for more. If contact has no SMTP address, value must be "{}".

Value of socials must be string JSON of key value pairs of social media accounts of the contact, see contact object for more. If contact has no social media account, value must be "{}".

Client must not expect anything except a status code to learn about is the server was able to add.

To edit information of a contact, an HTTPS POST request to /protocols/edit_contact is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "email": "username@example.com",
  "data": ""
}

Value of data must be stringified JSON of a contact object.

Client must not expect anything except a status code to learn about is the server was able to save.

To delete a contact, deleted object must be set to contact data using the same request configuration as editing contact.

Messages (API)

To list chats and get information about chats, an HTTPS POST request to /protocols/list_chats is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Response will be dictionaries, chat id as key and chat object as value.

last_index is the index of the last message in a chat. That means a for loop from 0 to last_index can be used to get all messages. To get a message, an HTTPS POST request to /protocols/get_message is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "chat": "",
  "id": 0
}

Response will be a message object.

To send message, an HTTPS POST to /protocols/send_message is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "chat": "",
  "body": ""
}

body must be in Markdown format.

Client must not expect anything except a status code to learn about is the server was able to save.

To create a chat group, send message with "/" as chat and a new stringified chat object as body.

Messages (Federation)

This requests must be done between networks, clients have nothing to do.

To send a message to a chat, message must be added to the chat in every user's data in the group because TheProtocols assumes messages people receive are in the disk space allocated to the user and there is not a single pool of messages. This means if there is two person in a chat from a different network than the current user, even these two are from same network as each, message must be sent to them separately. Just like sending emails.

To request from a network to add a message to a user's data, these steps must be followed in order:

  1. Get AAS Public Domain Key. If you don't know how to, read How to verify a domain using AAS
  2. HTTPS POST request to /protocols/lowend/add_message_to_server of remote network.

Example Body Server Must Expect:

{
  "add_to": "",
  "from": "",
  "chat": "",
  "body": "",
  "domain_key": ""
}

Value of add_to must be the username of the sender, not address.

Value of from must be the address of sender.

Value of chat must be the ID of the chat. If it is two party chat, it must be set same as from.

Value of domain_key must be the AAS Public Domain Key of the sender network.

Network must renew the public key as soon as remote verifies it.

Sender network must only expect a status code to make sure remote received the message.

Mail (API)

To list mailboxes, an HTTPS POST request to /protocols/list_mailboxes is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password"
}

Response will be a dictionary, mailbox name as key and index for most recent mail as value.

Every network must have these mailboxes available for everyone as standard: Primary, Promotions, Social, Spam, Sent, Archive, Trash. Also if a server software has a special process on mails, it can provide more default mailboxes. Users can create new mailboxes by moving a mail to a mailbox not exist. Continue reading to learn how to move a mail.

To get a mail, an HTTPS POST request to /protocols/get_mail is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "mailbox": "",
  "id": 0
}

id is index of mail in the mailbox.

Client must expect a mail object.

To move a mail, an HTTPS POST request to /protocols/move_mail is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "mailbox": "",
  "mail": 0,
  "move_to": ""
}

mail is index of mail in the mailbox.

This will move the mail from mailbox to move_to.

Client must not expect anything except a status code to learn about is the server was able to move.

To delete a mail permanently, move it to -.

To send a mail, an HTTPS POST request to /protocols/send_mail is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "body": "",
  "to": "",
  "cc": "",
  "bcc": "",
  "hashtag": "",
  "subject": ""
}

Values must follow same standards as a mail object except values of to and cc must be stringified with ; as deliminator.

Client must only expect a status code to make sure mail sent successfully.

Mail (Federation)

This requests must be done between networks, clients have nothing to do.

A mail must be sent to everyone added in to, cc, and bcc.

To request from a network to add a mail to a user's inbox, these steps must be followed in order:

  1. Get AAS Public Domain Key. If you don't know how to, read How to verify a domain using AAS
  2. HTTPS POST request to /protocols/lowend/add_mail_to_server of remote network.

Example Body Server Must Expect:

{
  "add_to": "",
  "from": "",
  "to": "",
  "cc": "",
  "body": "",
  "subject": "",
  "hashtag": "",
  "domain_key": ""
}

Value of add_to must be the username of the sender, not address.

Value of from must be the address of sender.

Values of to and cc must be list of receivers stringified with ; as deliminator.

Value of body must be in HTML format.

Hashtag must only contain lowercase, uppercase, and numbers.

Value of domain_key must be the AAS Public Domain Key of the sender network.

Network must renew the public key as soon as remote verifies it.

Sender network must only expect a status code to make sure remote received the mail.

Library Data

To get library data associated with a package name, an HTTPS POST request to /protocols/pull_library_data is used.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "app": "com.example.app"
}

Package name sent as the value of app key must be in reverse AAS address format.

Response will be the library data as JSON. If there is no data associated with the package name, blank JSON ({}) will be returned.

To push new data, data must be dumped as JSON and sent as the value of data key accordingly with an HTTPS POST request to /protocols/push_library_data.

Example Body Server Must Expect:

{
  "current_user_username": "Username",
  "current_user_password": "Password",
  "app": "com.example.app",
  "data": "{}"
}

Client must not expect anything except a status code to learn about is the server was able to save.

Security Considerations

Acknowledgements