Do the browse and download tutorial first if you do not already have the app and an in-app wallet on Arbitrum One. Rewards, profile edits, and uploads all use that same wallet. The web catalog at app.torrentech.org cannot pin, free-download, or upload. The shorter page is Pin & earn. Reward amounts are also on tokenomics.
RewardsV2 is the minter. A passed check pays 5 TTT. A pinner is checked at most once per round, which is 240 TTT a day. The desktop app offers one candidate every two hours when the wallet is bound. Pin and verifier pay have no Claim button. The moderation queue has a Claim button that calls settleModeration. The keeper settles pin and verifier pay, and can also settle moderation.
| Pinner / uploader (this guide) | |
|---|---|
| Everything in the browse and download tutorial | Yes, on the desktop app |
| Upload a new release (bytes on your node until it is reviewed) | Yes. upload in the top nav, after sign-in |
| Keep your own durable copy | Yes. Download and Pin, and the pin made when you unlock a format |
| Earn TTT for pinning | Yes. A passed check pays 5 TTT, at most one check per pinner per round (240 TTT a day). The desktop offers one candidate every two hours |
1. The bundled Kubo node
Run the desktop app. You do not install IPFS Desktop for normal use. The footer IPFS / This machine cell shows a peer count (1 peer, 12 peers, …) when the sidecar is up, or down when it is not. Wait for peers before you trust a local pin.
| Production app | Torrentech Test | |
|---|---|---|
| Library | ~/Torrentech (change from the IPFS This machine cell) | ~/Torrentech-test |
| Kubo API | 127.0.0.1:15001 (loopback only; stock Kubo is :5001) | 127.0.0.1:25201 |
| Repo | <library>/.torrentech-ipfs | same layout under the test library |
Public pin rewards are checked against the production mesh. Use the production app for that. Test builds talk to the test stack.
Windows bundles Kubo and can pin. It does not bundle a Ceramic sidecar; catalog reads stay on the Torrentech replica. Linux and macOS also start a local Ceramic replica. Writes (uploads, profile, comments, votes) still go to hosted Ceramic. See footer status in the browse and download tutorial.
The library path is shown under the IPFS This machine peers, with change. change opens Choose library folder, moves the sidecar repo, and restarts Kubo on the new folder. A sidecar still on the previous folder is replaced on the next start. The onboarding line is: “Albums pinned from this folder must stay at these paths. Linked albums share file data with the original folder, so writing into a file (for example retagging in place) breaks the pin. Replacing the original file with a new file leaves the pin on the uploaded bytes.”
At start the sidecar joins the public IPFS mesh (AutoConf, mDNS on, leftover private-swarm filters removed). Extra bootstrap:
/ip4/95.217.135.193/tcp/4002/p2p/12D3KooWSrKeJ8jinMaDzBJDKPycKU99AiVvth7bNXkkY2oSCwPh
ipfs.torrentech.org is the HTTP gateway, not this swarm address.
Optional check against the local API (http://127.0.0.1:15001/api/v0 on the production app):
ipfs id
ipfs pin ls --type=recursive
ipfs pin ls --names
ipfs swarm peers
ipfs filestore ls
ipfs filestore verify
Point ipfs at that API (Kubo’s --api flag) if another daemon is also installed. Homebrew Kubo on :5001 is not the app’s node. filestore ls and filestore verify are the check for --nocopy uploads: each pointer should still resolve to a file under the library.
Library and filestore uploads
Choose album folder on the upload form opens the operating-system folder dialog. On Linux that dialog is required: the in-app file control cannot pick a whole album. The dialog opens at the library.
User and moderator uploads run ipfs add -r --nocopy on a folder under the library. The repo holds filestore pointers. A folder already in the library is added there. A folder on the same mounted filesystem raises Link into the library. The app hardlinks each imported file into <library>/<album>/ and leaves the original folder where it is. The two folders name the same file data. Another mount, or a filesystem that cannot hardlink, is refused. There is no move or copy.
The library names have to stay at that path. Renaming, moving, or deleting <library>/<album>/ makes the pin hollow: a later leaf fetch fails, and that album is not a pass. Deleting or moving the original folder leaves the library names in place. Writing into a linked file in place (retag, ReplayGain, ratings) changes the shared bytes and breaks the pin. A program that replaces the original with a new file leaves the pin on the uploaded bytes. There is no supported ipfs repo gc on this sidecar. Garbage collection drops filestore pins.
Download and Pin is different. It imports an authenticated full-DAG CAR into the repo, verifies the recursive pin, and writes a playable folder from the now-local node under a parent you choose. Deleting that saved folder does not unpin the repo copy. Unpinning, or a garbage collection aimed at this repo, does.
Admin catalog ingest does not --nocopy onto the admin sidecar and does not link or move the folder into the library. It streams the folder to the catalog seeds. That button is Pin to catalog, described under upload.
2. Your node is bound on chain
Verifiers find your node through PinnerRegistry on Arbitrum One: it records the Kubo Peer ID that answers checks for your wallet. The desktop binds it for you. Once the sidecar is live and the in-app wallet is unlocked, it signs a bind with the Kubo peer key and sends it from your wallet. The send costs a little gas and goes out without a dialog while Profile → Send pin reward transactions automatically is on. A wallet bound to another desktop moves to this one. A wallet bound to an operator origin peer stays there.
Profile → IPFS Peer ID (open Profile in the session bar) shows the sidecar’s Peer ID and the binding:
| What you see | What it means |
|---|---|
| “Bound on chain to this node. Pin checks credit this wallet.” | Nothing to do |
| “This wallet is bound to another node…” | The binding points at another machine. This app moves it here the next time it binds, for example after a restart |
| “Not bound yet…” | The bind has not gone out. Keep IPFS up and the wallet unlocked |
| “IPFS is not running on this device.” | The footer IPFS cell is down. Relaunch |
| “Admin desktops use the catalog node and do not pin here.” | Admin sessions do not pin on this machine |
ipfs id against 127.0.0.1:15001 prints the same Peer ID. There is nothing to paste or publish on the profile.
Reachability
A pin check dials your node directly over plain TCP. Your Kubo asks peers on the internet to dial it back (AutoNAT), and the app shows the answer in two places:
- Footer IPFS cell.
reachableornot reachableafter the peer count. Nothing is added while Kubo has no answer yet, which can take a minute after start. - Profile → IPFS Peer ID. “Pin checks can reach this node at
/ip4/…/tcp/…”, a warning, or “Checking whether pin checks can reach this node…”.
Not reachable means pin checks fail, so pins on this node earn nothing. Turn on UPnP on the router, or forward TCP port 14001 to this computer. The footer hint names the port. A node reachable only over WebSocket also counts as not reachable, because checks use plain TCP. Relays do not help: Kubo does not answer a check over a relayed connection.
3. Pin a release you did not upload
On a published format, after the wallet has access:
- Pay
<cost>TTT or Free download (desktop). When the local node is up, that unlock makes a best-effort public-mesh pin namedTorrentech download: <artist> - <album> [<format>]. Use Download and Pin for the authenticated gateway path that verifies a complete local pin. The row then offers the download buttons from the browse and download tutorial. - Download and Pin (shown only when the daemon is reachable; the label is Saving… while it runs). You pick a parent folder. The app fetches an authenticated CAR, imports and verifies the CID as
tT release: <artist> - <album> [<format>], then writes a child folder from the local sidecar:
Artist - Album [year] [FORMAT]
Empty year or format is omitted. Slashes in the artist, album, or format become -, so FLAC / 16-bit is [FLAC - 16-bit]. A retry skips files already in that folder with the same byte size, so an interrupted save can continue. The saved files are the album you can play. The pin in the repo is what has to stay for a later check.
Open in IPFS, Open using IPFS gateway, and Gateway .tar do not replace the pin.
Keep the app running, with that content still pinned, across the checks in how a pin becomes TTT. Quitting the app stops the sidecar. A pin that is present only while the verifier is not looking is a miss for that check.
Check names:
ipfs pin ls --type=recursive
ipfs pin ls --names | grep -E "tT release:|Torrentech download:"
4. Upload a release
upload is in the top nav after you sign in on the desktop app. The form says “Please connect your wallet to upload releases.” until that session exists.
| Field | Required | What it is |
|---|---|---|
| Weblink | No | Placeholder: “Discogs, Bandcamp, MusicBrainz, Apple Music, or Beatport URL”. fill pulls artist, album, date, tags, tracklist, and cover when the page can be read. Leaving the URL clears the tracklist and cover that fill wrote. Artist, album, label, CATNO, date, tags, and review stay |
| Artist | Yes | |
| Album Name | Yes | |
| Label | No | |
| CATNO | No | Catalog number, at most 16 characters. A weblink fill sets it only when the number fits |
| Release Year, Month, Day | No | Year is bounded by the form. Month 1–12. Day 1–31 |
| Tags | No | Genre, Format, Source, Descriptive. Format and Source allow one tag each |
| Tracklist | No | |
| Cover Art (Image) | No | Image file. A weblink fill may set this and show a short notice |
| Content File/Folder | Yes | Choose album folder. The hint: “Opens at the library folder. Albums elsewhere on the same mounted filesystem are linked into it, not moved. Don't rewrite the files in place after upload.” After a pick, the form shows file count, audio count, size, and the directory name |
| File format | Yes | The allowlist from Administration (for example FLAC / 16-bit, FLAC / 24-bit, MP3 / 320k CBR). Generic FLAC and bare MP3 are retired and are not in the menu. If the menu is empty: “No allowed formats configured. Ask an administrator to add formats in Administration.” |
| License | Yes | One of CC BY, CC BY-SA, CC BY-NC, CC BY-NC-SA, CC BY-NC-ND, CC0, Public Domain, or Bandcamp.com free release |
| Source URL | Yes | Where the release comes from. Maximum 2048 characters |
| Rights statement | Yes | Placeholder: “Why this release may be distributed”, for example “I am the artist”. Maximum 256 characters |
| I have the right to distribute this release | Yes | Checkbox |
| Review | No | Maximum 2048 characters |
The moderation queue shows the license, source URL, rights statement, and checkbox. Approve stays disabled while any of them is missing.
On the desktop app, a wallet without a staff credential signs the submission before the catalog write. The signature names the content, its CID hash, your wallet, and the time. It is not a transaction and costs no gas. If the wallet refuses to sign, the upload stops. A moderator’s decision on a signed submission goes on chain and pays the 40 TTT review fee described in the moderator tutorial. Staff uploads are not signed.
Submit release runs the add, then the Ceramic write. The button shows the current phase while it is busy. On success: “Release uploaded successfully! CID: …”. A similar artist and album does not stop the submit, and the warning does not stay on screen after the form resets. An exact match on artist, album, and a filled label is blocked when another wallet owns it (Sangoma, Sangoma Records, and Sangoma Recordings are the same label; Pixan Recordings is a different release). This wallet’s own exact match resumes that release. A blank label still matches that artist and album.
What the node stores:
- The album is added with
--nocopyfrom the library folder. Keep that folder in place. - The recursive pin is named
tT release: <artist> - <album> [<format>] - [1/<blocks>], where<blocks>is the number of chunk refs. A published file without its chunk manifest is invisible to pin verification, so a finished upload always has one. - Cover, when present, is pinned as
torrentech cover.
The new release is not public until a moderator approves it. my pending uploads lists three groups:
- Pending — waiting for moderation. Open / Edit.
- Approved — status sync pending — a moderator approved it and the public status has not caught up. Open Details / Retry.
- Rejected.
Until it is published (or approved), it is not offered for a check. After approval it is eligible like any other published format, only while your node can serve it and the wallet is bound.
Admins
On a user or moderator format that is not already a catalog copy, desktop admins see Pin to catalog. That lands the CID on the catalog seeds with --nocopy and the same Artist - Album [year] [FORMAT] directory name. The button’s own download action reads Download to folder and does not pin that CID onto the catalog node. User and moderator streams can then be copied onto a catalog Ceramic stream.
Administration → Pin Rewards is admin-only and read-only. It lists pin, verifier, and moderation settlements for the connected wallet: kind, amount in TTT, and the task or decision id. The keeper settles that pay. There is no button that sends a transaction. A normal pinner does not use that screen.
5. How a pin becomes TTT
| Rule | Live behavior |
|---|---|
| Reward | 5 TTT per passed check. A failed check pays nothing |
| Round | At most one check per pinner per round (240 TTT a day). While it runs with the wallet unlocked, the desktop app commits one candidate every two hours. It picks from the published releases its own Kubo pins, including pins from earlier sessions and your own uploads, and takes a different release each time. The bind and these offers go out without a confirm dialog while Profile → Send pin reward transactions automatically is on (the default). They send no ETH value and cost a little gas. Every other send still asks |
| Network | About 12,200 TTT a day across pin checks, finished verifications, and moderation |
| Payout | Pin and verifier pay have no Claim button. The moderation queue has a Claim button that calls settleModeration. The keeper settles pin and verifier pay, and can also settle moderation |
| What counts | A published release the bound wallet offered, after a check passes. Creating or approving a release does not pay by itself |
| Your cap | 5,000 TTT a day for one wallet. All operator wallets together are capped at 15,000 TTT a day |
| Who is paid | The wallet that was checked |
Keep the app, its Kubo sidecar, and the album pin up so a drawn check can fetch the piece. A miss pays nothing. The next round starts clean.
Only release pins are rewarded. Avatar pins, unnamed experiments, and a catalog you are not actually serving do not add to the count.
6. GUIBo (optional)
GUIBo is a third-party Qt desktop app for people who already run Kubo. It talks to Kubo’s HTTP RPC and can list pins, add files, work with IPNS, inspect swarm and repo stats, and export UnixFS files. It does not replace the Kubo daemon, and it does not replace Torrentech. The Torrentech app already pins, names those pins, and binds your node on chain. You do not need GUIBo to earn TTT.
If you want that extra window on the same node the app started, point GUIBo’s RPC URL at:
http://127.0.0.1:15001
That is the production sidecar API. It is loopback only. Torrentech Test uses http://127.0.0.1:25201 instead. The Peer ID GUIBo shows should match Profile → IPFS Peer ID.
Builds on that site at the time of writing are 1.1.4 (Linux AppImage, .deb, and .rpm for amd64 and arm64; macOS .dmg for amd64 and arm64; Windows setup and zip for amd64 and arm64). Check the site for a newer build.
Without a license, GUIBo stays in trial mode: the pin list shows at most three rows (the status line still has the full count), Add to IPFS accepts files only and at most three files per add, and auto-refresh stays off. A lifetime license is US $5, paid in DAI, USDC, or USDT on Ethereum mainnet (not Arbitrum), from the Activation dialog inside GUIBo. That payment is GUIBo’s, not a Torrentech fee, and it does not interact with TTT.
Use GUIBo to look: pin list, pin-type filter, copy a CID, Peer ID, swarm, repo stats. Leave unpin and repository garbage collection unused against the Torrentech sidecar. Either one drops the copies the verifier fetches, and garbage collection is especially destructive for --nocopy uploads whose only bytes are the library files plus filestore pointers. Torrentech has no supported ipfs repo gc on this repo.
GUIBo’s public-gateway “open” action uses https://ipfs.io/ipfs/…. Torrentech album bytes are token-gated, so that public URL will not fetch a catalog release. Use the app’s Open using IPFS gateway after you have unlocked the format, or read the files Download and Pin already wrote.
7. Larger nodes and other people’s Kubo
The desktop sidecar is the supported pinner. A node that serves a lot of data wants Pebble or Badger on SSD, reprovider strategy roots, and connection limits. Flatfs plus reprovide-all does not scale at that size. That tuning, a standalone Kubo, and a 24/7 VPS seeder are operator setups, not this desktop path. On a standalone node, filestore has to be enabled and albums have to stay under the directory that contains the IPFS repo.
A Kubo the app did not start cannot bind yet: the bind is signed with the peer key of the sidecar the desktop runs. Pins on another daemon earn nothing until a bind tool for it ships.
Troubleshooting
- No Download and Pin button. Sidecar Kubo is down. Gateway
.tar/.zipstill work. Quit from the tray and relaunch. The IPFS This machine cell should show peers. - “already stored in the blockstore; filestore pin is not possible for this album.” This sidecar already has a normal (copied) pin of that album, so
--nocopycannot take it. Re-upload under a new folder name, or wait. There is no sidecarrepo gcto clear the old blocks. - Uploaded album missing, or the pin looks hollow. The
--nocopyfiles left the library. Put the same folder back under the library path, or upload again. A leaf the peer cannot serve is not a pass. - Profile says the wallet is bound to another node. Restart the app with IPFS up and the wallet unlocked. The bind moves the wallet to this node. Until then, checks go to the other node.
- Pinned, and still no TTT. The wallet has to be bound, the node reachable, the release published, and a check has to pass. The desktop offers one candidate every two hours. Pay is 5 TTT per passed check, at most one check per round. The keeper settles it. There is no claim button. Administration → Pin Rewards is only visible to admins. The desktop checks every five minutes. Each time the reason changes, it writes a
pin-candidate:line totorrentech.login the app’s log folder, for examplewallet lockedorcommitted …. - Download and Pin saved files, then the app was quit. The repo pin survives the next launch only if you did not unpin it and did not garbage-collect the repo. The sidecar has to be running at check time for the checker to dial you.
- Contact from moderators about an upload: they use Blockscan Chat, or Matrix and Email if you set those on Profile. Details are in Getting help.