Skip to content

Commit 08e5b02

Browse files
nillonillo
committed
fixes in docs policymanager and ledger
1 parent 91bccf0 commit 08e5b02

File tree

3 files changed

+234
-64
lines changed

3 files changed

+234
-64
lines changed

‎packages/apps/docs/src/pages/marmalade/architecture/ledger.md

+120-26
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,13 @@ layout: full
99

1010
# The Marmalade Ledger Explained
1111

12-
**What is the Marmalade Ledger?**
12+
## What is the Marmalade Ledger?
1313

14-
What is it and what is it used for. Think of a
15-
[Ledger](https://github.com/kadena-io/marmalade/blob/v2/pact/ledger.pact) as
16-
your personal bank statement, only in this case its not just for you, it's for
17-
everybody participating in the system. It's this big ol' record that keeps track
18-
of the things within marmalade that happen. You can look at the ledger as the
19-
heart of marmalade, the place where most of the action happens.
14+
What is it and what is it used for. Think of a Ledger as your personal bank
15+
statement, only in this case its not just for you, it's for everybody
16+
participating in the system. It's this big ol' record that keeps track of the
17+
things within marmalade that happen. You can look at the ledger as the heart of
18+
marmalade, the place where most of the action happens.
2019

2120
In the context of NFTs, the Marmalade Ledger plays a crucial role in managing
2221
the lifecycle of these unique digital assets. It provides the underlying
@@ -39,31 +38,125 @@ transactions.
3938
When delving further into the ledger's workings, we find each function and
4039
capability playing a unique role in its operation and management.
4140

42-
**Capabilities**
41+
## Marmalade functions
4342

44-
There are capabilities like `TRANSFER`, which work similarly to the transfer
45-
feature on your online banking application. They help move tokens between
46-
accounts. There are also capabilities for updates and checks, such as `SUPPLY`,
47-
`TOKEN`, `ACCOUNT_GUARD`, and `RECONCILE`.
43+
**Create Token**
4844

49-
Some more specific capabilities include `DEBIT` and `CREDIT`, which gives the
50-
power to use debit or credit functions, and `UPDATE_SUPPLY` allows adjustments
51-
to a token's total circulation.
45+
A Token is created in marmalade via running `create-token`. Arguments include:
5246

53-
Capabilities like `MINT` and `BURN` enable creation and removal of tokens
54-
respectively.
47+
- `id`: token-id, formatted in `t:{token-detail-hash}`. Should be created using
48+
`create-token-id`
49+
- `precision`: Number of decimals allowed for for the token amount. For one-off
50+
token, precision must be 0, and should be enforced in the policy's
51+
`enforce-init`.
52+
- `uri`: url to external JSON containing metadata
53+
- `policies`: policies contracts with custom functions to execute at marmalade
54+
functions
55+
- `creation-guard`: Non stored guard (usally a Keyset). Must be used to reserve
56+
a `token-id`
5557

56-
**Marketplace related capabilities**
58+
`policy-manager.enforce-init` calls `policy::enforce-init` in stored
59+
token-policies, and the function is executed in `ledger.create-token`.
5760

58-
Special marketplace-related capabilities like `SALE`, `OFFER`, `WITHDRAW`, and
59-
`BUY` facilitate the trading of tokens within the marketplace.
61+
**Creation guard usage**
6062

61-
**Core functions**
63+
Before creating a token, the creator must choose a temporary guard, which can be
6264

63-
Core functions such as `create-token`, `create-account`, `mint`, `burn`,
64-
`offer`, `withdraw`, `buy`, `transfer`, `get-balance`, `details`,
65-
`total-supply`, and `get-uri` offer a variety of operations from creating new
66-
tokens and accounts to managing token trading in the marketplace.
65+
- An usual keyset. (eg: one already used in the guard-policy).
66+
- But also a single-use keyset, since it isn't stored and won't be needed
67+
anymore.
68+
- Some more complex setups could involve other guard types (eg: when token
69+
creations are managed by a SC).
70+
71+
This guard will be part of the `token-id` (starting `t:`) creation. As a
72+
consequence, it protects the legit creator from being front-runned during token
73+
creation. With this mechanism, only the legit creator who owns the creation key
74+
can create a specific `token-id`.
75+
76+
Creation steps:
77+
78+
- Generate a unique `token-id` by calling
79+
`(ledger.create-token-id details creation-guard)`
80+
- Create the token by calling `(ledger.create-token ... creation-guard)`
81+
- This transaction must include the `TOKEN` capability signed with the keyset
82+
`creation-guard`
83+
84+
**Mint Token**
85+
86+
Token amount is minted to an account at `mint`. Arguments include:
87+
88+
- `id`: token-id
89+
- `account`: account that will receive the minted token
90+
- `guard`: guard of the minted account
91+
- `amount`: amount to be minted
92+
93+
`policy-manager.enforce-mint` calls `policy:enforce-mint` in stored
94+
token-policies, and the function is executed at `ledger.mint`.
95+
96+
**Burn Token**
97+
98+
Token amount is burnt from an account at `burn`. Arguments include:
99+
100+
- `id`: token-id
101+
- `account`: account where the token will be burnt from
102+
- `amount`: amount to be burnt
103+
104+
`policy-manager.enforce-burn` calls `policy:enforce-burn` in stored
105+
token-policies, and the function is executed at `ledger.burn`.
106+
107+
**Transfer**
108+
109+
Token amount is transferred from sender to receiver at `transfer`. Arguments
110+
include:
111+
112+
- `id`: token-id
113+
- `sender`: sender account
114+
- `receiver`: receiver account
115+
- `amount`: amount to be transferred
116+
117+
`policy-manager.enforce-transfer` calls `policy:enforce-transfer` in stored
118+
token-policies, and the function is executed at `ledger.transfer`.
119+
120+
**Sale**
121+
122+
`sale` allows a two-step offer - buy escrow system using
123+
[defpact](https://pact-language.readthedocs.io/en/latest/pact-reference.html#defpact).
124+
Arguments include:
125+
126+
- `id`: token-id
127+
- `seller`: seller account
128+
- `amount`: amount to be sold
129+
- `timeout`: timeout of the offer
130+
131+
**offer**
132+
133+
Step 0 of `sale` executes `offer`. `offer` transfers the token from the seller
134+
to the escrow account.
135+
136+
`policy-manager.enforce-offer` calls `policy:enforce-offer` in stored
137+
token-policies, and the function is executed at step 0 of `sale`.
138+
139+
**withdraw (cont)**
140+
141+
Step 0-rollback executes `withdraw`. `withdraw` transfers token from the escrow
142+
back to the seller. `withdraw` can be executed after timeout, by sending in
143+
`cont` command with `rollback: true`, `step: 0`. Formatting `cont` commands can
144+
be read in
145+
[here](https://pact-language.readthedocs.io/en/latest/pact-reference.html?highlight=continuation#yaml-continuation-command-request)
146+
147+
`policy-manager.enforce-withdraw` calls `policy:enforce-withdraw` in stored
148+
token-policies, and the function is executed at step 0-rollback of `sale`.
149+
150+
**buy (cont)**
151+
152+
Step 1 executes `buy`. `buy` transfers token from the escrow to the buyer. `buy`
153+
can be executed before `timeout`. The `buyer` and `buyer-guard` information is
154+
read from the `env-data` of the command instead of passing in arguments. Just
155+
like `withdraw`, `buy` is executed using `cont` command with `rollback:false`,
156+
`step: 0`.
157+
158+
`policy-manager.enforce-buy` calls `policy:enforce-buy` in stored
159+
token-policies, and the function is executed at step 1 of `sale`.
67160

68161
---
69162

@@ -77,5 +170,6 @@ We hope you've got a sense of what the marmalade ledger is all about.
77170
Whether you're a code whizz or a crypto newbie, we hope this journey into the
78171
workings of this ledger has helped to unravel some of the mysteries behind it.
79172
You could be buying a new digital art piece today or selling some tomorrow.
173+
Marmalade makes it possible.
80174

81-
**Marmalade makes it possible.**
175+
[Leder code](https://github.com/kadena-io/marmalade/blob/v2/pact/ledger.pact)

‎packages/apps/docs/src/pages/marmalade/architecture/policy-manager.md

+112-36
Original file line numberDiff line numberDiff line change
@@ -7,58 +7,134 @@ order: 2
77
layout: full
88
---
99

10-
# Policy Manager
10+
# Policy Manager in Marmalade V2
1111

12-
Marmalade V2 introduces the
13-
[Policy manager](https://github.com/kadena-io/marmalade/blob/v2/pact/policy-manager/policy-manager.pact),
14-
a powerful tool that revolutionizes how policies are managed, but also enabling
15-
stacking of policies for non-fungible tokens (NFTs). The Policy Manager serves
16-
as the repository for these policies. If a general-purpose policy gains
17-
widespread acceptance, it could be incorporated as a concrete policy. This
18-
allows dApps, marketplaces, or wallets to readily identify token properties,
19-
such as collections, non-fungibility, or royalty specifications, by leveraging
20-
the concrete policies stored in the Policy Manager.
12+
Marmalade V2 introduces a groundbreaking Policy Manager, a tool that transforms
13+
how policies for non-fungible tokens (NFTs) are curated and implemented. With
14+
this innovation, dApps, marketplaces, and wallets can seamlessly identify token
15+
properties like collections, non-fungibility, and royalty specifications,
16+
leveraging the concrete policies within the Policy Manager.
2117

22-
## Key Features of the Policy Manager
18+
## Overview
2319

24-
**1. Policies Tailored to You**
20+
The Policy Manager stands as a central repository for these policies, supporting
21+
both general-purpose policies and concrete policies. When a general-purpose
22+
policy becomes widely accepted, it has the potential to be assimilated as a
23+
concrete policy, contributing to the stability and uniformity of token
24+
attributes.
2525

26-
With the Policy Manager, you can add (manage) policies that match your unique
27-
use cases. These policies define the behavior and attributes of your NFTs.
26+
**Key Features of the Policy Manager:**
2827

29-
**2. Dynamic Implementation with Concrete Policies and Custom Policies**
28+
1. **Tailored Policies**: Customize and manage policies to define your NFTs'
29+
behavior and attributes.
30+
2. **Dynamic Implementation**: Utilize both immutable Concrete Policies
31+
(provided by Marmalade's creators) and Custom Policies (created by anyone)
32+
for additional, unique functionalities.
33+
3. **Policy Stacking**: Stack multiple policies with tokens, resulting in
34+
dynamic and intricate NFTs.
35+
4. **Standardized Enforcement**: Policies are consistently enforced across the
36+
Marmalade ecosystem through the
37+
[`kip.token-policy-v2`](https://github.com/kadena-io/marmalade/blob/v2/pact/kip/token-policy-v2.pact)
38+
interface.
3039

31-
**Concrete Policies**: These are the default policies provided by Marmalade's
32-
creators, representing the most commonly used functionalities in token creation.
33-
They are immutable and written and maintained by the Marmalade team.
40+
Venturing further into the realm of Marmalade V2, token creators gain the
41+
flexibility to program tokens by selecting multiple policies, encompassing rules
42+
for creation, mints, transfers, burns, sales, and more.
3443

35-
**Custom Policies**: In addition to concrete policies, you can create custom
36-
policies that provide additional functionality. Once established, these policies
37-
are also immutable and can be added during token creation.
44+
## Technical Details
3845

39-
With the Policy Manager, you can stack multiple policies and associate them with
40-
tokens. This unprecedented flexibility allows NFTs to accommodate N number of
41-
policies, enabling you to create dynamic and sophisticated tokens.
46+
### Policy Manager and Quotes
4247

43-
**3. Type Checking for Policy Validation**
48+
The Policy Manager promotes a standard for collecting and distributing
49+
fungibles. In the predecessor, Marmalade V1, the fixed-quote-policy managed
50+
fungible transfers during sales. Now, with Marmalade V2, every token optionally
51+
benefits from this feature via the Policy Manager.
4452

45-
To ensure the correctness of your policies, the Policy Manager provides
46-
type-checking functionality. This feature identifies any inconsistencies or
47-
discrepancies between abstract policies and their concrete implementations,
48-
safeguarding the integrity of your NFT ecosystem.
53+
### Components
4954

50-
**4. Policy Enforcement via
51-
[kip.token-policy-v2](https://github.com/kadena-io/marmalade/blob/v2/pact/kip/token-policy-v2.pact)
52-
Interface**
55+
- **Ledgers Table**: Ensures functions are initiated only from the ledger.
56+
- **Concrete Policies Table**: Maintains concrete policy information for each
57+
token.
58+
- **Sale Whitelist Table**: Lists valid whitelisted sale contracts.
59+
- **Quotes Table**: Archives quotes for quoted sales.
60+
- **Ledger Schema**: Contains the module reference governed by the policy
61+
manager, adhering strictly to the ledger-v1 interface.
62+
- **Concrete Policies Schema**: Includes the module reference, strictly using
63+
the token-policy-v2 interface.
5364

54-
Each policy is enforced by the Policy Manager following the
55-
`kip.token-policy-v2` interface. This standardized interface ensures consistent
56-
and reliable enforcement of policies across the Marmalade ecosystem.
65+
### Capabilities
5766

58-
---
67+
The Policy Manager supports a comprehensive set of capabilities to cover a wide
68+
array of functionalities:
69+
70+
- `GOVERNANCE`
71+
- `QUOTE @event`
72+
- `ESCROW`
73+
- `INIT-CALL`
74+
- `TRANSFER-CALL`
75+
- `MINT-CALL`
76+
- `BURN-CALL`
77+
- `OFFER-CALL`
78+
- `WITHDRAW-CALL`
79+
- `BUY-CALL`
80+
- `SALE-GUARD-CALL`
81+
- `FUNGIBLE-TRANSFER-CALL`
82+
- `UPDATE-QUOTE-PRICE @event`
83+
- `SALE-WHITELIST @event`
84+
- `CONCRETE-POLICY @event`
85+
- `OFFER`
86+
- `BUY`
87+
- `WITHDRAW`
88+
89+
### Policy Functions
90+
91+
**General Principle**: The `enforce-**` functions require the `ledger::**-CALL`
92+
capability to be in scope, ensuring functions are initiated from the ledger.
93+
These functions then extract the policy list from the token input, which lists
94+
the associated policies.
95+
96+
- **enforce-init**: Initiates `policies::enforce-init` at
97+
`marmalade-v2.ledger.create-token`.
98+
- **enforce-mint**: Executes `policies::enforce-mint` at
99+
`marmalade-v2.ledger.mint`.
100+
- **enforce-burn**: Activates `policies::enforce-burn` at
101+
`marmalade-v2.ledger.burn`.
102+
- **enforce-offer**: Runs `policies::enforce-offer` at
103+
`marmalade-v2.ledger.offer` (step 0 of `marmalade-v2.ledger.sale`). Here, an
104+
optional parameter "quote" can be accessed in the `env-data` field. If a quote
105+
is identified, the offer saves this quote, and escrow accounts are generated.
106+
Otherwise, the offer continues without quotes.
107+
- **enforce-withdraw**: Operates `policies::enforce-withdraw` at
108+
`marmalade-v2.ledger.withdraw` (step 1 rollback of
109+
`marmalade-v2.ledger.sale`).
110+
- **enforce-buy**: Engages `policies::enforce-buy` at `marmalade-v2.ledger.buy`
111+
(step 1 of `marmalade-v2.ledger.sale`).
112+
- **write-concrete-policy**: This function registers a concrete policy modref
113+
into the concrete policies table.
114+
115+
- **get-escrow-account**: Returns the fungible escrow account created for quoted
116+
sales at enforce-offer. The escrow account receives the fungible from the
117+
buyer and distributes the fungibles to the policies and the seller at buy
118+
step.
119+
120+
- **write-concrete-policy**: Registers concrete policy modref into the
121+
concrete-policies table.
122+
123+
Required Capability
124+
Capability: (CONCRETE-POLICY policy-field policy)
125+
Signer: (keyset-ref-guard marmalade-v2.marmalade-admin)
126+
127+
- **get-concrete-policy**: Returns the modref of the concrete policy.
128+
- **enforce-sale-pact**: Ensures that the sale parameter provided to the
129+
function is equal to the ID of the currently executing pact. It does this by
130+
calling the pact-id function to retrieve the ID of the currently executing
131+
pact and comparing it to the provided sale parameter. If they are not equal,
132+
an exception will be thrown".
59133

60134
With the Policy Manager and its support for policy stacking, you can craft
61135
sophisticated and innovative NFTs that push the boundaries of creativity and
62136
functionality. As you embark on this exciting journey, we await your innovative
63137
ideas and creativity to further enrich the NFT experience within Kadena's
64138
Marmalade ecosystem. Happy crafting!
139+
140+
[Policy manager code](https://github.com/kadena-io/marmalade/blob/v2/pact/policy-manager/policy-manager.pact)

‎packages/apps/docs/src/pages/marmalade/marmalade-v1/why-v2.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ from each policy as we used to, we now call them from this central hub, making
3333
policy enforcement smoother and more streamlined.
3434

3535
We've made the move from On-chain manifest to Off-chain URI to standardise token
36-
data retrieval. We've also encouraged the use of IPFS for off-chain data hosting
37-
for a more decentralized approach, which many of you advocated for.
36+
data retrieval. We've also encouraged the use of IPFS / ARWeave for off-chain
37+
data hosting for a more decentralized approach, which many of you advocated for.
3838

3939
And remember, we respect and value the diversity of our community. We know some
4040
of you prefer to stick with on-chain manifests. Don't worry, we've got you

0 commit comments

Comments
 (0)