PostOffice.sol

Overview

The PostOffice.sol contract facilitates the decentralized packaging and shipping of assets within Capsules. It provides a secure and transparent way to create, ship, and redeem packages.

The shipper, most often the package manager (unless an intermediary contract ships on behalf of users), creates packages by encapsulating assets, setting security measures such as password protection and unlock timestamps, and assigning a receiver. Packages can then be shipped or delivered directly to the receiver, manually or through the Capsule Relay.

Recipients can pick up packages by verifying their identity and password, or they can choose to redeem the Capsule NFT package itself and transfer the contents to their address.

PostOffice.sol also supports functionalities like canceling packages and updating package details such as the asset key, package manager, password hash, receiver, and unlock timestamp.

Overall, the PostOffice.sol contract streamlines the process of package management, enhances security, and enables efficient and reliable package shipping and delivery in a decentralized manner.

View PostOffice.sol verified proxy contract code on Etherscan

CPaS: Important Methods

Function: shipPackage

Parameters:

• packageContent_: The content of the package encapsulated in a CapsuleContent struct.

  • packageContent_.capsuleType: The type of the capsule representing the package.

  • packageContent_.metadataURI: The URI string representing the metadata of the package.

• securityInfo_: The security information of the package encapsulated in a SecurityInfo struct.

  • securityInfo_.unlockTimestamp: The timestamp indicating when the package can be unlocked. Set to 0 for any time.

  • securityInfo_.keyAddress: The address of the ERC721 collection used as the asset key. Set to address(0) if not applicable.

  • securityInfo_.keyId: The ID of the specific ERC721 token within the asset key collection. Set to type(uint256).max for any NFT in the collection.

  • securityInfo_.passwordHash: The hashed password used to protect the package. Highly reccomended.

• receiver_: The address of the recipient who will receive the package.

Returns:

• PackageID (uint256): The identifier assigned to the shipped package.

Description: Invoked by the package manager to initiate the shipping process for a single package. The function encapsulates the given assets into the package, secures it with the password hash, and sets the unlock timestamp.

Function: shipPackages

Parameters:

• packageContent_: An array of CapsuleContent structs representing the content of each package.

  • packageContent_[].capsuleType: The type of the capsule representing the package.

  • packageContent_[].metadataURI: The URI string representing the metadata of the package.

• securityInfo_: An array of SecurityInfo structs representing the security information of each package.

  • securityInfo_[].unlockTimestamp: The timestamp indicating when each package can be unlocked. Set to 0 for any time.

  • securityInfo_[].keyAddress: The address of the ERC721 collection used as the asset key for each package. Set to address(0) if not applicable.

  • securityInfo_[].keyId: The ID of the specific ERC721 token within the asset key collection for each package. Set to type(uint256).max if not applicable.

  • securityInfo_[].passwordHash: The hashed password used to protect each package. Set to bytes32(0) if not applicable.

• receiver_: An array of recipient addresses for each package.

Returns:

• _packageIds (uint256[]): An array of uint256 values representing the identifiers assigned to the shipped packages.

Description: Allows the package manager to initiate the shipping process for multiple packages in one transaction. Essentially a batch version of the shipPackage function for efficiency.

Function: pickup

Parameters:

• packageId_: The identifier of the package to be picked up.

• rawPassword_: The plain text password provided by the shipper. Empty string if no password.

• salt_: The plain text salt provided by the shipper. Empty string if no password.

• shouldRedeem_: A boolean flag indicating whether the package should be unwrapped or received as is.

  • true: Unwrap the package by burning the Capsule NFT and transferring the contents to the caller.

  • false: Receive the Capsule NFT without unwrapping. The Capsule NFT can be redeemed later to receive the contents.

Description: Called by the package receiver to pick up a package. Before delivering the package, this function ensures that the caller is the designated receiver and passes all the necessary security measures.

Function: cancelPackage

Parameters:

• packageId_: The identifier of the package to cancel.

• contentReceiver_: The address that will receive the contents of the package.

Description: Allows the package manager to cancel a package shipment. It is typically used when the delivery or receipt of a package needs to be stopped or canceled for any reason.

Function: deliverPackage

Parameters:

• packageId_: The identifier of the package to deliver.

Description: Allows the package manager to deliver a package directly to the designated receiver, bypassing all security measures. This function is typically used for expedited deliveries or in special circumstances where it is necessary to override the usual security checks.

Function: redeemPackage

Parameters:

• packageId_: The identifier for the package to be redeemed.

• receiver_: The receiver's address.

Description: The redeemPackage function is used to redeem a package by unwrapping it, burning the Capsule NFT, and transferring the package contents to the specified receiver_ address.

This function is applicable in two cases:

1. When the package has been delivered to the recipient, and the recipient wants to unwrap the package by redeeming the Capsule NFT.

2. When the recipient has accepted the package at the PostOffice without redeeming it, and now wants to unwrap it.

Function: securityInfo

Parameters:

• packageId_: The identifier of the package.

Description: Allows users to retrieve the security information associated with a package. This function is useful when conducting security checks or verifying the security measures applied to a specific package. It allows users to obtain information about the unlock timestamp, password hash, and other security-related details of the package.

CPaS: Package Modification

Function: updatePackageAssetKey

Parameters:

• packageId_: The identifier of the package.

• newKeyAddress_: The new address of the ERC721 collection used as the asset key.

• newKeyId_: The new ID of the specific ERC721 token within the asset key collection.

Description: Allows the package manager to update the asset key of a specific package. It takes in the packageId_, newKeyAddress_, and newKeyId_ parameters, and updates the package's security information with the new asset key address and ID.

Function: updatePackageManager

Parameters:

• packageId_: The identifier of the package.

• newPackageManager_: The new address of the package manager.

Description: Allows the package manager to update the package manager of a specific package. It takes in the packageId_ and newPackageManager_ parameters, and updates the package's manager address with the new value.

This function is useful when the package manager needs to transfer the management rights of a package to a different address, ensuring proper control and authorization over the package.

Function: updatePackagePasswordHash

Parameters:

• packageId_: The identifier of the package.

• newPasswordHash_: The new password hash.

Description: Allows the package manager to update the password hash of a specific package. It takes in the packageId_ and newPasswordHash_ parameters, and updates the package's security information with the new password hash.

This function is useful when the package manager wants to change the password used to protect the package, providing enhanced security and control over package access.

Function: updatePackageReceiver

Parameters:

• packageId_: The identifier of the package.

• newReceiver_: The new receiver address.

Description: Allows the package manager to update the receiver of a specific package. It takes in the packageId_ and newReceiver_ parameters, and updates the package's receiver address with the new value.

This function is useful when there is a need to change the recipient of a package, ensuring that it is delivered to the correct address.

Function: updatePackageUnlockTimestamp

Parameters:

• packageId_: The identifier of the package.

• newUnlockTimestamp_: The new unlock timestamp.

Description: Allows the package manager to update the unlock timestamp of a specific package. It takes in the packageId_ and newUnlockTimestamp_ parameters, and updates the package's security information with the new unlock timestamp.

This function is useful when there is a need to change the unlock time for a package, providing control over when the recipient can access its contents.