Tutorial

Pin and upload

The desktop app plus the Kubo node it starts for you. You keep albums pinned on that node, you can upload releases whose bytes stay on that node until a moderator approves them, and the wallet bound to your node can receive TTT for pins the verifiers accept.

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 tutorialYes, 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 copyYes. Download and Pin, and the pin made when you unlock a format
Earn TTT for pinningYes. 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 appTorrentech Test
Library~/Torrentech (change from the IPFS This machine cell)~/Torrentech-test
Kubo API127.0.0.1:15001 (loopback only; stock Kubo is :5001)127.0.0.1:25201
Repo<library>/.torrentech-ipfssame 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 seeWhat 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:

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:

  1. Pay <cost> TTT or Free download (desktop). When the local node is up, that unlock makes a best-effort public-mesh pin named Torrentech 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.
  2. 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.

FieldRequiredWhat it is
WeblinkNoPlaceholder: “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
ArtistYes
Album NameYes
LabelNo
CATNONoCatalog number, at most 16 characters. A weblink fill sets it only when the number fits
Release Year, Month, DayNoYear is bounded by the form. Month 1–12. Day 1–31
TagsNoGenre, Format, Source, Descriptive. Format and Source allow one tag each
TracklistNo
Cover Art (Image)NoImage file. A weblink fill may set this and show a short notice
Content File/FolderYesChoose 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 formatYesThe 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.”
LicenseYesOne 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 URLYesWhere the release comes from. Maximum 2048 characters
Rights statementYesPlaceholder: “Why this release may be distributed”, for example “I am the artist”. Maximum 256 characters
I have the right to distribute this releaseYesCheckbox
ReviewNoMaximum 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 new release is not public until a moderator approves it. my pending uploads lists three groups:

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

RuleLive behavior
Reward5 TTT per passed check. A failed check pays nothing
RoundAt 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
NetworkAbout 12,200 TTT a day across pin checks, finished verifications, and moderation
PayoutPin 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 countsA published release the bound wallet offered, after a check passes. Creating or approving a release does not pay by itself
Your cap5,000 TTT a day for one wallet. All operator wallets together are capped at 15,000 TTT a day
Who is paidThe 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.

Leave these alone

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