From 6dfb8ea38e34807a1f56a551d7a68f3c5e541f43 Mon Sep 17 00:00:00 2001 From: Joseph Fajen Date: Thu, 18 Jan 2024 14:18:42 -0800 Subject: [PATCH] adding new page Roles in Marlowe --- .../large-contracts.md | 2 +- .../object-format.md | 2 +- .../on-chain-limitations.md | 2 +- .../roles-in-marlowe.md | 44 +++++++++++++++++++ .../versioning-policy.md | 2 +- 5 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 docs/platform-and-architecture/roles-in-marlowe.md diff --git a/docs/platform-and-architecture/large-contracts.md b/docs/platform-and-architecture/large-contracts.md index dd53b64..b29eb38 100644 --- a/docs/platform-and-architecture/large-contracts.md +++ b/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, diff --git a/docs/platform-and-architecture/object-format.md b/docs/platform-and-architecture/object-format.md index 91bafb3..999bd39 100644 --- a/docs/platform-and-architecture/object-format.md +++ b/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 diff --git a/docs/platform-and-architecture/on-chain-limitations.md b/docs/platform-and-architecture/on-chain-limitations.md index d423292..a6706d8 100644 --- a/docs/platform-and-architecture/on-chain-limitations.md +++ b/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)**. diff --git a/docs/platform-and-architecture/roles-in-marlowe.md b/docs/platform-and-architecture/roles-in-marlowe.md new file mode 100644 index 0000000..1409f80 --- /dev/null +++ b/docs/platform-and-architecture/roles-in-marlowe.md @@ -0,0 +1,44 @@ +--- +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 hardcoded addresses, pre-determined prior to launching a contract or determined after launching a contract. + +These roles are uniquely identified using role tokens. + +## Role tokens + +Role tokens are used to identify roles to authorize transactions providing additional security and flexibility for your smart contracts. They are handled implicitly by the 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. + +You can view these role tokens in your wallet under NFTs/Assets with a name reflective of the name specified for the role in the smart contract. (In Nami, Lace does not carry the name over from the DApp to the asset.) + +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 the 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. diff --git a/docs/platform-and-architecture/versioning-policy.md b/docs/platform-and-architecture/versioning-policy.md index d8d946f..176c3b5 100644 --- a/docs/platform-and-architecture/versioning-policy.md +++ b/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.