From 41fb2db7ca3c13593e80cdd5241f78e107c48f2c Mon Sep 17 00:00:00 2001 From: Cofson <41572590+Cofson@users.noreply.github.com> Date: Fri, 27 Sep 2024 04:39:32 +0200 Subject: [PATCH] fixes and changes to the status specs fixes and changes --- status/6/payloads.md | 384 ++++++++++++++++++ status/8/EIPS.md | 270 ++++++++++++ .../{account-address.md => ethereum-usage.md} | 0 3 files changed, 654 insertions(+) create mode 100644 status/6/payloads.md create mode 100644 status/8/EIPS.md rename status/9/{account-address.md => ethereum-usage.md} (100%) diff --git a/status/6/payloads.md b/status/6/payloads.md new file mode 100644 index 00000000..5a3021af --- /dev/null +++ b/status/6/payloads.md @@ -0,0 +1,384 @@ +--- +slug: 6 +title: 6/PAYLOADS +name: Payloads +status: draft +description: Status relation with the EIPs +editor: Ricardo Guilherme Schmidt +contributors: +- +--- + +## Abstract + +This specification describes how the payload of each message in Status looks +like. It is primarily centered around chat and chat-related use cases. + +The payloads aim to be flexible enough to support messaging but also cases +described in the Status Whitepaper as well as various clients created using +different technologies. + +## Table of Contents + +- [Abstract] +- [Table of Contents] +- [Introduction] +- [Payload wrapper] +- [Encoding] +- [Types of messages] + - [Message] + - [Payload] + - [Payload] + - [Content types] + - [Sticker content type] + - [Message types] + - [Clock vs Timestamp and message ordering] + - [Chats] + - [Contact Update] + - [Payload] + - [Contact update] + - [SyncInstallationContact] + - [Payload] + - [SyncInstallationPublicChat] + - [Payload] + - [PairInstallation] + - [Payload] + - [MembershipUpdateMessage and MembershipUpdateEvent] +- [Upgradability] +- [Security Considerations] +- [Changelog] + - [Version 0.3] + +## Introduction + +This document describes the payload format and some special considerations. + +## Payload Wrapper + +The node wraps all payloads in a protobuf record: + +```protobuf +message ApplicationMetadataMessage { + bytes signature = 1; + bytes payload = 2; + + Type type = 3; + + enum Type { + UNKNOWN = 0; + CHAT_MESSAGE = 1; + CONTACT_UPDATE = 2; + MEMBERSHIP_UPDATE_MESSAGE = 3; + PAIR_INSTALLATION = 4; + SYNC_INSTALLATION = 5; + REQUEST_ADDRESS_FOR_TRANSACTION = 6; + ACCEPT_REQUEST_ADDRESS_FOR_TRANSACTION = 7; + DECLINE_REQUEST_ADDRESS_FOR_TRANSACTION = 8; + REQUEST_TRANSACTION = 9; + SEND_TRANSACTION = 10; + DECLINE_REQUEST_TRANSACTION = 11; + SYNC_INSTALLATION_CONTACT = 12; + SYNC_INSTALLATION_PUBLIC_CHAT = 14; + CONTACT_CODE_ADVERTISEMENT = 15; + PUSH_NOTIFICATION_REGISTRATION = 16; + PUSH_NOTIFICATION_REGISTRATION_RESPONSE = 17; + PUSH_NOTIFICATION_QUERY = 18; + PUSH_NOTIFICATION_QUERY_RESPONSE = 19; + PUSH_NOTIFICATION_REQUEST = 20; + PUSH_NOTIFICATION_RESPONSE = 21; + } +} +``` + +`signature` is the bytes of the signed SHA3-256 of the payload, +signed with the key of the author. +The node uses the signature to validate authorship of the message +so it can be relayed to third parties. +Messages without signatures will not be relayed +and are considered plausibly deniable. + +`payload` is the protobuf-encoded content of the message, +with the corresponding type set. + +## Encoding + +The node encodes the payload using Protobuf. + +## Types of Messages + +### Message + +The type `ChatMessage` represents a chat message exchanged between clients. + +### Payload + +The protobuf description is: + +```protobuf +message ChatMessage { + uint64 clock = 1; // Lamport timestamp of the chat message + uint64 timestamp = 2; // Unix timestamps in milliseconds + string text = 3; // Text of the message + string response_to = 4; // Id of the message being replied to + string ens_name = 5; // Ens name of the sender + string chat_id = 6; // Chat id + MessageType message_type = 7; + ContentType content_type = 8; + + oneof payload { + StickerMessage sticker = 9; + } + + enum MessageType { + UNKNOWN_MESSAGE_TYPE = 0; + ONE_TO_ONE = 1; + PUBLIC_GROUP = 2; + PRIVATE_GROUP = 3; + SYSTEM_MESSAGE_PRIVATE_GROUP = 4; + } + + enum ContentType { + UNKNOWN_CONTENT_TYPE = 0; + TEXT_PLAIN = 1; + STICKER = 2; + STATUS = 3; + EMOJI = 4; + TRANSACTION_COMMAND = 5; + SYSTEM_MESSAGE_CONTENT_PRIVATE_GROUP = 6; + } +} +``` + +### Payload Fields + +| Field | Name | Type | Description | +| ----------- | ----------- | ----------- | ------------------------------------------- | +| 1 | clock | `uint64` | The clock of the chat | +| 2 | timestamp | `uint64` | Sender timestamp at message creation | +| 3 | text | `string` | The content of the message | +| 4 | response_to | `string` | ID of the message replied to | +| 5 | ens_name | `string` | ENS name of the user sending the message | +| 6 | chat_id | `string` | Local ID of the chat | +| 7 | message_type | `MessageType` | Type of message (one-to-one, public, group) | +| 8 | content_type | `ContentType` | Type of message content | +| 9 | payload | `Sticker\|nil` | Payload of the message | + +## Content Types + +Nodes require content types to interpret incoming messages. Not all messages +are plain text; some carry additional information. + +The following content types **MUST** be supported: + +- `TEXT_PLAIN`: Identifies a message with plaintext content. + +Other content types that **MAY** be implemented by clients include: + +- `STICKER` +- `STATUS` +- `EMOJI` +- `TRANSACTION_COMMAND` + +## Mentions + +A mention **MUST** be represented as a string in the `@0xpk` format, +where `pk` is the public key of the user to be mentioned, +within the text field of a message with `content_type: TEXT_PLAIN`. +A message **MAY** contain more than one mention. + +This specification **RECOMMENDS** that the application does not require the user +to enter the entire public key. Instead, it should allow the user +to create a mention by typing `@` followed by the ENS or 3-word pseudonym, +with auto-completion functionality. + +For better user experience, the client **SHOULD** display the ENS name +or 3-word pseudonym corresponding to the key instead of the public key. + +## Sticker Content Type + +A `ChatMessage` with `STICKER` content type **MUST** specify the ID of the pack +and the hash of the pack in the `Sticker` field: + +```protobuf +message StickerMessage { + string hash = 1; + int32 pack = 2; +} +``` + +## Message Types + +A node requires message types to decide how to encrypt a message and what +metadata to attach when passing it to the transport layer. + +The following message types **MUST** be supported: + +- `ONE_TO_ONE`: A one-to-one message. +- `PUBLIC_GROUP`: A message to the public group. +- `PRIVATE_GROUP`: A message to the private group. + +## Clock vs Timestamp and Message Ordering + +If a user sends a new message before receiving messages that were sent while +they were offline, the new message should be displayed last in the chat. + +The Status client speculates that its Lamport timestamp will beat the current +chat timestamp, using the format: `clock = max({timestamp}, chat_clock + 1)`. + +This satisfies the Lamport requirement: if `a -> b`, then `T(a) < T(b)`. + +- `timestamp` **MUST** be Unix time in milliseconds when the node creates the +message. This field **SHOULD** not be relied upon for message ordering. +- `clock` **SHOULD** be calculated using Lamport timestamps, based on the last +received message's clock value: `max(timeNowInMs, last-message-clock-value + 1)`. + +Messages with a clock greater than 120 seconds over the Whisper/Waku timestamp +**SHOULD** be discarded to prevent malicious clock increases. Messages with a +clock less than 120 seconds under the Whisper/Waku timestamp may indicate +attempted insertion into chat history. + +The node uses the clock value for message ordering. The distributed nature of +the system produces casual ordering, which may lead to counter-intuitive results +in edge cases. For example, when a user joins a public chat and sends a message +before receiving previous messages, their message clock might be lower, causing +the message to appear in the past once historical messages are fetched. + +## Chats + +A chat is a structure used to organize messages, helping to display messages +from a single recipient or group of recipients. + +All incoming messages are matched against a chat. The table below shows how to +calculate a chat ID for each message type: + +| Message Type | Chat ID Calculation | Direction | Comment | +| -------------- | ------------------------------------------- | -------------- | --------- | +| PUBLIC_GROUP | Chat ID equals public channel name | Incoming/Outgoing | | +| ONE_TO_ONE | Hex-encode the recipient's public key as chat ID | Outgoing | | +| user-message | Hex-encode the message sender’s public key as chat ID | Incoming | If no match, node may discard or create a new chat | +| PRIVATE_GROUP | Use chat ID from the message | Incoming/Outgoing | If no match, discard message | + +## Contact Update + +`ContactUpdate` notifies peers that the user has been added as a contact or +that user information has changed. + +```protobuf +message ContactUpdate { + uint64 clock = 1; + string ens_name = 2; + string profile_image = 3; +} +``` + +### Payload Fields + +| Field | Name | Type | Description | +| ----------- | ------------- | ------- | ------------------------------------------------ | +| 1 | clock | uint64 | Clock value of the chat with the user | +| 2 | ens_name | string | ENS name if set | +| 3 | profile_image | string | Base64-encoded profile picture of the user | + +A client **SHOULD** send a `ContactUpdate` when: + +- The `ens_name` has changed. +- The profile image is edited. + +Clients **SHOULD** also periodically send `ContactUpdate` messages to contacts. +The Status official client sends these updates every 48 hours. + +## SyncInstallationContact + +The node uses `SyncInstallationContact` messages to synchronize contacts across +devices in a best-effort manner. + +```protobuf +message SyncInstallationContact { + uint64 clock = 1; + string id = 2; + string profile_image = 3; + string ens_name = 4; + uint64 last_updated = 5; + repeated string system_tags = 6; +} +``` + +### Payload Fields + +| Field | Name | Type | Description | +| -------------- | ------------- | ------------- | ----------------------------------------- | +| 1 | clock | uint64 | Clock value of the chat | +| 2 | id | string | ID of the contact synced | +| 3 | profile_image | string | Base64-encoded profile picture of the user | +| 4 | ens_name | string | ENS name of the contact | +| 5 | system_tags | array[string] | System tags like ":contact/added" | + +## SyncInstallationPublicChat + +The node uses `SyncInstallationPublicChat` to synchronize public chats across +devices. + +```protobuf +message SyncInstallationPublicChat { + uint64 clock = 1; + string id = 2; +} +``` + +### Payload Fields + +| Field | Name | Type | Description | +| ----------- | ------ | ------ | --------------------- | +| 1 | clock | uint64 | Clock value of the chat | +| 2 | id | string | ID of the chat synced | + +## PairInstallation + +The node uses `PairInstallation` messages to propagate information about a +device to its paired devices. + +```protobuf +message PairInstallation { + uint64 clock = 1; + string installation_id = 2; + string device_type = 3; + string name = 4; +} +``` + +### Payload Fields + +| Field | Name | Type | Description | +| ----------------- | -------------- | ------ | ---------------------------------------------- | +| 1 | clock | uint64 | Clock value of the chat | +| 2 | installation_id | string | Randomly generated ID that identifies this device | +| 3 | device_type | string | OS of the device (iOS, Android, or desktop) | +| 4 | name | string | Self-assigned name of the device | + +## MembershipUpdateMessage and MembershipUpdateEvent + +`MembershipUpdateEvent` propagates information about group membership changes +in a group chat. The details are covered in the [Group Chats specs](https://specs.status.im/draft/7-group-chat.md). + +## Upgradability + +There are two ways to upgrade the protocol without breaking compatibility: + +- A node always supports accretion. +- A node does not support deletion of existing fields or messages, +which might break compatibility. + +## Security Considerations + +- + +## Changelog + +### Version 0.3 + +- **Released**: May 22, 2020 +- **Changes**: Added language to include Waku in all relevant places. + +## Copyright + +Copyright and related rights waived via CC0. diff --git a/status/8/EIPS.md b/status/8/EIPS.md new file mode 100644 index 00000000..bc65cb2d --- /dev/null +++ b/status/8/EIPS.md @@ -0,0 +1,270 @@ +--- +slug: 8 +title: 8/EIPS +name: EIPS +status: draft +description: Status relation with the EIPs +editor: Ricardo Guilherme Schmidt +contributors: +- +--- + +## Abstract + +This specification describes how Status relates with EIPs. + +## Table of Contents + +- [Abstract] +- [Table of Contents] +- [Introduction] +- [Components] + +## Introduction + +Status should follow standards as much as possible. +Whenever the Status app needs a feature, +it should first check if a standard exists. +If not, Status should propose a new standard. + +## Support Table + +| | Status v0 | Status v1 | Other | State | +| ---------- | --------- | --------- | ----- | ------ | +| BIP32 | N | Y | N | stable | +| BIP39 | Y | Y | Y | stable | +| BIP43 | N | Y | N | stable | +| BIP44 | N | Y | N | stable | +| EIP20 | Y | Y | Y | stable | +| EIP55 | Y | Y | Y | stable | +| EIP67 | P | P | N | stable | +| EIP137 | P | P | N | stable | +| EIP155 | Y | Y | Y | stable | +| EIP165 | P | N | N | stable | +| EIP181 | P | N | N | stable | +| EIP191 | Y? | N | Y | stable | +| EIP627 | Y | Y | N | stable | +| EIP681 | Y | N | Y | stable | +| EIP712 | P | P | Y | stable | +| EIP721 | P | P | Y | stable | +| EIP831 | N | Y | N | stable | +| EIP945 | Y | Y | N | stable | +| EIP1102 | Y | Y | Y | stable | +| EIP1193 | Y | Y | Y | stable | +| EIP1577 | Y | P | N | stable | +| EIP1581 | N | Y | N | stable | +| EIP1459 | N | - | N | raw | + +## Components + +### BIP32 - Hierarchical Deterministic Wallets + +- **Support**: Dependency. +- **Reference**: +[BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) +- **Description**: Enable wallets to derive multiple private keys from the same +seed. +- **Used for**: Dependency of BIP39 and BIP43. + +### BIP39 - Mnemonic Code for Generating Deterministic Keys + +- **Support**: Dependency. +- **Reference**: +[BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) +- **Description**: Enable wallet to create private key based on a safe seed +phrase. +- **Used for**: Security and user experience. + +### BIP43 - Purpose Field for Deterministic Wallets + +- **Support**: Dependency. +- **Reference**: +[BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki) +- **Description**: Enable wallet to create private keys branched for a specific +purpose. +- **Used for**: Dependency of BIP44, uses “ethereum” coin. + +### BIP44 - Multi-Account Hierarchy for Deterministic Wallets + +- **Support**: Dependency. +- **Reference**: +[BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) +- **Description**: Enable wallet to derive multiple accounts on top of BIP39. +- **Used for**: Privacy. +- **Source code**: +[BIP44](https://github.com/status-im/status-mobile/blob/develop/src/status_im/constants.cljs#L240) + +_Observation_: BIP44 doesn’t solve privacy issues regarding transaction +transparency. Connected addresses through transactions can be identified via +“network reconnaissance attacks” on transaction history, which may expose user +privacy despite BIP44. + +### EIP20 - Fungible Token + +- **Support**: Full. +- **Reference**: [EIP20](https://eips.ethereum.org/EIPS/eip-20) +- **Description**: Enable wallets to use tokens based on smart contracts +compliant with this standard. +- **Used for**: Wallet feature. +- **Source code**: +[EIP20](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/tokens.cljs) + +### EIP55 - Mixed-case Checksum Address Encoding + +- **Support**: Full. +- **Reference**: [EIP55](https://eips.ethereum.org/EIPS/eip-55) +- **Description**: Checksum standard that uses lowercase and uppercase inside +address hex value. +- **Used for**: Sanity check of forms using Ethereum addresses. +- **Source code**: +[EIP55](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/eip55.cljs) + +### EIP67 - Standard URI Scheme with Metadata, Value, and Byte Code + +- **Support**: Partial. +- **Reference**: [EIP67](https://github.com/ethereum/EIPs/issues/67) +- **Description**: A standard way of creating Ethereum URIs for various use- +cases. +- **Used for**: Legacy support. + +### EIP137 - Ethereum Domain Name Service + +- **Support**: Partial. +- **Reference**: [EIP137](https://eips.ethereum.org/EIPS/eip-137) +- **Description**: Enable wallets to lookup ENS names. +- **Used for**: User experience, as a wallet and identity feature. +- **Source code**: +[EIP137](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/ens.cljs#L86) + +### EIP155 - Simple Replay Attack Protection + +- **Support**: Full. +- **Reference**: [EIP155](https://eips.ethereum.org/EIPS/eip-155) +- **Description**: Defined chainId parameter in the signed Ethereum transaction +payload. +- **Used for**: Signing transactions, crucial for user safety against replay +attacks. +- **Source code**: +[EIP155](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/core.cljs) + +### EIP165 - Standard Interface Detection + +- **Support**: Dependency/Partial. +- **Reference**: [EIP165](https://eips.ethereum.org/EIPS/eip-165) +- **Description**: Standard interface for contracts to answer if they support +other interfaces. +- **Used for**: Dependency of ENS and EIP721. +- **Source code**: +[EIP165](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/eip165.cljs) + +### EIP181 - ENS Support for Reverse Resolution of Ethereum Addresses + +- **Support**: Partial. +- **Reference**: [EIP181](https://eips.ethereum.org/EIPS/eip-181) +- **Description**: Enable wallets to render reverse resolution of Ethereum +addresses. +- **Used for**: Wallet feature. +- **Source code**: +[EIP181](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/ens.cljs#L86) + +### EIP191 - Signed Message + +- **Support**: Full. +- **Reference**: [EIP191](https://eips.ethereum.org/EIPS/eip-191) +- **Description**: Contract signature standard, adds padding to signed messages +to differentiate from Ethereum transaction messages. +- **Used for**: DApp support, security, dependency of EIP712. + +### EIP627 - Whisper Specification + +- **Support**: Full. +- **Reference**: [EIP627](https://eips.ethereum.org/EIPS/eip-627) +- **Description**: Format of Whisper messages within the ÐΞVp2p Wire Protocol. +- **Used for**: Chat protocol. + +### EIP681 - URL Format for Transaction Requests + +- **Support**: Partial. +- **Reference**: [EIP681](https://eips.ethereum.org/EIPS/eip-681) +- **Description**: A link that pops up a transaction in the wallet. +- **Used for**: QR code data for transaction requests, chat transaction requests, +and DApp links to transaction requests. +- **Source code**: +[EIP681](https://github.com/status-im/status-mobile/blob/develop/src/status_im/ethereum/eip681.cljs) + +### EIP712 - Typed Signed Message + +- **Support**: Partial. +- **Reference**: [EIP712](https://eips.ethereum.org/EIPS/eip-712) +- **Description**: Standardize types for contract signatures, allowing users to +inspect what’s being signed. +- **Used for**: User experience, security. + +### EIP721 - Non-Fungible Token + +- **Support**: Partial. +- **Reference**: [EIP721](https://eips.ethereum.org/EIPS/eip-721) +- **Description**: Enable wallets to use tokens based on smart contracts +compliant with this standard. +- **Used for**: Wallet feature. + +### EIP945 - Web3 QR Code Scanning API + +- **Support**: Full. +- **Reference**: [EIP945](https://github.com/ethereum/EIPs/issues/945) +- **Used for**: Sharing contact code, reading transaction requests. +- **Related**: +[Issue](https://github.com/status-im/status-mobile/issues/5870) + +### EIP1102 - Opt-in Account Exposure + +- **Support**: Full. +- **Reference**: [EIP1102](https://eips.ethereum.org/EIPS/eip-1102) +- **Description**: Allow users to opt-in to expose their Ethereum address to dapps. +- **Used for**: Privacy, DApp support. +- **Related**: +[Issue](https://github.com/status-im/status-mobile/issues/7985) + +### EIP1193 - Ethereum Provider JavaScript API + +- **Support**: Full. +- **Reference**: [EIP1193](https://eips.ethereum.org/EIPS/eip-1193) +- **Description**: Allows dapps to recognize event changes on wallet. +- **Used for**: DApp support. +- **Related**: +[PR](https://github.com/status-im/status-mobile/pull/7246) + +### EIP1577 - Contenthash Field for ENS + +- **Support**: Partial. +- **Reference**: [EIP1577](https://eips.ethereum.org/EIPS/eip-1577) +- **Description**: Allows users to browse ENS domains using the contenthash standard. +- **Used for**: Browser, DApp support. +- **Related**: +[Issue](https://github.com/status-im/status-mobile/issues/6688) +- **Source code**: +[Contenthash](https://github.com/status-im/status-mobile/blob/develop/src/status_im/utils/contenthash.cljs) + +### EIP1581 - Non-wallet Usage of Keys Derived from BIP-32 Trees + +- **Support**: Partial. +- **Reference**: [EIP1581](https://eips.ethereum.org/EIPS/eip-1581) +- **Description**: Allow wallets to derive less sensitive keys (non-wallet). +- **Used for**: Security (don’t reuse wallet key), user experience (no keycard). +- **Related**: +[Issue](https://github.com/status-im/status-mobile/issues/9088) +- **Source code**: +[Constants](https://github.com/status-im/status-mobile/blob/develop/src/status_im/constants.cljs#L242) + +### EIP1459 - Node Discovery via DNS + +- **Support**: N/A. +- **Reference**: [EIP1459](https://eips.ethereum.org/EIPS/eip-1459) +- **Description**: Storing and retrieving nodes via merkle trees in TXT domain records. +- **Used for**: Finding Waku nodes. + +--- + +## Copyright + +Copyright and related rights waived via CC0. diff --git a/status/9/account-address.md b/status/9/ethereum-usage.md similarity index 100% rename from status/9/account-address.md rename to status/9/ethereum-usage.md