wrappedfi / wrapped_token_stacks

An open source standard for assets on the Stacks network from Wrapped.com, written in Clarity

Wrapped Token on the Stacks Blockchain

Mainnet deployments

xBTC

SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin

xUSD

SP2TZK01NKDC89J6TA56SA47SDF7RTHYEQ79AAB9A.Wrapped-USD

About

The token implements the SIP 10 standard and has been reviewed and audited by NCC Group.

The SIP-10 standard is the "Standard Trait Definition for Fungible Tokens" on the Stacks network. This trait exposes functions for token metadata:

• get-name
• get-symbol
• get-decimals
• get-token-uri

The get-token-uri method mimics the functionality found on the ERC721 standard. The expectation is that a token owner can set this to reference an external URI that contains extra metadata about the token (such as logos, agreements, or other documentation)

In addition to metadata, it exposes functions for querying the current total supply of the token and the balance for a specific account:

• get-balance
• get-total-supply

Finally, it defines the function for transferring tokens:

• transfer

This trait is defined in ft-trait.clar.

Token Restrictions

The following public functions are available similar to ERC1404:

• detect-transfer-restriction
• message-for-transfer-restriction

If any restrictions are put into place that would prevent a transfer from succeeding, the standard transfer function would fail with a u403 error code. 403 was chosen to mimic the HTTP 403 Forbidden status.

A wallet should check the detect-transfer-restriction function to determine why the transfer was restricted, and then can return a human readable message found by calling message-for-transfer-restriction to the user to take corrective actions.

This trait is defined in restricted-token-trait.clar.

Initialization

Each deployed token should have a different name, symbol, etc. The principal that deploys the contract can call an initialize function on the contract to set all initial values. This function can only be called once and will set the following:

• Token Name
• Token Symbol
• Decimals
• Initial Owner Principal

The reason that these items are set dynamically is that once the contract has been audited, we don't want to accidentally make any changes to the source code that could affect the functionality. Also, if this contract represents a registered security, it may be necessary that the deployer (e.g. Wrapped) never holds the ownership role of the contract.

Role Based Access Control

The token has certain roles built into it to allow administrative actions. One or more principals can be granted each of the roles and a principal can be granted multiple roles. The following roles are available:

• Owner
• Minter
• Burner
• Revoker
• Blacklister

By default, the account specified in the initialize call will be granted the Owner role. The Owner role is the only role that can add or remove other accounts from roles.

NOTE!!! If all owners are removed then no other role administration can be performed. Any time an owner removes themselves, great care must be taken to ensure another owner still exists. Also, this means that all admin functionality can be irrevocably disabled by removing all roles from all principals.

Administrative Capabilities

Minting

A principal with the Minter role can mint new tokens to any principal. The total supply of the token will be increased when new tokens are minted.

Burning

A principal with the Burner role can burn new tokens from any principal. The total supply of the token will be decreased when existing tokens are burned.

Revoking

A principal with the Revoker role can move tokens from any principal to another principal.

Blacklisting

A principal with the Blacklister role can add or remove any principal to a blacklist. Any transaction sending tokens to OR from a blacklisted account will be denied and the transaction will fail.

Dev

Install dependencies:

yarn install

Testing

yarn test

Questions? Feedback?

Stop by our Telegram or send us an email.

wrapped_token_stacks's Issues

Simplify has-role

The function could be simplified to

;; Checks if an account has the specified role
(define-read-only (has-role (role-to-check uint) (principal-to-check principal))
    (default-to false (get allowed (map-get? roles {role: role-to-check, account: principal-to-check}))))

Q: Testnet availability?

Do you have a token deployed to testnet that I can test Boom wallet with?

Error code ambiguity in token transfer

After receiving an error on a token transfer transaction, the caller will not be able to tell what went wrong. This may introduce unintended behavior in higher-level applications of the contract. In addition, the transfer function implementation diverges from what is described by SIP 10, which may introduce incompatibilities with competing implementations.

A potential solution, in SIP-10, a notion of post-condition is introduced. Eventual existence of post-conditions impacts the list of possible error codes returned by the transfer function. Consider modifying SIP 10 to allocate error codes for post-condition handling, including black listing related error codes. Consider modifying the implementation to conform to the new spec.

Remove initialize function

Initialize should be done on deployment, the relevant variables should be constants.

Remove message-for-restriction

As the source code is readable on chain, there is little need for the mapping from ints to strings.

If you want more expressive error I would put them directly into (err {cause: "ABC", code:...})

Memo field is being disregarded

From @MarvinJanssen:

https://github.com/wrappedfi/tokensoft_token_stacks/blob/main/contracts/tokensoft-token.clar#L56

We are disregarding the memo field. The SIP010 language is unclear on whether it is a requirement to print, but best to print it.

Related: stacksgov/sips#36

Lack of token supply limiting

The TokenSoft Token contract does not use the Clarity’s native functionality for limiting the supply of tokens. All TokenSoft Token contracts will have the same maximal supply of 2128 − 1 tokens. On an attempt to mint more than the maximal number of tokens, the Clarity REPL results with a panic, however, the actual Clarity VM running inside the blockchain client is expected to just abort the transaction.

Possible solution is to allow users to set the limit on the token supply. In the case users opt to not set such a limit, the Clarity VM inside the blockchain client is expected to guard from panic and Denial of Service.