describe an initial deposit of assets for the accounts in the contract. The key is the address or role name and the value is the assets. These assets will be deposited in the accounts at the creation of the contract, and will come from the contract creator's wallet.
The Marlowe Runtime utilizes this mandatory field and any additional addresses provided in usedAddresses
to search for UTxOs that can be used to balance the contract creation transaction.
Any change from the creation transaction will be sent here.
Optional collateralUTxUTxOs provided as collateral in case the Tx built will unexpectedly fail at the submit phase.
The collateral mechanism is an important feature that has been designed to ensure successful smart contract execution.
Collateral is used to guarantee that nodes are compensated for their work in case phase-2 validation fails. Thus, collateral is the monetary guarantee a user gives to assure that the contract has been carefully designed and thoroughly tested.
Collateral amount is specified at the time of constructing the transaction. Not directly, but by adding collateral inputs to the transaction.
The total balance in the UTXOs corresponding to these specially marked inputs is the transaction’s collateral amount.
If the user fulfills the conditions of the guarantee, and a contract gets executed, the collateral is safe.
Optional metadataCardano Metadata about the contract creation.
Metadata can be expressed as a JSON object with some restrictions: - All top-level keys must be integers between 0 and 2^63 - 1. - Each metadata value is tagged with its type. - Strings must be at most 64 characters long (64 bytes) when UTF-8 is encoded. - Bytestrings are hex-encoded, with a maximum length of 64 bytes.
Metadata aren't stored as JSON on the Cardano blockchain but are instead stored using a compact binary encoding (CBOR). The binary encoding of metadata values supports three simple types:
-(2^63 - 1) to 2^63 - 1Optional minimumMinimum Lovelace value to add on the UTxO created (Representing the Marlowe Contract Created on the ledger).This value is computed automatically within the Runtime, so this parameter is only necessary if you need some custom adjustment.
Creating a Marlowe contract over Cardano is about creating UTxO entries on the Ledger.
To protect the ledger from growing beyond a certain size that will cost too much to maintain, a constraint called "Minimum ada value requirement (minimumLovelaceUTxODeposit)" that adjust the value (in ADA) of each UTxO has been added.
The bigger the UTxOs entries are in terms of bytesize, the higher the value if minimum ADA required.
Optional rolesRole Token Configuration for the new contract passed in the contractOrSourceId field.
Participants (Party) in a Marlowe Contract can be expressed in 2 ways:
cardano-cli, another Marlowe Contract Created, etc.. )contractOrSourceId first will be identified as a participant by receiving the Role Token in their wallet. In that case, participants are unknown at the creation and the participation is open to any meeting the criteria.Smart Constructors are available to ease these configuration:
//////////////
// #1 - Mint Role Tokens
//////////////
const anAddressBech32 = "addr_test1qqe342swyfn75mp2anj45f8ythjyxg6m7pu0pznptl6f2d84kwuzrh8c83gzhrq5zcw7ytmqc863z5rhhwst3w4x87eq0td9ja"
const aMintingConfiguration =
{ "closed_Role_A_NFT" : mintRole(anAddressBech32)
, "closed_Role_B_FT" :
mintRole(
anAddressBech32,
5, // Quantities
{ "name": "closed_Role_B_FT Marlowe Role Token",
"description": "These are metadata for closedRoleB",
image": "ipfs://QmaQMH7ybS9KmdYQpa4FMtAhwJH5cNaacpg4fTwhfPvcwj",
"mediaType": "image/png",
"files": [
{
"name": "icon-1000",
"mediaType": "image/webp",
"src": "ipfs://QmUbvavFxGSSEo3ipQf7rjrELDvXHDshWkHZSpV8CVdSE5"
}
]
})
, "open_Role_C" : mintRole(openRole)
, "open_Role_D" : mintRole(
openRole,
2, // Quantities
{ "name": "open_Role_D Marlowe Role Token",
"description": "These are metadata for closedRoleB",
image": "ipfs://QmaQMH7ybS9KmdYQpa4FMtAhwJH5cNaacpg4fTwhfPvcwj",
"mediaType": "image/png",
"files": [
{
"name": "icon-1000",
"mediaType": "image/webp",
"src": "ipfs://QmUbvavFxGSSEo3ipQf7rjrELDvXHDshWkHZSpV8CVdSE5"
}
]
})
}
//////////////
// #2 Use Minted Roles Tokens
const aUseMintedRoleTokensConfiguration =
useMintedRoles(
"e68f1cea19752d1292b4be71b7f5d2b3219a15859c028f7454f66cdf",
["role_A","role_C"]
)
Optional stakeMarlowe contracts can have staking rewards for the ADA locked in the contract. Use this field to set the recipient address of those rewards
Optional tagsMarlowe Tags are stored as Metadata within the Transaction Metadata under the top-level Marlowe Reserved Key (1564).
Tags allows to Query created Marlowe Contracts via Get contracts
const myTags : Tags = { "My Tag 1 That can be as long as I want": // Not limited to 64 bytes
{ a: 0
, b : "Tag 1 content" // Limited to 64 bytes (Cardano Metadata constraint)
},
"MyTag2": { c: 0, d : "Tag 2 content"}};
Optional Experimental threadThe Thread Roles capability is an implementation details of the runtime. It allows you to provide a custom name if the thread role name is conflicting with other role names used.
- the Thread Role Name is "" by default.
Optional usedThe Marlowe Runtime utilizes the mandatory changeAddress and any additional addresses provided here
to search for UTxOs that can be used to balance the contract creation transaction.
changeAddress field, it is redundant to include it here (but it doesn't fail).The Marlowe validator version to use.
Request options for the Build Create Contract Tx endpoint