BlogChain

In this article, learn about the use of “wrapper contracts” — smart contracts that call other smart contracts — in order to offer new features.

Quick note: “wrapping” here is a form of indirection in calling a smart contract. It does not refer to “wrapping tokens” via the bridge, which is an entirely separate process.

Smart-contract blockchains are unique app environments as they combine storefronts, back ends, and APIs into one dynamic environment. A single dapp may be composed of numerous contracts: an NFT exchange might have separate contracts for handling the auction vs offering a token for instance.

Since blockchains are open systems, these contracts are all on display for anyone to inspect, and while some functions are “private” (either not callable from the outside, like in Solidity, or protected with a capability, in Pact), most functions can be called by anyone.

This is why for instance Kaddex or Uniswap can have numerous non-official front-end apps: the real business of the DEX happens inside the smart contract, while the front end is just Chrome and wallet integration.

You can do this on the blockchain too: you can write a “wrapper” smart contract that has the same or similar function signatures as an existing smart contract. The wrapper smart contract calls the corresponding functions on the wrapped smart contract functions, before or after functionality that offers some extra service.

To see what this looks like, let’s consider a concrete example of a smart contract sitting in front of the Kadena Chain Relay. The relay offers fixed-size bonding at 50,000 KDA. A wrapper contract could allow multiple accounts to form a single bond and divvy up rewards accordingly.

Let’s look at how a wrapper contract would work, starting with bond creation. Creating a new bond at the smart contract level means calling the function relay.pool.new-bond (the code can be seen here):

The “normal” case is that account is a single-signer KDA account, and guard is the key on that account. The function returns the name of the new bond, which is used later for servicing the bond.

For our example, we want a smart contract to be in charge, and “wrapping” the call to new-bond is the most straightforward way to do that.

Wrapping the call to new-bond is easily done in our wrapper contract.

Of course, this isn’t very interesting by itself, but it illustrates the mechanism: there is nothing preventing another contract issuing the relay.pool.new-bond call instead of directly accepting it from a front-end app. Here it does exactly what a direct call would do: provides the unchanged arguments, and returns the bond name.

The first thing we want to do is give the wrapper contract control over the bond administration, which is easily achieved with a module guard:

This now means that the module guard named "bond-wrapper" administers the bond: now, only calls from the module defining wrap-new-bond will be able to invoke things like renew-bond and other bond-servicing operations. We have achieved autonomous control over the bond servicing.

This means we have to wrap the other calls now too, in order to leverage the module guard for administration. We’ll look at that later in the article.

The next step is to actually model the multibond itself. A simple approach simply collects tranche accounts and sizes in a “multi” object:

Done! A tranche combines a KDA account with a tranche amount. A multi simply collects tranches that add up to the bond size. The multis table stores multi records under a unique KDA account name along with the bond size .

We’re ready to create a new multibond!

The steps involved to use the multibond are:

The new-multibond function takes the tranches multi object and a KDA account name that acts both as the storage account for the initial bond and future rewards, as well as the ID for the multibond itself.

The first step is to transfer the tranche amounts into the new shared account. The function debit-tranche is called on each tranche using map . This is a simple function that just calls coin.transfer-create :

Note that the shared KDA account is also autonomously guarded by the module using create-module-guard "tranche" . This means that only this module code can debit from the new account.

We then store the multibond by the account. This is straightforward.

The third step sets up bond creation by installing the TRANSFER capability. This is how autonomous ownership is managed. Normally in a transfer, the user adds the TRANSFER capability to their signatures. Since this is a smart contract, it simply “installs” the capability.

We’re ready to create the bond!

Let’s consider what’s going on here. The relay will attempt to transfer the bond amount from account into the relay bank. Thus, if the tranche transfers above were not enough, the transaction will fail, which is what we want. We’ll talk about another error case — the tranches add up to too much — later.

That’s it! We’ve added significant functionality to bonding with only a few lines of code.

Administering the bond requires allocating rewards. Let’s take a look at how that might work:

It’s really pretty simple. We check the balance of the multibond KDA account to compute the increase from rewards. We wrap relay.pool.renew to service the bond, which will succeed because it is autonomously administered by this module. We compute the new amount using the current balance and the old balance.

Allocation is the only tricky part, but armed with our tranches, the bond size, and the new amount, we can simply map over the tranches to perform the allocation.

The main code here computes the tranche amount by multiplying the total reward amount by the proportion of the tranche. It then installs the autonomous TRANSFER capability and allocates to the source account.

This doesn’t cover everything. unbond still needs to be wrapped, plus the relay activities propose , endorse and others will need to be wrapped as a simple pass-through so that the module can provide the authorization by simply calling the wrapped code.

There are also error cases that need to be handled:

Finally there are features to add:

Finally, it’s worth noting that the new-bond call will be a *multi-sig transaction *because everything is done in one step, so all tranche owners have to sign the same transaction. It would probably be easier from a front-end, wallet perspective to collect the tranche amounts beforehand, and then make the bond.

Hopefully this shows the power of wrapper contracts as a way of offering new services to blockchain users. Pact makes such contracts easy and safe. Indeed, it’s way safer than Solidity as you can’t really get the target contract wrong as the wrapper won’t load if there’s a typo. In Solidity you’d better get the target contract address right or it’s game over, and it can’t tell you if your calls will actually succeed. Pact is a game-changer for smart contracts, so get going with your Pact dapp on Kadena blockchain and experience the power for yourself!