├── data └── .keep ├── .gitignore ├── algorand ├── README.md └── setting-up.md ├── ethereum-instructions ├── README.md └── setting-up.md ├── substrate-instructions ├── README.md ├── starting-and-stopping-the-indexer.md ├── setting-up.md ├── installing-starting-stopping-the-indexer.md └── installing-the-indexer.md ├── static └── favicon.ico ├── .gitbook └── assets │ ├── image.png │ ├── image (1).png │ ├── image (10).png │ ├── image (11).png │ ├── image (12).png │ ├── image (13).png │ ├── image (14).png │ ├── image (2).png │ ├── image (3).png │ ├── image (4).png │ ├── image (5).png │ ├── image (6).png │ ├── image (7).png │ ├── image (8).png │ ├── image (9).png │ ├── image (4) (1).png │ └── image (6) (1).png ├── .gitmodules ├── config.toml ├── mailchain-web-inbox ├── mailchain-web-interface.md └── configuring-the-web-interface.md ├── getting-started.md ├── running-the-application.md ├── reference ├── types.md ├── polkadot │ ├── substrate-transaction-indexer.md │ └── README.md ├── ethereum.md ├── polkadot.md ├── programmable-envelopes.md └── algorand.md ├── concepts ├── overview.md ├── receive.md ├── read.md └── send.md ├── advanced-configuration ├── advanced-server-options.md ├── advanced-ethereum-json-rpc-endpoint-configuration.md ├── setting-up.md ├── mailchain-settings-viewing-and-updating.md └── advanced-storage-configuration.md ├── README.md ├── upgrading.md ├── troubleshooting ├── common-inbox-errors.md └── troubleshooting.md ├── setting-up.md ├── SUMMARY.md ├── installation.md ├── development └── sending-testnet-messages.md ├── mailchain-connectors └── mailchain-connector-imap.md └── LICENSE /data/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | public -------------------------------------------------------------------------------- /algorand/README.md: -------------------------------------------------------------------------------- 1 | # Algorand Instructions 2 | 3 | -------------------------------------------------------------------------------- /ethereum-instructions/README.md: -------------------------------------------------------------------------------- 1 | # Ethereum Instructions 2 | 3 | -------------------------------------------------------------------------------- /substrate-instructions/README.md: -------------------------------------------------------------------------------- 1 | # Substrate Instructions 2 | 3 | -------------------------------------------------------------------------------- /static/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/static/favicon.ico -------------------------------------------------------------------------------- /.gitbook/assets/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image.png -------------------------------------------------------------------------------- /.gitbook/assets/image (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (10).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (10).png -------------------------------------------------------------------------------- /.gitbook/assets/image (11).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (11).png -------------------------------------------------------------------------------- /.gitbook/assets/image (12).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (12).png -------------------------------------------------------------------------------- /.gitbook/assets/image (13).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (13).png -------------------------------------------------------------------------------- /.gitbook/assets/image (14).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (14).png -------------------------------------------------------------------------------- /.gitbook/assets/image (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (2).png -------------------------------------------------------------------------------- /.gitbook/assets/image (3).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (3).png -------------------------------------------------------------------------------- /.gitbook/assets/image (4).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (4).png -------------------------------------------------------------------------------- /.gitbook/assets/image (5).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (5).png -------------------------------------------------------------------------------- /.gitbook/assets/image (6).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (6).png -------------------------------------------------------------------------------- /.gitbook/assets/image (7).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (7).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (8).png -------------------------------------------------------------------------------- /.gitbook/assets/image (9).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (9).png -------------------------------------------------------------------------------- /.gitbook/assets/image (4) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (4) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (6) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mailchain/docs.mailchain.xyz/master/.gitbook/assets/image (6) (1).png -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "themes/hugo-apex-theme"] 2 | path = themes/hugo-apex-theme 3 | url = https://github.com/caarlos0/hugo-apex-theme.git 4 | -------------------------------------------------------------------------------- /config.toml: -------------------------------------------------------------------------------- 1 | baseURL = "https://docs.mailchain.xyz/" 2 | LanguageCode = "en-us" 3 | title = "Mailchain" 4 | copyright = "Made with ❤️ by Mailchain contributors." 5 | theme = "hugo-apex-theme" 6 | pygmentsCodeFences = true 7 | pygmentsStyle = "dracula" 8 | 9 | [params] 10 | logo = "https://mailchain.xyz/images/app-logo-512.png" 11 | ghdocsrepo = "https://github.com/mailchain/docs.mailchain.xyz/tree/master" 12 | name = "Mailchain" 13 | description = "Email-like messaging for blockchain accounts and public addresses" 14 | twitter = "mailchain_xyz" 15 | -------------------------------------------------------------------------------- /substrate-instructions/starting-and-stopping-the-indexer.md: -------------------------------------------------------------------------------- 1 | # Starting and Stopping the Indexer 2 | 3 | Ensure you have [installed the indexer](installing-the-indexer.md). 4 | 5 | ### Starting the Indexer 6 | 7 | To start the indexer container, run: 8 | 9 | ```bash 10 | docker-compose -f ~/docker/mailchain/docker-compose.substrate.yml up --build 11 | ``` 12 | 13 | NOTE: You may need to adjust the path to the location you downloaded your docker-compose file. 14 | 15 | ### Stopping the Indexer 16 | 17 | To gracefully stop the receiver, press `Ctrl+C`. 18 | 19 | -------------------------------------------------------------------------------- /mailchain-web-inbox/mailchain-web-interface.md: -------------------------------------------------------------------------------- 1 | # Mailchain Web Interface 2 | 3 | You can access the Mailchain web interface to send and receive messages by visiting [https://inbox.mailchain.xyz](https://inbox.mailchain.xyz). 4 | 5 | ![The Mailchain Web Interface](../.gitbook/assets/image%20%286%29.png) 6 | 7 | {% hint style="info" %} 8 | The Mailchain web interface communicates with the Mailchain application. You need to be running the mailchain command line application first. For more information, see [installing](../getting-started.md#quick-install) and [serving](../getting-started.md#serve) the application. 9 | {% endhint %} 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Instructions on how to get started with Mailchain 3 | --- 4 | 5 | # Getting Started 6 | 7 | In this guide, we’ll walk you through how to install Mailchain onto your machine. Then we’ll setup the application to send, then receive messages. 8 | 9 | Installing Mailchain is easy: 10 | 11 | * First, you install the application onto your local machine. See [Installation](installation.md) page for details. 12 | * Then you’ll add a private key to send and receive messages. See the appropriate instructions for setting up [Ethereum](ethereum-instructions/) or [Substrate](substrate-instructions/). 13 | * Then, you can then navigate to the web interface [https://inbox.mailchain.xyz](https://inbox.mailchain.xyz) and start working. 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /running-the-application.md: -------------------------------------------------------------------------------- 1 | # Running the Application 2 | 3 | ## Serve 4 | 5 | After you have configured your account\(s\), and any other steps required for the protocol you will be sending messages with, you are ready to start the application and the api. 6 | 7 | To start the application, run: 8 | 9 | ```bash 10 | mailchain serve 11 | ``` 12 | 13 | _When prompted enter the same passphrase as when you added the account._ 14 | 15 | You are now ready to start sending and receiving mails. Navigate to [https://inbox.mailchain.xyz](https://inbox.mailchain.xyz) to see your mailbox. 16 | 17 | The Mailchain web interface has all the functionality needed to send and receive messages. It's easy and fun to use. For more information on switching between protocols and networks, see [Mailchain Web Interface](mailchain-web-inbox/mailchain-web-interface.md). 18 | 19 | -------------------------------------------------------------------------------- /reference/types.md: -------------------------------------------------------------------------------- 1 | # Types 2 | 3 | ## Message Location Identifier 4 | 5 | Data stored in a transaction costs. Encoding [https://message-location-domain.com/](https://message-location-domain.com/) is inefficient due to each char needs 1 byte for storage. A reasonable minimum domain name with a length of 3, minimum top level domain \(TLD\) size 2, plus schema 4/5 \(e.g. http/https\), and separators "://". The minimum expected size is 15, e.g. [https://mcx.mx/](https://mcx.mx/). A unsigned int of variable size can represent 18446744073709551615 mappings in a max of 10 bytes. 6 | 7 | 8 | ## Uint64Bytes 9 | 10 | Typed tuple that combines a variable sized integer and byte array in a single byte array to reduce the number of bytes needed to store both fields. The motivation behind this data type is to reduce the padding requirements to encrypt a variable sized integer. 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /reference/polkadot/substrate-transaction-indexer.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | The Mailchain Substrate Transaction Indexer makes it possible to listen for 4 | Mailchain messages on Substrate chains where the contracts module is 5 | configured for configured account addresses 6 | --- 7 | 8 | # Substrate Transaction Indexer 9 | 10 | Substrate does not natively support an address index or similar functionality that identifies all transactions sent to or from a specific address. 11 | 12 | The Mailchain Substrate Transaction Indexer makes it possible to listen for Mailchain messages in Substrate extrinsics for configured accounts. The Mailchain API can then retrieve mailchain messages from the indexer for those configured accounts. 13 | 14 | The latest version of the substrate indexer can be found here: [https://github.com/mailchain/mailchain/blob/master/docker-compose.substrate.yml](https://github.com/mailchain/mailchain/blob/master/docker-compose.substrate.yml) 15 | 16 | -------------------------------------------------------------------------------- /concepts/overview.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | The majority of blockchain protocols provide no standard way to handle messaging. Some account holders have sent messages as an encrypted or unencrypted string included in transaction data. Some applications work around the problem by asking users to link another method of contact \(e.g. email address, phone number etc.\) to an application. This compromises anonymity by asking users to link or reveal an identity. It also increases exposure to security risks, and relies on additional centralized services. 4 | 5 | Mailchain gives users the ability to [send](send.md), [receive](receive.md), and [read](read.md) rich-media HTML messages between public addresses through a simple, email-like interface. All message contents and attachments are encrypted so only the intended recipient of the message can decrypt and view messages. 6 | 7 | ### Protocols 8 | 9 | Mailchain is a simple, secure and practical standard which can be implemented across different blockchain protocols. It uses underlying native blockchain protocol foundational capabilities including addressing, transaction history, data transmission, and cryptography. 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /advanced-configuration/advanced-server-options.md: -------------------------------------------------------------------------------- 1 | # Advanced Serve Options 2 | 3 | The mailchain application runs with the default settings using the following command: 4 | 5 | ```bash 6 | mailchain serve 7 | ``` 8 | 9 | To configure advanced options, run: 10 | 11 | ```bash 12 | mailchain serve [flags] 13 | ``` 14 | 15 | | Flag | Options | 16 | | :--- | :--- | 17 | | --cors-allowed-origins _string_ | Allowed origins for CORS \(default "\*"\) | 18 | | --cors-disabled | Disable CORS on the server \(enabled by default\) | 19 | | --passphrase _string_ | Passphrase to decrypt key for sending / receiving messages. If this is not entered, the application with prompt you to enter the passphrase. | 20 | | --port _int_ | Port to run server on \(default 8080\) | 21 | 22 | Global Flags 23 | 24 | | Flag | Options | 25 | | :--- | :--- | 26 | | --config _string_ | The location of the config file \(default is $HOME/.mailchain/.mailchain.yaml\) | 27 | | --empty-passphrase | No passphrase and no prompt | 28 | | --log-level _string_ | Set the log level \[Panic,Fatal,Error,Warn,Info,Debug\] \(default "warn"\) | 29 | 30 | For more information, run: 31 | 32 | ```bash 33 | mailchain serve --help 34 | ``` 35 | 36 | 37 | 38 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | [Mailchain](https://github.com/mailchain/mailchain) enables blockchain-based email-like messaging with plain or rich text and attachment capabilities. Using blockchain protocols and decentralized storage, Mailchain delivers a simple, secure, messaging experience. 4 | 5 | Account holders or owners of a public address often need to communicate in the context of the account or public address. Communication may relate to transactions, account actions or some type of notification. 6 | 7 | Examples of use cases for blockchain messaging include invoicing, receipts, contacting users of a service or application developers. 8 | 9 | The majority of blockchain protocols provide no standard way to handle messaging. Some account holders have sent messages as an encrypted or unencrypted string included in transaction data. Some applications work around the problem by asking users to link another method of contact \(e.g. email address, phone number etc.\) to an application. This compromises anonymity by asking users to link or reveal an identity. It also increases exposure to security risks, and relies on additional centralized services. 10 | 11 | Visit [Getting Started](getting-started.md) to install the application and start sending and receiving messages. 12 | 13 | -------------------------------------------------------------------------------- /substrate-instructions/setting-up.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | After installation, to start sending Mailchain messages on Substrate, follow 4 | the steps below... 5 | --- 6 | 7 | # Setting Up 8 | 9 | ## Add Account 10 | 11 | To send and receive messages with Mailchain on Substrate, you will need to add an existing account \(or create a new one and save the raw seed\). 12 | 13 | ```bash 14 | mailchain account add --protocol=substrate --private-key=[PRIVATE-KEY-VALUE] --key-type=sr25519 15 | ``` 16 | 17 | * `--protocol=substrate` 18 | * `--private-key` is the raw seed of your account to be able to sign and decrypt messages. 19 | * `--key-type=` either `sr25519` or `ed25519` \(for Substrate\). The account type is selected when you create a substrate account. 20 | 21 | {% hint style="info" %} 22 | _Mailchain stores your private key in an encrypted format, a passphrase is required._ 23 | 24 | Enter a non-guessable passphrase, and again to confirm it. You must remember your password to decrypt the key later to send or receive messages. 25 | {% endhint %} 26 | 27 | {% hint style="danger" %} 28 | You should never expose your private keys to an entity you don't trust. 29 | 30 | Mailchain stores your private key locally, in an encrypted format. Your private keys are never sent anywhere. They are only used to decrypt messages data, and sign transactions. 31 | {% endhint %} 32 | 33 | -------------------------------------------------------------------------------- /concepts/receive.md: -------------------------------------------------------------------------------- 1 | # Receive 2 | 3 | Messages are received by querying transactions sent to an address via the address index. This is then filtered for transactions containing a Mailchain envelope. [Envelopes](../reference/programmable-envelopes.md) are then decoded to extract message contents. 4 | 5 | Because each blockchain protocol may have differences in the way data and transactions are handled, Mailchain uses a standard format plus any protocol specifics. 6 | 7 | ### Address Index 8 | 9 | To see all recipient messages, a list of all transactions sent to that recipient is required. Not all blockchain protocols have an address index as part of the core implementation. If this does not exist, a third party or custom index can be used to build the index. 10 | 11 | ### Filtering 12 | 13 | Once the address index returns all of the transactions received by an address, they need to be filtered to extract transactions that contain Mailchain envelopes in transaction data field. The expected format is: 14 | 15 | ```text 16 | [protocol-prefix]+[mailchain-prefix]+[envelope] 17 | ``` 18 | 19 | The filtering removes the prefix and searches for a `mailchain-prefix`. 20 | 21 | ### Decoding Envelope 22 | 23 | Programmable envelopes contain message information fields: URL, IntegrityHash, and ContentsHash. This information allows the recipient to download, validate, and verify the message. Decoding the envelope removes the `[protocol-prefix]`and `[mailchain-prefix]` to leave the `[envelope]` bytes for processing the message. 24 | 25 | 26 | 27 | 28 | 29 | -------------------------------------------------------------------------------- /advanced-configuration/advanced-ethereum-json-rpc-endpoint-configuration.md: -------------------------------------------------------------------------------- 1 | # Advanced Ethereum JSON-RPC Endpoint Configuration 2 | 3 | ### Configuring Mailchain to Use a Custom Ethereum JSON-RPC Endpoint 4 | 5 | You can use a 3rd party API or your own node to send \(broadcast\) your message \(transaction\) to a blockchain. 6 | 7 | A JSON-RPC Endpoint is required to send transactions, a node is required for each network you want to send transactions on. There are different options for getting access to a JSON-RPC endpoint, we recommend using [Infura](https://infura.io/), its a managed service and there is no cost. 8 | 9 | * [Infura](https://infura.io/) - Sign up for an account and create an endpoint. Each endpoint has a unique URL. 10 | * [Go Ethereum](https://geth.ethereum.org/) - [Install](https://geth.ethereum.org/install-and-build/Installing-Geth) and run a node. You can enable the JSON-RPC Endpoint and [obtain](https://github.com/ethereum/wiki/wiki/JSON-RPC#json-rpc-endpoint) the URL. 11 | * [Parity](https://www.parity.io/) - [Install](https://www.parity.io/ethereum/#download) and enable the JSON-RPC Endpoint and [obtain](https://wiki.parity.io/JSONRPC) the URL. 12 | 13 | In each case the URL is supplied when [initializing](../getting-started.md#initialize) the Mailchain application. 14 | 15 | {% hint style="info" %} 16 | We are working to remove the requirement of having access to a JSON-RPC Endpoint, you can track the progress at [this issue](https://github.com/mailchain/mailchain/issues/120). Subscribe to notifications to track our progress. 17 | {% endhint %} 18 | 19 | -------------------------------------------------------------------------------- /mailchain-web-inbox/configuring-the-web-interface.md: -------------------------------------------------------------------------------- 1 | # Configuring the Web Interface 2 | 3 | ## Changing the network 4 | 5 | To change between different networks, click the 'change' link in the top right of the inbox. 6 | 7 | ![Accessing the Mailchain Network Settings](../.gitbook/assets/image%20%287%29.png) 8 | 9 | Selecting a network from the dropdown will change the network and refresh the inbox. 10 | 11 | ![Mailchain Network Settings](../.gitbook/assets/image%20%286%29%20%281%29.png) 12 | 13 | Click 'Close' when you are finished. 14 | 15 | ## Changing the Server Settings 16 | 17 | {% hint style="info" %} 18 | See Advanced Configuration > [Advanced Serve Options](../advanced-configuration/advanced-server-options.md) to change how the mailchain application settings 19 | {% endhint %} 20 | 21 | To change how the Mailchain web interface interacts with your mailchain application, you can update the Server Settings in the top right of the inbox. 22 | 23 | ![Accessing the Server Settings](../.gitbook/assets/image%20%283%29.png) 24 | 25 | Update any of the settings as needed to communicate with the mailchain application and click 'Save' when finished. 26 | 27 | ![Server Settings](../.gitbook/assets/image%20%284%29%20%281%29.png) 28 | 29 | | Setting | Description | Default | 30 | | :--- | :--- | :--- | 31 | | Web Protocol | The protocol used to reach the application | http | 32 | | Host | The host serving the mailchain application, e.g. localhost, www.example.com, 127.0.0.1 | 127.0.0.1 | 33 | | Port | The port on the host serving the mailchain application | 8080 | 34 | 35 | -------------------------------------------------------------------------------- /advanced-configuration/setting-up.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | After installation, to start sending Mailchain messages, follow the steps 4 | below... 5 | --- 6 | 7 | # Advanced Set Up 8 | 9 | ## Add Account 10 | 11 | To send and receive messages with Mailchain you will need to add an account. 12 | 13 | Specific instructions for supported protocols can be found here: 14 | 15 | * [Ethereum](../ethereum-instructions/setting-up.md) 16 | * [Substrate](../substrate-instructions/setting-up.md) 17 | 18 | ```bash 19 | mailchain account add --protocol=[PROTOCOL] --private-key=[PRIVATE-KEY-VALUE] --key-type=[KEY-TYPE] 20 | ``` 21 | 22 | * `--protocol` currently supported protocols are: `ethereum` and `substrate`. 23 | * `--private-key`of your account to be able to sign and decrypt messages. 24 | 25 | `--passphrase` can be optionally supplied in the command line or at the prompt when the application starts. 26 | 27 | * `--key-type` includes `secp256k1` \(default for Ethereum\), `ed25519` \(default for Substrate\), `sr25519` \(Substrate\) 28 | 29 | {% hint style="info" %} 30 | _Mailchain stores your private key in an encrypted format, a passphrase is required._ 31 | 32 | Enter a non-guessable passphrase, and again to confirm it. You must remember your password to decrypt the key later to send or receive messages. 33 | {% endhint %} 34 | 35 | {% hint style="danger" %} 36 | You should never expose your private keys to an entity you don't trust. 37 | 38 | Mailchain stores your private key locally, in an encrypted format. Your private keys are never sent anywhere. They are only used to decrypt messages data, and sign transactions. 39 | {% endhint %} 40 | 41 | 42 | 43 | -------------------------------------------------------------------------------- /algorand/setting-up.md: -------------------------------------------------------------------------------- 1 | # Setting Up 2 | 3 | ## Add Account 4 | 5 | To send and receive messages with Mailchain on Algorand, you will need to add an existing account \(or create a new one and save the 25 word mnemonic phrase\). 6 | 7 | ```text 8 | mailchain account add --protocol=algorand --network=[NETWORK] --private-key-encoding=mnemonic/algorand --private-key=[PRIVATE-MNEMONIC-STRING-VALUE] --key-type=ed25519 9 | ``` 10 | 11 | * `--network=mainnet` or a testnet you are working on. 12 | * `--private-key-encoding=mnemonic/algorand` is the encoding used for supplied private key 13 | * `--private-key` is the 25 word mnemonic phrase of your account to be able to sign and decrypt messages. 14 | * `--key-type=ed25519` \(for Algorand\). 15 | 16 | {% hint style="info" %} 17 | _Mailchain stores your private key/ mnemonic phrase in an encrypted format, a passphrase is required._ 18 | 19 | Enter a non-guessable passphrase, and again to confirm it. You must remember your password to decrypt the key later to send or receive messages. 20 | {% endhint %} 21 | 22 | {% hint style="danger" %} 23 | You should never expose your private keys mnemonic phrase to an entity you don't trust. 24 | 25 | Mailchain stores your private key locally, in an encrypted format. Your private keys are never sent anywhere. They are only used to decrypt messages data, and sign transactions. 26 | {% endhint %} 27 | 28 | ## Mailchain Settings 29 | 30 | By default, Mailchain comes preconfigured with some default values to make it easier to get started. [Algoexplorer](https://algoexplorer.io/) is configured by default to query the received messages. 31 | 32 | To change the API lookup settings in the Mailchain Client, follow the instructions here: [Mailchain Settings: Viewing and Updating](../advanced-configuration/mailchain-settings-viewing-and-updating.md) 33 | 34 | 35 | 36 | -------------------------------------------------------------------------------- /ethereum-instructions/setting-up.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | After installation, to start sending Mailchain messages on Ethereum, follow 4 | the steps below... 5 | --- 6 | 7 | # Setting Up 8 | 9 | ## Add Account 10 | 11 | To send and receive messages with Mailchain on Ethereum, you will need to add an existing account \(or create a new one and save the private key\). 12 | 13 | ```bash 14 | mailchain account add --protocol=ethereum --network=mainnet --private-key=[PRIVATE-KEY-VALUE] --key-type=secp256k1 15 | ``` 16 | 17 | * `--protocol=ethereum` 18 | * `--network=mainnet` or a testnet you are working on. 19 | * `--private-key`of your account to be able to sign and decrypt messages. 20 | * `--key-type=secp256k1` \(for Ethereum\). 21 | 22 | {% hint style="info" %} 23 | _Mailchain stores your private key in an encrypted format, a passphrase is required._ 24 | 25 | Enter a non-guessable passphrase, and again to confirm it. You must remember your password to decrypt the key later to send or receive messages. 26 | {% endhint %} 27 | 28 | {% hint style="danger" %} 29 | You should never expose your private keys to an entity you don't trust. 30 | 31 | Mailchain stores your private key locally, in an encrypted format. Your private keys are never sent anywhere. They are only used to decrypt messages data, and sign transactions. 32 | {% endhint %} 33 | 34 | ## Mailchain Settings 35 | 36 | By default, Mailchain comes preconfigured with some default values to make it easier to get started. Etherscan is configured by default, but Etherscan recently made it a requirement to use an API key to access the API. 37 | 38 | To obtain an API key, follow the instructions here: [https://etherscan.io/apis](https://etherscan.io/apis). 39 | 40 | To add the API key to the Mailchain Client, follow the instructions here: [Mailchain Settings: Viewing and Updating](../advanced-configuration/mailchain-settings-viewing-and-updating.md) 41 | 42 | 43 | 44 | -------------------------------------------------------------------------------- /upgrading.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Instructions on how to upgrade to the latest version of Mailchain 3 | --- 4 | 5 | # Updating Mailchain 6 | 7 | ## What Version of Mailchain Am I Running? 8 | 9 | To check which version of Mailchain you are running, use the `mailchain version` command. For example:\` 10 | 11 | ```bash 12 | $ mailchain version 13 | Version: v0.0.36 14 | ``` 15 | 16 | The latest release version can be seen on the [Mailchain releases page on Github](https://github.com/mailchain/mailchain/releases/latest). 17 | 18 | ## Upgrade on a Mac via Homebrew 19 | 20 | If you used [Homebrew](https://brew.sh/) to install Mailchain, you can easily upgrade by running: 21 | 22 | ```bash 23 | brew upgrade mailchain 24 | ``` 25 | 26 | #### Checking if Mailchain was installed using Homebrew 27 | 28 | You can check if Mailchain was installed with Homebrew by running: 29 | 30 | ```bash 31 | brew list mailchain 32 | ``` 33 | 34 | Installed: `/usr/local/Cellar/mailchain/X.Y.Z/bin/mailchain` 35 | 36 | Not installed: `Error: No such keg: /usr/local/Cellar/mailchain` 37 | 38 | ## Quick Upgrade \(Linux and Windows\) 39 | 40 | To upgrade Mailchain suing the installation scripts, run the following command to download and upgrade the application on your local machine. 41 | 42 | ```bash 43 | curl -sL https://run.mailchain.xyz/install.sh | sh 44 | ``` 45 | 46 | ## Manual Upgrade 47 | 48 | To choose where to store the application, you can install mailchain manually. 49 | 50 | ### Download the latest release 51 | 52 | Download the application directly via the [Mailchain releases](https://github.com/mailchain/mailchain/releases/latest) page. Save it to the directory you initially saved mailchain to \(we recommended you save it in your home directory: `~/.mailchain/bin`\). 53 | 54 | #### Checking where Mailchain is saved to: 55 | 56 | To check where Mailchain was saved to, run the following command in Terminal: 57 | 58 | ```bash 59 | which mailchain 60 | ``` 61 | 62 | ## 63 | 64 | 65 | 66 | -------------------------------------------------------------------------------- /troubleshooting/common-inbox-errors.md: -------------------------------------------------------------------------------- 1 | # Common Inbox Errors 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 21 | 22 | 23 | 25 | 32 | 33 | 34 | 37 | 44 | 45 | 46 |
ErrorFix
"Mailchain client does not seem to be running" 14 |
    15 |
  1. Check you have downloaded and configured the 16 | Mailchain client.
    2. 17 |
  2. Check your server settings are 18 | correct.
    3. 19 |
20 |
"Your Mailchain client version is A.B.C. Please upgrade it to version 24 | X.Y.Z to ensure things work as expected." 26 |

See Upgrading Mailchain for further information 27 | on how to upgrade.

28 |

29 |

NOTE: To check the latest release version, visit Mailchain releases on Github 30 |

31 |
"Error 500: could not send message: could not send transaction: Insufficient 35 | funds. The account you tried to send transaction from does not have enough 36 | funds. Required 46528000000000 and got: 0." 38 |

The address you are sending FROM does not have enough balance to pay the 39 | gas cost to send a transaction.

40 |

41 |

Check that you are sending on the right network and that you have a balance 42 | on that account.

43 |
47 | 48 | 49 | 50 | -------------------------------------------------------------------------------- /advanced-configuration/mailchain-settings-viewing-and-updating.md: -------------------------------------------------------------------------------- 1 | # Mailchain Settings: Viewing and Updating 2 | 3 | By default, Mailchain comes preconfigured with some default values to make it easier to get started. 4 | 5 | To configure your own values, for example, adding your API Key for Etherscan to retrieve your messages, you can edit the config \(by default located in `~/.mailchain/.mailchain.yaml` \) 6 | 7 | By default, `mailchain.yaml` only has a few lines of config, e.g. 8 | 9 | ```text 10 | server: 11 | cors: 12 | disabled: false 13 | port: 8080 14 | version: 0.0.65 15 | ``` 16 | 17 | Each value you add to the config overrides the default value. To view the current values, run the following command: 18 | 19 | ```text 20 | mailchain settings view 21 | ``` 22 | 23 | It will show the default values with `#` in front. 24 | 25 | ![Mailchain default settings](../.gitbook/assets/image%20%2814%29.png) 26 | 27 | To edit the values, for example, adding an Etherscan.io API Key \(available [here](https://etherscan.io/myapikey)\) to be able to poll their API and check for new messages on Ethereum Mainnet, add the following to you config file: 28 | 29 | ```text 30 | server: 31 | cors: 32 | disabled: false 33 | port: 8080 34 | protocols: 35 | ethereum: 36 | networks: 37 | mainnet: 38 | public-key-finder: "etherscan" 39 | receiver: "etherscan" 40 | public-key-finders: 41 | etherscan: 42 | api-key: "" 43 | receivers: 44 | etherscan: 45 | api-key: "" 46 | ``` 47 | 48 | Now if you run the `mailchain settings view` command again, you will see that the config shows in the output without the `#` before the line: 49 | 50 | ![](../.gitbook/assets/image%20%2812%29.png) 51 | 52 | ![](../.gitbook/assets/image%20%2811%29.png) 53 | 54 | ![](../.gitbook/assets/image%20%2810%29.png) 55 | 56 | Now, when you run `mailchain serve`, the Mailchain API client will be using the values you configured. 57 | 58 | To revert to defaults, simply remove the value from the config file. 59 | 60 | -------------------------------------------------------------------------------- /troubleshooting/troubleshooting.md: -------------------------------------------------------------------------------- 1 | # Command Line Errors 2 | 3 | The table below give common reasons for error found in the output of the mailchain command line application: 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 18 | 19 | 20 | 21 | 24 | 25 | 26 | 28 | 35 | 36 | 37 | 40 | 43 | 44 | 45 |
ErrorLikely Cause
ERRO[ {date} ] status 500: secretbox: Could not decrypt invalid inputMessage has been retrieved but could not be decrypted. Ensure you entered 17 | the right passphrase for your keystore.
ERRO[ {date} ] status 500: insufficient funds for gas * price + valueThe balance on this address is insufficient to send a message. If you 23 | have a balance, check you are sending on the correct network.
ERRO[ {date} ] status 500: No transactions found for address 27 | 29 |

The recipient address has not yet sent a transaction on this network. 30 | This means the public key associated with the address is not available 31 | to encrypt the message.

32 |

To resolve this, the recipient address needs to have sent at least one 33 | transaction (even zero value).

34 |
ERRO[ {date} ] status 500: Transaction gas price is too low. There is 38 | another transaction with same nonce in the queue. Try increasing the gas 39 | price or incrementing the nonce.There is another transaction (or message) waiting to be accepted into 41 | a block with the same nonce. 42 |
Try waiting a few seconds and then trying again.
46 | 47 | 48 | 49 | -------------------------------------------------------------------------------- /setting-up.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | After installation, to start sending Mailchain messages, follow the steps 4 | below... 5 | --- 6 | 7 | # Setting Up 8 | 9 | ## Add Account 10 | 11 | To send and receive messages with Mailchain you will need to add an account. To do this you will need a private key for an Ethereum account. 12 | 13 | ```bash 14 | mailchain account add --protocol=ethereum --private-key=[PRIVATE-KEY-VALUE] --key-type=[KEY-TYPE] 15 | ``` 16 | 17 | * `--protocol` is the protocol which the key is added to. Currently supported `[ethereum]`. 18 | * `--private-key` the private key value which should be added. The public key and account will be calculated. 19 | * `--passphrase` is can be optionally supplied in the command line or at the prompt when the application starts. 20 | * `--key-type` includes `secp256k1` \(default for Ethereum\), `ed25519` \(default for Polkadot\), `sr25519` \(Polkadot\) 21 | 22 | {% hint style="info" %} 23 | _Mailchain stores your private key in an encrypted format, a passphrase is required._ 24 | 25 | Enter a non-guessable passphrase, and again to confirm it. You must remember your password to decrypt the key later to send or receive messages. 26 | {% endhint %} 27 | 28 | {% hint style="danger" %} 29 | You should never expose your private keys to an entity you don't trust. 30 | 31 | Mailchain stores your private key locally, in an encrypted format. Your private keys are never sent anywhere. They are only used to decrypt messages data, and sign transactions. 32 | {% endhint %} 33 | 34 | ## Serve 35 | 36 | After you have added the account, you are ready to start the application and serve the api. 37 | 38 | To start the application, run: 39 | 40 | ```bash 41 | mailchain serve 42 | ``` 43 | 44 | _When prompted enter the same passphrase as when you added the account._ 45 | 46 | You are now ready to start sending and receiving mails. Navigate to [https://inbox.mailchain.xyz](https://inbox.mailchain.xyz) to see your mailbox. 47 | 48 | The Mailchain web interface has all the functionality needed to send and receive messages. It's easy and fun to use. For more information on switching between Mainnet and testnets, see [Mailchain Web Interface](mailchain-web-inbox/mailchain-web-interface.md). 49 | 50 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | 3 | * [Introduction](README.md) 4 | * [Getting Started](getting-started.md) 5 | * [Installation](installation.md) 6 | * [Ethereum Instructions](ethereum-instructions/README.md) 7 | * [Setting Up](ethereum-instructions/setting-up.md) 8 | * [Algorand Instructions](algorand/README.md) 9 | * [Setting Up](algorand/setting-up.md) 10 | * [Substrate Instructions](substrate-instructions/README.md) 11 | * [Setting Up](substrate-instructions/setting-up.md) 12 | * [Installing, Starting & Stopping The Indexer](substrate-instructions/installing-starting-stopping-the-indexer.md) 13 | * [Running the Application](running-the-application.md) 14 | * [Updating Mailchain](upgrading.md) 15 | 16 | ## Concepts 17 | 18 | * [Overview](concepts/overview.md) 19 | * [Send](concepts/send.md) 20 | * [Receive](concepts/receive.md) 21 | * [Read](concepts/read.md) 22 | 23 | ## Mailchain Web Inbox 24 | 25 | * [Mailchain Web Interface](mailchain-web-inbox/mailchain-web-interface.md) 26 | * [Configuring the Web Interface](mailchain-web-inbox/configuring-the-web-interface.md) 27 | 28 | ## Troubleshooting 29 | 30 | * [Command Line Errors](troubleshooting/troubleshooting.md) 31 | * [Common Inbox Errors](troubleshooting/common-inbox-errors.md) 32 | 33 | ## Advanced Configuration 34 | 35 | * [Mailchain Settings: Viewing and Updating](advanced-configuration/mailchain-settings-viewing-and-updating.md) 36 | * [Advanced Storage Configuration](advanced-configuration/advanced-storage-configuration.md) 37 | * [Advanced Ethereum JSON-RPC Endpoint Configuration](advanced-configuration/advanced-ethereum-json-rpc-endpoint-configuration.md) 38 | * [Advanced Set Up](advanced-configuration/setting-up.md) 39 | * [Advanced Serve Options](advanced-configuration/advanced-server-options.md) 40 | 41 | ## Reference 42 | 43 | * [Algorand](reference/algorand.md) 44 | * [Ethereum](reference/ethereum.md) 45 | * [Substrate \(Polkadot\)](reference/polkadot/README.md) 46 | * [Substrate Transaction Indexer](reference/polkadot/substrate-transaction-indexer.md) 47 | * [Programmable Envelopes](reference/programmable-envelopes.md) 48 | * [Types](reference/types.md) 49 | 50 | ## Development 51 | 52 | * [Sending Ethereum Testnet Messages](development/sending-testnet-messages.md) 53 | 54 | ## Mailchain Connectors 55 | 56 | * [Mailchain Connector for IMAP](mailchain-connectors/mailchain-connector-imap.md) 57 | 58 | -------------------------------------------------------------------------------- /substrate-instructions/installing-starting-stopping-the-indexer.md: -------------------------------------------------------------------------------- 1 | # Installing, Starting & Stopping The Indexer 2 | 3 | ### Installation 4 | 5 | The transaction indexer comes as a docker cluster which runs locally. 6 | 7 | #### Prerequisites 8 | 9 | [Docker](https://www.docker.com/) should be installed and running. 10 | 11 | Clone the Mailchain repository to your `.mailchain/mailchain` folder: 12 | 13 | ```text 14 | git clone https://github.com/mailchain/mailchain.git ~/.mailchain/mailchain 15 | cd ~/.mailchain/mailchain 16 | ``` 17 | 18 | ### Starting the Indexer 19 | 20 | The indexer is preconfigured for 3 networks: 21 | 22 | | Network | Command | 23 | | :--- | :--- | 24 | | Edgeware Mainnet | `make edgeware-mainnet` | 25 | | Edgeware Testnet \(beresheet\) | `make edgeware-beresheet` | 26 | | Edgeware Local \(development\) | `make edgeware-local` | 27 | 28 | Select the network and run the appropriate make command \(e.g. `make edgeware-mainnet`\). This will download or update the required docker containers. 29 | 30 | NOTE: If working in local mode, you can access the preconfigured development accounts [here](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/accounts) if you need to transfer a balance to accounts you configured in [Setting Up > Add Account](../ethereum-instructions/setting-up.md#add-account). 31 | 32 | If successful, the output will be similar to the following: 33 | 34 | ```text 35 | Creating network "mailchain_default" with the default driver 36 | Pulling database (postgres:)... 37 | latest: Pulling from library/postgres 38 | bf5952930446: Downloading [===============> ] 8.399MB/27.09MB 39 | ... 40 | Creating mailchain_database_1 ... done 41 | Creating mailchain_receiver_1 ... done 42 | Creating mailchain_indexer-migration_1 ... done 43 | Creating mailchain_indexer-substrate-mainnet_1 ... done 44 | ... 45 | indexer-substrate_1 | 2020/09/27 19:19:51 Connecting to ws://mainnet1.edgewa.re:9944... 46 | receiver_1 | [negroni] listening on :8080 47 | indexer-substrate_1 | block number: 3191664 48 | indexer-substrate_1 | block hash: 0x81c694ba6973213905a8beaa8f8b69db395fb060606411d19c4f3b575c5f9b4c 49 | indexer-substrate_1 | next block number: 3191665 50 | indexer-substrate_1 | block number: 3191665 51 | ``` 52 | 53 | ### Stopping the Indexer 54 | 55 | To gracefully stop the indexer, press `Ctrl+C`. 56 | 57 | ### 58 | 59 | -------------------------------------------------------------------------------- /concepts/read.md: -------------------------------------------------------------------------------- 1 | # Read 2 | 3 | Message metadata is extracted after [decoding the contents of an envelope](receive.md#read-envelope). This provides the URL, IntegrityHash, and ContentsHash. With this metadata the message can be [downloaded](read.md#download), [decrypted](read.md#decrypt), and [decoded](read.md#decode). 4 | 5 | ### Download 6 | 7 | The envelope contains a [URL](../reference/programmable-envelopes.md#url) field which specifies the location of a message which is accessible to the recipient to download. 8 | 9 | Envelopes have an optional [IntegrityHash](../reference/programmable-envelopes.md#integrityhash) which returns a hash represented as a byte array. If this field is available, the hash must be used to validate the contents of the downloaded message before proceeding. This ensure the contents of the message has not been altered. 10 | 11 | {% hint style="info" %} 12 | Contents of the message cannot be changed after it has been sent without invalidating the IntegrityHash or ContentsHash. Downloaded message contents can be cached indefinitely. 13 | {% endhint %} 14 | 15 | ### Decrypt 16 | 17 | If appropriate, to ensure a message can only be read by the recipient it is [encrypted with the recipient public key](send.md#content-encryption). Once the contents have been [downloaded and validated](read.md#download) they can be decrypted. The first byte of the encrypted contents describes the encryption method used. This indicates which cipher is required for decryption. After the message contents have been decrypted successfully, it can be verified by comparing the [ContentsHash](../reference/programmable-envelopes.md#contentshash) contained in the envelope with a hash of the decrypted contents. The default hash function is `SHA3-256`. 18 | 19 | {% hint style="danger" %} 20 | The ContentsHash provides a cryptographically secure mechanism to ensure the contents of the message are as the sender intended. If the hashes do not match the contents should not be trusted and discarded. 21 | {% endhint %} 22 | 23 | ### Decode 24 | 25 | Mailchain message contents can be encoded with different methods depending on the type and contents. To ensure that the correct method is used to decode the message inspect the `Content-Type` and `Content-Transfer-Encoding` message headers that were set when [preparing to send](send.md#message-preparation) the message. 26 | 27 | Once decoded, the message fields \(headers, subject, body, etc.\) can be extracted and displayed to a user through an interface. 28 | 29 | -------------------------------------------------------------------------------- /advanced-configuration/advanced-storage-configuration.md: -------------------------------------------------------------------------------- 1 | # Advanced Storage Configuration 2 | 3 | ### Configuring Mailchain to Use Your Own Sent Storage Location 4 | 5 | Mailchain supports multiple sent storage options: 6 | 7 | 1. \*\*\*\*[**Mailchain**](advanced-storage-configuration.md#mailchain) \(encrypted sent store, managed by Mailchain on Amazon S3\) 8 | 2. \*\*\*\*[**Amazon S3**](advanced-storage-configuration.md#amazon-s3) \(encrypted sent store, in your own Amazon S3 account\) 9 | 3. \*\*\*\*[**IPFS**](advanced-storage-configuration.md#ipfs) \(encrypted sent store, pinned indefinitely, using [Pinata](https://pinata.cloud)\) 10 | 11 | ### Mailchain \(Default\) 12 | 13 | #### **Setting Up Mailchain-Managed Storage** 14 | 15 | For convenience, Mailchain provides a storage endpoint for messages. This is configured by default. 16 | 17 | If you need to re-apply the configuration, you can update the `mailchain.yaml` configuration file with: 18 | 19 | ```yaml 20 | sentstore: 21 | kind: "mailchain" 22 | ``` 23 | 24 | ### Amazon S3 25 | 26 | #### Setting Up Amazon S3 27 | 28 | Amazon S3 can be configured either through the console, via the CLI, or with CloudFormation. We recommend using CloudFormation, to make this easier we have supplied a [template](https://github.com/mailchain/sent-storage-s3) you can run in your account. The easiest way to create this resource is by clicking on the launch stack icon below. 29 | 30 | [![Launch Stack](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=mailchain-sent-storage&templateURL=https://s3.amazonaws.com/mailchain-sent-storage-s3-cloudformation-template/output.yaml) 31 | 32 | You can now update the `mailchain.yaml` configuration file with your S3 details: 33 | 34 | ```yaml 35 | sentstore: 36 | kind: "s3" 37 | s3: 38 | accessKeyId: "YOUR-S3-ACCESS-KEY" 39 | bucket: "YOUR-S3-BUCKET" 40 | region: "YOUR-S3-REGION" 41 | secretAccessKey: "YOUR-S3-ACCESS-SECRET" 42 | ``` 43 | 44 | ### IPFS 45 | 46 | #### Setting Up IPFS using Pinata 47 | 48 | Mailchain supports IPFS using Pinata \([https://pinata.cloud](https://pinata.cloud)\). It's easy to get started, simply sign up \(and confirm your email address\), then get your API key and API secret to use Pinata as the sent store. 49 | 50 | You can now update the `mailchain.yaml` configuration file with your Pinata details: 51 | 52 | ```yaml 53 | sentstore: 54 | kind: "pinata" 55 | pinata: 56 | api-key: "YOUR-PINATA-API-KEY" 57 | api-secret: "YOUR-PINATA-API-SECRET" 58 | ``` 59 | 60 | -------------------------------------------------------------------------------- /installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Follow the steps below to install Mailchain... 3 | --- 4 | 5 | # Installation 6 | 7 | ## Quick Install \(Mac\) 8 | 9 | To install Mailchain for the first time, we recommend using [Homebrew](https://brew.sh/) to download, install and manage the application on your local machine. 10 | 11 | First we need to tap mailchain repository to the list of formulae that brew tracks using 12 | 13 | ```bash 14 | brew tap mailchain/tap 15 | ``` 16 | 17 | Once you have done this, you can install mailchain using 18 | 19 | ```bash 20 | brew install mailchain 21 | ``` 22 | 23 | ## Quick Install \(Linux\) 24 | 25 | To install Mailchain for the first time, run the following command to download and install the application on your local machine. 26 | 27 | ```bash 28 | curl -sL https://run.mailchain.xyz/install.sh | sh 29 | ``` 30 | 31 | ## Quick Install \(Windows\) 32 | 33 | **Prerequisites:** 34 | 35 | To install Mailchain for the first time, you need to install [Scoop.sh](https://scoop.sh/). To do this, open Powershell and run: 36 | 37 | ```bash 38 | Set-ExecutionPolicy RemoteSigned -scope CurrentUser 39 | iwr -useb get.scoop.sh | iex 40 | ``` 41 | 42 | **Install:** 43 | 44 | Once Scoop is installed, run the following command to download and install the application on your local machine. 45 | 46 | ```bash 47 | scoop install git 48 | scoop bucket add mailchain https://github.com/mailchain/scoop-bucket.git 49 | scoop install mailchain 50 | 51 | $path = "$home\.mailchain\.mailchain.yaml"; If(!(test-path $path)) { New-Item -ItemType "file" -Force -Path $path } 52 | ``` 53 | 54 | ## Manual Install 55 | 56 | To choose where to store the application, you can install mailchain manually. 57 | 58 | ### 1. Download the application 59 | 60 | Download the application directly via the [Mailchain releases](https://github.com/mailchain/mailchain/releases/latest) page. We recommend you save it in your home directory: `~/.mailchain/bin` 61 | 62 | ### 2. Export the application path 63 | 64 | Next, add mailchain to your environmental variable path with: 65 | 66 | ```bash 67 | export PATH=$PATH:$HOME/.mailchain/bin 68 | ``` 69 | 70 | {% hint style="info" %} 71 | Note: if you changed the location of the mailchain executable, you should update the path as appropriate: 72 | 73 | ```bash 74 | export PATH=$PATH:$HOME/{mailchain_executable_location} 75 | ``` 76 | {% endhint %} 77 | 78 | Verify the application is installed and running correctly with: `mailchain version`. For example:\` 79 | 80 | ```bash 81 | $ mailchain version 82 | Version: v0.0.11 83 | ``` 84 | 85 | Next, if the application is working as expected, you’ll want to add the path to `~/.profile`, `.zshrc`, or `~/.bash_profile`, depending on which shell you use. 86 | 87 | To determine the shell you use, run `echo $SHELL`. For example, if using zsh, as shown below: 88 | 89 | ```bash 90 | $ echo $SHELL 91 | ``` 92 | 93 | | Shell output | Command to export the path to the shell profile | 94 | | :--- | :--- | 95 | | /bin/zsh | `echo 'export PATH=$PATH:$HOME/.mailchain/bin' >> ~/.zshrc` | 96 | | /bin/bash | `echo 'export PATH=$PATH:$HOME/.mailchain/bin' >> ~/.bashrc` | 97 | | /bin/ksh | `echo 'export PATH=$PATH:$HOME/.mailchain/bin' >> ~/.kshrc` | 98 | 99 | You are now ready to initialise the application, following the appropriate instructions for [Ethereum](ethereum-instructions/) or [Substrate](substrate-instructions/). 100 | 101 | -------------------------------------------------------------------------------- /substrate-instructions/installing-the-indexer.md: -------------------------------------------------------------------------------- 1 | # Installing the Indexer 2 | 3 | ### Installation 4 | 5 | The transaction indexer comes as a docker cluster which runs locally. 6 | 7 | #### Prerequisites 8 | 9 | You need to have already installed: 10 | 11 | 1. [Docker](https://www.docker.com/) 12 | 13 | #### Installation and Setup 14 | 15 | To obtain the latest docker container download the docker-compose file from the Mailchain repository: [https://github.com/mailchain/mailchain/blob/master/docker-compose.substrate.yml](https://github.com/mailchain/mailchain/blob/master/docker-compose.substrate.yml). Save the [raw file](https://raw.githubusercontent.com/mailchain/mailchain/master/docker-compose.substrate.yml) in your preferred location for docker-compose files. 16 | 17 | For this example the container file is stored as `~/docker/mailchain/docker-compose.substrate.yml`using the command: 18 | 19 | ```text 20 | mkdir -p ~/docker/mailchain 21 | curl https://raw.githubusercontent.com/mailchain/mailchain/master/docker-compose.substrate.yml >> ~/docker/mailchain/docker-compose.substrate.yml 22 | ``` 23 | 24 | Next, open the file in your editor and update any default values \(e.g. network, ports or passwords\). For this example, we will keep the default Edgeware Mainnet configuration. 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 38 | 39 | 40 | 41 | 42 | 44 | 45 | 46 | 47 | 48 | 50 | 51 | 59 | 60 | 61 | 63 | 64 | 65 | 66 | 67 |
ServiceImageConfiguration
database 37 | postgresThe postgres image configuration
indexer-migration 43 | mailchain/indexerConfiguration for the mailchain/indexer
indexer-substrate-mainnet 49 | mailchain/indexer 52 |

Configuration for the:

53 |
    54 |
  • RPC endpoint to use
    • 55 |
  • Starting block
    • 56 |
  • Database image access
    • 57 |
58 |
receiver 62 | mailchain/receiverConfiguration for the mailchain/receiver
68 | 69 | Once you have updated your configuration, run the following to start the indexer container: 70 | 71 | ```bash 72 | docker-compose -f ~/docker/mailchain/docker-compose.substrate.yml up --build --no-start 73 | ``` 74 | 75 | NOTE: You may need to adjust the path to the location you downloaded your docker-compose file. 76 | 77 | If successful, the output will be similar to the following: 78 | 79 | ```text 80 | Creating network "mailchain_default" with the default driver 81 | Pulling database (postgres:)... 82 | latest: Pulling from library/postgres 83 | bf5952930446: Downloading [===============> ] 8.399MB/27.09MB 84 | ... 85 | Creating mailchain_database_1 ... done 86 | Creating mailchain_receiver_1 ... done 87 | Creating mailchain_indexer-migration_1 ... done 88 | Creating mailchain_indexer-substrate-mainnet_1 ... done 89 | ``` 90 | 91 | ### 92 | 93 | -------------------------------------------------------------------------------- /development/sending-testnet-messages.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: How to get started sending a Mailchain test message on a testnet 3 | --- 4 | 5 | # Sending Ethereum Testnet Messages 6 | 7 | ### Ethereum Testnets 8 | 9 | To send testnet messages using Mailchain, you will need an Ethereum address with a small balance \(around 0.0007 Ether\). 10 | 11 | Ethereum addresses are valid across the Ethereum mainnet and testnets, so it's best to create a **new address for development purposes only**. This way, if your private key gets exposed, only test ETH can get stolen. 12 | 13 | #### 1. Create an Ethereum Address for Testing/ Development 14 | 15 | To create a new Ethereum address, we recommend using either [MyCrypto](https://mycrypto.com/generate) or [Metamask](https://metamask.io/) \(which comes built into [Brave Browser](https://brave.com/)\). 16 | 17 | {% hint style="danger" %} 18 | Please take the time to write everything down that enter into your computer. 19 | At the least, you'll need to record a seed phrase \(or private key\) and password. 20 | {% endhint %} 21 | 22 | #### 2. Get Some Test ETH 23 | 24 | **Metamask** 25 | 26 | If you are using Metamask, you can switch networks in the Metamsk interface and go to [https://faucet.metamask.io/](https://faucet.metamask.io/) 27 | 28 | **MyCrypto or Other Wallet Software** 29 | 30 | You can head to one of the following faucets and follow the instructions to be sent some test ether. 31 | 32 | | Network | Faucets \(all working at the time of writing\) | 33 | | :--- | :--- | 34 | | Mainnet | N/A | 35 | | Ropsten | [https://faucet.ropsten.be/](https://faucet.ropsten.be/) | 36 | | Goerli | [https://faucet.goerli.mudit.blog/](https://faucet.goerli.mudit.blog/) | 37 | | Kovan | [https://faucet.kovan.network/](https://faucet.kovan.network/) | 38 | | Rinkerby | [https://www.rinkeby.io/\#faucet](https://www.rinkeby.io/#faucet) | 39 | 40 | #### 3. Install Mailchain 41 | 42 | Follow the docs at [Getting Started](../getting-started.md) and add your private key for the test/dev ethereum address you created in [step 1](sending-testnet-messages.md#1-create-an-ethereum-address-for-testing-development). 43 | 44 | #### 4. Load Your Mailchain Inbox 45 | 46 | With your Mailchain [client running locally](../advanced-configuration/setting-up.md#serve), head to the Mailchain Inbox \([https://inbox.mailchain.xyz](https://inbox.mailchain.xyz)\). 47 | 48 | #### 5. Switch To A Testnet 49 | 50 | In the Mailchain Inbox, [switch to the testnet ](../mailchain-web-inbox/configuring-the-web-interface.md#changing-the-network)that you want to send a message on \(and have a balance on\). 51 | 52 | #### 6. Compose and Send a Message 53 | 54 | {% hint style="info" %} 55 | Because you have not yet sent any transactions from this ethereum address on this network, Mailchain won't be able to be able to determine your public key. 56 | {% endhint %} 57 | 58 | _If this is the first message or transaction you are sending on this testnet:_ 59 | 60 | Click "COMPOSE" in the Inbox interface and send a message to an ethereum address which has already sent a transaction, e.g. the Mailchain Developer address: 0x4ad2b251246aafc2f3bdf3b690de3bf906622c51. 61 | 62 | If you have sent a message or transaction on this testnet, you can receive messages from other developers, send messages to yourself, either from the same address or another development address. 63 | 64 | {% hint style="success" %} 65 | Top tip: Because Mailchain supports ENS, you can configure an easy, human readable name for your development address on the testnet you are working on. This makes it easier to keep track when switching between different addresses. 66 | {% endhint %} 67 | 68 | 69 | 70 | -------------------------------------------------------------------------------- /reference/ethereum.md: -------------------------------------------------------------------------------- 1 | # Ethereum 2 | 3 | Mailchain users can send messages to any Ethereum account address. This section details how the Ethereum implementation of the [Message Flow](../concepts/overview.md) is achieved. 4 | 5 | ### Networks 6 | 7 | Mailchain supports all the common Ethereum networks 8 | 9 | | Network | Status | 10 | | :--- | :--- | 11 | | Mainnet | Full | 12 | | Ropsten | Full | 13 | | Goerli | Full | 14 | | Kovan | Full | 15 | | Rinkerby | Full | 16 | 17 | ### Public Key Finder 18 | 19 | To send an encrypted message, a public key is required. Mailchain uses the public key associated with an account address to encrypt the data, and if specified by the envelope, the message contents. This ensures the recipient is also the owner of the private key and only they can decrypt data. The public key finder searches for transactions sent by the recipient address and extracts the public key. 20 | 21 | {% hint style="info" %} 22 | The public key for an account address can either be calculated from a transaction signed by that account address or supplied by that account holder. In order to calculate the public key, the recipient address needs to have sent at least one Ethereum transaction. 23 | {% endhint %} 24 | 25 | ### Sender 26 | 27 | Ethereum transactions are used to [send](../concepts/send.md) a message. 28 | 29 | #### Envelope 30 | 31 | Transactions contain a `data` field that stores the [envelope](programmable-envelopes.md). Bytes can be stored in the `data` field and must be hexadecimal encoded, prefixed with `0x` as per the Ethereum specification. Data stored in a transaction must follow the Mailchain [standard encoding format](../concepts/send.md#send-transaction):`[protocol-prefix]+[mailchain-prefix]+[envelope]`. 32 | 33 | | Field | Example | Notes | 34 | | :--- | :--- | :--- | 35 | | protocol-prefix | `0x` | Required Ethereum transaction data prefix | 36 | | mailchain-identifier | `6d61696c636861696e` | "mailchain" encoded as hexadecimal | 37 | | envelope | `010a82012ee10c59024c836d7ca12470b5ac74673002127ddedadbc6fc4375a8c086b650060ede199f603a158bc7884a903eadf97a2dd0fbe69ac81c216830f94e56b847d924b51a7d8227c80714219e6821a51bc7cba922f291a47bdffe29e7c3f67ad908ff377bfcc0b603007ead4bfd87ff0acc272528ca03d6381e6d0e1e2c5dfd24d521` | Envelope encoded as hexadecimal | 38 | 39 | An example of transaction data for a Mailchain message sent on Ethereum is as follows: 40 | 41 | ```text 42 | 0x6d61696c636861696e010a82012ee10c59024c836d7ca12470b5ac74673002127ddedadbc6fc4375a8c086b650060ede199f603a158bc7884a903eadf97a2dd0fbe69ac81c216830f94e56b847d924b51a7d8227c80714219e6821a51bc7cba922f291a47bdffe29e7c3f67ad908ff377bfcc0b603007ead4bfd87ff0acc272528ca03d6381e6d0e1e2c5dfd24d521 43 | ``` 44 | 45 | The same transaction and data can be viewed on [here](https://etherscan.io/tx/0x2bf261a81e624d649450a3851df2d0639a8b98ed3bce39da14e8f318adf3edb9) on Etherscan. 46 | 47 | #### Transaction Fields 48 | 49 | To send a message these Ethereum transaction fields must be specified. 50 | 51 | | Field | Type | Example | Notes | | 52 | | :--- | :--- | :--- | :--- | :--- | 53 | | `nonce` | [unit64](https://golang.org/pkg/builtin/#uint64) | 8 | Sequential number that represents the number of transactions the sender account has made on the network. _Added by the client, based on last nonce._ | | 54 | | `gasprice` | [unit64](https://golang.org/pkg/builtin/#uint64) | 0**.**00000002 | Execution fee for sending the message. _Added by the client, based on network gas price._ | | 55 | | `startgas` | [\*big.Int](https://golang.org/pkg/math/big/#Int) | 30,660 | Maximum gas used for sending the transaction. Mailchain messages uses ~30,000 GAS approx 1.5x the cost of a basic transaction. _Added by the client, based on required gas._ | | 56 | | `to` | [\[\]byte](https://golang.org/pkg/builtin/#byte) | `0x92d8f10248c6a3953cc3692a894655ad05d61efb` | Address of the recipient. _Added by the client, based on recipient address in message._ | | 57 | | `value` | [\*big.Int](https://golang.org/pkg/math/big/#Int) | `0` | Set to send zero value transactions by default | | 58 | | `data` | [\[\]byte](https://golang.org/pkg/builtin/#byte) | `0x6d61696c636861696e....` | Envelope data | | 59 | 60 | Once the transaction fields have been populated, it must be signed using the sender private key. The signed transaction bytes can then be transmitted to the ethereum network over JSON-RPC using the [eth\_sendrawtransaction](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sendrawtransaction) method. 61 | 62 | ### Receiver 63 | 64 | To [read](../concepts/read.md) Mailchain messages for a specific address, transactions sent to that address need to be identified. Ethereum does not natively support an address index or similar functionality that identifies all transactions sent to or from a specific address. Third parties have API's that provide this functionality, including [Etherscan.io](https://etherscan.io/). 65 | 66 | -------------------------------------------------------------------------------- /reference/polkadot.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: This page is currently a draft spec. Please don't use yet. 3 | --- 4 | 5 | # Polkadot / Substrate \(draft\) 6 | 7 | Mailchain users can send messages to any Substrate account address. This section details how the Substrate implementation of the [Message Flow](../concepts/overview.md) is achieved. 8 | 9 | ### Networks 10 | 11 | Mailchain plans to support substrate networks that have the Contract Substrate Runtime Module Library enabled \([srml\_contracts](https://substrate.dev/rustdocs/v1.0/srml_contract/struct.Module.html#method.call)\). 12 | 13 | ### Public Key Finder 14 | 15 | To send an encrypted message, a public key is required. Mailchain uses the public key associated with an address to encrypt the data, and if specified by the envelope, the message contents. This ensures the recipient is also the owner of the private key and only they can decrypt data. The public key finder decodes a recipient address from base58 and extracting the public key \(dropping the first byte and last two bytes before prepending '0x'\). 16 | 17 | #### Example 18 | 19 | | Field | Example | 20 | | :--- | :--- | 21 | | Address \(base58 encoded\) | `5EU2BwdEH8rojoKuJ16p3t1Gs8uUUp6SoaomKud2FmXBvdbp` | 22 | | Decoded Address \(from Base58\) | `2a6a40d2c0edf1dfa67a639599dd3de2f49eb55fcd73991ba33a67debfb04b5846459b` | 23 | | Extracting Public Key | ~~\[2a\]~~6a40d2c0edf1dfa67a639599dd3de2f49eb55fcd73991ba33a67debfb04b5846~~\[459b\]~~ | 24 | | Public Key | `0x6a40d2c0edf1dfa67a639599dd3de2f49eb55fcd73991ba33a67debfb04b5846` | 25 | 26 | {% hint style="info" %} 27 | The public key for an account address can either be calculated from an address or supplied by that account holder. 28 | 29 | Using the same private key to generate addresses on different networks produces the same public key, but a different public address. 30 | {% endhint %} 31 | 32 | ### Sender 33 | 34 | Mailchain uses the functionality provided by the Contract module \([srml\_contracts](https://substrate.dev/rustdocs/v1.0/srml_contract/)\) \`call\` function which is similar to a standard Substrate transaction \(signed extrinsic\) with the addition of a data field \([Vec](https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html)<[u8](https://doc.rust-lang.org/nightly/std/primitive.u8.html)>\). A substrate parachain \(or parathread\) with the Contract module enabled permits [sending](../concepts/send.md) transactions with an envelope containing a message. 35 | 36 | #### Envelope 37 | 38 | Contract transactions \(signed calls\) contain a `data` field that stores the [envelope](programmable-envelopes.md). Bytes can be stored in the `data` field and must be hexadecimal encoded, prefixed with `0x`. Data stored in a transaction must follow the Mailchain [standard encoding format](../concepts/send.md#send-transaction):`[protocol-prefix]+[mailchain-prefix]+[envelope]`. 39 | 40 | ~~~~ 41 | 42 | | Field | Example | Notes | 43 | | :--- | :--- | :--- | 44 | | protocol-prefix | 0x | Required Contract SRML `call` function data prefix | 45 | | mailchain-identifier | `6d61696c636861696e` | "mailchain" encoded as hexadecimal | 46 | | envelope | `010a82012ee10c59024c836d7ca12470b5ac74673002127ddedadbc6fc4375a8c086b650060ede199f603a158bc7884a903eadf97a2dd0fbe69ac81c216830f94e56b847d924b51a7d8227c80714219e6821a51bc7cba922f291a47bdffe29e7c3f67ad908ff377bfcc0b603007ead4bfd87ff0acc272528ca03d6381e6d0e1e2c5dfd24d521` | Envelope encoded as hexadecimal | 47 | 48 | TODO 49 | 50 | An example of transaction data for a Mailchain message sent on \[INSERT TESTNET HERE\] is as follows: 51 | 52 | ``` 53 | ????? 54 | ``` 55 | 56 | The same transaction and data can be viewed on **here** on Polkascan. 57 | 58 | /TODO 59 | 60 | #### Transaction/ Extrinsic Fields 61 | 62 | To send a message the following transaction fields must be specified. 63 | 64 | | Field | Type | Example | Notes | 65 | | :--- | :--- | :--- | :--- | 66 | | origin | [AccountId](https://substrate.dev/rustdocs/v1.0/srml_system/trait.Trait.html#associatedtype.AccountId) | | TODO | 67 | | dest | [AccountId](https://substrate.dev/rustdocs/v1.0/srml_system/trait.Trait.html#associatedtype.AccountId) | | TODO | 68 | | value | [BalanceOf](https://substrate.dev/rustdocs/v1.0/srml_contract/type.BalanceOf.html) | | TODO | 69 | | gas\_limit | [Gas](https://substrate.dev/rustdocs/v1.0/srml_contract/trait.Trait.html#associatedtype.Gas) | | TODO | 70 | | data | [Vec](https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html)<[u8](https://doc.rust-lang.org/nightly/std/primitive.u8.html)> | | TODO | 71 | 72 | Once the fields have been populated, the function must be signed using the sender private key. The signed transaction bytes can then be transmitted to the substrate network over JSON-RPC using the Contract module `call` function. 73 | 74 | ### Receiver 75 | 76 | To [read](../concepts/read.md) Mailchain messages for a specific address, Contract calls sent to that address need to be identified. Substrate does not natively support an address index or similar functionality that identifies all transactions sent to or from a specific address. Third parties have API's that provide this functionality, including Polkascan \[TODO: confirm polkascan api reqs; needs testnet example\]. 77 | 78 | -------------------------------------------------------------------------------- /reference/polkadot/README.md: -------------------------------------------------------------------------------- 1 | # Substrate \(Polkadot\) 2 | 3 | Mailchain users can send messages to any Substrate account address. This section details how the Substrate implementation of the [Message Flow](../../concepts/overview.md) is achieved. 4 | 5 | ### Networks 6 | 7 | Mailchain plans to support substrate networks that have the Contract Substrate Runtime Module Library enabled \([srml\_contracts](https://substrate.dev/rustdocs/v1.0/srml_contract/struct.Module.html#method.call)\). 8 | 9 | ### Public Key Finder 10 | 11 | To send an encrypted message, a public key is required. Mailchain uses the public key associated with an address to encrypt the data, and if specified by the envelope, the message contents. This ensures the recipient is also the owner of the private key and only they can decrypt data. The public key finder decodes a recipient address from base58 and extracting the public key \(dropping the first byte and last two bytes before prepending '0x'\). 12 | 13 | #### Example 14 | 15 | | Field | Example | 16 | | :--- | :--- | 17 | | Address \(base58 encoded\) | `5EU2BwdEH8rojoKuJ16p3t1Gs8uUUp6SoaomKud2FmXBvdbp` | 18 | | Decoded Address \(from Base58\) | `2a6a40d2c0edf1dfa67a639599dd3de2f49eb55fcd73991ba33a67debfb04b5846459b` | 19 | | Extracting Public Key | ~~\[2a\]~~6a40d2c0edf1dfa67a639599dd3de2f49eb55fcd73991ba33a67debfb04b5846~~\[459b\]~~ | 20 | | Public Key | `0x6a40d2c0edf1dfa67a639599dd3de2f49eb55fcd73991ba33a67debfb04b5846` | 21 | 22 | {% hint style="info" %} 23 | The public key for an account address can either be calculated from an address or supplied by that account holder. 24 | 25 | Using the same private key to generate addresses on different networks produces the same public key, but a different public address. 26 | {% endhint %} 27 | 28 | ### Sender 29 | 30 | Mailchain uses the functionality provided by the Contract module \([srml\_contracts](https://substrate.dev/rustdocs/v2.0.0-rc5/pallet_contracts/struct.Module.html#method.call)\) \`call\` function which is similar to a standard Substrate transaction \(signed extrinsic\) with the addition of a data field \([Vec](https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html)<[u8](https://doc.rust-lang.org/nightly/std/primitive.u8.html)>\). A substrate parachain \(or parathread\) with the Contract module enabled permits [sending](../../concepts/send.md) transactions with an envelope containing a message. 31 | 32 | #### Envelope 33 | 34 | Contract transactions \(signed calls\) contain a `data` field that stores the [envelope](../programmable-envelopes.md). Bytes can be stored in the `data` field and must be hexadecimal encoded, prefixed with `0x`. Data stored in a transaction must follow the Mailchain [standard encoding format](../../concepts/send.md#send-transaction):`[protocol-prefix]+[mailchain-prefix]+[envelope]`. 35 | 36 | ~~~~ 37 | 38 | | Field | Example | Notes | 39 | | :--- | :--- | :--- | 40 | | protocol-prefix | 0x | Required Contract SRML `call` function data prefix | 41 | | mailchain-identifier | `6d61696c636861696e` | "mailchain" encoded as hexadecimal | 42 | | envelope | `010a82012ee10c59024c836d7ca12470b5ac74673002127ddedadbc6fc4375a8c086b650060ede199f603a158bc7884a903eadf97a2dd0fbe69ac81c216830f94e56b847d924b51a7d8227c80714219e6821a51bc7cba922f291a47bdffe29e7c3f67ad908ff377bfcc0b603007ead4bfd87ff0acc272528ca03d6381e6d0e1e2c5dfd24d521` | Envelope encoded as hexadecimal | 43 | 44 | #### Transaction/ Extrinsic Fields 45 | 46 | To send a message the following transaction fields must be specified. 47 | 48 | | Field | Type | Example | 49 | | :--- | :--- | :--- | 50 | | origin | [AccountId](https://substrate.dev/rustdocs/v1.0/srml_system/trait.Trait.html#associatedtype.AccountId) | | 51 | | dest | [AccountId](https://substrate.dev/rustdocs/v1.0/srml_system/trait.Trait.html#associatedtype.AccountId) | | 52 | | value | [BalanceOf](https://substrate.dev/rustdocs/v1.0/srml_contract/type.BalanceOf.html) | | 53 | | gas\_limit | [Gas](https://substrate.dev/rustdocs/v1.0/srml_contract/trait.Trait.html#associatedtype.Gas) | | 54 | | data | [Vec](https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html)<[u8](https://doc.rust-lang.org/nightly/std/primitive.u8.html)> | | 55 | 56 | Once the fields have been populated, the extrinsic must be signed using the sender private key. The signed extrinsic bytes can then be transmitted to the substrate network over JSON-RPC using the Contract module `call` function. 57 | 58 | ### Receiver 59 | 60 | To [read](../../concepts/read.md) Mailchain messages for a specific address, Contract calls sent to that address need to be identified. 61 | 62 | Substrate does not natively support an address index or similar functionality that identifies all transactions sent to or from a specific address. Third parties provide some of this information through a web interface \(including Subscan.io\) but as of August 2020, no APIs consistently provide a transaction index for received transactions and their data fields. 63 | 64 | **Transaction Indexer** 65 | 66 | Mailchain provides a simple transaction indexer which listens for transactions and filters mailchain messages for the recipient. Further details and instructions for running it can be found here: [Substrate Transaction Indexer](substrate-transaction-indexer.md). 67 | 68 | 69 | 70 | 71 | 72 | -------------------------------------------------------------------------------- /concepts/send.md: -------------------------------------------------------------------------------- 1 | # Send 2 | 3 | Messages are sent by creating a transaction with the data field containing an encoded [envelope](../reference/programmable-envelopes.md). Each blockchain protocol may have differences in the way data and transactions are handled. Mailchain uses a standard format plus any protocol specifics.‌ 4 | 5 | ### Compose Message 6 | 7 | In the [web interface](../mailchain-web-inbox/mailchain-web-interface.md), a user composes a message which is sent to the Mailchain client via an API, messages can also be sent programmatically via the API. The following fields are available to compose a message: 8 | 9 | **Fields** 10 | 11 | | Field | Type | Description | Example | 12 | | :--- | :--- | :--- | :--- | 13 | | To | Encoded Address | Recipient public address | `0xd5ab4ce3605cd590db609b6b5c8901fdb2ef7fe6` | 14 | | From | Encoded Address | Sender public address | `0x92d8f10248c6a3953cc3692a894655ad05d61efb` | 15 | | Reply-To | Encoded Address _\(Optional\)_ | Public address responses should be sent to \[optional\] | `0x92d8f10248c6a3953cc3692a894655ad05d61efb` | 16 | | Subject | String | Message subject | ​Hello world | 17 | | Body | String | Message body | ​This is my first Mailchain message | 18 | | Public Key | Encoded Public Key | The recipient public key | `0x69d908510e355beb1d5bf2df8129e5b6401e1969891e8016a0b2300739bbb00687055e5924a2fd8dd35f069dc14d8147aa11c1f7e2f271573487e1beeb2be9d0` | 19 | 20 | {% hint style="info" %} 21 | To determine the recipient public key, an existing transaction needs to have been sent on the blockchain by that Ethereum account. For example, to determine Bob’s public key, Bob needs to have sent a transaction.‌ 22 | {% endhint %} 23 | 24 | ### Message Preparation 25 | 26 | Before sending the message it needs to be prepared. The Mailchain client handles this by [building fields](send.md#add-fields), [generating a contents hash](send.md#generate-contents-hash), and [encrypting the contents](send.md#encrypt-contents). 27 | 28 | #### Message Fields 29 | 30 | The client adds the following fields to each message: 31 | 32 | | Field | Type | Description | Example | 33 | | :--- | :--- | :--- | :--- | 34 | | Date | [RFC1123](https://tools.ietf.org/html/rfc1123) date format | Date and time of message | `2019-04-12T18:21:00+01:00` | 35 | | Message-ID | String | A unique message id composed of 64 chars \(32 bytes\) + `@mailchain` | `40fb138807253554afc5161740ca3dade11db7e74e799c9f6091b904277cb9b839393802dc38b8a815615543@mailchain` | 36 | | Content-Type | String [RFC6532](https://tools.ietf.org/html/rfc6532) content type | Describe the contents of the message | `text/plain; charset="UTF8"` | 37 | | Content-Transfer-Encoding | String | The message body is encoded according to this field | `quoted-printable` | 38 | 39 | #### ‌Contents Hash Generation 40 | 41 | The [contents hash](../reference/programmable-envelopes.md#contentshash) is used to verify the message has not changed since being sent. To generate the hash, the message is encoded using the specified method in the `Content-Type` and `Content-Type-Encoding` fields into a bytes representation. The bytes representation is then passed to the hash function. 42 | 43 | {% hint style="info" %} 44 | Contents hash provides cryptographic proof to check the message has not changed from when it was initially included in a transaction. The default hash function is`SHA3-256.` 45 | {% endhint %} 46 | 47 | #### Content Encryption 48 | 49 | The message is encrypted using the recipient public key, the default encryption method is `AES-256-CBC`. The encrypted message can only be decrypted by the owner of the private key that corresponds to the public key. 50 | 51 | An [integrity hash](../reference/programmable-envelopes.md#integrityhash) is created from the encrypted message, providing a basic integrity protection layer prior to message decryption. 52 | 53 | {% hint style="info" %} 54 | Integrity hash is intended to ensure the message has not been tampered with before attempting to decrypt the message. No cryptographic proof is required for this hash, the default method is`murmur3.` 55 | {% endhint %} 56 | 57 | ### Message Transmission 58 | 59 | To complete sending the message to a recipient, the client will [store the message](send.md#store-message), [create an envelope](send.md#create-envelope), and [send a transaction](send.md#send-transaction). 60 | 61 | #### Store Message 62 | 63 | A consistent characteristic of blockchain protocols is that storing bytes has a cost. Mailchain messages are stored 'off-chain' to minimise the costs of storing messages 'on-chain'. The [Mailchain specification](https://github.com/mailchain/mailchain-specification/blob/master/mailchain_specification.md#message-storage) details the requirements for a message store. 64 | 65 | #### Create Envelope 66 | 67 | [Programmable envelopes](../reference/programmable-envelopes.md) provide a specific wrapper around each message. Envelopes differ in functionality to support different message use cases. Envelopes are marshalled into bytes and can be encoded per the blockchain protocol encoding requirements. 68 | 69 | #### Send Transaction 70 | 71 | To transmit the message to the recipient, a transaction is sent from the message sender to the message recipient. These transactions are similar to standard transactions with the exception that the `data` or equivalent type of field is used. The information included in this data field includes: a protocol prefix followed by the mailchain prefix, and then the envelope represented as bytes. 72 | 73 | The following fields are then encoded to build the transaction data: 74 | 75 | | Field | Description | Example using Hex Encoding | 76 | | :--- | :--- | :--- | 77 | | protocol-prefix | _Optional and varies per protocol_ | `0x` for Ethereum | 78 | | mailchain-identifier | "mailchain" encoded | `6d61696c636861696e` hex encoded | 79 | | envelope | Bytes of envelope | | 80 | 81 | The data is combined as `[protocol-prefix]+[mailchain-prefix]+[envelope]`and encoded according to the preferred protocol encoding standard \(e.g. hex, base32, base58, etc.\). 82 | 83 | To send the transaction, the remaining transaction fields need to be supplied, before it is signed and transmitted as per the protocol requirements.[ 84 | ](https://app.gitbook.com/@mailchain/s/mailchain/~/drafts/-LmkujL2pCds-laZEl8b/primary/reference/ethereum) 85 | 86 | -------------------------------------------------------------------------------- /reference/programmable-envelopes.md: -------------------------------------------------------------------------------- 1 | # Programmable Envelopes 2 | 3 | Programmable envelopes contain predefined fields to allow different types of messages to be sent according to specific use case requirements. Mailchain is flexible and extensible, adding a messaging layer to blockchain protocols, supporting different types of messages to be sent. Blockchain protocols typically allow sending `data` as a byte array, which is efficient but not descriptive. Programmable Envelopes allow descriptive implementations of messaging use cases that can be encoded to a byte array. 4 | 5 | Each envelope is implemented as code, describing the encoding method, fields, and interface functions. 6 | 7 | Programmable Envelopes are preferred over adding optional fields. They remove some of the complexity, the need for additional documentation, are extensible in a modular sense, and create an improved developer experience. 8 | 9 | {% hint style="info" %} 10 | Backwards and forwards compatibility can be achieved by never modifying an envelope after deployment. 11 | {% endhint %} 12 | 13 | ## Envelopes 14 | 15 | ### 0x00 - Reserved for unset value 16 | 17 | Zero value is reserved to identify that it has not been set and should be treated like an unset envelope identifier. 18 | 19 | ### 0x01 - Private Message Stored with MLI 20 | 21 | The Private Message Stored with MLI \(Message Location Identifier\) is optimized for secure, verifiable messaging with minimal bytes, [URL](programmable-envelopes.md#url) and [ContentsHash](programmable-envelopes.md#contentshash) are encrypted with a publicly verified [IntegrityHash](programmable-envelopes.md#integrityhash). 0x01 uses [MLI](types.md#message-location-identifier) to reduce the bytes needed to store the [URL](programmable-envelopes.md#url), the [IntegrityHash](programmable-envelopes.md#integrityhash) is optional reducing the required number of bytes. 22 | 23 | #### Encoding 24 | 25 | [Protocol buffers](https://developers.google.com/protocol-buffers/) are used to define the structure of this message. This is the `proto3` spec. 26 | 27 | ```text 28 | // Use hosted location where the decryptedhash is the same as the location. Location, decrypted hash are encrypted so only receipient can location and verify the message. 29 | message ZeroX01 { 30 | bytes UIBEncryptedLocationHash = 1; 31 | bytes encryptedHash = 2; 32 | } 33 | ``` 34 | 35 | **Fields** 36 | 37 | | **Name** | Type | Notes | 38 | | :--- | :--- | :--- | 39 | | UIBEncryptedLocationHash | bytes | _Required_ - Bytes are stored are represented with [UInt64Bytes](types.md#uint-64-bytes). | 40 | | encryptedHash | bytes | _Optional_ - Bytes of hash | 41 | 42 | ### 0x02 - Private Message Stored on IPFS 43 | 44 | The Private Message Stored on [IPFS](https://ipfs.io/) \(InterPlanetary File System\) is optimized for secure, verifiable messaging with minimal bytes, [URL](programmable-envelopes.md#url) and [IntegrityHash](programmable-envelopes.md#integrityhash) are encrypted with a verified [ContentsHash](programmable-envelopes.md#contentshash). 0x02 uses an `ipfs://` URL, the [ContentsHash](programmable-envelopes.md#contentshash) is required. 45 | 46 | #### Encoding 47 | 48 | [Protocol buffers](https://developers.google.com/protocol-buffers/) are used to define the structure of this message. This is the `proto3` spec. 49 | 50 | ```text 51 | // Use hosted location where the encrypted hash is the same as the location. Location and decrypted hash are encrypted so only receipient can location and verify the message. 52 | message ZeroX02 { 53 | bytes UIBEncryptedLocationHash = 1; 54 | bytes decryptedHash = 2; 55 | } 56 | ``` 57 | 58 | **Fields** 59 | 60 | | **Name** | Type | Notes | 61 | | :--- | :--- | :--- | 62 | | UIBEncryptedLocationHash | bytes | _Required_ - Bytes are stored are represented with [UInt64Bytes](types.md#uint-64-bytes). | 63 | | decryptedHash | bytes | _Required_ - Bytes of hash | 64 | 65 | #### 0x50 - Alpha 66 | 67 | ## Implementation 68 | 69 | ### Encoding 70 | 71 | The first byte will describe the envelope implementation and encoding method used. 72 | 73 | | Byte Value | Notes | 74 | | :--- | :--- | 75 | | `0x00` | **Reserved** for unset value | 76 | | `0x01` | [Private message stored with MLI](programmable-envelopes.md#0x01-private-message-stored-with-mli) | 77 | | `0x50` | [Alpha envelope](programmable-envelopes.md#0x50-alpha) | 78 | | `0xFF` | **Reserved** to extend beyond 255 envelope definitions | 79 | 80 | {% hint style="info" %} 81 | While [Protocol buffers](https://developers.google.com/protocol-buffers/) are used by the first implemented envelopes, this is not a requirement. Each envelope describes it encoding method in the definition. 82 | {% endhint %} 83 | 84 | ### Interface 85 | 86 | Each envelope is required to implement the data interface. The interface enables each different envelope to define its implementation of the methods, this allows for different combinations of fields or logic to return a valid response for each of these methods. 87 | 88 | This interface is defined as: 89 | 90 | ```go 91 | type Data interface { 92 | URL(decrypter cipher.Decrypter) (url *url.URL, err error) 93 | IntegrityHash(decrypter cipher.Decrypter) (hash []byte, err error) 94 | ContentsHash(decrypter cipher.Decrypter) (hash []byte, err error) 95 | Valid() error 96 | } 97 | ``` 98 | 99 | ### Methods 100 | 101 | #### URL 102 | 103 | Addressable location of the message, the URL may be encrypted requiring decrypter to be supplied to decrypt URL. 104 | 105 | **Parameters:** 106 | 107 | | Name | Type | Notes | 108 | | :--- | :--- | :--- | 109 | | decrypter | [cipher.decrypter](https://godoc.org/github.com/mailchain/mailchain/crypto/cipher#Decrypter) | Used to decrypt the URL where the message can be found. Decrypter is required but is only used if the url is stored encrypted. | 110 | 111 | **Returns:** 112 | 113 | | **Name** | Type | Notes | 114 | | :--- | :--- | :--- | 115 | | url | [\*url.URL](https://godoc.org/net/url#URL) | Address of the message. _Nil if error._ | 116 | | err | error | Error object describing the cause. | 117 | 118 | #### In**tegrityHash** 119 | 120 | Hash of the encrypted content. This can be used to validate the integrity of the envelope contents before decrypting. 121 | 122 | **Parameters:** 123 | 124 | | Name | Type | Notes | 125 | | :--- | :--- | :--- | 126 | | decrypter | [cipher.decrypter](https://godoc.org/github.com/mailchain/mailchain/crypto/cipher#Decrypter) | Used to decrypt the hash, where only the intended recipient can validate the contents. Decrypter is required but is only used if the hash is stored encrypted. | 127 | 128 | **Returns:** 129 | 130 | | **Name** | Type | Notes | 131 | | :--- | :--- | :--- | 132 | | hash | [\[\]byte](https://godoc.org/builtin#byte) | Hash of the contents to validate integrity. _Nil if error._ | 133 | | err | error | Error object describing the cause. | 134 | 135 | {% hint style="danger" %} 136 | Integrity Hash is not intended to be cryptographically secure, use [ContentsHash](programmable-envelopes.md#url) for a secure cryptographic hash. 137 | {% endhint %} 138 | 139 | #### **ContentsHash** 140 | 141 | Hash of the decrypted content. This can be used to verify the contents of the message have not been tampered with. 142 | 143 | **Parameters:** 144 | 145 | | Name | Type | Notes | 146 | | :--- | :--- | :--- | 147 | | decrypter | [cipher.decrypter](https://godoc.org/github.com/mailchain/mailchain/crypto/cipher#Decrypter) | Used to decrypt the hash, where only the intended recipient can verify the contents. Decrypter is required but is only used if the hash is stored encrypted. | 148 | 149 | **Returns:** 150 | 151 | | **Name** | Type | Notes | 152 | | :--- | :--- | :--- | 153 | | hash | [\[\]byte](https://godoc.org/builtin#byte) | Hash of the contents to validate the message contents. _Nil if error._ | 154 | | err | error | Error object describing the cause. | 155 | 156 | ### 157 | 158 | 159 | 160 | -------------------------------------------------------------------------------- /mailchain-connectors/mailchain-connector-imap.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | The Mailchain Connector for IMAP makes it possible to receive Mailchain 4 | messages in your email inbox... 5 | --- 6 | 7 | # Mailchain Connector for IMAP 8 | 9 | The Mailchain Connector for IMAP makes it possible to receive Mailchain messages in your email inbox \(i.e. your webmail, desktop or phone mail application\). 10 | 11 | It connects to the Mailchain API, converts messages to emails, then uploads them to your chosen IMAP mailbox. 12 | 13 | ### Installation 14 | 15 | #### Prerequisites 16 | 17 | You need to have already installed: 18 | 19 | 1. The Mailchain API client \([https://docs.mailchain.xyz/installation](https://docs.mailchain.xyz/installation)\) 20 | 2. Ruby \(we suggest using [RVM](https://rvm.io/)\) 21 | 22 | #### Installation and Setup 23 | 24 | Install `mailchain_connector_imap` by running: 25 | 26 | ```bash 27 | gem install mailchain_connector_imap 28 | ``` 29 | 30 | Next, if running mailchain\_connector\_imap for the first time, or to change the configuration, run: 31 | 32 | ```bash 33 | mailchain_connector_imap --configure 34 | ``` 35 | 36 | This will walk you through the configuration options \(for more information on details, see [Configuration Details](mailchain-connector-imap.md#configuration-details) below\). 37 | 38 | #### Running the Mailchain Connector for IMAP 39 | 40 | Once installed and configured, run the connector. It will prompt you to enter your IMAP \(email\) password so it can connect to the IMAP server: 41 | 42 | ```bash 43 | mailchain_connector_imap 44 | ``` 45 | 46 | ### Configuration Details 47 | 48 | The `mailchain_connector_imap` configuration is stored at `~/.mailchain_connector/imap/config.json`. 49 | 50 | The wizard steps through the following options: 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 63 | 64 | 65 | 66 | 67 | 71 | 72 | 73 | 74 | 78 | 79 | 80 | 81 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 93 | 94 | 95 | 96 | 97 | 101 | 102 | 103 | 104 | 108 | 109 | 110 | 111 | 116 | 117 | 118 | 119 | 125 | 126 | 127 | 128 | 131 | 132 | 133 | 134 | 136 | 137 | 138 |
QuestionDescription
IMAP Settings: 62 |
IMAP server 68 |

The hostname of the IMAP server.

69 |

e.g. imap.example.com

70 |
IMAP username 75 |

Your IMAP username, usually your email address.

76 |

e.g. tim@example.com

77 |
IMAP Port 82 |

The port that the IMAP server is listening on.

83 |

e.g. IMAP = 143 or IMAP SSL = 993

84 |
Use SSLRecommended if your IMAP server supports this.
Mailchain Settings: 92 |
Mailchain client hostnameThe hostname or IP address where the Mailchain client is running. If you 98 | are running the client on your local machine, this is likely to be 127.0.0.1. 99 |
e.g. 127.0.0.1 or mailchain.example.com
Use HTTPS (SSL) 105 |

If the Mailchain client is hosted, it will likely connect over https.

106 |

NOTE: When running locally, the Mailchain client does not use HTTPS.

107 |
Mailchain client port 112 |

The port that the Mailchain client is listening on.

113 |

If you are running the client on your local machine with configuration 114 | defaults, this is likely to be 8080.

115 |
Folder Structure for IMAP 120 |

The structure of the folders in IMAP can be either:

121 |

Protocol>Network>Address

122 |

or

123 |

Address>Protocol>Network

124 |
mainnet messages delivered Inbox folderBecause most IMAP servers will only alert a user when a new message arrives 129 | in the Inbox, rather than other folders, some users prefer to receive `mainnet` 130 | messages in their regular Inbox folder.
Message check intervalConfigured in seconds. Minimum interval is 60 seconds. 135 |
e.g. 300 = 5 minutes
139 | 140 | _Sample configuration file:_ 141 | 142 | ```text 143 | { 144 | "imap": { 145 | "server": "imap.example.com", 146 | "username": "tim@example.com", 147 | "port": "993", 148 | "ssl": true 149 | }, 150 | "mailchain": { 151 | "hostname": "127.0.0.1", 152 | "ssl": false, 153 | "port": "8080", 154 | "folders": "by_network", 155 | "mainnet_to_inbox": true, 156 | "interval": "300" 157 | } 158 | } 159 | ``` 160 | 161 | ### FAQs 162 | 163 | **Can I connect my regular email account using the Mailchain Connector to receive Mailchain messages?** 164 | Yes. The Mailchain Connector for IMAP works with any IMAP-supported email account. 165 | NOTE: You may want to create a new email account with the sole purpose of receiving Mailchain messages to achieve separation between messages. 166 | 167 | **Can I use the Mailchain Connector for IMAP with Gmail?** 168 | Yes. We recommend you follow the instructions to create an [App Password](https://support.google.com/accounts/answer/185833?hl=en) to sign into your Gmail account, then configure your IMAP settings as [recommended by Gmail](https://support.google.com/mail/answer/7126229?hl=en-GB). 169 | 170 | **Can I use the Mailchain Connector for IMAP with my own IMAP server?** 171 | Yes. Simply configure the IMAP settings according to the configuration instructions. 172 | 173 | **Can I store my IMAP password in the Mailchain Connector for IMAP configuration?** 174 | No. We prefer you enter it at runtime so your email credentials are not stored on the local machine. 175 | 176 | **Can I view Mailchain messages in email client on my desktop \(e.g. Outlook or Mail\), iPhone, Android, or other smartphone?** 177 | Yes. By using the Mailchain Connector for IMAP to transfer your Mailchain messages to an IMAP email account, you can connect your email client to that IMAP email account to receive the messages in the same way as you would receive regular email. 178 | 179 | **Are the Mailchain messages still encrypted when they are sent to my IMAP server?** 180 | No. The Mailchain client decrypts messages so they can be converted into regular emails before being transferred to the IMAP server. 181 | 182 | **Will my email provider be able to read my Mailchain messages?** 183 | Because the Mailchain messages are converted to emails before being stored on the IMAP server, your email provider will have the same visibility of the your Mailchain messages as any other email in your inbox. 184 | NOTE: Greater privacy can be achieved by running your own email server. 185 | 186 | **Can I search the Mailchain messages in my email inbox?** 187 | Yes. The Mailchain messages in your email inbox will be searchable in the same way as any other email might be. 188 | 189 | **Can I reply to messages from my email client?** 190 | No. In order to reply to Mailchain messages, an SMTP connector would be required. This is on the roadmap. 191 | 192 | **Where can I find the log file for the Mailchain Connector for IMAP?** 193 | You can find the logs here: `~/.mailchain_connector/imap/mailchain_connector_imap.log` 194 | 195 | **How do I uninstall the Mailchain Connector for IMAP?** 196 | To uninstall the Mailchain Connector for IMAP, run`gem uninstall mailchain_connector_imap` 197 | Next, delete the folder `~/.mailchain_connector/imap/` 198 | 199 | 200 | 201 | -------------------------------------------------------------------------------- /reference/algorand.md: -------------------------------------------------------------------------------- 1 | # Algorand 2 | 3 | Mailchain users can send messages to any Algorand account address. This section details how the Algorand implementation of the [Message Flow](../concepts/overview.md) is achieved. 4 | 5 | ### Networks 6 | 7 | Mailchain supports all the public Algorand networks 8 | 9 | | Network | Status | 10 | | :--- | :--- | 11 | | Mainnet | Full | 12 | | BetaNet | Full | 13 | | TestNet | Full | 14 | 15 | ### Public Key Finder 16 | 17 | To send an encrypted message, a public key is required. Mailchain uses the public key associated with an account address to encrypt message data, and if specified by the envelope, the message contents too. This ensures the recipient is also the owner of the private key and only they can decrypt data. The public key finder returns the public key for a recipient public address. 18 | 19 | {% hint style="info" %} 20 | The public key for an account address can be calculated from the public address by converting it from its Base32 encoded representation to Base58 and removing the 4-byte checksum. 21 | {% endhint %} 22 | 23 | ### Sender 24 | 25 | Algorand transactions are used to [send](../concepts/send.md) a message. 26 | 27 | #### Envelope 28 | 29 | Transactions contain a `note` field that stores the [envelope](programmable-envelopes.md). Bytes can be stored in the `note` field and can be any data up to 1000 bytes. Data stored in a transaction must follow the Mailchain [standard encoding format](../concepts/send.md#send-transaction):`[protocol-prefix]+[mailchain-prefix]+[envelope]`. This data will be encoded to Base64 when transmitted. 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 52 | 53 | 54 | 55 | 56 | 58 | 59 | 60 | 61 |
FieldExampleNotes
protocol-prefixNone 44 |

Transaction data prefix is not required for Algorand.

45 |

46 |
mailchain-identifierbWFpbGNoYWlu 51 | "mailchain" encoded as base64
envelopeAQpuKuI/nZUw6qvRDt+/aAUOqu7J72/CZMc+kPsbVrCTq1MB9JwTVJadZJLB4h07XEon6Yf9ubvaxTTHAltoFjyWipQzyuxFfP1I8Y5OZE4dUFsEheF2jN8DUfKwpQKEKILoySTH6a4VhWwq8R1T3/0SBiIEsORJjw 57 | Envelope encoded as hexadecimal
62 | 63 | An example of a transaction `note` field for a Mailchain message sent on Algorand is as follows: 64 | 65 | ```text 66 | bWFpbGNoYWluAQpuKuI/nZUw6qvRDt+/aAUOqu7J72/CZMc+kPsbVrCTq1MB9JwTVJadZJLB4h07XEon6Yf9ubvaxTTHAltoFjyWipQzyuxFfP1I8Y5OZE4dUFsEheF2jN8DUfKwpQKEKILoySTH6a4VhWwq8R1T3/0SBiIEsORJjw== 67 | ``` 68 | 69 | The same transaction and data can be viewed [here](https://testnet.algoexplorer.io/tx/YA6BWUPKZGT237Y7MTDJHEKOZKRAQPTF7YY2EENBQGQWU7TWJFVA) on [Algoexplorer](https://algoexplorer.io/). 70 | 71 | #### Transaction Fields 72 | 73 | To send a message the following Algorand transaction fields must be specified. 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 91 | 93 | 94 | 96 | 97 | 98 | 99 | 100 | 102 | 104 | 105 | 107 | 109 | 110 | 111 | 112 | 114 | 116 | 117 | 119 | 120 | 121 | 122 | 123 | 125 | 126 | 127 | 130 | 131 | 132 | 133 | 134 | 136 | 140 | 142 | 147 | 148 | 149 | 150 | 151 | 153 | 157 | 159 | 164 | 165 | 166 | 167 | 168 | 170 | 172 | 173 | 175 | 176 | 177 | 178 | 179 | 181 | 182 | 184 | 185 | 186 | 187 | 188 | 189 | 191 | 193 | 195 | 200 | 201 | 202 | 203 |
FieldCodecTypeExampleNotes
Feefee 90 | uint64 92 | 1000Paid by the sender to the FeeSink to prevent denial-of-service. The minimum 95 | fee on Algorand is currently 1000 microAlgos.
FirstValidfv 101 | uint64 103 | 6000000The first round for when the transaction is valid. If the transaction 106 | is sent prior to this round it will be rejected by the network.
LastValidlv 113 | uint64 115 | 6001000The ending round for which the transaction is valid. After this round, 118 | the transaction will be rejected by the network.
GenesisHashgh 124 | [32]byte"mainnet-v1.0"The hash of the genesis block for the network for which the transaction 128 | is valid. See Algorand developer documentation for details of the genesis 129 | hash for MainNet, TestNet, and BetaNet.
Sendersnd 135 | 137 |

Address

138 |

(string)

139 | 		G2GTKMEEEEZH5TFUDYZMWWGXZLO3Z7765CR52ZXBBNCCMNPDYM3ZII7CSI 141 | 143 |

The address of the account that sends the messages and pays the fee.

144 |

Added by the client, based on sender address in message. 145 |

146 |
Receiverrcv 152 | 154 |

Address

155 |

(string)

156 | 		UWH6MCLMZSD2UYWTJVKFKX6JMTX2TGXAOYPUBNHFFQFBBVJULXJXZJNPBU 158 | 160 |

The address of the account that receives the message.

161 |

Added by the client, based on recipient address in message. 162 |

163 |
TxTypetype 169 | string 171 | "pay"Specifies the type of Algorand transaction. Mailchain uses a zero-value payment transaction by default. 174 |
Notenote 180 | []bytebWFpbGNoYWluAQpuKuI/nZUw6qvRDt+/aAUOqu7J72/CZMc+kPsbVrCTq1MB9JwTVJadZJLB4h07XEon6Yf9ubvaxTTHAltoFjyWipQzyuxFfP1I8Y5OZE4dUFsEheF2jN8DUfKwpQKEKILoySTH6a4VhWwq8R1T3/0SBiIEsORJjw== 183 | Envelope data
Amountamt 190 | uint64 192 | 0 194 | 196 |

The total amount to be sent in microAlgos.

197 |

Mailchain sets this to 0 (zero). 198 |

199 |
204 | 205 | Once the transaction fields have been populated, it must be signed using the sender private key. The signed transaction bytes can then be transmitted to the Algorand network via the Algorand network API endpoint using the `POST` [/v2/transactions](https://developer.algorand.org/docs/reference/rest-apis/algod/v2/#post-v2transactions) method. 206 | 207 | ### Receiver 208 | 209 | To [read](../concepts/read.md) Mailchain messages for a specific address, transactions sent to that address need to be identified. The Algorand indexer natively supports an address index to identify all transactions sent to a specific address. 210 | 211 | ### Rekeying 212 | 213 | Rekeying an account enables an Algorand account holder to maintain a static public address while dynamically rotating the authoritative private spending keys \(see [https://developer.algorand.org/docs/features/accounts/rekey/](https://developer.algorand.org/docs/features/accounts/rekey/) for more information\). 214 | 215 | If an account has been rekeyed, Mailchain will include the rekeyed account address in the reply-to field. Any replies to messages received from an authorised address for a rekeyed account will be sent to the initial rekeyed account. 216 | 217 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright 2022 Mailchain Ltd. 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | --------------------------------------------------------------------------------