Case Study: Real Estate

1% property token

Let’s imagine a market for “1% property”. A property owner can issue many pieces of a token, each representing 1% ownership of the property. He can sell these tokens for cash. A buyer needs to know quite a bit of information. It’s easy to understand that such a token would fetch 1% of the sales revenue if the underlying property is sold, but a lot more details are needed:

  1. Where is the property and what status is it in?
  2. Can a 1% property token owner vote? For example, on the purchase decision to insurance against a bush fire?
  3. Is the 1% automatically converted into currency at the time of property sales, or can the token holder elect to continue holding it?
  4. Is the token properly underwritten to prevent double-collateralization?
  5. If the property was collateralized for a mortgage, what is the condition for a liquidation event?
  6. Is providing a buyer’s identity attestation a condition of a purchase?
  7. Is the seller the actual owner of the property?
  8. What was the performance of similar properties in the region in the past years?
  9. What was the historical sales price of this property?

Specific to blockchain, we also have:

  1. How to correctly and securely construct a transaction for the asset (purchase, voting etc)? You can’t expect any investor to be a blockchain geek who knows how to load the smart contract files in his wallet.

We categorise these trade-sensitive information into four categories:

  1. Product description[^pd]: Item 2, 3, 5, 6
  2. Attested information (attestations): Item 1, 4, 6, 7.
  3. Reference information: Item 8, 9.
  4. Action information (how to perform an asset action): Item 10.

Understandably, the buyers need to access all these for an informed decision. To allow tokenization of deliverables to happen, these informations must show up on his wallet when he starts interacting with the token. In the following chapters, we will describe how these informations categorizes manifest in TokenScript.

[^pd] The word is loaned from the financial sector, usually used to describe packaged investment products. It means the formula which profit is calculated and the current values of the variables in the formula.

Product description

Product description information is typically part of the smart contract. They can be obtained by making a few Smart Contract function calls, therefore, the only needed work is to convert them into a presentation. Usually, this means translating them to the language user speaks and converting “True” value into a nicely ticked checkbox.

This serves to introduce the first functionality of TokenScript: acting as a presentation layer for smart-contracts. In XML it looks like this:

   Voting right










         No Voting Right




         Voting rights on sale




         Voting rights on expense (e.g. insurance)




This simplified attribute-type code snippet allows the value for Voting Right to be fetched from holding-contract, which is a smart contract defined somewhere else in the TokenScript, and present it in one of a few languages.

As another functionality, TokenScript can extend the product description and integrate variable parts, which can be upgraded without messing with upgradability of smart contracts.

Attested information

Attestation is just a signed message stating a fact. Attestations are often used to satisfy the conditions of the transactions — more on that in chapter Attestations. In the 1% property token example, the involved attestations are:

  • The Identity authority and title deeds office attest the issuer’s ownership of the property.
  • A collateralization authority[^set-operation] prevents double collateralization
  • The buyers provide their identity or capacity to invest in this type of asset

[^set-operation]: Eventually, this could be a cryptographic set operation, but even if that happens, the metadata directing the context (user-agent) to perform the computation still needs to be described in TokenScript.

The first two attestations are not stored in a smart contract for privacy and cost (size and number of transactions) reasons. It’s possible to utilise zero-knowledge proof to provide anonymous proof that the attestation is for the said property and said owner, and it has not expired. What proofs are expected and can be validated is also described in TokenScript.

Furthermore, the transaction requires an identity attestation or investment capacity attestation from the buyers. These are described in TokenScript as well so the context (e.g. user-agent) can prevent the user from submitting a transaction without qualifying proof or help the user to select suitable attestations for a purchase transaction.

TokenScript does not just help relay the attestation data, but it also enables wallets to conveniently allow buyers and sellers to submit and read the attestation data without the need for a hosted DApp service.

Reference information

Reference information is relevant to the token, but not part of the smart contract. In our example reference information includes data like previous property sales price or regional property performance. This is data which is useful for the owner or buyer of a token. It is provided by web services, typically through a RESTful API call.[^trusted-information]

[^trusted-information]: Originally we call it “Trusted information”, meaning the data is just “provided”, without blockchain proofs or attestations, hence, it has to be explicitly trusted by the user. As it turned out, this term misfired as some developers think it means “proven information” and provided as trusted already. So we used a less precise term “Reference information”, which, unfortunately, feels like a catch-all phrase.

It could be possible that eventually such information will end up being onchained. But even than they will be created and uploaded by an entity which has to be trusted. Reference data always leads to the problem of trust and web integration. With TokenScript this data is signed by the token issuer (not by the token owner – the token issuer is often an entity that deployed the smart contract). In the case of the property this could be a real estate specialist. The reference information sourced from web APIs specified in TokenScript is assumed to be trusted, but can be changed later. The security chapter will detail different levels of trust.

Today, all such information related to a token is usually held together on a DAPP website made by the same entity that deployed the token. This has the shortcoming that the DAPP is only useful when the API is still available and reliable. Having it not in the smart contract but in TokenScript enables the token issuer to change the API source.

Thus, we argue that for tokens to be effectively marketized, reference information needs to be abstracted out and placed in the token behaviour language TokenScript.

Action information

Action information dictates the correct method to construct a blockchain transaction, like:

  • What attestations are needed to prove the buyer’s capacity to purchase?
  • What parameters are needed for a purchase (e.g. number of 1% shares)?
  • How to render the purchase form and translate to the user’s local language?
  • Are the conditions all met (e.g. a purchase isn’t possible after the underlying property is liquidated)?
  • How to cast a vote if one is aligned with token ownership?

In Ethereum this information is a super-set of the smart contract programmable interface called ABI. It also contains business logic (e.g. property must be still valid and owned by the seller) and presentation logic (e.g. the message “The property is liquidated. Purchase no longer possible”). With more sophisticated token, this parts becomes more complex and will make it hard to load it in a smart contract and visualize it appropriately in the wallet.

TokenScript makes both the content as the visualization of the action information more flexible and accessible.

In conclusion, TokenScript allows the context (user-agent or trading engine) to:

  • Fetch token related information from its holding smart contract, attestations and references.
  • Produce a visual or audio rendering of the token
  • Produce a list of actions that can be performed and explain how to construct the transactions.

Any party is able to render and apply functions to the token using TokenScript, including entities like generic marketplaces, user-agents and 3rd party apps. We call these parties “context” in general.

Advantages of TokenScript

Much of the advantages might be already known after reading the chapters above, which covered the challenges of Tokenization and a description of what TokenScript can provide on a high-level perspective. But it is helpful to provide a section focused on the advantages of TokenScript, as it works out the problems with the legacy token model and the advantages of TokenScript on a more precise level.

Delivery Side


Let’s suppose a property guru named Peter creates a website called “Peter’s Pride Asset”, where he selects the best properties available on the market and represents each by a token that serves as the deliverable. Peter can create a listing of those properties with rich information about price, location and so on, and allow users to purchase it with one click.

Peter doesn’t need permission, because the data of those tokens are on the blockchain. However, he needs knowledge how to render the token on his website. He also needs to upgrade his website, when the underlying smart contract or the transaction rules was changed. If he misses doing it in time, his users would submit transactions not conforming but getting rejected.

The same problems emerge with a lot of application. TokenScript helps Peter to keep his platform upgraded and to better react on events. The real estate token can easily be operated on all kind of platforms.


Horizontally, the same type of asset might have its token instances across multiple networks like Plasma Chains. Without such architectures a token economy will hardly be able to scale. But having an all-knowing node to provide rendered token information for all existing tokens will be hard – and detrimental to the goal of scaling the blockchain economy while keeping the burden on nodes small. Therefore, the knowledge about the token (TokenScript) must be detached from the access to the token.

Vertically, you might structure transactions like creating tokens on top of a token. For example, you have a token which is made up from 1% property tokens, but distributes the risk over a sample of 100 global cities. The transaction and token access the component tokens. It cannot depend on the availability, security and openness of the original DApp tied to that asset. TokenScript would work in the middle for the making of such tokens. It would allow the flexibility needed to vertically scale Token assets.


How do you know that the transaction you sign is what you want to sign? With standard payment transaction this is a minor problem, but as some instances of keylogger-malware show, still a problem. But when it comes to the complex logic of token transfers, the legacy model of blockchain token will face large prroblems.

Sure, you can render transactions in a user-readable format. It’s easy to start with such an effort with a transaction visualiser tool, but ultimately the system integrates and the UX needs would surpass what a dictionary style transaction visualiser can do.

Take the 1% property token as an example. A confirmation might look like this: You are going to purchase 1% of property #802820 with 45 Ethers, are you sure? The user will be unsure if the glass ceiling designer 2-bedroom house he is watching is #802820. A dictionary based translation visualiser cannot go further because correctly rendering the property token requires more than word processing.

Eventually, a transaction is generated with code, and the user would have to delegate the trust to the code. In a user’s words, I am accessing the website tied to this token, so I will trust that this transaction I am signing is generated for the intention I have while using the site. This is a broken trust model, a regression to the TLS model of trusting the site instead of the content. In fact, it is more secure to rely on the traditional model to trust estate agents and notaries.

TokenScript is designed to separate token rendering code and transaction generating code, and package them into its container, signed by a party that the user is likely to trust (often, signed by the same key used for deploying a smart contract). There are a few trust levels left, which we will detail in later chapters.

A user who is purchasing a 1% property token from Peter’s Pride Property recommendation website can be supplied with a rendering and transaction package, signed by the same group of people who created the holding contract of such tokens. Therefore, the user can purchase assets from any website with a similar level of trust, or purchase it from a WeChat or Facebook private message and know it is the real token being rendered and transacted.


Almost all business operations involve some kind of identity. When you purchase 1% property token, in most jurisdiction you will be required to provide some kind of identity proof. In the traditional model, when you use a third party website like Peters Pride Assets, this site will require the identity proof and forward it to the seller, the notary or the authority. We already see this in masses when ICOs try to comply with regulations. Investors are uploading passport pictures on mass.

The problems with this approach are well known. You simply don’t want your identity documents being stored on many website databases, if you don’t want to fall victim to identity theft. The website taking your credentials can abuse it – for example, sell or analyze it – or the website can be hacked. The problem of uploading passport images or other identity files on webservers is one of the worst consequence of a web integrated by webservers and lacking a ownership and identity mechanism.

With TokenScript the issuer of the token can formulate a destination where to send the identity file, add a public key of the receiver, a reference to the cryptographic library used to encrypt the file, and let the buyer forward it automatically. For example, you pick your property on Peter’s site, and while the amount to pay will go to the property seller – minus the provision for Peter – the encrypted identity proof could go directly to the land registry authority, with a note about the purchased property attached.


Imagine you have purchased a few 1% property shares on Peter’s site. In a traditional wallet you only see it as little symbols – at best – with no further information. This is not what property investors want to see. They want to have pictures of the estate, prices, charts about the regional estate properties, expected date of payout and so on.

You could show this in a wallet. It would ‘just’ require the wallet to adjust to the individual smart contract overloaded with these information or to trust a random website providing this information and adjust the UX to match it. In reality, no wallet made this possible, ending with users either using hosted DApps or smart contract providers trying to create their own wallet matching their needs.

TokenScript allows wallets to easily display all the needed data, as shown above.


As an owner of a 1% property share you have some interesting options: You can vote on decisions about renovation or restructuring of the property, you can request a payout of income, you can sell the property, or you can take a mortgage on it. If those options are part of the smart contract, you need to access the blockchain to process them.

When Peter’s Pride Assets serves as a DApp site, you will perform your actions using his site. When his site is unavailable or down – or maybe when he forgot to pay his SSL certificate – your token will be effectively unable to be used to pursue the rights you bought with the token. This could essentially be abused to manipulate property prices or ballots about renovation.

The problems become worse when the 1% property token is embedded in further contracts or tokens. For example, there could be a site called Brad’s Properties, which bundles 1% property token from other sides to create a property index. In the classical DApp model you would be dependent on Peter’s site being available to use a property token you bought there to become part of an index token. Or imagine you take a mortgage on your token. Which would be effectively a transaction between you and a bank would become a transaction involving Peter’s site.

With TokenScript the wallet will be able to support any required visualization and action by the user. This will make it unnecessary to rely on trusted third parties like DApps to use the functions associated with a token.

Have a project in mind?

We want to hear from you. Bootstrap your custom solution with our ready-to-market, white-label wallet. Or co-create with our expert team to tokenise your business model, at a fraction of the time and cost.