WP Manifestindependent plugin directory
manifest / ecommerce / near-web3-donate-wp

NEAR Donation Button

Accept NEAR Protocol donations on any WordPress site with a secure, wallet-agnostic donation button, shortcode and block. Developed by Pomnex.

by Pomnex · github.com/pomnex/near-web3-donate-wp

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/pomnex/near-web3-donate-wp/archive/refs/heads/main.zip
Readme github.com/pomnex/near-web3-donate-wp ↗

Accept NEAR Protocol donations on any WordPress site with a secure, wallet-agnostic donation button, block and shortcode.

Developed and maintained by Pomnex.
Version 2.0.0
Requires WordPress 6.3 or later (tested up to 7.1)
Requires PHP 7.4 or later (tested on 7.4 and 8.3)
License GPL-3.0-or-later, with an attribution term (see License)
Text domain near-donation

The user-facing documentation (features, FAQ, changelog and external services) is in readme.txt, in the WordPress.org format. This file is for developers.

How it works

  1. A site administrator sets the recipient account and the network under Settings > NEAR Donation. On save, the server checks on chain that the account exists.
  2. The block or shortcode renders a plain HTML form in PHP. The same renderer serves both, so their output is identical.
  3. A small front-end script (about 11 KB) enhances the form. When a visitor first hovers over, focuses or touches the form, it lazy-loads the wallet chunk (NEAR Wallet Selector and its modal, about 1.5 MB).
  4. The visitor picks a wallet and approves a single Transfer action to the configured recipient. Amounts are converted to yoctoNEAR with exact string/BigInt arithmetic.
  5. The script polls the RPC (tx, EXECUTED_OPTIMISTIC) and shows the final on-chain result with an explorer link.

No donation data is stored on the server, and the front end makes no requests to WordPress, so full-page caching is safe.

Security model

Threat Mitigation
Donations redirected to another account The recipient is an admin-only setting (manage_options). Shortcode and block attributes cannot change it. It is validated on save and again on every read (Settings::get()).
Private key theft through XSS Sign-in uses an empty contractId, so no function-call key is created or stored. Every transfer is approved in the donor's wallet.
Markup injection All PHP output is escaped. The JS writes messages with textContent only. Transaction hashes from the URL must match the base58 format and are only linked to the explorer, never treated as proof of payment.
Supply-chain attacks No CDN. Wallet libraries are bundled from exact, lock-filed versions. Node polyfills (buffer, process, util) are pinned, so nothing resolves from outside the project.
Rounding errors Amounts are never floats. PHP and JS share the same validation rules: at most 24 decimals, at most 12 integer digits, no exponents, and zero is rejected.
SSRF through the custom RPC URL Only HTTPS URLs are accepted, validated with wp_http_validate_url(), and requested with wp_safe_remote_post() without redirects and with a response size limit.
Direct file access Every PHP file checks ABSPATH (or WP_UNINSTALL_PLUGIN).

Project structure

near-donation.php          Plugin header and bootstrap
uninstall.php              Removes the settings (multisite aware)
readme.txt                 WordPress.org readme
LICENSE                    Full GPL-3.0 text
includes/
  class-plugin.php         Hooks, block and shortcode registration, privacy text
  class-settings.php       Settings API screen, sanitization, on-chain recipient check
  class-renderer.php       Shared markup for the shortcode and the block
  class-assets.php         Script and style registration, front-end configuration
  class-network.php        Mainnet/testnet presets and server-side RPC lookup
  class-validator.php      Account ID and amount validation
src/
  block/                   block.json and editor UI (dynamic block, server-side preview)
  frontend/
    index.js               Entry point: form initialization, wallet redirect handling
    form.js                Form controller (validation, states, messages)
    amount.js              Decimal/yoctoNEAR helpers
    connector.js           Lazy loader for the wallet chunk
    wallet.js              NEAR Wallet Selector integration (lazy chunk)
    public-path.js         Resolves lazy chunks from the plugin URL
    style.scss             Front-end styles (logical properties, RTL safe)
build/                     Compiled assets. Commit them: they are required at runtime

Development

Requirements: Node.js 22+, npm, PHP 7.4+ and Composer.

npm install          # JavaScript dependencies and @wordpress/scripts
composer install     # PHP_CodeSniffer, WordPress Coding Standards, PHPCompatibility

npm run build        # Production build into /build
npm run start        # Watch mode

npm run lint:js      # ESLint (WordPress rules)
npm run lint:css     # Stylelint (WordPress rules)
composer run lint    # PHPCS: WordPress standard and PHP 7.4+ compatibility

npm run plugin-zip   # Release ZIP with only the runtime files

The release ZIP contains only the files listed under files in package.json: build, includes, languages, LICENSE, index.php, near-donation.php, readme.txt and uninstall.php. Install that ZIP on production sites, not the source folder.

To regenerate the translation template, run npm run make-pot (requires WP-CLI).

Adding or removing wallets

Wallet modules are listed in src/frontend/wallet.js. Add the matching @near-wallet-selector/* package with an exact version, update the modules array, rebuild, and update the wallet list in readme.txt.

Hooks

Filter Arguments Purpose
pomnex_near_donation_frontend_config array $config, array $settings Change the configuration passed to the front-end script, for example modalTheme (auto, light or dark).
pomnex_near_donation_rpc_urls string[] $urls, string $network Change the RPC endpoints, in priority order.
pomnex_near_donation_explorer_url string $url, string $network Change the block explorer base URL.

Styling

The form uses BEM classes prefixed with pnd (.pnd, .pnd__button, .pnd__option and so on). Cosmetic rules have zero specificity (:where()), so theme styles take precedence. You can also set these custom properties on .pnd:

.pnd {
    --pnd-button-bg: #00c08b;
    --pnd-button-color: #000;
    --pnd-radius: 12px;
}

Credits

NEAR Donation Button is developed by Pomnex. Wallet connectivity is provided by NEAR Wallet Selector (MIT/Apache-2.0).

License

Copyright (C) 2026 Pomnex

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The full license text is in LICENSE. It is also available at https://www.gnu.org/licenses/gpl-3.0.html.

Additional term under GPLv3 Section 7(b): you must preserve the original author attribution ("Developed by Pomnex") in the source code headers and in the plugin's settings/about screen.

For contributors: every first-party source file starts with the notice Developed by Pomnex <https://pomnex.com>. and @license GPL-3.0-or-later. Keep both lines, and add them to new files. The attribution on the settings screen lives in Settings::render_page() (includes/class-settings.php).

Bundled third-party libraries keep their own licenses. They are mainly MIT, ISC, Apache-2.0 and BSD, all compatible with GPL-3.0.