Ledger contract

The Marmalade token standard provides interfaces that enable you to define, mint, and secure tokens. As discussed in Contract architecture, the Marmalade ledger contract provides the core functionality to create, manage, and transfer tokens minted using the Marmalade token standard. The ledger contract records and manages all token-related activity to ensure every transaction is accurate, every policy is enforced, and every account is up-to-date.

This part of the documentation describes the functions and capabilities defined in the Marmalade ledger contract in the marmalade-v2 namespace. The marmalade-v2 namespace is available on all twenty chains (0-19) in the Kadena test network and the Kadena main network.

Source code: ledger.pact

Use create-token-id to generate a unique token identifier with the specified token identifier.

Use the following arguments to create the token identifier.

Before creating a token, you must choose a temporary guard. The guard can be

This guard becomes part of the hashed data in the token-id string prefixed with t:. Including the guard in the hashed token identifier protects anyone else from creating the token. With this mechanism, only you—as the owner of the creation key—can create the token specified by the token-id string.

Generate a unique token-id by calling the following function:

(ledger.create-token-id details creation-guard)

Use create-token to create a token with the specified token identifier. You can apply one or more policies to a token when you create it. Depending on the policies you apply, you might need to grant additional capabilities or pass environment data to execute the function.

Use the following arguments to create a token.

When you submit the create-token transaction, the policy-manager.enforce-init function calls the policy:enforce-init function in the stored token policies and the function is executed.

To create a token with this function:

The create-token transaction must include the CREATE-TOKEN capability signed with the keyset creation-guard that you used to generate the token identifier. The create-token transaction also requires the marmalade-v2.collection-policy-v1.TOKEN-COLLECTION capability if you apply the collection-policy to create token.

Required capabilities and parameters for the create-token function:

If you apply the guard-policy to create a token, you can add the following information as raw data:

If you apply the collection-policy to create a token, you can add the following information as raw data:

If you apply the royalty-policy to create a token, you can add the following information as raw data:

The royalty_spec object includes the following properties:

Use mint to mint the specified token amount to the specified account.

Use the following arguments to mint a token.

When you submit the mint transaction, the policy-manager.enforce-mint function calls the policy:enforce-mint function in the stored token policies and the function is executed.

The mint transaction must include the MINT capability signed with the account that receives the token. The mint transaction also requires the marmalade-v2.guard-policy-v1.MINT capability if you apply the guard-policy and define a mint guard for the token.

Required capabilities and parameters for the mint function:

Use burn to destroy the specified token amount from the specified token owner account.

Use the following arguments to burn a token.

When you submit the burn transaction, the policy-manager.enforce-burn function calls the policy:enforce-burn function in the stored token policies and the function is executed.

The burn transaction must include the BURN capability signed with the account that owns the token. The burn transaction also requires the marmalade-v2.guard-policy-v1.BURN capability if you apply the guard-policy and define a burn guard for the token.

Required capabilities and parameters for the burn function:

Use transfer to transfer the specified token amount from the specified sender to the specified receiver.

Use the following arguments to transfer a token.

When you submit the transfer transaction, the policy-manager.enforce-transfer function calls the policy:enforce-transfer function in the stored token policies and the function is executed.

The transfer transaction must include the TRANSFER capability signed with the sender that owns the token. The transfer transaction also requires the marmalade-v2.guard-policy-v1.TRANSFER capability if you apply the guard-policy and define a transfer guard for the token.

Required capabilities and parameters for the transfer function:

Use transfer-create to transfer the specified token amount from the specified sender to the specified receiver and creates the receiver account, if the account doesn't exist.

Use the following arguments to transfer a token.

When you submit the transfer-create transaction, the policy-manager.enforce-transfer function calls the policy:enforce-transfer function in the stored token policies and the function is executed at ledger.transfer-create. The difference between transfer and transfer-create is that transfer-create can be used for both non-existent and existing receiver accounts, with an additional check for the receiver guard if already exists. The transfer can only be used for existing receiveraccount.

The transfer-create transaction must include the TRANSFER capability signed with the sender that owns the token. The transfer-create transaction also requires the marmalade-v2.guard-policy-v1.TRANSFER capability if you apply the guard-policy and define a transfer guard for the token.

Required capabilities and parameters for the transfer-create function:

Use sale to execute a two-step transaction using the offer and buy steps with an escrow account as described in Token sales and trustless-escrow.

Because a sale requires two steps that must be completed in a specific order, the transaction is defined using a pact. For information about the syntax used to define a pact, see defpact.

Use the following arguments to initiate the sale of a token.

The first step of a sale pact (step 0) executes the offer function. The offer function transfers the token from the seller's account to the escrow account.

The policy-manager.enforce-offer function calls the policy:enforce-offer function in the stored token policies and the function is executed at step 0 of the sale.

The offer transaction must include the OFFER capability signed with the seller that owns the token. The offer transaction also requires the marmalade-v2.guard-policy-v1.SALE capability if you apply the guard-policy and define a sales guard for the token.

Required capabilities and parameters for the offer function:

If the offer is a dutch or conventional auction, you can add the following information as raw data:

The quote object includes the following properties:

The sale pact includes a rollback step (step 0-rollback). The rollback step executes the withdraw function. The withdraw function transfers the tokens held in the escrow account for the sale back to the seller. If a timeout is specified, the withdraw function can only be executed after the timeout period has passed. You can execute the withdraw function by sending a continuation (cont) command with the following information:

For more information about formatting continuation commands, see Formatting API requests in YAML.

The policy-manager.enforce-withdraw function calls the policy:enforce-withdraw function in the stored token policies and the function is executed at step 0-rollback of sale.

The withdraw transaction must include the WITHDRAW capability signed with the seller that owns the token. The withdraw transaction also requires the marmalade-v2.guard-policy-v1.SALE capability if you apply the guard-policy and define a sales guard for the token.

Required capabilities and parameters for the withdraw function:

The second step of a sale pact (step 1) executes the buy function. The buy function transfers the tokens held in the escrow account to the buyer. The buy function can be executed before timeout. The buyer and buyer-guard information is read from the env-data of the command instead of passing in arguments. Like the withdraw function, the buy function is executed using a continuation (cont) command:

The policy-manager.enforce-buy function calls the policy:enforce-buy function in the stored token policies and the function is executed at step 1 of sale.

The buy transaction must include the BUY capability signed with the buyer that is buying the token. The buy transaction also requires the marmalade-v2.guard-policy-v1.SALE capability if you apply the guard-policy and define a sales guard for the token.

Required capabilities and parameters for the buy function:

If the sale is a dutch or conventional auction, you need to add the following information as raw data:

Use update-uri to update the uri for an existing token.

When you submit the update-uri transaction, the policy-manager.enforce-update-uri function calls the policy:enforce-update-uri function in the stored token policies and the function is executed at ledger.update-uri. Token creators should configure the entity that will be authorized to update the uri's in the guard-policy-v1, or in their custom policies.

The update-uri transaction must include the UPDATE-URI capability signed with the buyer that is buying the token. The update-uri transaction also requires the marmalade-v2.guard-policy-v1.UPDATE-URI capability if you apply the guard-policy and define a uri guard for the token.

Required capabilities and parameters for the update-uri function: