Current Version: 3.0

Test Suite: Not available yet

Implementation report: Not available yet

Author: Cagan Mert ISLEK

• Cagan Mert ISLEK

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.

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.

{
  "title": "Example",
  "url": "https://example.com/index.html",
  "description": "Lorem ipsum dolor sit amet"
}

{
  "title": "Post Title",
  "datetime": "YYYY-MM-DD HH:mm",
  "id": "post01",
  "content": "HTML"
}

{
  "Relation": "",
  "SMTP": {
    "Label": "username@example.com"
  },
  "Socials": {
    "App": "@username"
  }
}

{
  "deadline": "",
  "last_update_status": "2024-01-24 11:28",
  "repeat": "",
  "status": true,
  "subs": [],
  "title": "Demo Task"
}

{
  "deadline": "",
  "status": true,
  "title": "Demo Task"
}

{
    "last_index": 0,
    "image": "",
    "title": "",
    "participants": []
}

{
  "from": "",
  "body": "",
  "date_received": ""
}

{
  "subject": "",
  "date_received": "",
  "sender": "",
  "to": "",
  "cc": "",
  "hashtag": "",
  "body": ""
}

</deleted>

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"
}

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

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"
}

Standard gender values are Male, Female, Lesbian, Gay, Bisexual, Transgender, Queer, Intersexual, Asexual, and Pansexual. Clients and servers must code to support others before reporting the problem to me via email, GitHub, or HereUS. Clients are designed to assume there is no other possible value and unsupported values can cause problems.

+ 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.

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
}

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

Standard gender values are Male, Female, Lesbian, Gay, Bisexual, Transgender, Queer, Intersexual, Asexual, and Pansexual. Clients and servers must code to support others before reporting the problem to me via email, GitHub, or HereUS. Clients are designed to assume there is no other possible value and unsupported values can cause problems.

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.

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.

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.

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.

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.

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.

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"
}

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.

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
}

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.

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.

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.

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.

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.

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.

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.