Private Dapp Realms

A Private Dapp Realm is a space to privately hold all of a Dapp’s information. All data within this Realm is restricted to its members. The Asset Framework uses a Private Dapp Realm to create its basic application architecture on the Mercata Blockchain. A Private Dapp Realm is private all the way from its core app information down to the assets that it tracks.

A Private Dapp realm is constructed as a first-level Privacy Shard, one step away from the main chain; its parent chain is the main chain. This shard is referred to as the “Dapp Shard” because it holds the core Dapp logic and information. All assets and components of the Dapp reference this Shard.

Members of a Dapp Realm are controlled by the Governance algorithm implemented in the initial (Governance) contract of the Realm. This method can be invoked to add or remove stakeholders into/out of the Dapp.

Dapp Contract

A “Dapp” contract refers to the primary contract used to instantiate the Private Dapp Realm (Governance Contract.) This contract contains the source code for all other contracts in your Dapp, and typically also instantiates instances of “manager” contracts within the same realm, so that their functionality can be used later, such as user role and permission management. This serves as a higher order contract that simply creates and stores instances of the utility contracts referenced below.

When Asset Shards are created in the Dapp, they reference this contract’s source code by address using Code Pointers.

Asset Contracts can access manager contracts in the Dapp Privacy Realm by referencing the Dapp contract at the Governance Address (0x100):

contract Dapp {

    PermissionManager permissionManager;
    UserMembershipManager userMembershipManager;
    ...
}

contract PermissionManager {...}

contract MyAsset {

    PermissionManager pm;

    constructor() {
        // create a reference to the already existing Dapp contract on the parent shard
        Dapp tempDapp = Dapp(account(address(100), "parent"));
        // create a reference to the already existing PM contract on the parent shard
        // by accessing the address of the PM held in the Dapp's state variable
        pm = PermissionManager(account(tempDapp.permissionManager(), "parent"));
    }
}

In this way, contracts do not need to create new manager contracts everytime they are needed, rather the contracts reference existing contracts with data already in them, like user’s with permissions, etc.

Integrating with Private Dapps

The STRATO Mercata platform allows developers to integrate their own Private Dapps into other existing Dapps. This allows the new Dapp to read from and access the data from the foreign Dapp. All Dapp integrations must be declared when your Private Dapp Realm is initially created. As a privacy concern, all members of the new Dapp Realm must also be members of any foreign Dapp integration.

In order to use Dapp Integrations, you first need to have a name that you will use to refer to it in your own Dapp's contracts. So if you are intergrating with a payment app named "ABCPayments", you might also want to use the same name ("ABCPayments") for your Dapp's integration. Note that the name you use in your Dapp to refer to a foreign dapp does not have to strictly match the deployed name of the other Dapp.

Now you can use this name throughout your Dapp's contract code whenever it needs to reference a contract that exists on that Dapp Integration. Once you have constructed the Contract instance in the SolidVM code, you can use it like any other Contract type that exists on a separate chain. Just like referencing parent chains, you can only read state from integrated Dapps - you cannot modify the state. For example, you can check the balance of accounts in the ABCPayment Dapp, but not actually complete a payment from your own Dapp's context.

Contract Example

contract MyDapp {

    uint cost = 100;

    constructor() {...}

    function canMakePayment(address _userAddress) returns (bool) {
        PaymentDapp tempDapp = PaymentDapp(account(0x100, "ABCPayments"));
        return (tempDapp.getUserBalance(_userAddress) > cost);
    }
}

Now that you have the contract written for your Dapp, you can now deploy the Dapp to the Mercata Network with the Dapp Integrations. These are provided in the parentChains argument of the POST /chain API endpoint body. So first you need to fetch the chain ID of the Dapp you are integrating with. Once you have this, you can add the integration by providing a key/value pair in the parentChains object. They key should be the Dapp integration name as mentioned above, and the value must be the chain ID of the foreign Dapp.

Creation Example Args

{
    ...createChainArgs,
    parentChains: {
        "ABCPayments": "123456789abcdef"
    }
}