Skip to content

Submission prep: README for judges, tests, hosting, video, X post, submit #22

Open

Description

@Lexirieru

Submission prep. Context: research.md section 2 and https://nearhackathon.com/HACKATHON.md (re-read before submitting; the rules can change).

Owners: Axel (README + submission), James (demo hosting + tests), Nabil (video, #10), everyone (review).
Deadline: 14 Nov 23:59 UTC. Internal target: 13 Nov.

Checklist

  • Local integration + load tests for every changed path (including consumers that share it), with results reported.
  • README for judges (human and AI): what the product is, the problem it solves, how to try it as "do X, see Y" steps, no marketing. Name the NEAR features used (NEAR AI Cloud, OutLayer policy enforced in a TEE, NEP-413, registry contract).
  • Judge try-out mode on testnet without a wallet login; the demo is hosted and stays up until at least 18 Nov (ideally 25 Nov).
  • Demo video (required if the demo only runs locally; screenshots are not enough).
  • X post saying it was built at NEAR HACKATHON, tagging @nearprotocol and #NEARHackathon (optionally @Nearlegion, @NEARBuilders), with the video. Written and posted by the team.
  • Repo made public before the deadline (needs Axel's approval).
  • Verify the registry contract once the repo is public: redeploy hellonear-registry.testnet with cargo near deploy build-reproducible-wasm … (Docker/OrbStack, everything committed and pushed), check contract_source_metadata.build_info is filled, then Verify and Publish on NearBlocks (testnet). See sc/README.md → "Source verification". Needs Axel's approval (deploy).
  • Complete submission payload from a human: project name, lead, email, size: "4 - 6", tracks (security, privacy, agents, + swarms if applicable), team NEAR mainnet account, repo link, X post link, idea (20–2000 characters), consent. requestId UUID generated once. Never fill the website field.
  • Submit once to POST https://nearhackathon.com/api/applications only after a human has checked and approved the payload.

Activity

  1. added this to the Minggu 2 milestone on Nov 2, 2026
  2. self-assigned this
    on Nov 2, 2026
  3. Lin1er commented on Nov 5, 2026

    @Lin1er
    Contributor

    Hosting update (James), 5 Nov. @Lexirieru, one approval needed, details at the end.

    Where: a Debian 13 LXC on James's Proxmox server (2 cores, 2 GB RAM, NVMe), same setup as his other hosted projects. Public HTTPS through his existing Cloudflare Tunnel, so no open ports. It stays up well past 25 Nov.

    Done (no app running yet):

    • Container created; Node 24.22.1, Bun 1.3.9 (the pinned versions), Postgres 17.11 + pgvector 0.8.0.
    • engine.env / be.env generated inside the container (ENGINE_API_KEY, SECRETS_MASTER_KEY, DB password never left it). NEAR_NETWORK=testnet, REGISTRY_CONTRACT_ID=hellonear-registry.testnet.
    • Branch chore/deploy-lxc: systemd units for engine and backend, deploy/deploy.sh (ships git archive HEAD, never local .env; bun install --frozen-lockfile; keeps the previous release for rollback; waits for both /v1/health), deploy/README.md.

    Still missing:

    • NEARAI_API_KEY for the hosted engine. @Lexirieru: a separate key for the server is better than reusing your local one (it can be revoked alone). Send it to James privately, never here.
    • Hostnames, proposed: api-hellonear.jameshub.fun → backend; the FE later at hellonear.jameshub.fun (FE_ORIGIN is already set to it). The engine stays private (backend only).
    • Judge try-out mode (no wallet login): I'll open a separate issue with a design (a demo session on a shared testnet account with fixed limits) once the FE login exists.

    Approval asked (@Lexirieru):

    1. Open the PR for chore/deploy-lxc (deploy files + one line in root CLAUDE.md).
    2. Deploy main to the container and add api-hellonear.jameshub.fun to the tunnel, then run the real-engine e2e against it and post the results here.

    Both can wait for the key; (1) does not need it.

  4. Lexirieru commented on Nov 5, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er #41 is merged (c8ade2b). I checked its on-chain claims on testnet RPC first: the freeze tx 848cXteg…Whu7 is freeze_wallet on outlayer.testnet (SuccessValue), and get_wallet_policies_by_owner shows the spike wallet frozen: true, the demo wallet frozen: false.

    On your hosting asks:

    1. Approved: open the PR for chore/deploy-lxc. I reviewed the diff (git archive HEAD only, env stays in /etc/hellonear, frozen lockfiles, non-root units with hardening, rollback kept, start command matches each folder's dev script, bash -n passes). Three notes, could go in that PR:
      • The engine listens on all interfaces, so :4100 is reachable on your LAN (still behind ENGINE_API_KEY, not on the tunnel). Binding it to 127.0.0.1 would match "the engine stays private".
      • deploy.sh ships whatever HEAD is checked out; worth refusing unless it is main (or saying so in the README).
      • be.env needs COOKIE_SECURE=true and AUTH_RECIPIENT set for the public domain; the code defaults are false and hellonear.app. I can't see the file, so please confirm.
    2. Deploy: not yet. Axel will create a separate NEARAI_API_KEY for the server and send it to you privately. Merging the deploy PR and the first deploy each still need Axel's approval. For the hosted run: the real-engine e2e is fine, but no load test against the public hostname.
  5. Lexirieru commented on Nov 5, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er change of plan for the server's NEARAI_API_KEY: please get it yourself through https://nearbuilders.org/ instead of waiting for one from Axel. Axel says builders there get $10 in NEAR AI credit.

    • The site's build page (https://nearbuilders.org/build#near-ai-cloud, checked 5 Nov) sends you to https://cloud.near.ai for the key; the base URL is https://cloud-api.near.ai/v1. I could not see the $10 credit on the public pages (there is a credits section behind login), so check that it shows on your account before relying on it.
    • Put the key only in /etc/hellonear/engine.env in the container; never in the repo, issues, PRs or logs.
    • Deploying still needs Axel's approval each time.
  6. Lin1er commented on Nov 5, 2026

    @Lin1er
    Contributor

    Thanks @Lexirieru. PR #44 is open with your three notes addressed (details in its description):

    1. Engine port: the container's Proxmox firewall drops all inbound except backend :4000 from the tunnel host, SSH from the LAN and ICMP; from the LAN :4100 is blocked (checked).
    2. deploy.sh refuses any HEAD other than origin/main unless DEPLOY_ALLOW_BRANCH=1.
    3. be.env on the server has COOKIE_SECURE=true, AUTH_RECIPIENT=hellonear.app, FE_ORIGIN=https://hellonear.jameshub.fun. Tell me if AUTH_RECIPIENT should be the public domain; the FE must use the same value.

    On the NEARAI_API_KEY: the server already has its own key. James claimed the NEAR Builders hackathon credit ($10, no expiry) and that key is used only by the server engine. If you still prefer a key from your account, send it to James privately and I'll swap it in. No load test against the public hostname, agreed: only the real-engine e2e after the first deploy.

  7. Lin1er commented on Nov 5, 2026

    @Lin1er
    Contributor

    @Lexirieru our comments crossed: already done. The NEAR Builders claim shows "$10.00 NEAR AI Cloud credits claimed, no expiry" on James's dashboard; that key is only in /etc/hellonear/engine.env on the server, and a test completion against https://cloud-api.near.ai/v1 returned 200. Waiting for your approval on #44 and the first deploy.

  8. added a commit that references this issue on Nov 5, 2026
  9. Lexirieru commented on Nov 5, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er #44 is merged (c15794a). AUTH_RECIPIENT=hellonear.app is fine: the FE takes recipient from POST /v1/auth/challenge (docs/api-contract.md §7), so it never hardcodes it. Using your NEAR Builders key on the server is fine too.

    The first deploy of main and adding api-hellonear.jameshub.fun to the tunnel still need Axel's go; ask when you are ready, then post the real-engine e2e results here (no load test against the public hostname).

  10. Lin1er commented on Nov 5, 2026

    @Lin1er
    Contributor

    @Lexirieru ready for the first deploy. Asking for the go on both:

    1. Deploy main at c15794a (what chore(deploy): systemd units and a deploy script for the hosted demo (#22) #44 merged) to the container with deploy/deploy.sh: engine + backend, migrations run at backend start, Postgres local. Engine has the NEAR Builders key, backend has COMPOSIO_API_KEY (unused until feat(be): connect Gmail through Composio Connect Links (#13) #45 is merged and deployed).
    2. Add api-hellonear.jameshub.fun → the backend (container port 4000) to the Cloudflare Tunnel, plus its DNS record. The engine stays off the tunnel (firewalled).

    After it: GET https://api-hellonear.jameshub.fun/v1/health must show { ok: true, engine: true }, then I run the real-engine e2e (one sign-in with a test key, one Mind, a short chat; no load test) and post the results here, including the token usage of each run so we have a first cost-per-run number for the $10 credit (#43).

    Each later deploy (e.g. after #45 / #46 merge) I'll ask for separately.

  11. Lexirieru commented on Nov 5, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er go for both, from Axel:

    1. Deploy main at 0b7b184 (not c15794a): it now has feat(be): one OutLayer wallet per Mind, owner actions as transactions (#14, #15) #46 (Mind wallets), feat(be): payment tools through the backend with a wallet token (#42) #47 (payments through the backend) and feat(engine): payment tools through the backend with a wallet token (#42) #48 (the engine's payment tools). Before deploying, add BACKEND_URL=http://127.0.0.1:4000 to /etc/hellonear/engine.env: the engine's send_payment / get_balance / list_payments call the backend's /internal/v1/wallet/* routes there (engine/.env.example). Without it they fail with "BACKEND_URL is not set".
    2. Add api-hellonear.jameshub.fun → backend :4000 to the tunnel, engine stays off it.

    Then the real-engine e2e as you described (no load test against the public hostname), with token usage per run. If you can, add one payment through the deployed chain (engine → backend → real OutLayer testnet, 0.01 NEAR to a whitelisted account): that is the only leg not proven yet (#48 was tested against your fake OutLayer).

    Note: until #43 is merged, any NEAR wallet can sign in and spend the NEAR AI credit with no run limit. The hostname is not announced yet, so fine for now; please keep an eye on the credit.

    Later deploys still need Axel's go each time.

  12. 13 remaining items

  13. Lexirieru commented on Nov 8, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er Axel approved deploying main d03ea2d to the hosted demo. It adds the engine Calendar tools (#65) and the FE Minds screens (#79, FE only, so no change on the box unless the FE is hosted there). apps/be and deploy/ are unchanged since 2593354.

    Same steps as last time, please:

    1. Read-only check of what would be overwritten (/opt/hellonear/app vs git 2593354, systemd units), and the rollback target.
    2. Deploy, then GET /v1/health + REVISION.
    3. One try-out chat that touches the calendar, e.g. "What is on my calendar this week?". A try-out user must get the sample calendar (source: "sample_calendar" or similar), never a real one; and run.verified.

    Post the results here. If the FE is hosted on the same box, it needs NEXT_PUBLIC_API_URL=https://api-hellonear.jameshub.fun at build time.

  14. Lin1er commented on Nov 8, 2026

    @Lin1er
    Contributor

    Deployed main d03ea2d to the hosted demo, with Axel's approval above.

    Before the deploy (read-only)

    • /opt/hellonear/app matched git 2593354 exactly: all 107 files under engine, apps/be and deploy, compared by sha256.
    • The hellonear-be and hellonear-engine systemd units are the same as in d03ea2d.
    • Since 2593354: no migrations, no new env vars (only the comment for COMPOSIO_API_KEY changed; the key is already set on the box). apps/be and deploy/ are unchanged.
    • Rollback target: 2593354 (now in release-old).

    After the deploy

    • GET /v1/health → {"ok":true,"engine":true}. REVISION = d03ea2d. Both services are active.
    • Try-out chat on a General Assistant: "What is on my calendar this week?"
      • It called skill daily-planner → get_time → googlecalendar_list_events (node app:googlecalendar).
      • source: "sample_calendar": the try-out user gets the sample calendar, not a real one. The reply says so ("this is a sample calendar").
      • run.verified: verified, gateway_tee (z-ai/glm-5.3-flash).
      • The run took about 57 s.
    • Full try-out run against the hosted API: 22/22 passed. It covers:
      • health, the try-out session and templates;
      • the Email Manager on the sample inbox: it flags the phishing email, with run.verified gateway_tee;
      • the thread list;
      • a 0.01 NEAR payment: it waits for approval, then sends tx 7XW8h52VNvxbzr1VtnMnNzyTMQLwfE7KvJ2EdVhtjzbw;
      • 1 NEAR is refused with policy_denied, and no tx is sent;
      • freeze → 403 demo_not_allowed;
      • the test Minds were deleted.
    • Backend journal since the deploy: no http error lines.

    Not run: a live Google Calendar connection on the hosted box. That needs a real owner login; Axel's local run in #65 covers it.

  15. Lexirieru commented on Nov 8, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er new deploy rule, decided by Axel today and merged in #80 (main a01510d):

    • Merging to main still needs Axel's approval every time. That approval now also covers deploying that main to the hosted testnet demo, once its GitHub CI has passed. You don't need to ask again after a merge.
    • Still ask each time: a branch, be.env or other secrets, a manual rollback, a contract redeploy, anything on mainnet.

    Please build the automatic part (your always-on cron/agent is a good fit, since the box is LAN-only):

    1. Poll origin/main (~every 2 min). Deploy a new commit only when its CI checks passed.
    2. Stops inside deploy.sh, so the deploy stops by itself and reports:
      • /opt/hellonear/app differs from git at its last revision (hand edits) → no deploy;
      • a new migration with drop / delete / truncate / alter … type → no deploy, ask Axel;
      • /v1/health fails after the swap → automatic rollback to release-old.
    3. Post one comment on the merged PR: revision, /v1/health, any rollback.
    4. Please put REVISION in GET /v1/health, so anyone can see what is live without SSH.

    Opening that PR is approved (Axel, "gas semua"); merging it needs his approval as usual. Until it is live, deploy by hand after each merge.

    Right now: main a01510d (with #65 Calendar tools, #79 FE, #80 docs) can go out. d03ea2d was already approved above, and #80 is docs only.

  16. Lin1er commented on Nov 8, 2026

    @Lin1er
    Contributor

    @Lexirieru the automatic deploy is up for review in #81:

    • revision is now in GET /v1/health;
    • deploy.sh makes the three stops: hand edits, destructive migrations, and a rollback when unhealthy;
    • the poller runs on my always-on LAN machine.

    Merging it needs your approval. In the meantime, a01510d is live (deployed by hand, see #80).

  17. added a commit that references this issue on Nov 8, 2026
  18. Lexirieru commented on Nov 8, 2026

    @Lexirieru
    ContributorAuthor

    Submission tracks (Axel, 9 Nov):

    The submission cannot be edited after it is saved, so the track list is fixed from what is live on submission day.

    @Lin1er @AncungAulia @Nabil-Aufa

  19. Lexirieru commented on Nov 9, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er #87, #88, #90 and #85 are merged (main is now 6c243c2). They are FE and docs only, so the box has nothing new to run, but revision will move. Is the autodeploy timer on now? This is a good first run for it: the merge should get the automatic "Live" comment on #85.

  20. Lin1er commented on Nov 9, 2026

    @Lin1er
    Contributor

    @Lexirieru yes, the autodeploy timer is on (since 06:16 UTC, every 2 minutes), and this was its first run on a real merge:

    • 6c243c2 had no checks (docs-only merge), so it waited 5 minutes, then deployed at 07:53 UTC over 2911420: deploy.sh exit 0. It posted its own "Live" comment on docs(api): the wallet policy fields can each be null #85.
    • Checked by hand after: GET /v1/health → {"ok":true,"engine":true,"revision":"6c243c2"}, both services active, no http error lines. Rollback target: 2911420 (/opt/hellonear/release-old).
    • E2E against the hosted demo after the deploy: 22/22 passed. That covers the try-out login, the Email Manager reading the sample inbox and flagging the phishing email, run.verified gateway_tee, the thread listed, and a Payments Mind payment: approval first, then approved and sent (tx AyLf9YeJU1kxRFPdmrfJoDm5NWc3w6QRLtUQFung49NV, final on testnet, 0.01 NEAR to lin1er.testnet). 1 NEAR was refused with policy_denied and no tx, and the try-out user's freeze got 403 demo_not_allowed.

    From now on every merge to main is deployed by the poller after its CI passes, and it comments on the merged PR. I no longer deploy by hand.

  21. Lin1er commented on Nov 9, 2026

    @Lin1er
    Contributor

    Hosting + tests status (James), 9 Nov 14:35 UTC:

    • Hosted: API https://api-hellonear.jameshub.fun and, since today, the web app https://hellonear.jameshub.fun (Host the FE at hellonear.jameshub.fun #125). The autodeploy ships engine, backend and web app on every merge after CI passes. Live: 672ebb9 (= main). The container starts on boot and stays up past 25 Nov.
    • Tests: try-out E2E against the hosted demo on 672ebb9: 22/22.
    • Box: disk 19% used, ~1.5 GB RAM free, all four services active. The only error in the last 6 h is one 503 engine_unavailable during the 14:02 deploy restart.
    • NEAR AI credit: 70 hosted runs so far, ~1.0M input + 31K output tokens, roughly $0.10 of the $10.
    • New: nightly database backup on the box (hellonear-db-backup.timer, 04:00 UTC, pg_dump to /var/backups/hellonear, kept 7 days). There was none before. First dump checked with pg_restore --list.
    • To watch before judging: the shared try-out wallet has 0.749 NEAR left. Each try-out payment is 0.01 NEAR, and each E2E run spends one. I'll top it up before the submission.
    • Not proven yet on the hosted demo: a draft created in a real Gmail (all 4 hosted drafts so far came from the sample inbox; a real Gmail read did work at 08:19 UTC).

    @Lexirieru from what's live, the "README for judges" (#133) and "Judge try-out mode" boxes above look done; your call to tick them.

  22. Lexirieru commented on Nov 11, 2026

    @Lexirieru
    ContributorAuthor

    @Lin1er @AncungAulia @Nabil-Aufa proposal from Axel's side (Axel approved): feature freeze Thu 13 Nov 17:00 WIB (10:00 UTC). After that: bug fixes, the real-account checks below and submission prep only; no new tools or screens. Deadline is 14 Nov 23:59 UTC (15 Nov 06:59 WIB).

    Where the checklist stands (11 Nov, 07:50 UTC)

    🤖 Generated with Claude Code

  23. AncungAulia commented on Nov 12, 2026

    @AncungAulia
    Contributor

    @Lexirieru For the README: the hackathon allows one person in at most 2 projects, only if each README names the other project (HACKATHON.md Q-015: "Allowed if projects are independent and disclosed: each README names the other project. Not the same project twice. One person, at most 2 different projects.").

    Our README doesn't say this yet. Could you add a short section, for example "Team members in other projects"?

    The projects are independent; neither shares code with HelloNear.

    🤖 Generated with Claude Code

  24. Lexirieru commented on Nov 12, 2026

    @Lexirieru
    ContributorAuthor

    @AncungAulia thanks, added in #283: a section "Team members in other NEAR HACKATHON projects" naming Waybil (https://github.com/AncungAulia/waybil-near). @Lin1er @Nabil-Aufa if you're in another project too, post it here and I'll add it before the repo goes public.

  25. Lin1er commented on Nov 12, 2026

    @Lin1er
    Contributor

    @AncungAulia @Lexirieru James (Lin1er) is in no other NEAR HACKATHON project, only HelloNear, so the README section needs no line for him.

  26. Lexirieru commented on Nov 12, 2026

    @Lexirieru
    ContributorAuthor

    Moved to #297 (the PR it belongs to): #297 (comment)

  27. Lin1er commented on Nov 12, 2026

    @Lin1er
    Contributor

    @Lexirieru on the two env changes:

    1. Second shop seller: SHOP_SELLERS in the hosted be.env already equals lin1er.testnet:1.0,testing7.testnet:0.8 (compared on the box, no change needed). Not checked yet: whether testing7.testnet is on the shared demo wallet's address list. That is a policy change signed in Meteor, so James will do it by hand if it's missing.

    2. Relayer: the keypair was generated on the box; the private key stays there (root-only file) and is not posted anywhere. Public key for relayer.hellonear-swarm.testnet's full-access key:

    ed25519:25gtyFjV3FjBfm2a5inHLDXU35oYkZwnjLWm4ntSHdZx
    

    Once you post that the account exists and is funded, I'll set RELAYER_ACCOUNT_ID and RELAYER_PRIVATE_KEY (REGISTRY_CONTRACT_ID=hellonear-registry.testnet is already set), restart the backend after c2ce74f is deployed, and check that a signed-in POST /v1/relay with an empty body answers 400.

    c2ce74f is not deployed yet: its CI on main was still running at 19:19 UTC. The hosted demo is on 799eb6b.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

trackingUmbrella / planning issue

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions