feat: add NEAR docs #3
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,168 @@ | ||
| --- | ||
| title: "NEAR" | ||
| description: "Request Network's support for NEAR including native and fungible token payments" | ||
| --- | ||
|
|
||
| import { CopyButton, ExternalLinkButton } from "/snippets/contract-buttons.jsx" | ||
|
|
||
| ## Overview | ||
|
|
||
| Request Network supports payments on NEAR, a sharded, proof-of-stake blockchain that offers unique capabilities compared to EVM-compatible chains. NEAR's architecture enables more complex smart contract interactions through asynchronous callbacks and cross-contract calls. | ||
|
Check warning on line 10 in resources/near-blockchain.mdx
|
||
|
|
||
| <Note> | ||
| NEAR support is currently available through the **Request Network SDK only**. The Request Network API does not support NEAR blockchain interactions. | ||
| </Note> | ||
|
|
||
| ## Key Differences from EVM Chains | ||
|
|
||
| NEAR has several important architectural differences that affect how payments work: | ||
|
|
||
| <CardGroup cols={2}> | ||
| <Card title="Asynchronous Callbacks" icon="arrows-rotate"> | ||
| Unlike EVM chains where transactions are atomic, NEAR supports **asynchronous callbacks** that can span multiple transactions or blocks. This enables more complex payment flows but requires different handling. | ||
| </Card> | ||
|
|
||
| <Card title="Account-Based System" icon="user"> | ||
| NEAR uses human-readable account names (like `alice.near`) instead of hex addresses. Smart contracts are deployed to named accounts and can be upgraded by their owners. | ||
| </Card> | ||
| </CardGroup> | ||
|
|
||
| <CardGroup cols={2}> | ||
| <Card title="Storage Deposits" icon="database"> | ||
| To receive NEP-141 fungible tokens, accounts must first register with the token contract and pay a small storage deposit (~0.00125 NEAR) to cover storage costs. | ||
| </Card> | ||
|
|
||
| <Card title="Gas Model" icon="gas-pump"> | ||
| NEAR uses a different gas model with TGas (TeraGas) units. Gas costs are predictable and much lower than Ethereum mainnet. | ||
|
Check warning on line 36 in resources/near-blockchain.mdx
|
||
| </Card> | ||
| </CardGroup> | ||
|
|
||
| ## Supported Payment Types | ||
|
|
||
| ### Native NEAR Payments | ||
|
|
||
| Direct payments using NEAR's native token through the payment proxy smart contract. | ||
|
|
||
| **Features:** | ||
| - ✅ Direct NEAR token transfers with payment references | ||
| - ✅ Fee collection support | ||
| - ✅ Payment detection and indexing | ||
|
|
||
| ### Fungible Token Payments (NEP-141) | ||
|
|
||
| Payments using NEAR's fungible token standard (NEP-141) equivalent to ERC-20 on Ethereum. | ||
|
Check warning on line 53 in resources/near-blockchain.mdx
|
||
|
|
||
| **Features:** | ||
| - ✅ Support for all NEP-141 compliant tokens | ||
| - ✅ Fee collection in the same token | ||
| - ✅ Payment detection and indexing | ||
| - ⚠️ Requires storage deposit registration | ||
|
|
||
| ### Native Token Conversion Payments | ||
|
|
||
| Payments for requests denominated in one currency (typically fiat like USD) but paid in NEAR native tokens. On-chain oracles provide real-time price feeds to calculate the correct NEAR amount. | ||
|
|
||
| **Features:** | ||
| - ✅ Conversion payments denominated in USD, settled in NEAR | ||
| - ✅ Price conversion at the moment of payment, using onchain price feeds | ||
| - ✅ Payment detection and indexing | ||
|
|
||
| ## Smart Contract Addresses | ||
|
|
||
| ### Mainnet (near) | ||
|
|
||
| | Payment Type | Contract Address | Actions | Description | | ||
| |--------------|------------------|---------|-------------| | ||
| | **Native NEAR Payments** | `requestnetwork.near` | <div className="flex gap-1"><CopyButton text="requestnetwork.near" /><ExternalLinkButton href="https://nearblocks.io/address/requestnetwork.near" /></div> | Direct NEAR token payments with references | | ||
| | **Fungible Token Payments** | `pay.reqnetwork.near` | <div className="flex gap-1"><CopyButton text="pay.reqnetwork.near" /><ExternalLinkButton href="https://nearblocks.io/address/pay.reqnetwork.near" /></div> | NEP-141 token payments with fees | | ||
| | **Native Conversion Payments** | `native.conversion.reqnetwork.near` | <div className="flex gap-1"><CopyButton text="native.conversion.reqnetwork.near" /><ExternalLinkButton href="https://nearblocks.io/address/native.conversion.reqnetwork.near" /></div> | Fiat/token to NEAR conversions | | ||
|
|
||
| ### Testnet (near-testnet) | ||
|
|
||
| | Payment Type | Contract Address | Actions | Description | | ||
| |--------------|------------------|---------|-------------| | ||
| | **Native NEAR Payments** | `dev-1631521265288-35171138540673` | <div className="flex gap-1"><CopyButton text="dev-1631521265288-35171138540673" /><ExternalLinkButton href="https://testnet.nearblocks.io/address/dev-1631521265288-35171138540673" /></div> | Direct NEAR token payments with references | | ||
| | **Fungible Token Payments** | `pay.reqnetwork.testnet` | <div className="flex gap-1"><CopyButton text="pay.reqnetwork.testnet" /><ExternalLinkButton href="https://testnet.nearblocks.io/address/pay.reqnetwork.testnet" /></div> | NEP-141 token payments with fees | | ||
| | **Native Conversion Payments** | `native.conversion.reqnetwork.testnet` | <div className="flex gap-1"><CopyButton text="native.conversion.reqnetwork.testnet" /><ExternalLinkButton href="https://testnet.nearblocks.io/address/native.conversion.reqnetwork.testnet" /></div> | Fiat/token to NEAR conversions | | ||
|
|
||
| ## Payment Detection | ||
|
|
||
| Payment detection for NEAR transactions is handled through dedicated subgraphs: | ||
|
|
||
| - **NEAR Mainnet**: [Request Payments Near Subgraph](https://thegraph.com/explorer/subgraphs/9yEg3h46CZiv4VuSqo1erMMBx5sHxRuW5Ai2V8goSpQL?view=Query&chain=arbitrum-one) | ||
| - **NEAR Testnet**: [Request Payments Near Testnet Subgraph](https://thegraph.com/explorer/subgraphs/AusVyfndonsMVFrVzckuENLqx8t6kcXuxn6C6VbSGd7M?view=Query&chain=arbitrum-one) | ||
|
|
||
| These subgraphs index payment events and transaction data to enable efficient payment detection and status tracking. | ||
|
|
||
| ## Technical Considerations | ||
|
|
||
| ### Asynchronous Callbacks | ||
|
|
||
| NEAR's asynchronous architecture means payment transactions may require multiple blockchain interactions: | ||
|
Check warning on line 101 in resources/near-blockchain.mdx
|
||
|
|
||
| ```javascript | ||
| // Example: Fungible token payment flow | ||
| 1. Call ft_transfer_call on token contract | ||
| 2. Token contract calls proxy contract | ||
| 3. Proxy processes payment and logs event | ||
| 4. Callback confirms or reverts transaction | ||
| ``` | ||
|
|
||
| This differs from EVM chains where the entire payment happens in a single atomic transaction. | ||
|
|
||
| ### Storage Deposits | ||
|
|
||
| Before receiving NEP-141 tokens, accounts must register with the token contract: | ||
|
|
||
| <Warning> | ||
| **Important**: Payment addresses must have sufficient storage deposit registered with the token contract. The SDK automatically checks for this requirement and will throw an error if the recipient is not properly registered. | ||
| </Warning> | ||
|
|
||
| **Minimum Storage Deposit**: ~0.00125 NEAR per token contract | ||
|
|
||
| ### Gas Considerations | ||
|
|
||
| <Tip> | ||
| NEAR uses a TGas (TeraGas) unit system and gas costs are predictable and much lower than Ethereum mainnet, typically costing fractions of a cent in USD terms. | ||
|
Check warning on line 126 in resources/near-blockchain.mdx
|
||
| </Tip> | ||
|
|
||
| ## Integration Guide | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| 1. **NEAR Wallet Connection**: Applications need to integrate with NEAR wallet providers | ||
| 2. **SDK Installation**: Use `@requestnetwork/request-client.js` with NEAR support | ||
| 3. **Account Registration**: Ensure payment recipients are registered for token contracts | ||
|
|
||
| ### Basic Payment Flow | ||
|
|
||
| ```javascript | ||
| import { RequestNetwork } from '@requestnetwork/request-client.js'; | ||
|
|
||
| // Create request for NEAR native payment | ||
| const request = await requestNetwork.createRequest({ | ||
| currency: { | ||
| type: 'ETH', // NEAR native uses ETH type | ||
| value: 'NEAR', | ||
| network: 'near' | ||
| }, | ||
| expectedAmount: '1000000000000000000000000', // 1 NEAR in yoctoNEAR | ||
| paymentAddress: 'recipient.near' | ||
| }); | ||
| ``` | ||
|
|
||
| ## Limitations | ||
|
|
||
| <Warning> | ||
| **Current Limitations:** | ||
| - NEAR support is SDK-only (not available in Request Network API) | ||
| - Crosschain payments to/from NEAR are not supported | ||
| - Advanced payment types like batch payments are not implemented | ||
| </Warning> | ||
|
|
||
| ## Developer Resources | ||
|
|
||
| - [NEAR Documentation](https://docs.near.org/) | ||
| - [NEP-141 Fungible Token Standard](https://nomicon.io/Standards/Tokens/FungibleToken/Core) | ||
| - [NEAR Smart Contract Source Code](https://github.com/RequestNetwork/near-contracts) | ||
| - [Request Network SDK Documentation]() | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| export const CopyButton = ({ text, title = "Copy Address" }) => { | ||
| const copyToClipboard = () => { | ||
| navigator.clipboard.writeText(text).then(() => { | ||
| console.log(`Copied ${text} to clipboard!`); | ||
| }).catch(err => { | ||
| console.error("Failed to copy: ", err); | ||
| }); | ||
|
Comment on lines
+3
to
+7
There was a problem hiding this comment. Console messages should provide more user-friendly feedback. Consider implementing visual feedback (toast notifications, temporary button state changes) instead of relying solely on console logs that users won't see. Copilot uses AI. Check for mistakes. |
||
| }; | ||
|
|
||
| return ( | ||
| <button | ||
| onClick={copyToClipboard} | ||
| title={title} | ||
| className="inline-flex items-center justify-center w-8 h-8 text-gray-600 dark:text-gray-400 transition-all duration-300 rounded-md hover:bg-gray-100 dark:hover:bg-gray-700 active:scale-95 focus:outline-none focus:ring-2 focus:ring-opacity-50 no-underline contract-button" | ||
| style={{ | ||
| '--primary-color': '#01B089' | ||
| }} | ||
| > | ||
| <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"> | ||
| <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect> | ||
| <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path> | ||
| </svg> | ||
| <style jsx>{` | ||
| .contract-button:hover { | ||
| color: var(--primary-color) !important; | ||
| } | ||
| .contract-button:focus { | ||
| color: var(--primary-color) !important; | ||
| box-shadow: 0 0 0 2px var(--primary-color) !important; | ||
| } | ||
| .contract-button:active { | ||
| color: var(--primary-color) !important; | ||
| } | ||
| `}</style> | ||
|
Comment on lines
+23
to
+34
There was a problem hiding this comment. The same CSS styling block is duplicated between CopyButton and ExternalLinkButton components. Consider extracting this into a shared constant or moving it to a common stylesheet to reduce code duplication. Copilot uses AI. Check for mistakes. |
||
| </button> | ||
| ); | ||
| }; | ||
|
|
||
| export const ExternalLinkButton = ({ href, title = "View on Block Explorer" }) => { | ||
| return ( | ||
| <button | ||
| onClick={() => window.open(href, '_blank', 'noopener,noreferrer')} | ||
| title={title} | ||
| className="inline-flex items-center justify-center w-8 h-8 text-gray-600 dark:text-gray-400 transition-all duration-300 rounded-md hover:bg-gray-100 dark:hover:bg-gray-700 active:scale-95 focus:outline-none focus:ring-2 focus:ring-opacity-50 no-underline contract-button" | ||
| style={{ | ||
| '--primary-color': '#01B089' | ||
| }} | ||
| > | ||
| <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"> | ||
| <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path> | ||
| <polyline points="15,3 21,3 21,9"></polyline> | ||
| <line x1="10" y1="14" x2="21" y2="3"></line> | ||
| </svg> | ||
| <style jsx>{` | ||
| .contract-button:hover { | ||
| color: var(--primary-color) !important; | ||
| } | ||
| .contract-button:focus { | ||
| color: var(--primary-color) !important; | ||
| box-shadow: 0 0 0 2px var(--primary-color) !important; | ||
| } | ||
| .contract-button:active { | ||
| color: var(--primary-color) !important; | ||
| } | ||
| `}</style> | ||
| </button> | ||
| ); | ||
| }; | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.