hpw-convert-eip681 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Osumi Akari
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Osumi Akari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# hpw-convert-eip681
+![Crates.io Version](https://img.shields.io/crates/v/hpw-convert-eip681)
+![Crates.io Downloads (latest version)](https://img.shields.io/crates/dv/hpw-convert-eip681)
+![NPM Version](https://img.shields.io/npm/v/hpw-convert-eip681)
+![NPM Downloads](https://img.shields.io/npm/dy/hpw-convert-eip681)
+![GitHub License](https://img.shields.io/github/license/oageo/hpw-convert-eip681)
+
+日本におけるとある中央集権的なステーブルコイン決済QRコード（HashPort Wallet形式の決済リンク）のURLを解析し、EIP-681（ERC-681）形式の支払いURIや送金先アドレス・金額に変換する[Rust製ライブラリ](https://crates.io/crates/hpw-convert-eip681)です。[WebAssembly版（npm）](https://www.npmjs.com/package/hpw-convert-eip681)も同梱しています。
+
+## 免責事項 / 非公式ツールについて
+
+**本プロジェクトは個人による無保証のの非公式（unofficial）ツールです。** 
+
+本ライブラリの目的は、あくまで相互運用性（interoperability）の確保です。
+
+実装は純粋なクライアントサイドの文字列・URL解析のみを行い、**外部のサーバーへ一切ネットワークリクエストを送信しません。** 入力として受け取ったURL文字列をその場でパースし、EIP-681形式の文字列やアドレス・金額に変換して返すだけです。
+
+## 対応範囲
+
+現時点では以下のみに対応しています（他のチェーン・通貨は今後の対応も未定です）:
+
+- チェーン: **Polygon (chain id `137`)** のみ
+- 通貨: **JPYC** (`master_currency_id=487`) のみ
+
+対応外のURL・チェーン・通貨は `ParseError` （もしくはJS側のタグ付きエラー）として明示的に拒否されます。
+
+## 対象とするURL形式
+
+```
+https://link.expo2025-wallet.com/pay?to=<address>&master_currency_id=487&amount=<hex>&to_name=<label>
+```
+
+これをEIP-681形式に変換します:
+
+```
+ethereum:<JPYCコントラクトアドレス>@137/transfer?address=<to>&uint256=<amount>
+```
+
+`amount` は元URLに存在しないことがあります。その場合 `amount` は
+`None`（JS側では `undefined`）として扱われ、EIP-681出力からも
+`uint256=` パラメータ自体が省かれます（`ethereum:<contract>@137/transfer?address=<to>`）。これはEIP-681仕様が金額未指定のリクエストを
+許容している（受け取り側のウォレットがユーザーに入力させる）ことに
+対応したものです。
+
+## インストール
+
+### Rust (`core`)
+
+```
+cargo add hpw-convert-eip681
+```
+
+### npm (`wasm`)
+
+```
+npm install hpw-convert-eip681
+```
+
+## 使い方
+
+### Rust
+
+```rust
+use hpw_convert_eip681::{is_supported, parse};
+
+fn main() {
+    let url = "https://link.expo2025-wallet.com/pay?to=0x1234567890123456789012345678901234567890&master_currency_id=487&amount=0x3e8&to_name=Coffee%20Shop";
+
+    // 対応しているURLかどうかを事前に確認する
+    if !is_supported(url) {
+        eprintln!("unsupported link");
+        return;
+    }
+
+    // パースする
+    let link = parse(url).expect("valid HashPort link");
+
+    // EIP-681形式のURIを取得する
+    println!("{}", link.to_eip681());
+    // => ethereum:0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29@137/transfer?address=0x1234...&uint256=1000
+
+    // アドレスと金額を個別に取得する（amountは元URLに無いこともあるため Option<U256>）
+    println!("to: {}", link.address());
+    match link.amount() {
+        Some(amount) => println!("amount: {amount}"),
+        None => println!("amount: (unspecified)"),
+    }
+
+    // まとめて取得することもできる
+    let addr_amount = link.address_amount();
+    println!("{} / {:?}", addr_amount.address, addr_amount.amount);
+}
+```
+
+### JavaScript / TypeScript
+
+```ts
+import { isSupported, parseHashportLink, isValidChecksum } from "hpw-convert-eip681";
+
+const url =
+  "https://link.expo2025-wallet.com/pay?to=0x1234567890123456789012345678901234567890&master_currency_id=487&amount=0x3e8&to_name=Coffee%20Shop";
+
+// 対応しているURLかどうかを事前に確認する
+if (!isSupported(url)) {
+  throw new Error("unsupported link");
+}
+
+// パースする（失敗時は { kind: "...", ... } 形式のエラーをthrow）
+try {
+  const link = parseHashportLink(url);
+
+  // EIP-681形式のURIを取得する
+  console.log(link.toEip681());
+  // => ethereum:0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29@137/transfer?address=0x1234...&uint256=1000
+
+  // アドレスと金額を個別に取得する（amountは元URLに無い場合 undefined になる）
+  console.log(link.to, link.amount, link.amountHex);
+
+  // その他のフィールド
+  console.log(link.chainId, link.currencySymbol, link.currencyContract, link.toName);
+} catch (err) {
+  console.error(err.kind, err);
+}
+```
+
+## チェックサム検証（オプション）
+
+`parse` / `parseHashportLink` はアドレスの大文字・小文字を厳密にはチェックしない、寛容な（lenient）パースを行います。これとは別に、EIP-55チェックサムを厳密に検証したい場合のためのオプトインAPIとして `validate_checksum` / `isValidChecksum` を用意しています。
+
+```rust
+use hpw_convert_eip681::validate_checksum;
+
+match validate_checksum("0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29") {
+    Ok(address) => println!("valid checksum: {address}"),
+    Err(e) => eprintln!("invalid checksum: {e}"),
+}
+```
+
+```ts
+import { isValidChecksum } from "hpw-convert-eip681";
+
+isValidChecksum("0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29"); // => true / false
+```
+
+## ライセンス
+
+[MIT License](./LICENSE)

package/package.json

@@ -4,7 +4,7 @@
   "collaborators": [
     "Osumi Akari"
   ],
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,7 +15,8 @@
     "hpw_convert_eip681.js",
     "hpw_convert_eip681_bg.js",
     "hpw_convert_eip681.d.ts",
-    "LICENSE"
+    "LICENSE",
+    "README.md"
   ],
   "main": "hpw_convert_eip681.js",
   "types": "hpw_convert_eip681.d.ts",