Skip to content

Commit

Permalink
Merge branch 'main' into patch-1
Browse files Browse the repository at this point in the history
  • Loading branch information
@KuznetsovNikita
KuznetsovNikita authored Dec 27, 2023
2 parents d8c619f + e40bf41 commit fe0246c
Showing 1 changed file with 3 additions and 338 deletions.
341 changes: 3 additions & 338 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,6 @@
* [Donation](#unauthenticated-donations)
* [Deploy](#unauthenticated-transfers)
* [SignRawPayload](#unauthenticated-transfers)
* [NFTs](#nfts)
* [Deploy NFT collection](#deploy-nft-collection)
* [Deploy NFT item](#deploy-nft-item)
* [Deploy Single NFT](#deploy-single-nft)
* [Change Collection Owner](#change-collection-owner)
* [Transfer NFT](#transfer-nft)
* [Basic NFT Sale](#basic-nft-sale)
* [Getgems NFT Sale](#getgems-nft-sale)
* [Cancel NFT Sale](#cancel-nft-sale)
* [Subscriptions](#subscriptions)


Expand Down Expand Up @@ -163,7 +154,7 @@ ton://transfer/<destination-address>?
[forward-amount=<nanocoins>]
```

Opens the pre-filled NFT-send screen and offers user to enter the missing data.
Opens the pre-filled Jetton-send screen and offers user to enter the missing data.
* `to`: (string) destination account ID. Optional.
* `amount` (decimal string): amount of transferred jettons in elementary units.
* `fee-amount` (decimal string): nanocoins to be sent to the Jetton contract for paying fee. All not used TONs should be returned back by Jetton contract. If not specified default value will be used - 1 TON.
Expand Down Expand Up @@ -276,14 +267,7 @@ Transaction request must be discarded if the local time is greater than the `exp
"type": "transfer" |
"donation" |
"deploy" |
"sign-raw-payload" |
"nft-collection-deploy" |
"nft-item-deploy" |
"nft-single-deploy" |
"nft-change-owner" |
"nft-transfer" |
"nft-sale-place-getgems" |
"nft-sale-cancel",
"sign-raw-payload",
"expires_sec: integer,
Expand All @@ -292,14 +276,7 @@ Transaction request must be discarded if the local time is greater than the `exp
"params": TransferParams |
DonationParams |
DeployParams |
SignBoc |
NftCollectionDeployParams |
NftItemDeployParams |
NftSingleDeployParams |
NftChangeOwnerParams |
NftTransferParams |
NftSalePlaceParams |
NftSaleCancelParams
SignBoc
}
```

Expand Down Expand Up @@ -410,318 +387,6 @@ Example:
```



## NFTs

### Deploy NFT collection

[Transaction request](#transaction-request) object with type `nft-collection-deploy`.

Parameters:

* `ownerAddress` (string, optional)
* `royalty` (float): number from 0 to 1.
* `royaltyAddress` (string)
* `collectionContentUri` (string): URI to the collection content
* `nftItemContentBaseUri` (string): URI to the item content
* `nftCollectionStateInitHex` (string, optional): hex-encoded collection stateinit BoC with one cell
* `nftItemCodeHex` (string): hex-encoded item contract code BoC with one cell
* `amount` (decimal string): nanotoncoins

If the `ownerAddress` is set:
* single-wallet app checks that the address matches user’s address.
* multi-wallet app selects the wallet with the matching address; fails otherwise.

If the `ownerAddress` is missing: wallet app uses the current address.

Note: `ownerAddress` cannot be set to some other wallet, not controlled by the initiator of the transaction.

If the `royaltyAddress` is set and not equal to the `ownerAddress` wallet app shows separate line with royalty recipient.

If the `nftCollectionStateInitHex` is specified, then all the data parameters (royalty, URIs, NFT item code) are ignored and raw state init cell is used instead. Collection ID is calculated from that stateinit.

Primary confirmation UI displays:

* Royalty address (if not the same as the wallet).
* Royalty (%): fraction formatted in percents.
* Fee: actual tx fee + amount (which will be deposited on the interim contracts)

Secondary UI with raw data:

* NFT Collection ID: EQr6...jHyR (TODO: check if that must be front-and-center or not)
* collectionContentUri
* nftItemContentBaseUri
* nftItemCodeHex


### Deploy NFT item

[Transaction request](#transaction-request) object with type `nft-item-deploy`.

Parameters:

* `ownerAddress` (string, optional): owner of the collection.
* `nftCollectionAddress` (string): contract address of the collection that will deploy the item.
* `nftItemContentBaseUri` (string): base URL of the NFT collection metadata that will be used in concatenation with `itemContentUri`.
* `amount` (decimal string): nanocoins to be sent to the item’s contract
* `forwardAmount` (decimal string): nanocoins to be sent by collection to the item.
* `itemIndex` (integer): index of the item in the collection
* `itemContentUri` (string): path to the item description

If the `ownerAddress` is set:
* single-wallet app checks that the address matches user’s address.
* multi-wallet app selects the wallet with the matching address; fails otherwise.

If the `ownerAddress` is missing: wallet app uses the current address.

Note: `ownerAddress` cannot be set to some other wallet, not controlled by the initiator of the transaction.

Wallet must check if `forwardAmount` is above zero and less than `amount`.

Primary confirmation UI displays:

* Item Name
* Collection Name
* Fee: actual tx fee + amount (which will be deposited on the interim contracts)

Secondary UI with raw data:

* Item Index (TODO: figure out what happens if this clashes with existing one)
* NFT Collection ID
* itemContentUri


### Deploy Single NFT

[Transaction request](#transaction-request) object with type `nft-single-deploy`.

* TBD.
* `stateInitHex` (string): hex-encoded NFT stateinit BoC with one cell.
* `amount` (decimal string): nanotoncoins to be sent to that deployed NFT contract.

All data parameters are used in UI only, while raw state init cell is used for actual deploy.



### Change Collection Owner

[Transaction request](#transaction-request) object with type `nft-change-owner`.

Parameters:

* `newOwnerAddress` (string)
* `nftCollectionAddress` (string)
* `amount` (decimal string): nanocoins to be sent to the item’s contract

Primary confirmation UI displays:

* New owner address: `EQrJ...`
* Fee: `<actual tx fee + amount>`

Secondary UI with raw data:

* NFT Collection ID



### Transfer NFT

[Transaction request](#transaction-request) object with type `nft-transfer`.

Parameters:

* `newOwnerAddress` (string): recipient’s wallet
* `nftItemAddress` (string): ID of the nft item
* `amount` (decimal string): nanocoins to be sent to the item’s contract
* `forwardAmount` (decimal string): nanocoins to be sent as a notification to the new owner
* `text` (string, optional): optional comment

Wallet must validate that the `forwardAmount` is less or equal to the `amount`.

Primary confirmation UI displays:

* Recipient: `EQjTpY...tYj82s`
* Fee: `<actual tx fee + amount>`
* Text: `<freeform comment>`

Secondary:

* NFT Item ID: `Ekrj...57fP`


### Basic NFT Sale

(WIP)

[Transaction request](#transaction-request) object with type `nft-sale-place`.

Parameters:

* `marketplaceAddress` (string): address of the marketplace
* `nftItemAddress` (string): identifier of the specific nft item
* `fullPrice` (decimal string): price in nanocoins
* `marketplaceFee` (decimal string): nanocoins as marketplace fee
* `royaltyAddress` (string): address for the royalties
* `royaltyAmount` (decimal string): nanotoncoins sent as royalties
* `deployAmount` (decimal string): nanotoncoins sent with deployment of sale contract
* `transferAmount` (decimal string): nanotoncoins sent with nft transfer message
* `forwardAmount` (decimal string): nanocoins to be sent as a forward for the NFT transfer (in the second transaction)

Primary confirmation UI displays:

* Marketplace: `EQh6...`
* Price: `100.00 TON`
* Your proceeds: `79.64 TON`
* Fees & royalties: `<txfee + deployAmount + transferAmount + marketplace fee + royalties>`

Secondary UI:

* NFT item ID: `EQr4...`
* Marketplace fee: `10 TON`
* RoyaltyAddress: `Eqt6...`
* Royalty: `5 TON`
* Blockchain fee: `0.572 TON` (txfee + amount)




### Getgems NFT Sale

[Transaction request](#transaction-request) object with type `nft-sale-place-getgems`.

Parameters:

* `marketplaceFeeAddress` (string): fee-collecting address
* `marketplaceFee` (decimal string): nanocoins as marketplace fee
* `royaltyAddress` (string): address for the royalties
* `royaltyAmount` (decimal string): nanotoncoins sent as royalties
* `createdAt`: (integer): UNIX timestamp of the sale creation date
* `marketplaceAddress` (string): address of the marketplace
* `nftItemAddress` (string): identifier of the specific nft item
* `ownerAddress` (string): owner of the NFT item
* `fullPrice` (decimal string): price in nanocoins
* `deployAmount` (decimal string): nanotoncoins sent with deployment of sale contract
* `transferAmount` (decimal string): nanotoncoins sent with nft transfer message
* `saleMessageBocHex` (string): hex-encoded arbitrary BoC with one cell (typically an empty cell)
* `marketplaceSignatureHex` (string): hex-encoded signature
* `forwardAmount` (decimal string): nanocoins to be sent as a forward for the NFT transfer (in the second transaction)

Primary confirmation UI displays:

* Marketplace: `EQh6...`
* Price: `100.00 TON`
* Your proceeds: `79.64 TON`
* Fees & royalties: `<txfee + deployAmount + transferAmount + marketplace fee + royalties>`

Secondary UI:

* NFT item ID: `EQr4...`
* Marketplace fee: `10 TON`
* Marketplace fee address: `EQmAr...`
* RoyaltyAddress: `EQRy1t...`
* Royalty: `5 TON`
* Blockchain fee: `0.572 TON` (txfee + amount)


Sale Contract BOC (Base64-encoded):
```
te6cckECDAEAAikAART/APSkE/S88sgLAQIBIAMCAATyMAIBSAUEAFGgOFnaiaGmAaY/9IH0gfSB9AGoYaH0gfQB9IH0AGEEIIySsKAVgAKrAQICzQgGAfdmCEDuaygBSYKBSML7y4cIk0PpA+gD6QPoAMFOSoSGhUIehFqBSkHCAEMjLBVADzxYB+gLLaslx+wAlwgAl10nCArCOF1BFcIAQyMsFUAPPFgH6AstqyXH7ABAjkjQ04lpwgBDIywVQA88WAfoCy2rJcfsAcCCCEF/MPRSBwCCIYAYyMsFKs8WIfoCy2rLHxPLPyPPFlADzxbKACH6AsoAyYMG+wBxVVAGyMsAFcsfUAPPFgHPFgHPFgH6AszJ7VQC99AOhpgYC42EkvgnB9IBh2omhpgGmP/SB9IH0gfQBqGBNgAPloyhFrpOEBWccgGRwcKaDjgskvhHAoomOC+XD6AmmPwQgCicbIiV15cPrpn5j9IBggKwNkZYAK5Y+oAeeLAOeLAOeLAP0BZmT2qnAbE+OAcYED6Y/pn5gQwLCQFKwAGSXwvgIcACnzEQSRA4R2AQJRAkECPwBeA6wAPjAl8JhA/y8AoAyoIQO5rKABi+8uHJU0bHBVFSxwUVsfLhynAgghBfzD0UIYAQyMsFKM8WIfoCy2rLHxnLPyfPFifPFhjKACf6AhfKAMmAQPsAcQZQREUVBsjLABXLH1ADzxYBzxYBzxYB+gLMye1UABY3EDhHZRRDMHDwBTThaBI=
```

SaleStateInit cell for the sale contract:

```
StateInit {
codeCell: saleContractBOC[0],
dataCell: Cell {
isComplete: Uint(1), // store 0 (isComplete = false)
createdAt: Uint(32),
marketplaceAddress: Address,
nftItemAddress: Address,
nftOwnerAddress: Address, // write null (writeUint(0, 2))
fullPrice: Coins,
refs: [
Cell {
marketplaceFeeAddress: Address,
marketplaceFee: Coins,
royaltyAddress: Address,
royaltyAmount: Coins,
}
]
}
}
```

Sale contract address:

```
Address {
workchain: 0,
hash: SaleStateInit.hash
}
```

MessageBody cell layout for deployment:

```
Cell {
op: Uint(32), // write "1" (OperationCodes.DeploySale),
marketplaceSignature: Buffer(512), // write raw 512 bits of signature
refs: [
SaleStateInit,
saleMessageBoc.root_cells[0],
]
}
```

Transfer with TonWeb:

```
await wallet.methods.transfer({
secretKey: ...
toAddress: marketplaceAddress,
amount: deployAmount,
seqno: seqno,
payload: MessageBody,
sendMode: 3,
}).send()
```

Wallet performs the following:

1. Computes sale contract StateInit cell using parameters above.
2. Computes the sale contract address `S` using state init for workchain 0.
3. Prepares message body with the opcode 1, marketplace signature and provided message.
4. Sends this message to `marketplaceAddress` from the user's wallet matching `ownerAddress`.
5. Waits till the contract at address `S` is initialized on-chain (3 attempts with 10 second delay).
6. When `S` is initialized, automatically perform transfer of ownership for the token to address `S` with `transferAmount` as main amount and `forwardAmount` that allows notifying the new owner (the sale contract).



### Cancel NFT Sale

[Transaction request](#transaction-request) object with type `nft-sale-cancel`.

Parameters:

* `saleAddress` (string): address of the sale contract
* `ownerAddress` (string): owner of the NFT item
* `amount` (decimal string): nanotoncoins sent as commission with the message

Wallet must verify that it owns the `ownerAddress` and select the appropriate secret key and wallet contract to send the message from.

Primary confirmation UI displays:

* Sale address: `EQr4...`
* Fee: `<txfee>`







## Subscriptions

TBD: describe the API to submit subscriptions
Expand Down

1 comment on commit fe0246c

@hossen71
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fe0246c

Please sign in to comment.