WrapperToken - A CBC20 Token Standard Extension for Wrapping and Unwrapping Tokens

WrapperToken - A CBC20 Token Standard Extension

Abstract

This proposal defines a CBC20 extension for wrapping a designated CBC20 token. Users can deposit the underlying token to mint wrapper tokens and burn wrapper tokens to withdraw the underlying token.

Motivation

The extension provides a standard way for applications to discover the underlying token and perform wrapping and unwrapping without depending on a particular storage layout or initialization mechanism.

Specification

CBC-103 Interface

The following specification uses syntax from Ylem 0.8.4 (or above).

interface CBC103 /* is CBC20 */ {
    function wrappedToken() external view returns (address);
    function buy(uint256 amount) external payable;
    function sell(uint256 amount) external;
}

Underlying Token

wrappedToken() MUST return the designated underlying CBC20 token. The returned address MUST NOT be address(0) or the checksummed zero address, and it MUST NOT change during the lifetime of the wrapper token.

This standard does not prescribe how the underlying token address is stored or initialized.

Wrapping

buy(uint256 amount) MUST atomically:

1. transfer exactly amount underlying tokens from the caller to the wrapper token contract; and
2. mint exactly amount wrapper tokens to the caller.

The operation MUST revert without minting wrapper tokens if the underlying transfer reverts, returns false, or transfers less than amount.

Unwrapping

sell(uint256 amount) MUST atomically:

1. burn exactly amount wrapper tokens from the caller; and
2. transfer exactly amount underlying tokens to the caller.

The operation MUST revert without burning wrapper tokens if the underlying transfer reverts, returns false, or transfers less than amount.

Successful wrapping and unwrapping MUST follow the CBC20 minting and burning event requirements.

Backing Invariant

For an exact-transfer underlying token, the wrapper contract's underlying-token balance MUST be greater than or equal to the total supply of wrapper tokens. Direct transfers of underlying tokens to the wrapper contract can create excess backing but MUST NOT create additional wrapper tokens.

CBC-103 does not define wrapping of native XCB. Callers MUST NOT attach native XCB to buy() or sell().

Rationale

The one-to-one conversion model keeps accounting simple and makes the backing of the wrapper token independently verifiable. Keeping initialization and storage outside the standard allows constructor-based, initializer-based, and factory-based implementations.

Backward Compatibility

CBC-103 extends CBC20 without changing its existing functions. A CBC-103 implementation remains subject to all CBC20 requirements.

Security Considerations

• Implementations MUST handle both reverted transfers and transfers that return false.
• Fee-on-transfer, rebasing, or otherwise non-exact underlying tokens are incompatible with the one-to-one model unless the implementation explicitly accounts for actual balance changes.
• Implementations MUST preserve the backing invariant across external token calls and protect against reentrancy where the underlying token can execute callbacks or other arbitrary code.
• Users should verify wrappedToken() before acquiring wrapper tokens. A wrapper is only as secure and liquid as its underlying token.
• Native XCB sent to an implementation that does not explicitly reject or return it may become inaccessible.

Conclusion

CBC-103 provides a standard interface and one-to-one accounting model for CBC20 wrapper tokens.

Copyright

Copyright and related rights waived via CC0.