Flow FT 与 NFT 标准中的最佳实践

Flow FT 与 NFT 标准合约中的最佳实践

为什么要学习标准合约

抽象 —— 简化复杂需求

聚合 —— 统一标准接口

解耦 —— 灵活可扩展

最佳实践

权限控制

pub resource Vault: Provider, Receiver, Balance {

	pub var balance: UFix64

	init(balance: UFix64)
	/// withdraw subtracts `amount` from the Vault's balance

	/// and returns a new Vault with the subtracted balance
	pub fun withdraw(amount: UFix64): @Vault {

	//...
	}

	/// deposit takes a Vault and adds its balance to the balance of this Vault
	pub fun deposit(from: @Vault) {

	// Assert that the concrete type of the deposited vault is the same

	// as the vault that is accepting the deposit

	}
}

pub resource interface Provider {

	pub fun withdraw(amount: UFix64): @Vault {
		//...
	}

}

pub resource interface Receiver {

	pub fun deposit(from: @Vault)

}

pub resource interface Balance {

	pub var balance: UFix64

	init(balance: UFix64) {
		// ...
	}

}

pub resource Vault: FungibleToken.Provider, FungibleToken.Receiver, FungibleToken.Balance {
	// ...
}

init() {

	self.totalSupply = 1000.0

	// 1. init vault with total supply
	let vault <- create Vault(balance: self.totalSupply)
	// 2. save resource to user's storage path
	self.account.save(<-vault, to: /storage/exampleTokenVault)

	// 3. link Receiver interface to public path
	self.account.link<&{FungibleToken.Receiver}>(

		/public/exampleTokenReceiver,

		target: /storage/exampleTokenVault

	)

	// 4. link Balance interface to public path
	self.account.link<&ExampleToken.Vault{FungibleToken.Balance}>(

		/public/exampleTokenBalance,

		target: /storage/exampleTokenVault

	)


}

import FungibleToken from 0xFUNGIBLETOKENADDRESS

import ExampleToken from 0xTOKENADDRESS

transaction(amount: UFix64, to: Address) {

	// The Vault resource that holds the tokens that are being transferred

	let sentVault: @FungibleToken.Vault

	prepare(signer: AuthAccount) {

		// Get a reference to the signer's stored vault
		// 1. Get vault resource reference from sender， need auth
		let vaultRef = signer.borrow<&ExampleToken.Vault>(from: /storage/exampleTokenVault)
		?? panic("Could not borrow reference to the owner's Vault!")

		// Withdraw tokens from the signer's stored vault
		// 2. Set vault resource reference with withdraw vault
		self.sentVault <- vaultRef.withdraw(amount: amount)

	}

	execute {

		// Get the recipient's public account object

		let recipient = getAccount(to)

		// Get a reference to the recipient's Receiver
		// 3. Get pub receiver reference from receiver's account public path
		let receiverRef = recipient.getCapability(/public/exampleTokenReceiver)
		.borrow<&{FungibleToken.Receiver}>()
		?? panic("Could not borrow receiver reference to the recipient's Vault")

		// Deposit the withdrawn tokens in the recipient's receiver
		// 4. Call receiver's vault deposit function
		receiverRef.deposit(from: <-self.sentVault)

	}

}

1. 从发送者 Sender（交易授权者）的账户中获得 /storage/ path 的 Vault 资源，这个步骤是权限受限的

2. 调用 Vault 资源中的 withdraw 方法提取出对应包含转账金额的临时 Vault 资源

3. 在执行环节根据接收者 Receiver（无需权限）的地址获得他的公开账户，然后根据 /public/ path 中的 FungibleToken.Receiver 类型的接口借出接收人公开的 Vault 资源引用（这里的 Vault 和上一个不同，是通过公开的接口暴露出来的，Receiver 类型的接口只有 deposit 方法）

4. 调用接收方资源的 deposit 函数，完成转账操作。

注意：这里的转账脚本并不是操作合约的代码完成，而是调用发送者授权资源的提现方法和接收者公开资源的充值方法，以资源为中心，点对点的方式完成了代币的转移。

接口分离

• Provider(需授权调用)

• Receiver(无需授权)

• Balance(无需授权)

资源嵌套

// NFT resource
pub resource NFT {
    pub let id: UInt64
    pub var metadata: {String: String}
    ...
}

• 资源在同一时间只能存在于一个确切的位置

• 资源无法被复制

• 资源必须被明确的销毁

pub resource Collection: Provider, Receiver, CollectionPublic {

	// Dictionary to hold the NFTs in the Collection
	// 1. Store user's NFTs as a map
	pub var ownedNFTs: @{UInt64: NFT}

	// withdraw removes an NFT from the collection and moves it to the caller
	// 2. Withdraw NFT resource form ownedNFTs
	pub fun withdraw(withdrawID: UInt64): @NFT

	// deposit takes a NFT and adds it to the collections dictionary

	// and adds the ID to the id array
	// 3. Deposit NFT resource to ownedNFTs
	pub fun deposit(token: @NFT)

	// ...

}

// withdraw removes an NFT from the collection and moves it to the caller

pub fun withdraw(withdrawID: UInt64): @NonFungibleToken.NFT {
	// 1. Take NFT resource from ownedNFTs
	let token <- self.ownedNFTs.remove(key: withdrawID) ?? panic("missing NFT")

	emit Withdraw(id: token.id, from: self.owner?.address)
	// 2. return NFT resource
	return <-token

}

// deposit takes a NFT and adds it to the collections dictionary

// and adds the ID to the id array

pub fun deposit(token: @NonFungibleToken.NFT) {
	// 3. Convert type from super resource to resource
	let token <- token as! @ExampleNFT.NFT

	let id: UInt64 = token.id

	// add the new token to the dictionary which removes the old one
	// 4. Save NFT resource to ownedNFTs
	let oldToken <- self.ownedNFTs[id] <- token

	emit Deposit(id: id, to: self.owner?.address)

	destroy oldToken

}

类型转换

pub resource Collection: ExampleNFTCollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic, MetadataViews.ResolverCollection {

	// dictionary of NFT conforming tokens

	// NFT is a resource type with an `UInt64` ID field

	pub var ownedNFTs: @{UInt64: NonFungibleToken.NFT}

	init () {

		self.ownedNFTs <- {}

	}

	// ...

	// deposit takes a NFT and adds it to the collections dictionary

	// and adds the ID to the id array

	pub fun deposit(token: @NonFungibleToken.NFT) {
		// 1. Force down convert
		let token <- token as! @ExampleNFT.NFT

		let id: UInt64 = token.id

		// add the new token to the dictionary which removes the old one

		let oldToken <- self.ownedNFTs[id] <- token

		emit Deposit(id: id, to: self.owner?.address)

		destroy oldToken

	}


	// borrowNFT gets a reference to an NFT in the collection

	// so that the caller can read its metadata and call its methods

	pub fun borrowNFT(id: UInt64): &NonFungibleToken.NFT {
		// 2. Up convert
		return &self.ownedNFTs[id] as &NonFungibleToken.NFT

	}

	pub fun borrowExampleNFT(id: UInt64): &ExampleNFT.NFT? {

		if self.ownedNFTs[id] != nil {

			// Create an authorized reference to allow downcasting
			// 3. convert with owner's auth
			let ref = &self.ownedNFTs[id] as auth &NonFungibleToken.NFT

			return ref as! &ExampleNFT.NFT

		}

		return nil

	}

	//...
}

• 注释一： 向下转换，将抽象的资源类型，强制转换成实现的资源类型，因为@ExampleNFT.NFT 与 @NonFungibleToken.NFT 都实现了相同的父类型资源 @NonFungibleToken.INFT 所以他们之间是可以正常的强制转换。

// Interface that the NFTs have to conform to

//

pub resource interface INFT {

// The unique ID that each NFT has

	pub let id: UInt64

}

// Requirement that all conforming NFT smart contracts have

// to define a resource called NFT that conforms to INFT

pub resource NFT: INFT {

	pub let id: UInt64

}


pub resource NFT: NonFungibleToken.INFT, MetadataViews.Resolver {
	pub let id: UInt64
	// ...
}

• 注释二：因为我们在存储的时候使用的向下转换，那么为了满足标准接口的需求，我们必须在通过 borrow 函数获得引用之后再进行一次向上类型转换

• 注释三：资源引用的授权转换，这里因为会直接返回资源的引用类型，能够有权限调用资源中的函数，那么就需要使用 auth 修饰符，声明需要 owner 授权才可以完成转换。

条件判断

pub fun withdraw(amount: UFix64): @Vault {
	// 1. Check balance enough or not before transfer
	pre {
		self.balance >= amount:
		"Amount withdrawn must be less than or equal than the balance of the Vault"
	}
	// 2. Check balance after trasfer
	post {
		// use the special function `before` to get the value of the `balance` field
		// at the beginning of the function execution
		self.balance == before(self.balance) - amount:
		"New Vault balance must be the difference of the previous balance and the withdrawn Vault"
	}
}

/// deposit takes a Vault and adds its balance to the balance of this Vault
pub fun deposit(from: @Vault) {
	// Assert that the concrete type of the deposited vault is the same
	// as the vault that is accepting the deposit\\
	// 3. Check Vault type before deposit
	pre {
		from.isInstance(self.getType()):
		"Cannot deposit an incompatible token type"
	}
	// 4. Check balance after deposite
	post {
		self.balance == before(self.balance) + before(from.balance):
		"New Vault balance must be the sum of the previous balance and the deposited Vault"
	}
}

pub fun createEmptyVault(): @Vault {
	// 5. Check vault balance after resource init
	post {
		result.balance == 0.0: "The newly created Vault must have zero balance"
	}

}

总结