Documentation
Documentation
How to model token economies with TATAMI: the editor, the canvas, the blocks, the model state and the validator.
§1Overview
TATAMI (plaTform-Agnostic Token mAnagement & ModelIng) is a platform-independent, workflow-based visual modeling language for tokenomics. Instead of writing contracts, users arrange modular blocks that represent token-management primitives (creating, moving, splitting and destroying tokens) and connect them into token flows.
The language has two components: the Canvas, where token flows are built, and the Model State panel, where the data those flows read and modify is managed. Its concepts and their relations are specified by a metamodel, described in the paper.
A token stream is a directed edge that represents the movement of a specific quantity of tokens from one block to another. It carries both the amount and the type of token.
§2Getting started with the editor
The visual editor is where TATAMI models are built. This section covers the user interface and the recommended workflow for creating a model.
Interface overview
- The Canvas: the main area where you build your logic flows. Pan by clicking and dragging, and zoom with the mouse wheel.
- Adding blocks: right-click anywhere on the canvas to open a context menu, then select the block to add to the model.
- Managing model state: the button in the top-left corner opens the Model State Panel, where you define constants and inputs and inspect the state of the whole model.
- Exporting: the button in the top-right corner saves the current model as an XML file.
- Error checking: the Validate button checks the model for common errors (see Error checking).
- Documentation: the help button opens the built-in documentation panel at any time.
Recommended workflow
- Define the independent elements. Start from the core, non-flow elements found under Independent Elements in the context menu: Fungible Tokens, Non-Fungible Tokens and Pools. This step is crucial because it automatically generates the state variables the model needs.
- Set up variables and inputs. Open the Model State Panel to define the global constants or inputs your logic needs, for example a
fee_addressconstant or auser_idinput. - Build the logic flow. Add an Entry block to begin the flow, then other flow blocks such as Mint, If or Transfer. Connect them by dragging from a source handle (right side of a block) to a target handle (left side).
- Provide data with type blocks. Use type blocks (Number, Address and so on) to feed data into flow blocks. Their input field accepts a literal value (
'100'), a variable you created (mint_amount) or a model state property (Sender,MyToken_balanceOf(recipient_address)). - Validate the model. Run the validator periodically to catch unconnected blocks, loops or missing selections before they accumulate.
§3The Canvas
The Canvas is an interactive workspace where users build token flows from blocks. Unlike the edges of a traditional control-flow diagram, which represent the order of execution, a connection here represents the movement of tokens. A stream can be active or inactive; when it is inactive its token type is undefined, and some blocks need an active input stream to execute.
Blocks come in three categories:
- Independent elements define global entities: fungible tokens, non-fungible tokens and pools.
- Flow blocks compose the execution logic by manipulating streams and the model state.
- Type blocks supply dynamic input values to flow blocks.
Handles and colours
Every block follows the same pattern: input handles on the left, output handles on the right, and dropdown menus inside to select variables, tokens or pools. The colour of a handle identifies the data type it carries, which enforces type safety in connections.
| Colour | Carries |
|---|---|
| Light blue | Token streams |
| Red | Numeric values |
| Dark blue | Address values |
| Yellow | Boolean values |
| Green | String values |
Well-formedness rules
Syntactic rules guarantee well-formed token flows. They prohibit loops made of one or more blocks, the merging of two flows that originate from distinct Entry blocks into a single flow, and flows with empty input or output handles.
§4Blocks reference
Independent elements
These blocks work outside the direct execution flow. They act as global configuration, and creating one automatically adds read-only variables to the model state.
- Fungible Token: instantiates a fungible token. It requires a Name (used to generate its state variables, for example “GoldCoin”) and a Symbol (the ticker, for example “GDC”), and has two state attributes,
TotalSupplyandbalanceOf. - Non-Fungible Token: adds NFTs to the model, each instance identified by a unique identifier. The “+” button appends custom attributes, each with a unique name and a data type; their values are assigned when each token is minted. The Name identifies the collection, for example “Abstract Dreams”.
- Pool: a container that accumulates fungible or non-fungible tokens and supports deposits and withdrawals. It is associated with a token and can define
Keys(of typeStringorAddress) to compartmentalise funds, for example one balance per account; keys can be added or removed from the block. A rewards pool could be named “WeeklyRewards”, linked to the token “GDC” and given auserIdkey of typeAddressto track individual deposits.
Flow blocks
| Block | Inputs | Outputs | Description |
|---|---|---|---|
| Entry | Quantity (numeric) for each stream | One or more token streams | Mandatory initialization block and starting point of the workflow. It has a Name that identifies the flow. The token of each stream (fungible or non-fungible) is chosen from a dropdown, and the +/− buttons add or remove token outputs; for an NFT the input is the Token ID instead of a quantity. |
| Withdraw | Stream, Amount, pool Keys | Stream, Withdrawn stream | If the input stream is active, extracts tokens from a pool into a new stream and preserves the original one. |
| Set | Stream, Value | Stream | Updates a user-defined variable, selected from a dropdown, with the provided value. The assignment happens only if the incoming stream has a quantity greater than zero; the stream then passes through unchanged. |
| Deposit | Input stream, pool Keys | None (terminal) | Allocates the tokens of the stream into a pool. Key inputs are exposed according to the pool definition. |
| Burn | To burn (stream) | None (terminal) | Permanently removes the tokens from circulation, reducing the total supply. |
| Exception | Input stream | None (terminal) | Halts the execution if the stream is active and rolls back the changes made during execution. |
| Join | Input 1, Input 2 | Output | Merges two streams into one. Both must carry the same token type and originate from the same Entry block. |
| Transfer | Input stream, Recipient (address) | None (terminal) | Sends the tokens of the stream to a user or contract address and ends the flow. |
| If | Condition (boolean), Input stream | Then, Else | Routes the stream along one of two mutually exclusive paths; the other stream becomes inactive. |
| Split | Input stream, Branch 1, Branch 2 (numeric) | Output 1, Output 2 | Divides a stream into two streams according to the numerical proportions given by the two branches. |
| Mint | Stream, Quantity (numeric) | Stream, Minted | Creates new units of a token and forwards them in the Minted stream, continuing the original one. For an NFT, Quantity is replaced by one input for each attribute. |
Block examples
- Entry: to start a flow that distributes an airdrop, name it “AirdropFlow”, select the airdrop token and continue the logic from the output stream.
- Split: to send 70% of a stream to one path and 30% to another, connect a Number block with value
70to Branch 1 and one with value30to Branch 2. - Mint: to create 500 new tokens, connect a Mint block to a flow, select the token and connect a Number block with value
500to the Quantity input. - Burn: to remove a used NFT from circulation, direct its flow into the To burn input.
- Exception: when the condition of an If block fails (for example a required payment was not made), route the Else branch to an Exception block to halt that path.
- Join: after splitting a stream to perform separate actions, use a Join block to bring the two paths back into a single flow.
- If: to check whether a user is a premium member, connect a Boolean block with that status to the Condition input, then route Then to premium rewards and Else to standard actions.
- Deposit: to deposit staking rewards into a user-specific account, select “StakingPool”, connect the stream and provide the user’s Address to the matching key input.
- Withdraw: to let a user claim rewards, select “StakingPool”, provide a Number for the Amount and connect the user’s Address to the key input; the Withdrawn stream can then be transferred to the user.
- Transfer: after minting or withdrawing tokens, connect the stream to a Transfer block and provide the destination Address to the Recipient input.
- Set: to update a
scorevariable, select it from the dropdown and connect a Number block with the new score to the Value input; when a token flows through the block, the variable is updated.
Type blocks
Type blocks do not take part in the token flow: they provide parameters to the input handles of flow blocks. The language offers four data types: Numeric, Boolean, String and Address (the numeric block is labelled Number in the editor). Each block has a text field that accepts static literal values, references to variables or accessors of the model state, and a single colour-coded output handle. Numeric and Boolean blocks can also evaluate arithmetic and logical expressions.
| Block | The field accepts | Example |
|---|---|---|
| Boolean | A literal ('true', 'false'), a Boolean variable or a state accessor that returns a boolean. | Connected to the Condition of an If block, with value is_premium_user. |
| Number | A literal number ('100'), a numeric variable (mint_amount), a state accessor (MyToken_TotalSupply, MyToken_balanceOf(owner_address)) or a mathematical expression (my_var * 2). | Value mint_amount connected to the Quantity input of a Mint block. |
| Address | A literal address ('0x...'), an Address variable (owner_address) or a state accessor such as Sender. | Value Sender connected to the Recipient of a Transfer block. |
| String | A literal ('hello world') or a String variable. | A user’s nickname used as the key of a Deposit or Withdraw block when a pool is keyed by nickname. |
§5Model state
The model state is the aggregate set of inputs, variables, mappings and constants that the blocks read and modify. Each element has a name and one of the four data types.
Automatically generated elements
- The execution context:
Sender(the address of the transaction sender) andBlockNumber(the block number of the current execution). - For every fungible token f: the numeric variable
f_TotalSupplyand the address-to-number mappingf_balanceOf. - For every attribute a of an NFT n: a mapping
n_afrom a numeric key (the token ID) to the type of the attribute. For an NFTticketwith a numeric attributeprice, the mapping isticket_price. - For every pool p: the numeric variable
p_amount, the quantity of tokens currently deposited.
Custom elements
Users can also define their own state elements by giving a name, a data type and, for constants and variables, an initial value.
- Constants are immutable: fixed values set at design time, such as a fee amount.
- Inputs are dynamic values provided at execution time, such as a user ID.
- Global variables are mutable, change during execution through Set blocks, and hold a value that is common to every agent (account) interacting with the token flow.
- Local variables are mutable like global ones, but their value is specific to the account that executes the flow.
Using variables and state
To use any variable or state element, place a type block on the canvas and enter its name in the input field. The state generated for independent elements is read-only; examples include Sender, BlockNumber, MyToken_TotalSupply, MyToken_balanceOf(address) and MyPool_amount. The field also supports mathematical expressions such as my_var + 5. For state accessors that require a parameter, like balanceOf, use parentheses: MyToken_balanceOf(owner_address).
§6Error checking
The Validate button in the top-right corner of the editor runs a set of checks that help find common errors in a model. The validator looks for:
- Cyclical dependencies (loops): infinite loops in the token flow, which are not allowed.
- Unconnected handles: input or output handles not linked to another block; every handle must be connected for the logic to be complete.
- Unselected dropdown options: required selections left empty, such as the token of an Entry or Mint block.
- Undefined variable references: type blocks that reference a variable, input or constant that does not exist in the model.
- Join from different entries: a Join block cannot merge two streams that originate from different Entry blocks, even if each branch was connected correctly on its own.
- Dangling edges: connections whose source or target no longer points to an existing block, which can happen when a model is hand-edited or imported from another tool.
- Dangling references: a selected token, pool or variable (in an Entry, Mint, Pool, Deposit, Withdraw or Set block) that no longer matches an existing one, typically because it was renamed or deleted after being selected.
- Duplicate names: the same name reused across several tokens, pools or variables, which makes any reference by name ambiguous.
- Handle type mismatch: every connection must link compatible handle types (a boolean output cannot feed a number input); this is re-verified on every edge already in the model, not only when it is drawn.
- Single edge per output: each output handle, including type block outputs, can feed at most one connection. If a value or stream is needed in more than one place, duplicate the block.
- Single edge per input: each input handle can receive at most one incoming connection, since two simultaneous values on one input would be ambiguous.
- Join token mismatch: a Join block that combines two streams carrying different tokens, which would leave the token of the resulting stream undefined.
- Join / Split on non-fungible tokens: Join sums quantities and Split divides a quantity by a ratio, so neither is meaningful on a non-fungible token, which is identified by a unique ID rather than an amount.
Errors are shown in a list. In a future update, selecting an error will highlight the problematic block on the canvas.