adding new page Roles in Marlowe (#205)

* adding new page Roles in Marlowe

* Minor tweaks

* further edits, removed now redundant content about role tokens from Payouts DApp prototype page

* further edits

* removed unnecessary statement about Nami and Lace

* minor edits

---------

Co-authored-by: olgahryniuk <[email protected]>

docs/developer-tools/ts-sdk/payouts-dapp-prototype.md

@@ -31,10 +31,3 @@ Using the payouts DApp functionality alongside **[Runner](../../getting-started/
 
 The payouts DApp lists available tokens that an authorized role can withdraw for that wallet. The recipient clicks the ‘Withdraw’ button and sees a prompt to sign the transaction. After the recipient signs the transaction, the transaction is confirmed. The recipient can then see the funds in their wallet. 
 
-## Role tokens
-
-At a high level, role tokens are a unique feature of Marlowe smart contracts that provide additional security and flexibility. They are used to authorize transactions, and any participant in a contract can hold them. 
-
-Each participant in a Marlowe contract has a role, and each role has its own role token. Participants hold role tokens in their wallets and use them to authorize transactions. Participants who want to make a transaction include their role token as input. The token doesn’t stay with the script or go anywhere else; it simply passes through the script and returns to the participant, allowing them to authorize another transaction.
-
-Role tokens can be transferred between wallets, which means a participant can give their role to someone else. This feature introduces flexibility and security beyond the use of private keys alone.

docs/platform-and-architecture/large-contracts.md

@@ -1,6 +1,6 @@
 ---
 title: Managing large contracts (Merkleization)
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 In many real world scenarios, the size of a Marlowe contract can pose challenges. For instance,

docs/platform-and-architecture/object-format.md

@@ -1,6 +1,6 @@
 ---
 title: Marlowe object bundle format
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 One limitation of the Marlowe language is its lack of named abstraction (with

docs/platform-and-architecture/on-chain-limitations.md

@@ -1,6 +1,6 @@
 ---
 title: Marlowe's on-chain limitations
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 When developing smart contracts for Marlowe, there are a series of considerations to take into account before running them in production on mainnet. Highly recommended documents to review are **[Best Practices for Marlowe on Cardano](https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe/best-practices.md)** and the **[Marlowe Security Guide](https://github.com/input-output-hk/marlowe-cardano/blob/main/marlowe/security.md)**.

docs/platform-and-architecture/roles-in-marlowe.md

@@ -0,0 +1,46 @@
+---
+title: Roles in Marlowe
+sidebar_position: 5
+---
+
+Generally speaking, participants are actors in a smart contract. These participants fulfill roles that specify the ability to execute certain actions in the contract.
+
+Roles can be hard coded addresses, pre-determined before launching a contract or determined after launching a contract.
+
+These roles are uniquely identified using role tokens.
+
+## Role tokens
+
+Participants hold role tokens in their wallets as assets or NFTs. 
+
+Role tokens are used to identify roles to authorize transactions providing additional security and flexibility for your smart contracts. They are handled implicitly by Marlowe Runtime. 
+
+Each participant in a Marlowe contract has a role and each role has its own token. These tokens can be transferred between users in a peer-to-peer manner, allowing a participant to give their role to someone else.
+
+There could be one or many tokens for a specific role.
+
+Role tokens are distributed at contract initialization.
+
+Participants who want to make a transaction include their role token as input. The token doesn’t stay with the script or go anywhere else; it simply passes through the script and returns to the participant, allowing them to authorize another transaction.
+
+When designating an address after launching the contract, the open roles feature is used. 
+
+## Open roles
+
+'Open roles' allows for the specification of an address after contract deployment that is not known at deployment time.
+
+When using open roles, the Marlowe contract sends the role tokens to a validator script that holds them until you specify an address later, at which time they are sent to the appropriate address.
+
+This feature is best used when a developer is deploying a smart contract where certain addresses are unknown. It could be one address or all addresses associated with a contract.
+
+The developer would deploy a contract that could be verified on-chain before a user interacts with it. The user initiates some action, like a deposit or choice, which triggers the smart contract to assign them the appropriate role and distribute the role token from the validator script.
+
+The developer just needs to specify the `OpenRoles` type when setting participants in a contract, the rest is handled behind the scenes by Marlowe Runtime. 
+
+Because we have now introduced a separate validator script to help with our smart contract, we need to assign a 'thread token.'
+
+### Thread tokens
+
+Much like a role token is tied to a participant, a thread token is tied to a contract instance.
+
+Thread tokens are required for the validator script to be able to determine which 'thread' of role tokens to track, where 'threads' are instances of a contract. Without it, the script would not know which contract to apply the role tokens to.

docs/platform-and-architecture/versioning-policy.md

@@ -1,6 +1,6 @@
 ---
 title: Versioning policy
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 This document is intended to provide guidance for compatibility of tools within Marlowe with Cardano node. Developers can use this for tracking purposes and more formal support policies as the project matures.